Commit 7ff516d8 authored by ankraft's avatar ankraft
Browse files

Changed documentation according to HGI SHTF discussion.

parent c9402c98
This diff is collapsed.
......@@ -3,7 +3,7 @@
[Domain](#Domain)
[Device](#Device) | [SubDevice](#SubDevice)
[Property](#Property)
[ModuleClass](#ModuleClass)
[Module and ModuleClass](#ModuleClass)
   [Action](#Action)
   [DataPoint](#DataPoint)
   [Event](#Event)
......@@ -17,28 +17,10 @@
---
In this document an overview about the SDT 3.0 definitions and component hierarchy is given.
Various details about recommended structure for SDTs are described in the next sections. The key point to keep in mind is that HGI sought a compromise between, at the one extreme, complete flexibility (which could describe any device, of any complexity) and, at the other extreme, a rigid structure which could be 100% validated and lead to validated software APIs.
A major decision, facilitating validation of code and signalling, was to describe services (functionality) of devices in terms of ModuleClasses made up of combinations of three kinds of elements:
1. DataPoints which can be read/written,
2. Actions which consist of more complex sequences of operations;
3. Events which can be signalled ("published") by devices asynchronously.
This structure shown in the following figure.
![](images/MC.Action.DataPoint.png)
## SDT Overview
The following UML diagram presents an overview of the structure (elements) of every SDT which is conformant with these guidelines. As implied in the above descriptions, there can be many different choices of the details of a SDT, each one optimized for a particular market segment and the types of devices used in that market segment. Obviously an unnecessary proliferation is counter-productive, but as long as each SDT conforms to the structure shown below then it will be possible with little or modest effort for software applications to be adapted accordingly.
The reader must keep in mind that the UML diagram below is in a sense the meta-format for different possible Smart Device Templates (XSDs) for device descriptions (XMLs) of real devices - sorry about that.
The followng UML diagram presents an overview about the SDT components.
The following UML diagram presents an overview of the structure (elements) of every SDT which is conformant with these guidelines. As implied in the above descriptions, there can be many different choices of the details of a SDT, each one optimized for a particular market segment and the types of devices used in that market segment. Obviously an unnecessary proliferation is counter-productive, but as long as each SDT conforms to the structure shown below then it will be possible with little or modest effort for software to be adapted accordingly.
![](images/SDT_UML_Basic_Elements.png)
......@@ -46,11 +28,6 @@ The key to the diagram elements of the UML diagrams above and the snippets in th
![](images/SDT_UML_Key.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)
## Components
......@@ -79,12 +56,10 @@ It can also be used to collect all specified [ModuleClasses](#ModuleClasses)
xmlns="http://homegatewayinitiative.org/xml/dal/3.0"
id="org.homegatewayinitiative">
<Doc>Some documentation</Doc>
<Imports>
<!-- 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>
......@@ -166,7 +141,7 @@ An example for a compound device is a connected power-strip where each of the s
---
<a name="Property"/></a>
### Property
### Property : Element of a *Device* or *ModuleClass*
![](images/Property.png)
......@@ -194,7 +169,7 @@ Since the *Properties* are highly varied, depending on industry segment, no atte
---
<a name="ModuleClass"/></a>
### Module, ModuleClass
### Module and ModuleClass
![](images/ModuleClass.png)
......@@ -202,7 +177,7 @@ Since the *Properties* are highly varied, depending on industry segment, no atte
*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*.
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.
The advantage of identifying a subset of generic *ModuleClasses*, described below, 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.
......@@ -225,7 +200,7 @@ Typical *ModuleClasses* might be equivalent to "power ON/OFF", "Open/Close", "Pa
The element has the following attributes:
- **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.
- **[Properties](#Property)** : Further meta-data (or properties) about the *Module* or *ModuleClass*. 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.
......@@ -247,8 +222,52 @@ The element has the following attributes:
---
<a name="DataPoint"/></a>
### DataPoint : Element of *ModuleClass* and *Event*
![](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) use only *DataPoint* operations, so the mapping of a data models using an SDT into RESTful applications is easy.
However, *DataPoints* are not the only way of controlling devices, so further [Actions](#Action) and [Events](#Event) 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.
In EBNF:
name = dataPointName | "/" path ;
path = segment "/" path | dataPointName ;
segment = string ;
dataPointName = string ;
string = (* character string excluding the character "/" *) ;
#### Attributes
- **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
- **[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" writable="false">
<Doc>Some documentation for the DataPoint</Doc>
<DataType>
<SimpleType type="string" />
</DataType
</DataPoint>
</Data>
---
<a name="Action"/></a>
### Action
### Action : Element of *ModuleClass*
![](images/Action.png)
......@@ -265,6 +284,7 @@ Note that systems which rely on RESTful operations need to carry out such comple
- **[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.
<a name="ActionExample"/></a>
#### Example
The following are two examples for actions implementing a getter and a setter for boolean values.
......@@ -286,7 +306,7 @@ The following are two examples for actions implementing a getter and a setter fo
---
<a name="Arg"/></a>
### Arg
### Arg : Element of *Action*
![](images/Arg.png)
......@@ -301,54 +321,13 @@ The *Arg* has the following attributes and 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>
### DataPoint
![](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.
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.
In EBNF:
name = dataPointName | "/" path ;
path = segment "/" path | dataPointName ;
segment = string ;
dataPointName = string ;
string = (* character string excluding the character "/" *) ;
#### Attributes
- **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
- **[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" writable="false">
<Doc>Some documentation for the DataPoint</Doc>
<DataType>
<SimpleType type="string" />
</DataType
</DataPoint>
</Data>
See [example above](#ActionExample).
---
<a name="Event"/></a>
### Event
### Event : Element of *ModuleClass*
![](images/Event.png)
......@@ -378,26 +357,20 @@ In EBNF:
---
<a name="Data_Types"/></a>
### Data Types
### DataType
The data type can be simple integers or string text, or rather complex, as shown below:
![](images/SDT_UML_DataType.png)
The various elements are described in the sections below.
---
<a name="DataType"/></a>
### DataType
![](images/DataType.png)
![](images/TypeChoice.png)
The *DataType* element is a "container" for the various aspects of a type.
#### Attributes
- **name** : The name of the *DataType*. The name must be set for the [Struct](#Struct) types to distinguish individual fields in that structure. It can be used in other cases. Optional.
- **unitOfMeasure** : This is the option to label the data with the units of measurement. A "Temperature" measurement is meaningless until the units Kelvin, Celcius, Fahrenheit etc are known. Because of the extreme variety of units, a string field is the default annotation method, although of course a SDO could decide to reference a standardized list of units. Optional.
- **unitOfMeasure** : Before considering the type of data in detail, there is the option to label the data with the units of measurement. A "Temperature" measurement is meaningless until the units Kelvin, Celcius, Fahrenheit etc are known. Because of the extreme variety of units, a string field is the default annotation method, although of course a SDO could decide to reference a standardized list of units. Optional.
#### Elements
- **[Doc](#Documentation)** : Documentation for the *DataType* Element. Optional.
......@@ -426,12 +399,20 @@ The *Constraint* element is an optional element allowing the manufacturer to pro
---
### TypeChoice : Construct of *DataType*
![](images/TypeChoice.png)
The *TypeChoice* construct is required for syntactic reasons in the UML diagram and the choice from the enumerated list simply designates the complexity of the following DataType.
---
<a name="SimpleType"/></a>
### SimpleType
### SimpleType : Element of *TypeChoice*
![](images/SimpleType.png)
The "SimpleType" element is required in order for software to understand the format of the associated data, e.g. are the bytes an integer or real value? The selection choosen is based on practical experience to include some specific types which are slightly more complex:
The *SimpleType* element is required in order for software to understand the format of the associated data, e.g. are the bytes an integer or real value? The selection choosen by HGI is based on practical experience to include some specific types which are slightly more complex:
1. the (technically redundant) options of *date* and *time* - to avoid problems which can arise interpreting a *datetime* value;
2. *url* because it is expected to become extremely common to provide links to other data sources;
......@@ -454,7 +435,7 @@ If not stated otherwise datatypes should comply to the equivalent datatypes defi
---
<a name="StructType"/></a>
### StructType
### StructType : Element of *TypeChoice*
![](images/Struct.png)
......@@ -467,7 +448,7 @@ The *StructType* element can be used to represent an ordered list of diverse Dat
---
<a name="ArrayType"/></a>
### ArrayType
### ArrayType : Element of *TypeChoice*
![](images/Array.png)
......@@ -479,8 +460,11 @@ The *ArrayType* element is provided for defining lists of data; the definition i
---
<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 for the respective element. The documentation language *should* be English.
### Doc : Element for all Documentation
![](images/Doc.png)
*Doc* elements (optional for all the above Elements) are very important to help understand the software-readable information for specific devices and services. They contain the human-readable information. Many automation protocols describe every possible operation in a comprehensive specification, however SDT is designed to include the relevant information at the "point of use" for the software developer, inside the SDT (and XML files based on it).
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:
......
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