Commit ea53785e authored by ankraft's avatar ankraft
Browse files

- Copied from schema2.0

- Moved <Doc> elements to the top of each element.
- Added <Doc> to <Domain>
- DeviceDef is now directly included in SubDevice
- Added structured DataType and renamed element name in using elements
- Added unitOfMeasure attribute to DataType
parent 4c6327a9
<?xml version="1.0" encoding="UTF-8" ?>
<!-- - HGI Device Abstraction Layer - - - - - - - - - - - - - - - - - - - - -->
<!-- -->
<!-- Extends the standard build with targets for: -->
<!-- - generate XML schema the from Relax NG (xml) description -->
<!-- - validate DAL documents against the XML Schema -->
<!-- - generate HTML documentation from DAL documents -->
<project name="importing" basedir="." default="schemas">
<import file="etc/common.xml"/>
<!-- Read the namespace declarations from a file (to get linebreaks) - - - -->
<loadfile property="schema.xmlns" srcFile="${basedir}/etc/schema.xmlns"/>
<!-- The RNG file the XML and RNC schemas are generaed from - - - - - - - -->
<property name="" value="domain"/>
<property name="schema.rng" value="${path.src}/${}.rng"/>
<!-- HTML - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- -->
<!-- Generate HTML documentation from domain definitions in the test -->
<!-- directory. The module classes included via the extends tagged are -->
<!-- included in the documentation - so an xinclude capable XSL engine is -->
<!-- needed. -->
<!-- This needs Ant version 1.8+ and it must be augmented with an current -->
<!-- version of Xerces. Download the binray distribution and place the put -->
<!-- xml-apis.jar and xercesImpl.jar in the Ant lib directory. -->
<target name="html">
<mkdir dir="${path.genbase}" />
<xslt basedir="${basedir}/test" destdir="${basedir}/gen/html"
<param name="destdir" expression="${basedir}/gen/html"/>
<!-- Schemas - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- -->
<!-- The schema is specified using Relax NG (xml) and trang is used to -->
<!-- generate the XML schema. The schema is also generated in Relay NG -->
<!-- compact syntax, which is used by some validating editors (e.g. emacs) -->
<!-- The resulting schemas need some additional patching before thy are -->
<!-- usable -->
<target name="schemas">
<java jar="${basedir}/lib/trang.jar" fork="true">
<arg value="${schema.rng}"/>
<arg value="${basedir}/etc/${}.rnc"/>
<!-- So that the editor does not complain about include directives, the -->
<!-- resulting schema is included in another schema, which includes the -->
<!-- necessary element definitions. To be able to do this the -->
<!-- definition for Imports must be deleted from this generated schema. -->
<replace file="${basedir}/etc/${}.rnc"
token="Imports = element Imports { Domain* }?" value=""/>
<java jar="${basedir}/lib/trang.jar" fork="true">
<arg value="${schema.rng}"/>
<arg value="${path.src}/${}.xsd"/>
<!-- Can't validate against the generated schema unless we add the -->
<!-- target and default namespaces ... -->
<replace file='${path.src}/domain.xsd'
<!-- In addition the xml:base tag, which is added automatically when -->
<!-- including a document, must also be permitted by out schema. -->
<!-- The schema generated from RNG is almost correct schema ... but -->
<!-- the schemaLocation is wrong. -->
<replace file='${path.src}/domain.xsd'
token="xml.xsd" value=""/>
<!-- Validate - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- -->
<!-- Check the Device Description conforms to the Device Abstraction -->
<!-- Schema. Note that we need to activate support for XML includes -->
<target name="validate" depends="">
<schemavalidate warn="true">
<fileset dir="${basedir}/test" includes="*.xml"/>
<attribute name="" value="true"/>
<schema namespace=""
file="${path.src}/domain.xsd" />
<schema namespace=""
file="${basedir}/etc/XInclude.xsd" />
<schema namespace=""
file="${basedir}/etc/XMLSchema.xsd" />
# Backlog
To Be Discussed
<a name="Versions"></a>
## Versions
### Rational
A device vendor is free to add new functionality to a device and to change or to remove existing functionality from a device by a firmware update or changes in the configuration. These changes may mean that the device functionality and a description in SDT become "out of sync" because currently an application developer has only little means to associate a specific firmware version or device configuration to a version of a SDT description.
Even then the developer needs to manage different versions of the same SDT device description because there might be devices of the same type but with different firmware versions/configurations on a network.
The version information must be available to applications at runtime.
### Proposal
To solve this problem SDT components that can be influenced by firmware updates or configuration changes must be distinguishable by some kind of version scheme. Since different versions in the structure, attributes and elements of the SDT description as well as data types are already indicated by the "version number" of the SDT (e.g."") only the components that are instantiated for the devices etc need to indicate their current version.
The proposal is to add a *version* attribute to the following SDT components:
- RootDevice
- Device
- ModuleClass
*Event*, *Action* etc don't need an version number because a change in one of those components must be indicated by a different version in the ModuleClass.
The *version* attribute is just a string value without a defined format.
### Further Discussion
Does HGI define the version format? Or is this up to the vendors to provide their own?
At least the governing entity that managed all the different needs to define this format since it must be in agreement between the device vendors, driver provider, DAL provider and application developer.
Format suggestion: define the format of the version string as "major.minor.revision" with the following semantics for each number:
- **revision**: minimal change, internal bugfix, no change to data, formats or API.
- **minor**: Change to the API that could be incompatible to the previous version. Added or removed interfaces or modules, changes in data formats.
- **major**: Redesign of the overall structure and architecture.
The "numbers" could be just integer number, but may also contain letters, e.g. "1.0.1a".
<a name="Namespace"></a>
## Domain / Namespace
### Issue
The SDL now uses the namespace "" as a namespace to identify the schema (also used for includes). The namespace is **not** a URL, but uniquely identifies the namespace and *should* be registered by HGI.
That said, most validating parsers expect **that the namesapce IS a valid URL** or that at least there is a server on the other end rejecting the request. A timeout / no connection / no answer / ... leads to an error.
Therefore, we cannot use the namespace "" because parsers don't get an answer from this address.
<a name="Roles"></a>
## Roles
### Proposal
The proposal is to add a *role* to *RootDevice* / *Device*. DECT ULE defines roles such as client and server for direct communication of appliances without a local hub. Depending on the assigned role a device might support different functions.
<RootDevice name id=”xyz” role=”something”>
<a name="Optionals"></a>
## Optionals
### Rational
Introduce optional *Actions* in *ModuleClasses* to reduce the number of possible combinations. Some technologies offers flexibility in defining requireed and optional *Actions*, *DataPoints* and *Events*´. The alternative is to define similar *ModuleClasses* that offers the variants of required and optional elements.
DECT ULE, for example, has optional actions.
### Proposal
Add an attribute to *Actions* to mark them as optional in a ModuleClass. Perhaps *DataPoints* and *Events* as well.
<Action name=”abc” optional=”true”>
The default without the optional attribute would be ``optional="false"``, meaning required).
# Examples and Contributions
## HGI
### Multi Socket Electrical-Extension-Block
![Multi Socket Electrical-Extension-Block Structure](images/examples/hgi_mseeb.png)
## Echonet
## EnOcean
\ No newline at end of file
# Frequently Asked Questions
## What is the HGI?
## What is the SDT?
# Links & References
- **HGI** : [](
## XML
- **RELAX NG** : [](
- **RELAX NG Tutorial** : [](
## Tools
- **UMLet** : [](
The free UML drawing tool used to draw the UML file.
- **Apache Ant** : [](
Build tool
# Build System Libraries and Licenses
The following libraries are used in the build system for the SDT.
## trang.jar
Trang takes as input a schema written in any of the following formats:
- RELAX NG (XML syntax)
- RELAX NG (compact syntax)
- XML 1.0 DTD
and produces as output a schema written in any of the following formats:
- RELAX NG (XML syntax)
- RELAX NG (compact syntax)
- XML 1.0 DTD
- W3C XML Schema
Trang can also infer a schema from one or more example XML documents.
### License
Copyright (c) 2002, 2003, 2008 Thai Open Source Software Center Ltd
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the Thai Open Source Software Center Ltd nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
## Ant-Contrib Tasks
The Ant-Contrib project is a collection of tasks (and at one point maybe types and other tools) for Apache Ant.
### License
This Software is distributed under the Apache Software License.
## antSetLogLevel.jar
GUI dialog for Ant tasks.
Source: Deutsche Telekom
# SDT Build System
This document describes the SDT build system and how to build the SDT and validate new contributions.
The files referenced in this document point to version **3.0** of the SDT.
## Directory Structure and Important Files
- [SDT/schema3.0/](../..) : Base directory
- [SDT/schema3.0/src/](../src/) : Source files of the SDT.
- [domain.rng](../src/domain.rng) : RELAX NG file with the SDT schema definition. This is the source file that is converted to the actual schema definition *domain.xsd* during the build. See also [](
**Only edit this file when one wants to make changes to the SDT!**
- [domain.xsd](../src/domain.xsd) : The SDT schema defintion that is generated from *domain.rng*.
- [xml.xsd](../src/xml.xsd) : General schema definitions for the SDT
- [SDT/schema3.0/test/](../test/) : This directory contains all XML files with SDT definitions that should be validated whether they conform to the SDT schema. This could be example definitions or contributions.
- [SDT/schema3.0/build.xml](../build.xml) : This is the definition file for the ant build system.
- [SDT/schema3.0/etc/](../etc/), [SDT/schema3.0/style/](../style/) : internal directories for the build system. Please, don't make unnecessary changes to these files.
- [SDT/schema3.0/etc/](../etc), [SDT/schema3.0/style/](../style/) : internal directories for the build system. Please, don't make unnecessary changes to these files.
- [SDT/schema3.0/etc/dal.rnc](../etc/dal.rnc) : This file contains various configuration parameter to convert the file [domain.rng](../src/domain.rng) to schema file. **The important parameter to change when changing the namespace or the version number is**:
default namespace xsl = ""
- [SDT/schema3.0/etc/schemas.xml](../etc/schemas.xml) : This file contains the header for the schema file. **This must be changed when changing the namespace or the version number.**
- [SDT/schema3.0/lib/](../lib/) : Tasks for the ant-based build system. See also [SDT Build System Components and Licenses](
## Installation
- Install Java on your computer
- Download and install Apache ant from [](
- Clone the SDT repository from GitHub:
$ git clone
## How to Use the Build System
After cloning the repository go to the directoy *SDT/schema* and run commands depending on what you want to achieve.
### Build the Schema
Running *ant* without any parameter builds the schema definition from the rng-definition [SDT/schema3.0/src/domain.rng](../src/domain.rng) and writes it to [SDT/schema3.0/src/domain.xsd](../src/domain.xsd)
$ cd SDT/schema
$ ant
### Validate SDT Definitions
You can use the build system to validate new SDT definitions or changes made to existing ones by running the following command:
$ cd SDT/schema
$ ant validate
The output after a successful validation should look like this:
>[schemavalidate] 2 file(s) have been successfully validated.
>Total time: 1 second
Otherwise you most likely receive a stacktrace or some other error messages. Search the output for the line *BUILD FAILED*. Above this line you will find some helpful hints for the filename and line number on which the error occured (here: file *mseeb.xml* on line 66) and a reason:
>[schemavalidate] /Users/someone/Sources/git/RWD050/SDT/schema/test/mseeb.xml:66:18: cvc-elt.1: Cannot find the declaration of element 'Domain'.
## Editing
As mentioned above, the actual schema definition is defined in the file [domain.rng](../src/domain.rng) and converted to the XML schema definition [domain.xsd](../src/domain.xsd) during the build process.
**All changes to the schema must therefore be made in [domain.rng](../src/domain.rng), NOT [domain.xsd](../src/domain.xsd) !**
You may need to make additional changes in the following files, e.g. when the name space or the version number need to be adjusted.
- [SDT/schema3.0/build.xml](../build.xml)
e.g. in the *ant* target "validate"
- [SDT/schema3.0/etc/dal.rnc](../etc/dal.rnc)
e.g. the entry "default namespace xsl"
- [SDT/schema3.0/etc/schema.xmlns](../etc/schema.xmlns)
- [SDT/schema3.0/etc/schemas.xml](../etc/schemas.xml)
# SDT Components
In this document an overview about the SDT 3.0 definitions and component hierarchy is given.
## Contents
[RootDevice](#RootDevice) | [Device](#Device)
&nbsp;&nbsp;&nbsp;[Data / DataPoint](#Data)
## SDT Overview
The followng UML diagram presents an overview about the SDT components.
The syntax used in the diagram to model an XML Schema Definition (XSD) as an UML diagram follows the following approaches:
- [Design XML schemas using UML](
- [UML For W3C XML Schema Design](
## Components
<a name="Domain"></a>
### Domain
The *Domain* is the top-level component that defines all modules and devices of a domain. A *Domain* can import definitions of other domains.
A *Domain* can define [Modules](#ModuleClass) or [RootDevices](#RootDevice) only, or may choose to provide both.
#### Attributes
- **id** : The identifier for that *Domain*. Required.
#### Elements
- **Imports** : XML import/include of other XML files. Optional.
- **Modules** : A list of [Module](#ModuleClass) components that are global to the whole domain. Optional.
- **RootDevices** : a List of [RootDevices](#RootDevice) components. Optional.
#### Example
<Domain xmlns:xi=""
<xi:include href="./dal-core.xml" parse="xml" />
<!-- List of Domain global Modules goes here -->
<!-- List of RootDevices goes here -->
<a name="RootDevice"/></a>
### RootDevice
A *RootDevice* is the definition of a physical device that may contain optional embedded sub-devices. It represents the idea an appliance that is addressable on a Home Area Network where one or more sub-[Devices](#Devices) provide certain functionalities.
For each physical device on the network at least one *RootDevice* **must** be defined. If the physical device is a simple device, ie. it does not contain embedded devices, e.g. a light switch, it does not include further *Devices*. On the other hand, if the pyhsical is a compound device, ie. it does contain embedded devices that can be addressed separately, the *RootDevice* **should** contain *Devices* for each of the identifiable embedded devices.
There is also the possibility to have more than one *RootDevice* for one physical device if a physical device offers more than one distinguishable services or when it is for other reasons meaningful to deliberatly separate the device's services.
An example for a compound device is a connected power-strip where each of the sockets can be switched on and off individually. The power-strip itself can provide functions such as "all sockets off" and "overall power consumption".
If the *RootDevice* includes sub-[Devices](#Device) then each sub-device may be of the same type or of different types. The functionality ([Actions](#Action)) of the *RootDevice* may be different from the functionality of its sub-[Devices](#Device).
If the *RootDevice* does not include sub-devices then the *RootDevice* is the actual adressable device that provides all the functionality of the connected appliance.
*RootDevices* may define their own [ModuleClasses](#ModuleClass) or refer to predefined ModulesClasses of the same or another *Domain*.
#### Attributes
- **id** : The identifier for that *RootDevice*. The identifier must be unique at least in the scope of the domain, but the final scope is also influenced by implementing technologies. Required.
#### Elements
- **[Doc](#Documentation)** : Documentation for the *RootDevice*. Optional.
- **Modules** : A list of [Module](#ModuleClass) components that are local to the *RootDevice*. Optional.
- **[DeviceInfo](#DeviceInfo)** : Further meta-data about the *RootDevice*. Optional.
- **Devices** : A list of [Device](#Device) components. Optional.
#### Example
<RootDevice id="aRootDevice">
<Doc>Some documentation</Doc>
<!-- List of Modules local to the RootDevice goes here-->
<!-- The DeviceInfos for the RootDevice goes here-->
<!-- List of Sub-Devices of the RootDevice goes here-->
### Device
*Devices* are optional components of a [RootDevice](#RootDevice). They represent physical sub-devices inside another device (the RootDevice).
*Devices* may define their own [ModuleClasses](#ModuleClass) or extend ModulesClasses of its or another [Domain](#Domain).
#### Attributes
- **id** : The identifier for that *Device*. The identifier must be unique at least in the scope of the domain, but the final scope is also influenced by implementing technologies. Required.
#### Elements
- **[Doc](#Documentation)** : Documentation for the *Device*. Optional.
- **Modules** : A list of [Module](#ModuleClass) components that are local to the *Device*. Optional.
- **[DeviceInfo](#DeviceInfo)** : Further meta-data about the *Device*. Optional.
#### Example
<Device id="aDevice">
<Doc>Some documentation</Doc>
<!-- List of Modules local to the Device goes here-->
<!-- The DeviceInfo for the Device goes here-->
<a name="DeviceInfo"/></a>
### DeviceInfo
The *DeviceInfo* is an element of [RootDevice](#RootDevice) or [Device](#Device) where a device vendor can provide metadata for a device that may be presented to an end-user.
#### Attributes
#### Elements
- **Name** : Vendor-specific name of a device. Required.
- **Vendor** : Name of the vendor for the device. Required.
- **FirmwareVersion** : Current version number of the firmware or other version information. Optional.
- **VendorURL** : A URL that points to further information for that device. This might be the product page on the web or an URL to the device manual. Optional.
- **SerialNumber** : The serial number or serial string. Optional.
- **[Doc](#Documentation)** : Documentation for the *DeviceInfo*. Optional.
#### Example
<a name="ModuleClass"/></a>
### Module, ModuleClass
The *ModuleClass* represents the concept of a reusable module that defines the [Actions](#Action), [Data](#Data) and [Events](#Event) for a single functionality of a device. A connected device may contain or refer to single or multiple *ModuleClasses* to specify its inherent services it exposes for use by applications.
*Modules* represent instantiations of *ModuleClasses*.
*ModuleClasses* can be defined by a domain (on the level of the [Domain](#Domain) component) or in [RootDevices](#RootDevice)/[Devices](#Device): The first are global to a [Domain](#Domain) and can be used (refered to) by all [RootDevices](#RootDevice) resp. [Devices](#Device) of a [Domain](#Domain); the later are local to the [RootDevices](#RootDevice)/[Devices](#Device) where it is defined in. *ModuleClasses* defined on the [Domain](#Domain) level can be imported, extended and used by other domains.
New *ModuleClasses* can be defined by extending existing *ModuleClasses* from the same or other domains to add new or overriding defined [Actions](#Action), [Data](#Data) and [Events](#Event).
#### Attributes
- **Name** : Name of the *ModuleClass*. The name must be unique in the scope of the [Domain](#Domain). Required.
#### Elements
- **extends** : Reference to a another *ModuleClass* that is extended with this *ModuleClass*. Optional.
The element has the following attributes:
- **domain** : Identifier / Reference of the [Domain](#Domain) of the extended *ModuleClass*. Required when *extends* is specified.
- **class** : Name of the *ModuleClass* in the [Domain](#Domain) thet is extended.
- **[Doc](#Documentation)** : Documentation for the *ModuleClass*. Optional.
- **Actions** : A list of [Action](#Action) components, each defining a single action. Optional.
- **Data** : A list of [Data](#Data) components. Optional.
- **Events** : A list of [Event](#Event) components. Optional.
#### Example
<ModuleClass name="BooleanState">
<Doc>Some documentation</Doc>
<!-- List of Actions goes here-->
<!-- List of Events goes here-->
<!-- List of DataPoints goes here-->
<a name="Action"/></a>
### Action
An *Action* defines a single procedure call for a [ModuleClass](#ModuleClass). It is basically used for calling a function on a physical device in order to set or request data, or to invoke an action at a [Device](#Device). #
It is also possible that an *Action* results in calling multiple functions on the device. Examples for this are the assembly of single function calls into one *Action* in order to provide sanity checks on the arguments, or for managing and fullfil transactional function calls on the device.
#### Attributes
- **name** : The name of the *Action*. The name must be unique in the scope of the [ModuleClass](#ModuleClass). Required.
- **type** : The return type of the *Action*. It must comply to one of the defined [DataTypes](#DataType). Optional. If no *type* is specified the *Action* does not return a value.
#### Elements
- **[Doc](#Documentation)** : Documentation for the *Action*. Optional.
- **Arg** : Zero or more occurances of argument definitions for an *Action*. Optional.
The *Arg* has the following attributes and elements:
- **name** : The name of the *Arg*. Attribute. Required.
- **type** : The type of the *Arg*. It must comply to one of the defined [DataTypes](#DataType) Attribute. Required.
- **Doc** : Documentation for the *Arg* element. Optional.
#### Example
The following are two examples for actions implementing a getter and a setter for boolean values.
<Action name="get" type="boolean">
<Doc>Obtain the current associated state. Example of a getter.</Doc>