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

Finished detailed documentation

parent 7d7130a2
......@@ -9,9 +9,10 @@ In this document an overview about the SDT 2.0 definitions and component hierarc
   [DeviceInfo](#DeviceInfo)
[ModuleClass](#ModuleClass)
   [Action](#Action)
   [Data](#Data)
   [Data / DataPoint](#Data)
      [DataType](#DataType)
   [Event](#Event)
   [Event](#Event)
[Doc](#Documentation)
## SDT Overview
......@@ -31,7 +32,7 @@ The syntax used in the diagram to model an XML Schema Definition (XSD) as an UML
### 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 *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)
......@@ -40,8 +41,8 @@ A *Domain* can define *ModuleClasses* or *RootDevices* only, or may choose to pr
#### Elements
- **Imports** : XML import/include of other XML files. Optional.
- **Modules** : A list of *Module* components that are global to the whole domain. Optional.
- **RootDevices** : a List *RootDevice* components. Optional.
- **Modules** : A list of [Module](#ModuleClass) components that are global to the whole domain. Optional.
- **RootDevices** : a List [RootDevices](#RootDevice) components. Optional.
#### Example
......@@ -64,15 +65,15 @@ A *Domain* can define *ModuleClasses* or *RootDevices* only, or may choose to pr
<a name="RootDevice"/></a>
### 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".
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.
*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)
......@@ -82,9 +83,9 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
#### Elements
- **Doc** : Documentation for the *RootDevice*. Optional.
- **Modules** : A list of *Module* components that are local to the *RootDevice*. Optional.
- **DeviceInfo** : Further meta-data about the *RootDevice*. Optional.
- **Devices** : A list *Device* components. 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 [Device](#Device) components. Optional.
#### Example
......@@ -104,9 +105,9 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
---
### 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)
......@@ -115,8 +116,8 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
#### Elements
- **Doc** : Documentation for the *Device*. Optional.
- **Modules** : A list of *Module* components that are local to the *RootDevice*. Optional.
- **DeviceInfo** : A list *Device* components. 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
......@@ -134,7 +135,7 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
<a name="DeviceInfo"/></a>
### 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)
......@@ -162,11 +163,11 @@ None.
<a name="ModuleClass"/></a>
### 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)
......@@ -176,12 +177,12 @@ New *ModuleClasses* can be defined by extending existing *ModuleClasses* to add
#### 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* of the extended *ModuleClass*. Required when *extends* is specified.
- **class** : Name of the *ModuleClass* in the *Domain* thet is extended.
- **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 for the *ModuleClass*. Optional.
- **Actions** : A list of *Action* components, each defining a single action. Optional.
- **Data** : A list of *Data* components. Optional.
- **Events** : A list of *Event* components. 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
......@@ -202,13 +203,13 @@ The element has the following attributes:
<a name="Action"/></a>
### 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)
#### Attributes
- **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
- **Doc** : Documentation for the *Action*. Optional.
......@@ -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:
- **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.
- **Doc** : Documentation for the *Arg*. Element. Optional.
- **Doc** : Documentation for the *Arg* element. Optional.
#### Example
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*.
![](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 .
path : = node '/' path | leaf.
node := String .
leaf := String .
String := [character string excluding the character '/'] .
name = dataPointName | "/" path ;
path = segment "/" path | dataPointName ;
segment = string ;
dataPointName = string ;
string = (* character string excluding the character "/" *) ;
#### Attributes
......@@ -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.
- **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.
- **Doc** : Documentation for the *DataPoint*. Element. Optional.
- **Doc** : Documentation for the *DataPoint* element. Optional.
#### Example
......@@ -277,7 +278,7 @@ A *DataPoint* has the following attributes and elements:
<a name="DataType"/></a>
### 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) .
- **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
<a name="Event"/></a>
### 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)
......@@ -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.
#### Elements
- **Data** : A list of *Data* components. Optional.
#### Example
TODO continue
- **Data** : A list of [Data](#Data) components for an event's payload. Optional.
- **Doc** : Documentation for the *Event* Element. Optional.
#### Example
# DOC TBD
Explain. Describe content elements
<Event name="stateChanged">
<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">
<zeroOrMore>
<choice>
<text/>
<element name="em">
<text/>
</element>
<element name="b">
<text/>
</element>
<element name="tt">
<text/>
</element>
</choice>
</zeroOrMore>
</define>
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:
<define name="Doc">
<optional>
<element name="Doc">
<choice>
<ref name="DocText"/>
<zeroOrMore>
<choice>
<element name="p">
<ref name="DocText"/>
</element>
<element name="img">
<attribute name="src"/>
<element name="caption">
<text/>
</element>
</element>
</choice>
</zeroOrMore>
</choice>
</element>
</optional>
</define>
Doc = "<Doc>" docContent "</Doc" ;
docContent = docText | { paragraph | image } ;
docText = { text | emphasizedText | boldText | monotypeText } ;
emphasizedText = "<em>" text "</em>" ;
boldText = "<b>" text "</b>" ;
monotypeText = "<tt>" text "</tt>" ;
paragraph = "<p>" docText "</p>" ;
image = "<img src=" url ">" "<caption>" text "</caption>" "</img>" ;
url = "\"" (* valid URL *) "\"" ;
text = (* XML text element *) ;
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