SDT_Components.md 16.7 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 [Domain](#Domain) 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
#### Example

	<Domain xmlns:xi="http://www.w3.org/2001/XInclude"
50 51
    	xmlns="http://homegatewayinitiative.org/xml/dal/2.0" 
    	id="org.homegatewayinitiative">
52 53 54 55
    	<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 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.
69

70 71 72 73 74
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".
75

76
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).
77 78 79

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.

80
*RootDevices* may define their own [ModuleClasses](#ModuleClass) or refer to predefined ModulesClasses of its or another *Domain*.
81 82 83 84

![](images/RootDevice.png)

#### Attributes
85
- **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.
86 87 88 89

#### Elements

- **Doc** : Documentation for the *RootDevice*. Optional.
90 91
- **Modules** : A list of [Module](#ModuleClass) components that are local to the *RootDevice*. Optional.
- **[DeviceInfo](#DeviceInfo)** : Further meta-data about the *RootDevice*. Optional.
92
- **Devices** : A list of [Device](#Device) components. Optional.
93 94 95 96 97 98

#### Example

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

---
110 111

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

114
*Devices* may define their own [ModuleClasses](#ModuleClass) or extend ModulesClasses of its or another [Domain](#Domain).
115 116 117 118

![](images/Device.png)

#### Attributes
119
- **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.
120 121 122

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

#### Example

	<Device id="aDevice">
		<Doc>Some documentation</Doc>
		<Modules>
131
			<!-- List of Modules local to the Device goes here-->
132 133 134 135 136 137 138
		</Modules>
		<DeviceInfo>
			<!-- The DeviceInfo for the Device goes here-->
		</DeviceInfo>
	</RootDevice>

---
139

140 141
<a name="DeviceInfo"/></a>
### DeviceInfo
142
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.
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167

![](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.

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

---

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

172
*Modules* represent instantiations of *ModuleClasses*.
173

174 175 176
*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) 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).
177 178 179 180

![](images/ModuleClass.png)

#### Attributes
181
- **Name** : Name of the *ModuleClass*. The name must be unique in the scope of the [Domain](#Domain). Required.
182 183 184 185

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

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

208 209
---

210
<a name="Action"/></a>
211
### Action
212
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).
213 214 215 216

![](images/Action.png)

#### Attributes
217
- **name** : The name of the *Action*. The name must be unique in the scope of the [ModuleClass](#ModuleClass). Required.
218
- **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.
219 220 221 222 223 224 225

#### Elements
- **Doc** : 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*. Attribute. Required.
226
	- **Doc** : Documentation for the *Arg* element. Optional.
227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242

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

---
243

Andreas Kraft's avatar
Andreas Kraft committed
244
<a name="Data"/></a>
245
### Data
246
The *Data* component represents a list of *DataPoints* of a [ModuleClass](#ModuleClass). 
247 248 249

![](images/Data.png)

250 251
*DataPoints* serve to provide information to application developers about the internal structure, types and attributes of a device's data model. There are no implicite setter or getter actions to manipulate the data points directly. To do this, [Actions](#Action) must be defined and used explicitly.

252
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. 
Andreas Kraft's avatar
Andreas Kraft committed
253

254
In EBNF:
Andreas Kraft's avatar
Andreas Kraft committed
255

256 257 258 259 260
	name          = dataPointName | "/" path ;  
	path          = segment "/" path | dataPointName ;  
	segment       = string ;  
	dataPointName = string ;  
	string        = (* character string excluding the character "/" *) ;
Andreas Kraft's avatar
Andreas Kraft committed
261 262


263 264 265 266
#### Attributes
None.

#### Elements
Andreas Kraft's avatar
Andreas Kraft committed
267 268
- **DataPoint** : Zero or more occurances of *DataPoints. Optional.  
A *DataPoint* has the following attributes and elements:
269
	- **name** : The name (and possible path in a hierarchical data model) of the *DataPoint*. Attribute. The name must be unique in the scope of the [ModuleClass](#ModuleClass).Required.
Andreas Kraft's avatar
Andreas Kraft committed
270 271 272 273
	- **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.
274
	- **Doc** : Documentation for the *DataPoint* element. Optional.
Andreas Kraft's avatar
Andreas Kraft committed
275

276 277 278

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

---


<a name="DataType"/></a>
### DataType
289
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
290 291 292 293 294 295 296 297 298 299 300 301

- **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) .
- **integer** : An integer value as defined by [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 by [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 by [http://www.w3.org/TR/xmlschema-2/#string](http://www.w3.org/TR/xmlschema-2/#string) .
- **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.
- **date** : A date value as defined by [http://www.w3.org/TR/xmlschema-2/#date](http://www.w3.org/TR/xmlschema-2/#date) .
- **time** : A time value as defined by [http://www.w3.org/TR/xmlschema-2/#time](http://www.w3.org/TR/xmlschema-2/#time) .
- **datetime** : A time value as defined by [http://www.w3.org/TR/xmlschema-2/#dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) .
- **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) .
- **uri** : A URI that represents a Uniform Resource Identifier Reference (URI) as defined by as defined by [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) and amended by [RFC 2732](http://www.ietf.org/rfc/rfc2732.txt) .
302 303 304

---

Andreas Kraft's avatar
Andreas Kraft committed
305
<a name="Event"/></a>
306
### Event
307
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.
308

Andreas Kraft's avatar
Andreas Kraft committed
309
![](images/Event.png)
310 311

#### Attributes
312
- **name** : The name of the *Event*. The name must be unique in the scope of the [ModuleClass](#ModuleClass). Required.
Andreas Kraft's avatar
Andreas Kraft committed
313

314
#### Elements
315 316
- **Data** : A list of [Data](#Data) components for an event's payload. Optional.
- **Doc** : Documentation for the *Event* Element. Optional.
317 318


319
#### Example
320

321 322 323 324 325 326
	<Event name="stateChanged">
		<Data>
			<DataPoint name="state" type="boolean">
			</DataPoint>
		</Data>
	</Event>
327

328
---
Andreas Kraft's avatar
Andreas Kraft committed
329

330 331
<a name="Documentation"/></a>
# Documentation
332
The *Doc* documentation element is optionally available in most components of the SDT. Its purpose is to provide a short documentation for the respective element. The documentation language *should* be English.
Andreas Kraft's avatar
Andreas Kraft committed
333

334
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
335 336


337 338 339 340 341 342 343 344 345 346
	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
347

348

349
The intended use for each element is:
350

351 352 353 354 355
- **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.
356