Commit c9402c98 authored by ankraft's avatar ankraft
Browse files

Added more documentation and examples

parent f1208039
# Examples and Contributions
[A simple example](#simpleExample)
[Multi Socket Electrical-Extension-Block](#mseeb)
## HGI
<a name="simpleExample"></a>
## A very simple SDT example
In the ideal case, a large organization or SDO would define a widely-applicable set of [ModuleClasses](SDT_Components.md#ModuleClass), each of which could be used as needed to compose the description of a complex device. In order to show the appoach, this section will create a few example ModuleClasses based on - or inspired by - featues in the Echonet Lite protocol. Please note that the examples shown in this document are very "cut down" and by no means represent a true representation of Echonet Lite.
The Echonet Consortium has standardized their specifications within IEC/ISO (IEC62394, ISO/IEC24767-1, ISO/IEC24767-2, IEC62480, ISO/IEC14543-4-1, ISO/IEC14543-4-2, IEC62457) and they provide a comprehensive collection of various types of home appliances relevant to SmartGrid applications as ECHONET Device objects (see [https://echonet.jp/spec_object_rf_en/](https://echonet.jp/spec_object_rf_en/) ).
For the example in this document, to show re-use of ModuleClass definitions, two complex devices are chosen which have some common features and hence could be expected to both use some of the same ModuleClasses: an air conditioner and a washing machine.
<table>
<tr><th>Funtionality</th><th>Air Conditioner</th><th>Washing Machine</th></tr>
<tr><td>operationStatus</td><td>operates on/off</td><td>operates on/off</td></tr>
<tr><td>measuredCumulativePowerConsumption</td><td>the cumulative power consumption</td><td>the cumulative power consumption</td></tr>
<tr><td>installationLocation</td><td>this sets/reads a string text describing the location (room) of the air-conditioner.</td><td>this sets/reads a string text describing the location (room) of the washing machine.</td></tr>
<tr><td>setTimer</td><td>(not applicable. there is no preset start for an air-conditioner)</td><td>This sets/reads use the on/off timer</td></tr>
</table>
Based on the simplified example above, the two appliances will need the ModuleClasses below:
- *air-conditioner*: operationStatus, measuredCumulativePowerConsumption, installationLocation;
- *washing-machine*: operationStatus, measuredCumulativePowerConsumption, and setTimer.
<ModuleClass name="operationStatus">
<Data>
<DataPoint name="operationStatus" writable="true">
<Doc>This property sets/reads the ON/OFF status.</Doc>
<DataType>
<SimpleType type="boolean"/>
</DataType>
</DataPoint>
</Data>
<Events>
<Event name="operationStatus">
</Event>
</Events>
</ModuleClass>
<ModuleClass name="measuredCumulativePowerConsumption">
<Data>
<DataPoint name="measuredCumulativePowerConsumption" writable="false">
<Doc>This indicates cumulative power consumption of the device in increments of 0.001kWh.</Doc>
<DataType>
<SimpleType type="integer"/>
</DataType>
</DataPoint>
</Data>
</ModuleClass>
<ModuleClass name="installationLocation">
<Data>
<DataPoint name="installationLocation" writable="true">
<Doc>This property indicates the installation location</Doc>
<DataType>
<SimpleType type="string"/>
</DataType>
</DataPoint>
</Data>
<Events>
<Event name="installationLocation"> </Event>
</Events>
</ModuleClass>
<ModuleClass name="onTimerSetting">
<DataPoint name="onTimer" writable="true">
<Doc>Timer value (HH:MM)</Doc>
<DataType>
<SimpleType type="time"/>
</DataType>
</DataPoint>
</ModuleClass>
The structure and the according SDT now looks like this:
<table>
<tr><td colspan="2" width="50%"><b>Example1.SDT</b></td></tr>
<tr><td> </td><td>Namespace information</td></tr>
<tr><td> </td><td>Modules (contains ModuleClasses)</td></tr>
<tr><td> </td><td>operationStatus<ul>
<li>measuredCumulativePowerConsumption</li>
<li>installationLocation</li>
<li>onTimerSetting</li></ul></td></tr>
</table>
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Example1 SDT inspired by some Echonet Lite examples -->
<Domain xmlns="http://homegatewayinitiative.org/xml/dal/3.0"
xmlns:xi="http://www.w3.org/2001/XInclude"
id="example1.SDT">
<Modules>
<!-- Various examples for module classes -->
<ModuleClass name="operationStatus">
<Data>
<DataPoint name="operationStatus" writable="true">
<Doc>This property sets the ON/OFF status.</Doc>
<DataType>
<SimpleType type="boolean"/>
</DataType>
</DataPoint>
</Data>
<Events>
<Event name="operationStatus">
</Event>
</Events>
</ModuleClass>
<ModuleClass name="installationLocation">
<Data>
<DataPoint name="installationLocation" writable="true">
<Doc>This property indicates the installation location</Doc>
<DataType>
<SimpleType type="string"/>
</DataType>
</DataPoint>
</Data>
<Events>
<Event name="installationLocation"> </Event>
</Events>
</ModuleClass>
<ModuleClass name="measuredCumulativePowerConsumption">
<Data>
<DataPoint name="measuredCumulativePowerConsumption" writable="false">
<Doc>This indicates cumulative power consumption of the device in increments of 0.001kWh.</Doc>
<DataType>
<SimpleType type="integer"/>
</DataType>
</DataPoint>
</Data>
</ModuleClass>
<ModuleClass name="onTimerSetting">
<DataPoint name="onTimer" writable="true">
<Doc>Timer value (HH:MM)</Doc>
<DataType>
<SimpleType type="time"/>
</DataType>
</DataPoint>
</ModuleClass>
</Modules>
</Domain>
---
<a name="mseeb"></a>
### Multi Socket Electrical-Extension-Block
[mseeb.xml](../test/mseeb.xml)
This example is a specification for an imaginged device, a connected extension block with multiple power socket where each of the sockets are modeled as a
separate *SubDevice*.
![Multi Socket Electrical-Extension-Block Structure](images/examples/hgi_mseeb.png)
[mseeb.xml](../test/mseeb.xml)
## DECT ULE
## Echonet
---
## EnOcean
\ No newline at end of file
# SDT Components
[Domain](#Domain)
[RootDevice](#RootDevice) | [Device](#Device)
&nbsp;&nbsp;&nbsp;[DeviceInfo](#DeviceInfo)
[Device](#Device) | [SubDevice](#SubDevice)
[Property](#Property)
[ModuleClass](#ModuleClass)
&nbsp;&nbsp;&nbsp;[Action](#Action)
&nbsp;&nbsp;&nbsp;[Data / DataPoint](#Data)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[DataType](#DataType)
&nbsp;&nbsp;&nbsp;[DataPoint](#DataPoint)
&nbsp;&nbsp;&nbsp;[Event](#Event)
[Data Types](#Data_Types)
&nbsp;&nbsp;&nbsp;[DataType](#DataType)
&nbsp;&nbsp;&nbsp;[Constraint](#Constraint)
&nbsp;&nbsp;&nbsp;[SimpleType](#SimpleType)
&nbsp;&nbsp;&nbsp;[StructType](#StructType)
&nbsp;&nbsp;&nbsp;[ArrayType](#ArrayType)
[Doc](#Documentation)
---
......@@ -37,10 +42,6 @@ The followng UML diagram presents an overview about the SDT components.
![](images/SDT_UML_Basic_Elements.png)
The [DataType](#DataType) strukture is shown in the following UML diagram:
![](images/SDT_UML_DataType.png)
The key to the diagram elements of the UML diagrams above and the snippets in the following sections:
![](images/SDT_UML_Key.png)
......@@ -53,176 +54,181 @@ The syntax used in the diagram to model an XML Schema Definition (XSD) as an UML
## Components
**NOTE** The content here is still SDT2 and needs to be updated
<a name="Domain"></a>
### 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 [Modules](#ModuleClass) or [RootDevices](#RootDevice) only, or may choose to provide both.
![](images/Domain.png)
The *Domain* element allows labeling of different SDT templates for different technologies and/or industry segments ("verticals"): for example eHealth and Building Management might prefer quite different detailed structures/templates. This also helps keep information in human-friendly and manageable blocks. It is assumed that there will be multiple "SDT Templates" and some of them may be completely proprietary.
It can also be used to collect all specified [ModuleClasses](#ModuleClasses)
and [Devices](#Devices) in one referencable logical group.
#### Attributes
- **id** : The identifier for that *Domain*. Required.
#### Elements
- **[Doc](#Documentation)** : Documentation for the *Domain*. Optional.
- **Imports** : XML import/include of other XML files. Optional.
- **Modules** : A list of [Module](#ModuleClass) components that are global to the whole domain. Optional.
- **RootDevices** : a List of [RootDevices](#RootDevice) components. Optional.
- **[Module](#ModuleClass)** : A list of *Module* components that are global to the whole domain. Optional.
- **[Devices](#Device)** : a List of *Devices* components. Optional.
#### Example
<Domain xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns="http://homegatewayinitiative.org/xml/dal/3.0"
id="org.homegatewayinitiative">
<Doc>Some documentation</Doc>
<Imports>
<xi:include href="./dal-core.xml" parse="xml" />
<!-- Import other SDTs via XInclude's include mechanism -->
<xi:include href="./dal-core.xml" parse="xml" />
</Imports>
<Modules>
<!-- List of Domain global Modules goes here -->
</Modules>
<RootDevices>
<!-- List of RootDevices goes here -->
</RootDevices>
<Devices>
<!-- List of Devices goes here -->
</Devices>
</Domain>
---
<a name="RootDevice"/></a>
### RootDevice
<a name="Device"/></a>
### Device
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.
![](images/Device.png)
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.
The *Device* was initially thought of as the representation of "the basic things we are trying to model" and can still be considered so. However, after discussion with various SDOs, it was decided to add also "[sub-devices](#SubDevice)". That is, there is one level of hierarchy to allow modeling of e.g. a set of independent energy monitoring plugs in a single addressable power-extension-block. (Other SDOs might consider it more appropriate to use a recursive sub-sub-sub ... device definition). Note that all the different devices which one needs to model within a Domain are composed of one or more [Modules](#ModuleClass).
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.
For each physical device on the network at least one *Device* **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 [SubDevices](#SubDevices). On the other hand, if the physical is a compound device, ie. it does contain embedded devices that can be addressed separately, the *Device* **should** contain [SubDevices](SubDevices) for each of the identifiable embedded devices.
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".
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](#ModuleClass) or refer to predefined ModulesClasses of the same or another *Domain*.
![](images/RootDevice.png)
*Devices* may define their own [ModuleClasses](#ModuleClass) or refer to predefined ModulesClasses of the same or another [Domain](Domain).
#### Attributes
- **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.
- **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.
#### Elements
- **[Doc](#Documentation)** : Documentation for the *RootDevice*. 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 of [Device](#Device) components. Optional.
- **[Doc](#Documentation)** : Documentation for the *Device*. Optional.
- **[Properties](#Property)** : Further meta-data (or properties) about the *Device*. Optional.
- **[Modules](#ModuleClass)** : A list of *Module* components that are local to the *Device*. Optional.
- **[SubDevices](#SubDevice)** : A list of *SubDevice* components. Optional.
#### Example
<RootDevice id="aRootDevice">
<Device id="aDevice">
<Doc>Some documentation</Doc>
<Properties>
<!-- The list of Properties for the Device goes here-->
</Properties>
<Modules>
<!-- List of Modules local to the RootDevice goes here-->
<!-- List of Modules local to the Device goes here-->
</Modules>
<DeviceInfo>
<!-- The DeviceInfos for the RootDevice goes here-->
</DeviceInfo>
<Devices>
<!-- List of Sub-Devices of the RootDevice goes here-->
</Devices>
</RootDevice>
<SubDevices>
<!-- List of Sub-Devices of the Device goes here-->
</SubDevices>
</Device>
---
### Device
*Devices* are optional components of a [RootDevice](#RootDevice). They represent physical sub-devices inside another device (the RootDevice).
<a name="SubDevice"/></a>
### SubDevice
*SubDevices* are optional components of a [Device](#Device). They represent physical sub-devices and services inside another device (the *Device*).
*Devices* may define their own [ModuleClasses](#ModuleClass) or extend ModulesClasses of its or another [Domain](#Domain).
*SubDevices* may define their own [ModuleClasses](#ModuleClass) or extend ModulesClasses of its or another [Domain](#Domain).
![](images/Device.png)
![](images/SubDevice.png)
#### Attributes
- **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.
- **id** : The identifier for that *SubDevice*. The identifier must be unique at least in the scope of the domain, but the final scope is also influenced by implementing technologies. Required.
#### Elements
- **[Doc](#Documentation)** : Documentation for the *Device*. Optional.
- **Modules** : A list of [Module](#ModuleClass) components that are local to the *Device*. Optional.
- **[DeviceInfo](#DeviceInfo)** : Further meta-data about the *Device*. Optional.
- **[Doc](#Documentation)** : Documentation for the *SubDevice*. Optional.
- **[Properties](#Property)** : Further meta-data (or properties) about the *SubDevice*. Optional.
- **[Modules](#ModuleClass)** : A list of *Module* components that are local to the *SubDevice*. Optional.
#### Example
<Device id="aDevice">
<SubDevice id="aSubDevice">
<Doc>Some documentation</Doc>
<Properties>
<!-- The list of Properties for the Device goes here-->
</Properties>
<Modules>
<!-- List of Modules local to the Device goes here-->
</Modules>
<DeviceInfo>
<!-- The DeviceInfo for the Device goes here-->
</DeviceInfo>
</RootDevice>
</SubDevice>
---
<a name="DeviceInfo"/></a>
### DeviceInfo
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.
<a name="Property"/></a>
### Property
![](images/DeviceInfo.png)
![](images/Property.png)
*Property* elements are used to append to [Devices](#Device) and their [ModuleClass](ModuleClass) elements with arbitrary additional information. For [Devices](#Device) it would be very common for a manufacturer to want to add into the XML file which is describing the device such information as "Manufacturing Site", "Date of Manufacture", "Certification Code", "Energy Label Code", "compatible LAN technology", "URL for the device handbook", "physical limits of operation environments", etc.
Some of that information might in some devices be available by reading a specific device [DataPoint](#DataPoint), however even if it cannot be read from the device then at least it can be noted in the device's XML description. Examples for organizations that specifiy these kind of added "Property" information are [eCl@ss](http://www.eclass.eu) and [UNSPSC](http://www.unspsc.org) (United Nations Standard Products and Services Code).
Since the *Properties* are highly varied, depending on industry segment, no attempt is made in the SDT to constrain the options: however it is highly recommended to provide software-developer-friendly information in the [Doc](#Documentation) field of each Property.
#### Attributes
None.
- **name**: Name or identifier of a *Property*.
- **optional**: Boolean that indicates whether a *Property* is optional or mandatory. Optional, the default is *false*.
- **value**: Text representation of value of a *Property*. Optional.
#### 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.
- **[Doc](#Documentation)** : Documentation for the *DeviceInfo*. Optional.
- **[Doc](#Documentation)** : Documentation for the *Property*. Optional.
- **DataType** : The data type of the property. This must be a [SimpleType](#SimpleType).
#### Example
<DeviceInfo>
<Name>SomeDeviceName</Name>
<Vendor>ACME</Vendor>
<FirmwareVersion>1.0</FirmwareVersion>
<VendorURL>http://www.example.com/</VendorURL>
<SerialNumber>1234.5</SerialNumber>
</DeviceInfo>
<Property name="ManufacturedDate" value="2015.10.30 10:06">
<SimpleType type="datetime" />
</Property>
---
<a name="ModuleClass"/></a>
### Module, ModuleClass
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.
*Modules* represent instantiations of *ModuleClasses*.
![](images/ModuleClass.png)
*ModuleClasses* can be defined by a domain (on the level of the [Domain](#Domain) component) or in [RootDevices](#RootDevice)/[Devices](#Device): The first 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.
**Module**
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).
*Module* elements are basically constraints or templates for how to model functionality of real things/appliances/devices within the [Domain](#Domain). There could be an infinite number of possible functionalities, however it is recommended to identify a not-too-large selection of them as generic examples (called *"*ModuleClasses*, see below) and allow for additional proprietary extensions. In a particular [Domain](#Domain) there will be one *Module* for each of the agreed *ModuleClasses* plus additional ones for each extension of a *ModuleClass*.
![](images/ModuleClass.png)
The advantage of identifying a subset of generic *ModuleClasses* is that any suitable high-level software would then be able to "parse" the generic functionality for all compliant appliances, even if the proprietary parts could not be interpreted by the software.
Every [Device](#Device) can then be described by a collection of *Modules* (functionality). In the simplest examples, where there are no extensions needed, each *ModuleClass* has exactly one "child" Module ... in such cases the software developer can consider the two terms to be the same.
The relationship between a *ModuleClass* and a *Module* is very similar to the specification of a class and an instantiated object in an object oriented programming language.
**ModuleClass**
The set of *ModuleClasses* is defined at the [Domain](#Domain) level. Each one describes some functionality (services). In principle there could be an infinite number of *ModuleClasses* (as noted above), for every kind of functionality found in UPnP, ZigBee and all the other automation protocols ... However that would not simplify the job of software developers at all! Therefore, HGI recommends that a finite and convenient number of prototypical *ModuleClasses* are re-used as much as possible (within a Domain at least).
Typical *ModuleClasses* might be equivalent to "power ON/OFF", "Open/Close", "PanUP/DOWN", "ReadTemperature", etc. Those examples make it apparent that various read/write usage of parameters, invoking of actions and waiting for events might be needed in the different *ModuleClasses*, and a guideline for those structures is explained below.
#### Attributes
- **Name** : Name of the *ModuleClass*. The name must be unique in the scope of the [Domain](#Domain). Required.
- **name** : Name of the *Module* or *ModuleClass*. The name must be unique in the scope of the [Domain](#Domain). Required.
- **optional**: Boolean that indicates whether a *Module* or *ModuleClass* is optional or mandatory. Optional, the default is *false*.
#### Elements
- **extends** : Reference to a another *ModuleClass* that is extended with this *ModuleClass*. Optional.
- **[Doc](#Documentation)** : Documentation for the *Module* or *ModuleClass*. Optional.
- **extends** : Reference to a another *ModuleClass* or *Module* which is extended with this *ModuleClass*. Optional.
The element has the following attributes:
- **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)** : Documentation for the *ModuleClass*. 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.
- **domain** : Identifier / Reference of the [Domain](#Domain) of the extended *ModuleClass*. Required for this element.
- **class** : Name of the *ModuleClass* in the [Domain](#Domain) that is extended. Required for this element.
- **[Properties](#Property)** : Further meta-data (or properties) about the *SubDevice*. Optional.
- **[Actions](#Action)** : A list of *Action* components, each defining a single action. Optional.
- **[Data](#DataPoint)** : A list of *DataPoint* components. Optional.
- **[Events](#Event)** : A list of *Event* components. Optional.
#### Example
......@@ -243,23 +249,21 @@ The element has the following attributes:
<a name="Action"/></a>
### Action
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.
![](images/Action.png)
*Action* elements are an efficient way of describing arbitrary sequences of operations/methods; these are very common in automation. Typical example include "FactoryReset", and "AutoCalibrate". *Actions* preserve transaction integrity by putting together all the parameters ("args", see next section) with the method which checks and executes them, in one step.
Note that systems which rely on RESTful operations need to carry out such complex setup-parameters-then-do-action by first using (several) [DataPoint](#DataPoint) operations to "load" the parameters to the device and then do a [DataPoint](#DataPoint) operation to manipulate the "start operation NOW" action.
#### Attributes
- **name** : The name of the *Action*. The name must be unique in the scope of the [ModuleClass](#ModuleClass). Required.
- **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.
- **optional**: Boolean that indicates whether an *Action* is optional or mandatory. Optional, the default is *false*.
#### Elements
- **[Doc](#Documentation)** : 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](#DataType) Attribute. Required.
- **Doc** : Documentation for the *Arg* element. Optional.
- **[DataType](#DataType)** : The return type of the *Action*. It must comply to the *DataType* definition. Optional. If no *DataType* is specified the *Action* does not return a value.
- **Args** : Zero or more occurances of [argument](#Arg) definitions for an *Action*. Optional.
#### Example
The following are two examples for actions implementing a getter and a setter for boolean values.
......@@ -270,21 +274,43 @@ The following are two examples for actions implementing a getter and a setter fo
<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>
<Args>
<Arg name="value">
<Doc>The desired value of the associated state.</Doc>
<DataType>
<SimpleType type="boolean" />
</DataType>
</Arg>
</Args>
</Action>
---
<a name="Arg"/></a>
### Arg
![](images/Arg.png)
The *Arg* element represents the parameter information which a device needs to carry out a required *Action*.
The *Arg* has the following attributes and elements:
#### Attributes
- **name** : The name of the *Arg* attribute. Required.
#### Elements
- **[Doc](#Documentation)** : Documentation for the *argument*. Optional.
- **[DataType](#DataType)** : The return type of the *argument*. It must comply to the *DataType* definition. Required.
---
<a name="Data"/></a>
### Data
The *Data* component represents a list of *DataPoints* of a [ModuleClass](#ModuleClass).
### DataPoint
![](images/Data.png)
![](images/DataPoint.png)
A *DataPoint* element represents an aspect of a device which can be read/written to, and forms part of a device’s data model. Manipulating *DataPoints* is the most common way of controlling devices. Each *DataPoint* has an associated *type* (e.g. simple integer/real numbers, string of text, struct, or arrays thereof) which facillitates data integrity. Note that all RESTful systems (e.g. CoAP) only use *DataPoint* operations, so the mapping of a data models using an SDT into RESTful applications is easy.
*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.
However, *DataPoints* are not the only way of controlling devices, so further "Actions" and "Events are described below.
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.
......@@ -298,32 +324,120 @@ In EBNF:
#### Attributes
None.
- **name** : The name (and possible path in a hierarchical data model) of the *DataPoint*. The name must be unique in the scope of the [ModuleClass](#ModuleClass). Required.
- **optional**: Boolean that indicates whether a *DataPoint* is optional or mandatory. Optional, the default is *false*.
- **writable** : Boolean value that indicates whether this *DataPoint* is writable by an application. Optional. Default: true.
- **readable** : Boolean value that indicates whether this *DataPoint* is readable by an application. Optional. Default: true.
- **eventable** : Boolean value that indicates whether an internal or external change of this *DataPoint* raises an event. Optional. Default: false.
#### Elements
- **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. The name must be unique in the scope of the [ModuleClass](#ModuleClass).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.
- **[Doc](#Documentation)** : Documentation for the *DataPoint* element. Optional.
- **[Doc](#Documentation)** : Documentation for the *DataPoint*. Optional.
- **[DataType](#DataType)** : The type of the *DataPoint*. It must comply to the *DataType* definition. Required.
#### Example
<Data>
<DataPoint name="attributeName" type="string" writable="false">
<DataPoint name="attributeName" writable="false">
<Doc>Some documentation for the DataPoint</Doc>
<DataType>
<SimpleType type="string" />
</DataType
</DataPoint>
</Data>
---
<a name="Event"/></a>
### Event
![](images/Event.png)
*Event* elements are needed for automation protocols which "push" information, instead of relying on polling by the software application. A typical example would be a "SensorAlert" where a window sensor immediately transmits a change of its state from "closed" to "open", which could be used in a burglar alarm application, needs to be ready to accept such information immediately, and not wait for a regular polling of the device.
#### Attributes
- **name** : The name of the *Event*. The name must be unique in the scope of the [ModuleClass](#ModuleClass). Required.
- **optional**: Boolean that indicates whether an *Event* is optional or mandatory. Optional, the default is *false*.
#### Elements
- **[Doc](#Documentation)** : Documentation for the *Event* Element. Optional.
- **[Data](#DataPoint)** : A list of *DataPoint* components for an event's payload. Optional.
#### Example
<Event name="stateChanged">
<Doc>Some documentation for the Event</Doc>
<Data>
<DataPoint name="state">
<DataType>
<SimpleType type="boolean" />
</DataType>
</DataPoint>
</Data>
</Event>