Commit b212539a authored by ankraft's avatar ankraft

Added and updated more documentation to 3.0

parent 0533e668
......@@ -2,27 +2,47 @@
Repository for the Smart Device Template (SDT).
**Version 3.0**
Note that this project runs under Apache 2.0 license. Read the [LICENSE](LICENSE) in this repository, or refer to [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
Any contributions made to this project must comply with the forementioned license.
Any contributions made to this project must comply with the aforementioned license.
## Quick Links
- ['domain.xsd' Version 2.0](SDT/schema2.0/src/domain.xsd)
- [UML Diagram of the SDT 2.0](SDT/schema2.0/docs/images/SDT2.0_UML.png) ([source](SDT/schema2.0/docs/SDT_UML.uxf))
- ['domain.xsd' Version 3.0](SDT/schema3.0/src/domain.xsd)
- [UML Diagram of the SDT 3.0](SDT/schema3.0/docs/UML%20Diagram.md) ([source](SDT/schema3.0/docs/SDT_UML.uxf))
## Content
You can find further Information here:
- [SDT Components](SDT/schema2.0/docs/SDT_Components.md)
- [SDT Build System](SDT/schema2.0/docs/SDT%20Build%20System.md)
- [Examples](SDT/schema2.0/docs/Examples.md)
- [FAQ](SDT/schema2.0/docs/FAQ.md)
- [Links & References](SDT/schema2.0/docs/Links.md)
- [Backlog & Issues](SDT/schema2.0/docs/Backlog.md)
- [SDT Components](SDT/schema3.0/docs/SDT_Components.md)
- [SDT Build System](SDT/schema3.0/docs/SDT%20Build%20System.md)
- [Examples](SDT/schema3.0/docs/Examples.md)
- [FAQ](SDT/schema3.0/docs/FAQ.md)
- [Links & References](SDT/schema3.0/docs/Links.md)
- [LICENSE](LICENSE)
## Changes in 3.0
- Renamed ``<RootDevice>``to ``<Device>`` and ``<Device>`` to ``<SubDevice>``,
- Added complex data types: *Struct* and *Arrays*.
- Simplified the UML diagram. Split the UML diagram into two parts, one for the base elements and one for the data types.
- In the UML diagram: Moved ``<extends>`` into the UML ``<ModuleClass>`` element (easier to read).
- Added support to specify *Units of Measurement* to data types,
- Added ``<Doc>`` to ``<Domain>`` and other elements.
- ``<Doc>`` is now always the first part of an element.
- Changed ``<DeviceInfo>`` element to a list of ``<Characteristic>``.
- Added ``<Characteristic>`` list to ``<Modules>`` and ``<ModuleClasses>``.
- The ``<data>`` element in ``<Event>`` is now optional to support events without attached or associated data.
- In Actions: Added ``<Args>`` as a surrounding list around a list of ``<Arg>``.
- Added *Constraints* to ``<DataType>``.
- Added optional *name* attribute to ``<DataType>``. This mandatory for elements of a *struct*.
- Restructured the [RNG](SDT/schema3.0/src/domain.rng) file for better readability and maintainability.
- In the [RNG](SDT/schema3.0/src/domain.rng)/[XSD](SDT/schema3.0/src/domain.xsd): Changed cardinality of the occurrence of elements that are part of a list of elements (e.g. ``<SubDevices><SubDevice>…</SubDevice></SubDevices>`` from „zero or more“ to „one or more“ when the surrounding list element itself is optional (to avoid empty lists).
## Changes in 2.0.1
- Added missing "uri" data type.
......@@ -30,7 +50,7 @@ You can find further Information here:
- Introduced RootDevice to support hierarchical embedded devices.
- Added new data types (byte, float, array, enum, date, time, datetime, blob, uri)
- Added ``readable`` and ``eventable`` to data points.
- Added otional ``<SerialNumber>``, ``<VendorURL>`` and ``<FirmwareVersion>`` elements to DeviceInfo
- Added optional ``<SerialNumber>``, ``<VendorURL>`` and ``<FirmwareVersion>`` elements to DeviceInfo
- Added optional ``<Doc>`` element to Event
- Changed the optionality of the ``<DataPoint>``'s ``type`` attribute to "required".
- Added [UML diagram](SDT/schema2.0/docs/SDT_Components.md)
......
# Backlog
To Be Discussed
[Versions](#Versions)
[Namespace](#Namespace)
[Roles](#Roles)
[Optionals](#Optionals)
<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."http://hgi.org/xml/dal/3.0") 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 "homegatewayinitiative.org" 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 "homegateway.org" 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.
Example:
<RootDevice name id=”xyz” role=”something”>
...
</RootDevice>
---
<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.
Example:
...
<Action name=”abc” optional=”true”>
...
</Action>
The default without the optional attribute would be ``optional="false"``, meaning required).
......@@ -5,7 +5,7 @@ The following libraries are used in the build system for the SDT.
[http://www.thaiopensource.com/relaxng/trang-manual.html](http://www.thaiopensource.com/relaxng/trang-manual.html)
Trang takes as input a schema written in any of the following formats:
*Trang* takes as input a schema written in any of the following formats:
- RELAX NG (XML syntax)
- RELAX NG (compact syntax)
......@@ -18,7 +18,7 @@ and produces as output a schema written in any of the following formats:
- XML 1.0 DTD
- W3C XML Schema
Trang can also infer a schema from one or more example XML documents.
*Trang* can also infer a schema from one or more example XML documents.
### License
......@@ -49,7 +49,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[http://ant-contrib.sourceforge.net](http://ant-contrib.sourceforge.net)
The Ant-Contrib project is a collection of tasks (and at one point maybe types and other tools) for Apache Ant.
The *Ant-Contrib* project is a collection of tasks (and at one point maybe types and other tools) for Apache Ant.
### License
......
......@@ -8,7 +8,7 @@ The files referenced in this document point to version **3.0** of the SDT.
- [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 [http://en.wikipedia.org/wiki/RELAX_NG](http://en.wikipedia.org/wiki/RELAX_NG).
**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*.
- [domain.xsd](../src/domain.xsd) : The SDT schema definition 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.
......@@ -26,10 +26,10 @@ The files referenced in this document point to version **3.0** of the SDT.
- Download and install Apache ant from [http://ant.apache.org](http://ant.apache.org)
- Clone the SDT repository from GitHub:
$ git clone https://github.com/Homegateway/RWD050.git
$ git clone https://github.com/Homegateway/SmartDeviceTemplate.git
## 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.
After cloning the repository go to the directory *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)
......@@ -49,9 +49,9 @@ The output after a successful validation should look like this:
>BUILD SUCCESSFUL
>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:
Otherwise you most likely receive a stack trace 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 occurred (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'.
>[schemavalidate] /Users/someone/Sources/git/SmartDeviceTemplate/SDT/schema/test/mseeb.xml:66:18: cvc-elt.1: Cannot find the declaration of element 'Domain'.
>BUILD FAILED
---
......
This diff is collapsed.
# UML Diagram of the SDT 3.0
The source for the diagrams below is [here](SDT_UML.uxf).
## Basic Elements
![](images/SDT_UML_Basic_Elements.png)
## Data Types
![](images/SDT_UML_DataType.png)
## Key
![](images/SDT_UML_Key.png)
##
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment