Commit 6015535a authored by Andreas Kraft's avatar Andreas Kraft
Browse files

Finished detailed documentation

parent 7d7130a2
...@@ -9,9 +9,10 @@ In this document an overview about the SDT 2.0 definitions and component hierarc ...@@ -9,9 +9,10 @@ In this document an overview about the SDT 2.0 definitions and component hierarc
   [DeviceInfo](#DeviceInfo)    [DeviceInfo](#DeviceInfo)
[ModuleClass](#ModuleClass) [ModuleClass](#ModuleClass)
   [Action](#Action)    [Action](#Action)
   [Data](#Data)    [Data / DataPoint](#Data)
      [DataType](#DataType)       [DataType](#DataType)
   [Event](#Event)    [Event](#Event)
[Doc](#Documentation)
## SDT Overview ## SDT Overview
...@@ -31,7 +32,7 @@ The syntax used in the diagram to model an XML Schema Definition (XSD) as an UML ...@@ -31,7 +32,7 @@ The syntax used in the diagram to model an XML Schema Definition (XSD) as an UML
### Domain ### 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. 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 *ModuleClasses* or *RootDevices* only, or may choose to provide both. A *Domain* can define [Domain](#Domain) or [RootDevices](#RootDevice) only, or may choose to provide both.
![](images/Domain.png) ![](images/Domain.png)
...@@ -40,8 +41,8 @@ A *Domain* can define *ModuleClasses* or *RootDevices* only, or may choose to pr ...@@ -40,8 +41,8 @@ A *Domain* can define *ModuleClasses* or *RootDevices* only, or may choose to pr
#### Elements #### Elements
- **Imports** : XML import/include of other XML files. Optional. - **Imports** : XML import/include of other XML files. Optional.
- **Modules** : A list of *Module* components that are global to the whole domain. Optional. - **Modules** : A list of [Module](#ModuleClass) components that are global to the whole domain. Optional.
- **RootDevices** : a List *RootDevice* components. Optional. - **RootDevices** : a List [RootDevices](#RootDevice) components. Optional.
#### Example #### Example
...@@ -64,15 +65,15 @@ A *Domain* can define *ModuleClasses* or *RootDevices* only, or may choose to pr ...@@ -64,15 +65,15 @@ A *Domain* can define *ModuleClasses* or *RootDevices* only, or may choose to pr
<a name="RootDevice"/></a> <a name="RootDevice"/></a>
### RootDevice ### RootDevice
A *RootDevice* is the description 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* provide certain functionalities. A *RootDevice* is the description 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.
An example 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". An example 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* then each sub-device may be of the same type or of different types. The functionality (*Actions*) of the *RootDevice* may be different from the functionality of its sub-*Devices*. 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. 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* or refer to predefined ModulesClasses of its or another *Domain*. *RootDevices* may define their own [ModuleClasses](#ModuleClass) or refer to predefined ModulesClasses of its or another *Domain*.
![](images/RootDevice.png) ![](images/RootDevice.png)
...@@ -82,9 +83,9 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac ...@@ -82,9 +83,9 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
#### Elements #### Elements
- **Doc** : Documentation for the *RootDevice*. Optional. - **Doc** : Documentation for the *RootDevice*. Optional.
- **Modules** : A list of *Module* components that are local to the *RootDevice*. Optional. - **Modules** : A list of [Module](#ModuleClass) components that are local to the *RootDevice*. Optional.
- **DeviceInfo** : Further meta-data about the *RootDevice*. Optional. - **[DeviceInfo](#DeviceInfo)** : Further meta-data about the *RootDevice*. Optional.
- **Devices** : A list *Device* components. Optional. - **Devices** : A list [Device](#Device) components. Optional.
#### Example #### Example
...@@ -104,9 +105,9 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac ...@@ -104,9 +105,9 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
--- ---
### Device ### Device
*Devices* are optional components of a *RootDevice*. They represent physical sub-devices inside another device (the *RootDevice*). *Devices* are optional components of a [RootDevice](#RootDevice). They represent physical sub-devices inside another device (the RootDevice).
*Devices* may define their own *ModuleClasses* or refer to predefined ModulesClasses of its or another *Domain*. *Devices* may define their own [ModuleClasses](#ModuleClass) or refer to predefined ModulesClasses of its or another [Domain](#Domain).
![](images/Device.png) ![](images/Device.png)
...@@ -115,8 +116,8 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac ...@@ -115,8 +116,8 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
#### Elements #### Elements
- **Doc** : Documentation for the *Device*. Optional. - **Doc** : Documentation for the *Device*. Optional.
- **Modules** : A list of *Module* components that are local to the *RootDevice*. Optional. - **Modules** : A list of [Module](#ModuleClass) components that are local to the *Device*. Optional.
- **DeviceInfo** : A list *Device* components. Optional. - **[DeviceInfo](#DeviceInfo)** : Further meta-data about the *Device*. Optional.
#### Example #### Example
...@@ -134,7 +135,7 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac ...@@ -134,7 +135,7 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
<a name="DeviceInfo"/></a> <a name="DeviceInfo"/></a>
### DeviceInfo ### DeviceInfo
The *DeviceInfo* is an element of *RootDevice* or *Device* where a device vendor can provide metadata for a device that may be presented to an end-user. 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.
![](images/DeviceInfo.png) ![](images/DeviceInfo.png)
...@@ -162,11 +163,11 @@ None. ...@@ -162,11 +163,11 @@ None.
<a name="ModuleClass"/></a> <a name="ModuleClass"/></a>
### Module, ModuleClass ### Module, ModuleClass
The *Module* (or *ModuleClass*) represents the concept of a reusable module that defines the *Actions*, *Data* and *Events* 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. The *Module* (or *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.
*ModuleClasses* can be defined by a domain (on the level of the *Domain* component) or in *(Root)Devices*: The former are global to a domain and can be used by all *(Root)Devices* of a *Domain*; the later are local to the *Device*. *ModuleClasses* defined on the *Domain* level can be imported and used by other *Domains*. *ModuleClasses* can be defined by a domain (on the level of the [Domain](#Domain) component) or in [RootDevices](#RootDevice)/[Devices](#Device): The former are global to a [Domain](#Domain) and can be used (refered to) by all [RootDevices](#RootDevice)/[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 and used by other domains.
New *ModuleClasses* can be defined by extending existing *ModuleClasses* to add new or overriding defined *Actions*, *Data* and *Events*. New *ModuleClasses* can be defined by extending existing *ModuleClasses* to add new or overriding defined [Actions](#Action), [Data](#Data) and [Events](#Event).
![](images/ModuleClass.png) ![](images/ModuleClass.png)
...@@ -176,12 +177,12 @@ New *ModuleClasses* can be defined by extending existing *ModuleClasses* to add ...@@ -176,12 +177,12 @@ New *ModuleClasses* can be defined by extending existing *ModuleClasses* to add
#### Elements #### Elements
- **extends** : Reference to a another *ModuleClass* that is extended with this *ModuleClass*. Optional. - **extends** : Reference to a another *ModuleClass* that is extended with this *ModuleClass*. Optional.
The element has the following attributes: The element has the following attributes:
- **domain** : Identifier / Reference of the *Domain* of the extended *ModuleClass*. Required when *extends* is specified. - **domain** : Identifier / Reference of the [Domain](#Domain) of the extended *ModuleClass*. Required when *extends* is specified.
- **class** : Name of the *ModuleClass* in the *Domain* thet is extended. - **class** : Name of the *ModuleClass* in the [Domain](#Domain) thet is extended.
- **Doc** : Documentation for the *ModuleClass*. Optional. - **Doc** : Documentation for the *ModuleClass*. Optional.
- **Actions** : A list of *Action* components, each defining a single action. Optional. - **Actions** : A list of [Action](#Action) components, each defining a single action. Optional.
- **Data** : A list of *Data* components. Optional. - **Data** : A list of [Data](#Data) components. Optional.
- **Events** : A list of *Event* components. Optional. - **Events** : A list of [Event](#Event) components. Optional.
#### Example #### Example
...@@ -202,13 +203,13 @@ The element has the following attributes: ...@@ -202,13 +203,13 @@ The element has the following attributes:
<a name="Action"/></a> <a name="Action"/></a>
### Action ### Action
An *Action* is defines a single procedure call for a *ModuleClass*. It is basically for calling a function on a physical device in order to set or request data, or to invoke an action at a *Device*. An *Action* is defines a single procedure call for a [ModuleClass](#ModuleClass). It is basically for calling a function on a physical device in order to set or request data, or to invoke an action at a [Device](#Device).
![](images/Action.png) ![](images/Action.png)
#### Attributes #### Attributes
- **name** : The name of the *Action*. Required. - **name** : The name of the *Action*. Required.
- **type** : The return type of the *Action*. It must comply to one of the defined *DataTypes*. Optional. If no *type* is specified the *Action* does not return a value. - **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 #### Elements
- **Doc** : Documentation for the *Action*. Optional. - **Doc** : Documentation for the *Action*. Optional.
...@@ -216,7 +217,7 @@ An *Action* is defines a single procedure call for a *ModuleClass*. It is basica ...@@ -216,7 +217,7 @@ An *Action* is defines a single procedure call for a *ModuleClass*. It is basica
The *Arg* has the following attributes and elements: The *Arg* has the following attributes and elements:
- **name** : The name of the *Arg*. Attribute. Required. - **name** : The name of the *Arg*. Attribute. Required.
- **type** : The type of the *Arg*. It must comply to one of the defined *DataTypes*. Attribute. Required. - **type** : The type of the *Arg*. It must comply to one of the defined *DataTypes*. Attribute. Required.
- **Doc** : Documentation for the *Arg*. Element. Optional. - **Doc** : Documentation for the *Arg* element. Optional.
#### Example #### Example
The following are two examples for actions implementing a getter and a setter for boolean values. The following are two examples for actions implementing a getter and a setter for boolean values.
...@@ -240,15 +241,15 @@ The *Data* component represents a list of *DataPoints*. ...@@ -240,15 +241,15 @@ The *Data* component represents a list of *DataPoints*.
![](images/Data.png) ![](images/Data.png)
Though *DataPoints* only refer to single data points of a physical device it is possible to describe hierarchies by model the path to the data point in the hierarchy by a path-like structure like to the pathname of a UNIX file system. Here, the root node of the hierarchy is a slash (/ TODO hex value) and the nodes along the path are also separated by slashes. The actual datapoint is the last leaf at the path. Though *DataPoints* only refer to single data points of a physical device it is possible to describe hierarchies by model the path to the data point in the hierarchy by a path-like structure like to the pathname of a UNIX file system. Here, the root node of the hierarchy is a slash (/ 0x2F) and the segments or nodes along the path are also separated by slashes. The actual datapoint is the last leaf at the path.
In BNF: In EBNF:
name := leaf | '/' path . name = dataPointName | "/" path ;
path : = node '/' path | leaf. path = segment "/" path | dataPointName ;
node := String . segment = string ;
leaf := String . dataPointName = string ;
String := [character string excluding the character '/'] . string = (* character string excluding the character "/" *) ;
#### Attributes #### Attributes
...@@ -262,7 +263,7 @@ A *DataPoint* has the following attributes and elements: ...@@ -262,7 +263,7 @@ A *DataPoint* has the following attributes and elements:
- **writable** : Boolean value that indicates whether this *DataPoint* is writable by an application. Attribute. Optional. Default: false. - **writable** : Boolean value that indicates whether this *DataPoint* is writable by an application. Attribute. Optional. Default: false.
- **readable** : Boolean value that indicates whether this *DataPoint* is readable by an application. Attribute. Optional. Default: false. - **readable** : Boolean value that indicates whether this *DataPoint* is readable by an application. Attribute. Optional. Default: false.
- **eventable** : Boolean value that indicates whether an internal or external change of this *DataPoint* raises an event. Attribute. Optional. Default: false. - **eventable** : Boolean value that indicates whether an internal or external change of this *DataPoint* raises an event. Attribute. Optional. Default: false.
- **Doc** : Documentation for the *DataPoint*. Element. Optional. - **Doc** : Documentation for the *DataPoint* element. Optional.
#### Example #### Example
...@@ -277,7 +278,7 @@ A *DataPoint* has the following attributes and elements: ...@@ -277,7 +278,7 @@ A *DataPoint* has the following attributes and elements:
<a name="DataType"/></a> <a name="DataType"/></a>
### DataType ### DataType
The following *DataTypes* can be used in the SDT's *Actions*, *Args* and *DataTypes* elements and attributes. If not stated otherwise datatypes should comply to the equivalent datatypes defined in [XML Schema Part 2: Datatypes Second Edition](http://www.w3.org/TR/xmlschema-2/#boolean): The following *DataTypes* can be used in the SDT's [Action](#Action), *Arg* and [DataPoint](#Data) elements and attributes. If not stated otherwise datatypes should comply to the equivalent datatypes defined in [XML Schema Part 2: Datatypes Second Edition](http://www.w3.org/TR/xmlschema-2/#boolean):
- **boolean** : A boolean value as defined by [http://www.w3.org/TR/xmlschema-2/#boolean](http://www.w3.org/TR/xmlschema-2/#boolean) . - **boolean** : A boolean value as defined by [http://www.w3.org/TR/xmlschema-2/#boolean](http://www.w3.org/TR/xmlschema-2/#boolean) .
- **byte** : An integer datatype with the range of [0 - 255] as defined by [http://www.w3.org/TR/xmlschema-2/#unsignedByte](http://www.w3.org/TR/xmlschema-2/#unsignedByte) . - **byte** : An integer datatype with the range of [0 - 255] as defined by [http://www.w3.org/TR/xmlschema-2/#unsignedByte](http://www.w3.org/TR/xmlschema-2/#unsignedByte) .
...@@ -295,7 +296,7 @@ The following *DataTypes* can be used in the SDT's *Actions*, *Args* and *DataTy ...@@ -295,7 +296,7 @@ The following *DataTypes* can be used in the SDT's *Actions*, *Args* and *DataTy
<a name="Event"/></a> <a name="Event"/></a>
### Event ### Event
An *Event* is a component that defines properties for events that are raised as reactions to changes in *DataPoints* of a *device's* data model. These state changes can happen either through a device-internal change or by external means, e.g. a user operates a switch or the temperature in a room rises beyond a certain threshold. An *Event* is a component that defines properties for events that are raised as reactions to changes in [DataPoints](#Data) of a [Device](#Device)'s data model. These state changes can happen either through a device-internal change, e.g. a low battery level, or by external means, e.g. a user operates a switch or the temperature in a room rises beyond a certain threshold.
![](images/Event.png) ![](images/Event.png)
...@@ -303,64 +304,45 @@ An *Event* is a component that defines properties for events that are raised as ...@@ -303,64 +304,45 @@ An *Event* is a component that defines properties for events that are raised as
- **name** : The name of the *Event*. Required. - **name** : The name of the *Event*. Required.
#### Elements #### Elements
- **Data** : A list of *Data* components. Optional. - **Data** : A list of [Data](#Data) components for an event's payload. Optional.
- **Doc** : Documentation for the *Event* Element. Optional.
#### Example
TODO continue
#### Example
# DOC TBD <Event name="stateChanged">
Explain. Describe content elements <Data>
<DataPoint name="state" type="boolean">
</DataPoint>
</Data>
</Event>
DocText := [ text | emphasizedText | boldText | monotypeText ] * . ---
<a name="Documentation"/></a>
# Documentation
The *Doc* documentation element is optionally available in most components of the SDT. Its purpose is to provide a short documentation of the respective element.
<define name="DocText"> The text inside the *Doc* element can be structure using a very limited subset of HTML elements. The possible structuring is defined in EBNF as follows:
<zeroOrMore>
<choice>
<text/>
<element name="em">
<text/>
</element>
<element name="b">
<text/>
</element>
<element name="tt">
<text/>
</element>
</choice>
</zeroOrMore>
</define>
<define name="Doc"> Doc = "<Doc>" docContent "</Doc" ;
<optional> docContent = docText | { paragraph | image } ;
<element name="Doc"> docText = { text | emphasizedText | boldText | monotypeText } ;
<choice> emphasizedText = "<em>" text "</em>" ;
<ref name="DocText"/> boldText = "<b>" text "</b>" ;
<zeroOrMore> monotypeText = "<tt>" text "</tt>" ;
<choice> paragraph = "<p>" docText "</p>" ;
<element name="p"> image = "<img src=" url ">" "<caption>" text "</caption>" "</img>" ;
<ref name="DocText"/> url = "\"" (* valid URL *) "\"" ;
</element> text = (* XML text element *) ;
<element name="img">
<attribute name="src"/>
<element name="caption">
<text/>
</element>
</element>
</choice>
</zeroOrMore>
</choice>
</element>
</optional>
</define>
The intended use for each element is:
- **emphasizedText** : Emphasize the included text, e.g. printing it in italics font.
- **boldText** : Print the included text in bold font.
- **monotypeText** : Print the included text in a monospaced fonttype, e.g. to emphasize source code.
- **paragraph** : Structure the text in paragraphs.
- **image** : Include an image in the text. The image is loaded from the specified URL and must include a caption text.
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