SDT_Components.md 15.5 KB
Newer Older
1
# SDT Components
2

Andreas Kraft's avatar
Andreas Kraft committed
3
In this document an overview about the SDT 2.0 definitions and component hierarchy is given.
4

5 6
## Contents

7
[Domain](#Domain)  
8 9 10 11
[RootDevice](#RootDevice) | [Device](#Device)  
   [DeviceInfo](#DeviceInfo)  
[ModuleClass](#ModuleClass)  
   [Action](#Action)  
12
   [Data / DataPoint](#Data)  
13
      [DataType](#DataType)  
14 15
   [Event](#Event)  
[Doc](#Documentation)  
16

17

18 19 20 21 22 23 24 25 26 27
## SDT Overview
The followng UML diagram presents an overview about the SDT components.

![](images/SDT2.0_UML.png)

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](http://www.ibm.com/developerworks/library/x-umlschem/)
- [UML For W3C XML Schema Design](http://www.xml.com/pub/a/2002/08/07/wxs_uml.html)

28

29 30
## Components

31
<a name="Domain"></a>
32
### Domain
33 34
The *Domain* is the top-level component that defines all modules and devices of a domain. A *Domain* can import definitions of other domains.

35
A *Domain* can define [Modules](#ModuleClass) or [RootDevices](#RootDevice) only, or may choose to provide both.
36

37 38
![](images/Domain.png)

39 40 41 42 43
#### Attributes
- **id** : The identifier for that *Domain*. Required.

#### Elements
- **Imports** : XML import/include of other XML files. Optional.
44
- **Modules** : A list of [Module](#ModuleClass) components that are global to the whole domain. Optional.
45
- **RootDevices** : a List of [RootDevices](#RootDevice) components. Optional.
46

47 48 49 50 51 52 53 54 55
#### Example

	<Domain xmlns:xi="http://www.w3.org/2001/XInclude"
    	xmlns="http://hgi.org/xml/dal/2.0" 
    	id="org.hgi">
    	<Imports>
      	  <xi:include href="./dal-core.xml" parse="xml" />
    	</Imports>
    	<Modules>
56
    		<!-- List of Domain global Modules goes here -->
57 58
    	</Modules>
    	<RootDevices>
59
    		<!-- List of RootDevices goes here -->
60 61 62 63 64
		</RootDevices>
	</Domain>


---
65

66
<a name="RootDevice"/></a>
67
### RootDevice
68
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 (possibly independent) functionalities. 
69

70
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 own functions such as "all sockets off" and "overall power consumption".
71

72
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).
73 74 75

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.

76
*RootDevices* may define their own [ModuleClasses](#ModuleClass) or refer to predefined ModulesClasses of the same or another *Domain*.
77 78 79 80 81 82 83 84

![](images/RootDevice.png)

#### Attributes
- **id** : The identifier for that *RootDevice*. Required.

#### Elements

85
- **[Doc](#Documentation)** : Documentation for the *RootDevice*. Optional.
86 87 88
- **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.
89 90 91 92 93 94

#### Example

	<RootDevice id="aRootDevice">
		<Doc>Some documentation</Doc>
		<Modules>
95
			<!-- List of Modules local to the RootDevice goes here-->
96 97 98 99 100
		</Modules>
		<DeviceInfo>
			<!-- The DeviceInfos for the RootDevice goes here-->
		</DeviceInfo>
		<Devices>
101
			<!-- List of Sub-Devices of the RootDevice goes here-->
102 103 104 105
		</Devices>
	</RootDevice>

---
106 107

### Device
108
*Devices* are optional components of a [RootDevice](#RootDevice). They represent physical sub-devices inside another device (the RootDevice).
109

110
*Devices* may define their own [ModuleClasses](#ModuleClass) or refer to predefined ModulesClasses of its or another [Domain](#Domain).
111 112 113 114 115 116 117

![](images/Device.png)

#### Attributes
- **id** : The identifier for that *Device*. Required.

#### Elements
118
- **[Doc](#Documentation)** : Documentation for the *Device*. Optional.
119 120
- **Modules** : A list of [Module](#ModuleClass) components that are local to the *Device*. Optional.
- **[DeviceInfo](#DeviceInfo)** : Further meta-data about the *Device*. Optional.
121 122 123 124 125 126

#### Example

	<Device id="aDevice">
		<Doc>Some documentation</Doc>
		<Modules>
127
			<!-- List of Modules local to the Device goes here-->
128 129 130 131 132 133 134
		</Modules>
		<DeviceInfo>
			<!-- The DeviceInfo for the Device goes here-->
		</DeviceInfo>
	</RootDevice>

---
135

136 137
<a name="DeviceInfo"/></a>
### DeviceInfo
138
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.
139 140 141 142 143 144 145 146 147 148 149 150

![](images/DeviceInfo.png)

#### Attributes
None.

#### 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.
151 152
- **[Doc](#Documentation)** : Documentation for the *DeviceInfo*. Optional.

153 154 155 156 157 158 159 160 161 162 163 164 165

#### Example
	
	<DeviceInfo>
		<Name>SomeDeviceName</Name>
		<Vendor>ACME</Vendor>
		<FirmwareVersion>1.0</FirmwareVersion>
		<VendorURL>http://www.example.com/</VendorURL>
		<SerialNumber>1234.5</SerialNumber>
	</DeviceInfo>

---

166 167
<a name="ModuleClass"/></a>
### Module, ModuleClass
168
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.
169

170
*ModuleClasses* can be defined by a domain (on the level of the [Domain](#Domain) component) or in [RootDevices](#RootDevice)/[Devices](#Device): The former *ModuleClasses* 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 they are defined in. All *ModuleClasses* defined on the [Domain](#Domain) level can be imported and used by other domains.
171

172
New *ModuleClasses* can be defined by extending existing *ModuleClasses* to add new or overriding defined [Actions](#Action), [Data](#Data) and [Events](#Event).
173 174 175 176 177 178 179 180 181

![](images/ModuleClass.png)

#### Attributes
- **Name** : Name of the *ModuleClass*. Required.

#### Elements
- **extends** : Reference to a another *ModuleClass* that is extended with this *ModuleClass*. Optional.  
The element has the following attributes:
182 183
	- **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.
184
- **[Doc](#Documentation)** : Documentation for the *ModuleClass*. Optional.
185 186 187
- **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.
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203

#### Example

	<ModuleClass name="BooleanState">
		<Doc>Some documentation</Doc>
		<Actions>
			<!-- List of Actions goes here-->
		</Actions>
		<Events>
			<!-- List of Events goes here-->
		</Events
		<Data>
			<!-- List of DataPoints goes here-->
		</Data>
	</ModuleClass>

204 205
---

206
<a name="Action"/></a>
207
### Action
208 209 210
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.
211 212 213 214 215

![](images/Action.png)

#### Attributes
- **name** : The name of the *Action*. Required.
216
- **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.
217 218

#### Elements
219
- **[Doc](#Documentation)** : Documentation for the *Action*. Optional.
220 221 222
- **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.
223
	- **type** : The type of the *Arg*. It must comply to one of the defined [DataTypes](#DataType) Attribute. Required.
224
	- **Doc** : Documentation for the *Arg* element. Optional.
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240

#### 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>
	</Action>

	<Action name="setTarget">
		<Doc>Set the associated state to the specified value. Example of a setter.</Doc>
		<Arg name="value" type="boolean">
    		<Doc>The desired value of the associated state.</Doc>
    	</Arg>
	</Action>

---
241

Andreas Kraft's avatar
Andreas Kraft committed
242
<a name="Data"/></a>
243
### Data
Andreas Kraft's avatar
Andreas Kraft committed
244
The *Data* component represents a list of *DataPoints*.
245 246 247

![](images/Data.png)

248
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 data point is the last leaf at the path. 
Andreas Kraft's avatar
Andreas Kraft committed
249

250
In EBNF:
Andreas Kraft's avatar
Andreas Kraft committed
251

252 253 254 255 256
	name          = dataPointName | "/" path ;  
	path          = segment "/" path | dataPointName ;  
	segment       = string ;  
	dataPointName = string ;  
	string        = (* character string excluding the character "/" *) ;
Andreas Kraft's avatar
Andreas Kraft committed
257 258


259 260 261 262
#### Attributes
None.

#### Elements
Andreas Kraft's avatar
Andreas Kraft committed
263 264 265 266 267 268 269
- **DataPoint** : Zero or more occurances of *DataPoints. Optional.  
A *DataPoint* has the following attributes and elements:
	- **name** : The name (and possible path in a hierarchical data model) of the *DataPoint*. Attribute. Required.
	- **type** : The type of the *DataPoint*. It must comply to one of the defined *DataTypes*. Attribute. Required.
	- **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.
270
	- **[Doc](#Documentation)** : Documentation for the *DataPoint* element. Optional.
Andreas Kraft's avatar
Andreas Kraft committed
271

272 273 274

#### Example
	<Data>
Andreas Kraft's avatar
Andreas Kraft committed
275 276 277
		<DataPoint  name="attributeName" type="string" writable="false">
			<Doc>Some documentation for the DataPoint</Doc>
		</DataPoint>
278 279 280 281 282 283 284
	</Data>

---


<a name="DataType"/></a>
### DataType
285
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):
Andreas Kraft's avatar
Andreas Kraft committed
286

287 288 289 290 291
- **boolean** : A boolean value as defined in [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 in [http://www.w3.org/TR/xmlschema-2/#unsignedByte](http://www.w3.org/TR/xmlschema-2/#unsignedByte) .
- **integer** : An integer value as defined in [http://www.w3.org/TR/xmlschema-2/#integer](http://www.w3.org/TR/xmlschema-2/#integer) .
- **float** : An IEEE single-precision 32-bit floating point type as defined in [http://www.w3.org/TR/xmlschema-2/#float](http://www.w3.org/TR/xmlschema-2/#float) .
- **string** : The string datatype represents character strings as defined in [http://www.w3.org/TR/xmlschema-2/#string](http://www.w3.org/TR/xmlschema-2/#string) .
Andreas Kraft's avatar
Andreas Kraft committed
292
- **enum** : A complete and orderd list of items in a collection. Items in an enumeration are separated by commas (, 0x2c) and must be of one of the datatypes defined here. Commas (, 0x2c) and backslashes (\ 0x5c) in enumaration items must be escaped by backslash.
293 294 295
- **date** : A date value as defined in [http://www.w3.org/TR/xmlschema-2/#date](http://www.w3.org/TR/xmlschema-2/#date) .
- **time** : A time value as defined in [http://www.w3.org/TR/xmlschema-2/#time](http://www.w3.org/TR/xmlschema-2/#time) .
- **datetime** : A time value as defined in [http://www.w3.org/TR/xmlschema-2/#dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) .
Andreas Kraft's avatar
Andreas Kraft committed
296
- **blob** : A blob value represents a binary object. The internal encoding is transparent and not defined here. The binary object must be encoded conforming to [http://www.w3.org/TR/xmlschema-2/#base64Binary](http://www.w3.org/TR/xmlschema-2/#base64Binary) .
297
- **uri** : A URI that represents a Uniform Resource Identifier Reference (URI) as defined by as defined in [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) and amended in [RFC 2732](http://www.ietf.org/rfc/rfc2732.txt) .
298 299 300

---

Andreas Kraft's avatar
Andreas Kraft committed
301
<a name="Event"/></a>
302
### Event
303
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.
304

Andreas Kraft's avatar
Andreas Kraft committed
305
![](images/Event.png)
306 307

#### Attributes
Andreas Kraft's avatar
Andreas Kraft committed
308 309
- **name** : The name of the *Event*. Required.

310
#### Elements
311
- **Data** : A list of [Data](#Data) components for an event's payload. Optional.
312
- **[Doc](#Documentation)** : Documentation for the *Event* Element. Optional.
313 314


315
#### Example
316

317 318 319 320 321 322
	<Event name="stateChanged">
		<Data>
			<DataPoint name="state" type="boolean">
			</DataPoint>
		</Data>
	</Event>
323

324
---
Andreas Kraft's avatar
Andreas Kraft committed
325

326 327
<a name="Documentation"/></a>
# Documentation
328
The *Doc* documentation element is optionally available in most components of the SDT. Its purpose is to provide a short explanation of the respective element.
Andreas Kraft's avatar
Andreas Kraft committed
329

330
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:
Andreas Kraft's avatar
Andreas Kraft committed
331 332


333 334 335 336 337 338 339 340 341 342
	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 *) ;
Andreas Kraft's avatar
Andreas Kraft committed
343

344

345
The intended use for each element is:
346

347 348 349 350 351
- **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.
352