Commit b2f490ce8219deccb45e30e48eaa00f7396d4cfa

Authored by ankraft
1 parent d7bd559b

Added a new directory to work on version 4.0 of SDT.

Changed the license to 3-clause BSD.
Changed various version numbers from 3.0 to 4.0.
Showing 39 changed files with 2391 additions and 197 deletions

Too many changes to show.

To preserve performance only 39 of 94 files are displayed.

1   -Apache License
2   - Version 2.0, January 2004
3   - http://www.apache.org/licenses/
  1 +Copyright 2018, oneM2M Partners Type 1
4 2  
5   - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
  3 +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
6 4  
7   - 1. Definitions.
  5 +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
8 6  
9   - "License" shall mean the terms and conditions for use, reproduction,
10   - and distribution as defined by Sections 1 through 9 of this document.
  7 +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
11 8  
12   - "Licensor" shall mean the copyright owner or entity authorized by
13   - the copyright owner that is granting the License.
14   -
15   - "Legal Entity" shall mean the union of the acting entity and all
16   - other entities that control, are controlled by, or are under common
17   - control with that entity. For the purposes of this definition,
18   - "control" means (i) the power, direct or indirect, to cause the
19   - direction or management of such entity, whether by contract or
20   - otherwise, or (ii) ownership of fifty percent (50%) or more of the
21   - outstanding shares, or (iii) beneficial ownership of such entity.
22   -
23   - "You" (or "Your") shall mean an individual or Legal Entity
24   - exercising permissions granted by this License.
25   -
26   - "Source" form shall mean the preferred form for making modifications,
27   - including but not limited to software source code, documentation
28   - source, and configuration files.
29   -
30   - "Object" form shall mean any form resulting from mechanical
31   - transformation or translation of a Source form, including but
32   - not limited to compiled object code, generated documentation,
33   - and conversions to other media types.
34   -
35   - "Work" shall mean the work of authorship, whether in Source or
36   - Object form, made available under the License, as indicated by a
37   - copyright notice that is included in or attached to the work
38   - (an example is provided in the Appendix below).
39   -
40   - "Derivative Works" shall mean any work, whether in Source or Object
41   - form, that is based on (or derived from) the Work and for which the
42   - editorial revisions, annotations, elaborations, or other modifications
43   - represent, as a whole, an original work of authorship. For the purposes
44   - of this License, Derivative Works shall not include works that remain
45   - separable from, or merely link (or bind by name) to the interfaces of,
46   - the Work and Derivative Works thereof.
47   -
48   - "Contribution" shall mean any work of authorship, including
49   - the original version of the Work and any modifications or additions
50   - to that Work or Derivative Works thereof, that is intentionally
51   - submitted to Licensor for inclusion in the Work by the copyright owner
52   - or by an individual or Legal Entity authorized to submit on behalf of
53   - the copyright owner. For the purposes of this definition, "submitted"
54   - means any form of electronic, verbal, or written communication sent
55   - to the Licensor or its representatives, including but not limited to
56   - communication on electronic mailing lists, source code control systems,
57   - and issue tracking systems that are managed by, or on behalf of, the
58   - Licensor for the purpose of discussing and improving the Work, but
59   - excluding communication that is conspicuously marked or otherwise
60   - designated in writing by the copyright owner as "Not a Contribution."
61   -
62   - "Contributor" shall mean Licensor and any individual or Legal Entity
63   - on behalf of whom a Contribution has been received by Licensor and
64   - subsequently incorporated within the Work.
65   -
66   - 2. Grant of Copyright License. Subject to the terms and conditions of
67   - this License, each Contributor hereby grants to You a perpetual,
68   - worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69   - copyright license to reproduce, prepare Derivative Works of,
70   - publicly display, publicly perform, sublicense, and distribute the
71   - Work and such Derivative Works in Source or Object form.
72   -
73   - 3. Grant of Patent License. Subject to the terms and conditions of
74   - this License, each Contributor hereby grants to You a perpetual,
75   - worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76   - (except as stated in this section) patent license to make, have made,
77   - use, offer to sell, sell, import, and otherwise transfer the Work,
78   - where such license applies only to those patent claims licensable
79   - by such Contributor that are necessarily infringed by their
80   - Contribution(s) alone or by combination of their Contribution(s)
81   - with the Work to which such Contribution(s) was submitted. If You
82   - institute patent litigation against any entity (including a
83   - cross-claim or counterclaim in a lawsuit) alleging that the Work
84   - or a Contribution incorporated within the Work constitutes direct
85   - or contributory patent infringement, then any patent licenses
86   - granted to You under this License for that Work shall terminate
87   - as of the date such litigation is filed.
88   -
89   - 4. Redistribution. You may reproduce and distribute copies of the
90   - Work or Derivative Works thereof in any medium, with or without
91   - modifications, and in Source or Object form, provided that You
92   - meet the following conditions:
93   -
94   - (a) You must give any other recipients of the Work or
95   - Derivative Works a copy of this License; and
96   -
97   - (b) You must cause any modified files to carry prominent notices
98   - stating that You changed the files; and
99   -
100   - (c) You must retain, in the Source form of any Derivative Works
101   - that You distribute, all copyright, patent, trademark, and
102   - attribution notices from the Source form of the Work,
103   - excluding those notices that do not pertain to any part of
104   - the Derivative Works; and
105   -
106   - (d) If the Work includes a "NOTICE" text file as part of its
107   - distribution, then any Derivative Works that You distribute must
108   - include a readable copy of the attribution notices contained
109   - within such NOTICE file, excluding those notices that do not
110   - pertain to any part of the Derivative Works, in at least one
111   - of the following places: within a NOTICE text file distributed
112   - as part of the Derivative Works; within the Source form or
113   - documentation, if provided along with the Derivative Works; or,
114   - within a display generated by the Derivative Works, if and
115   - wherever such third-party notices normally appear. The contents
116   - of the NOTICE file are for informational purposes only and
117   - do not modify the License. You may add Your own attribution
118   - notices within Derivative Works that You distribute, alongside
119   - or as an addendum to the NOTICE text from the Work, provided
120   - that such additional attribution notices cannot be construed
121   - as modifying the License.
122   -
123   - You may add Your own copyright statement to Your modifications and
124   - may provide additional or different license terms and conditions
125   - for use, reproduction, or distribution of Your modifications, or
126   - for any such Derivative Works as a whole, provided Your use,
127   - reproduction, and distribution of the Work otherwise complies with
128   - the conditions stated in this License.
129   -
130   - 5. Submission of Contributions. Unless You explicitly state otherwise,
131   - any Contribution intentionally submitted for inclusion in the Work
132   - by You to the Licensor shall be under the terms and conditions of
133   - this License, without any additional terms or conditions.
134   - Notwithstanding the above, nothing herein shall supersede or modify
135   - the terms of any separate license agreement you may have executed
136   - with Licensor regarding such Contributions.
137   -
138   - 6. Trademarks. This License does not grant permission to use the trade
139   - names, trademarks, service marks, or product names of the Licensor,
140   - except as required for reasonable and customary use in describing the
141   - origin of the Work and reproducing the content of the NOTICE file.
142   -
143   - 7. Disclaimer of Warranty. Unless required by applicable law or
144   - agreed to in writing, Licensor provides the Work (and each
145   - Contributor provides its Contributions) on an "AS IS" BASIS,
146   - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147   - implied, including, without limitation, any warranties or conditions
148   - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149   - PARTICULAR PURPOSE. You are solely responsible for determining the
150   - appropriateness of using or redistributing the Work and assume any
151   - risks associated with Your exercise of permissions under this License.
152   -
153   - 8. Limitation of Liability. In no event and under no legal theory,
154   - whether in tort (including negligence), contract, or otherwise,
155   - unless required by applicable law (such as deliberate and grossly
156   - negligent acts) or agreed to in writing, shall any Contributor be
157   - liable to You for damages, including any direct, indirect, special,
158   - incidental, or consequential damages of any character arising as a
159   - result of this License or out of the use or inability to use the
160   - Work (including but not limited to damages for loss of goodwill,
161   - work stoppage, computer failure or malfunction, or any and all
162   - other commercial damages or losses), even if such Contributor
163   - has been advised of the possibility of such damages.
164   -
165   - 9. Accepting Warranty or Additional Liability. While redistributing
166   - the Work or Derivative Works thereof, You may choose to offer,
167   - and charge a fee for, acceptance of support, warranty, indemnity,
168   - or other liability obligations and/or rights consistent with this
169   - License. However, in accepting such obligations, You may act only
170   - on Your own behalf and on Your sole responsibility, not on behalf
171   - of any other Contributor, and only if You agree to indemnify,
172   - defend, and hold each Contributor harmless for any liability
173   - incurred by, or claims asserted against, such Contributor by reason
174   - of your accepting any such warranty or additional liability.
175   -
176   - END OF TERMS AND CONDITIONS
177   -
178   - Copyright 2014 HGI Home Gateway Initiative
179   -
180   - Licensed under the Apache License, Version 2.0 (the "License");
181   - you may not use this file except in compliance with the License.
182   - You may obtain a copy of the License at
183   -
184   - http://www.apache.org/licenses/LICENSE-2.0
185   -
186   - Unless required by applicable law or agreed to in writing, software
187   - distributed under the License is distributed on an "AS IS" BASIS,
188   - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
189   - See the License for the specific language governing permissions and
190   - limitations under the License.
  9 +3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
191 10  
  11 +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
192 12 \ No newline at end of file
... ...
... ... @@ -2,9 +2,9 @@
2 2  
3 3 Repository for the Smart Device Template (SDT).
4 4  
5   -**Version 3.0**
  5 +**Version 4.0**
6 6  
7   -Note that this project runs under Apache 2.0 license. Read the [LICENSE](LICENSE) in this repository, or refer to [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
  7 +Note that this project runs under the 3-Clause BSD License. Read the [LICENSE](LICENSE) in this repository, or refer to [https://opensource.org/licenses/BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause).
8 8  
9 9 Any contributions made to this project must comply with the aforementioned license.
10 10  
... ... @@ -12,23 +12,23 @@ Any contributions made to this project must comply with the aforementioned licen
12 12  
13 13 The Smart Device Template (SDT) is a template which is used to model the capabilities, actions and events of connected devices. The intent of the SDT is to be able to model any type of connected device using a well accepted and standardised format. The main application of SDT is to enable a uniformly structured Application Programmer’s Interface (API) to applications that need to interact with connected devices. Usually, these applications would communicate to devices using an Abstraction Layer as an intermediary logic. The Abstraction Layer „hides“ the technology-specific, native language format of devices of different technology type from the applications.
14 14  
15   -[Read the full Introduction.](SDT/schema3.0/docs/Introduction.md)
  15 +[Read the full Introduction.](SDT/schema4.0/docs/Introduction.md)
16 16  
17 17 ## Quick Links
18   -- ['domain.xsd' Version 3.0](SDT/schema3.0/src/domain.xsd)
19   -- [UML Diagram of the SDT 3.0](SDT/schema3.0/docs/UML%20Diagram.md) ([source](SDT/schema3.0/docs/SDT_UML.uxf))
  18 +- ['domain.xsd' Version 4.0](SDT/schema4.0/src/domain.xsd)
  19 +- [UML Diagram of the SDT 4.0](SDT/schema4.0/docs/UML%20Diagram.md) ([source](SDT/schema4.0/docs/SDT_UML.uxf))
20 20  
21 21  
22 22 ## Content
23 23  
24 24 You can find further Information here:
25 25  
26   -- [Introduction to the SDT](SDT/schema3.0/docs/Introduction.md)
27   -- [SDT Components](SDT/schema3.0/docs/SDT_Components.md)
28   -- [SDT Build System](SDT/schema3.0/docs/SDT%20Build%20System.md)
29   -- [Examples](SDT/schema3.0/docs/Examples.md)
30   -- [Links & References](SDT/schema3.0/docs/Links.md)
31   -- [Changelog](SDT/schema3.0/docs/Changelog.md)
  26 +- [Introduction to the SDT](SDT/schema4.0/docs/Introduction.md)
  27 +- [SDT Components](SDT/schema4.0/docs/SDT_Components.md)
  28 +- [SDT Build System](SDT/schema4.0/docs/SDT%20Build%20System.md)
  29 +- [Examples](SDT/schema4.0/docs/Examples.md)
  30 +- [Links & References](SDT/schema4.0/docs/Links.md)
  31 +- [Changelog](SDT/schema4.0/docs/Changelog.md)
32 32 - [LICENSE](LICENSE)
33 33  
34 34  
... ...
  1 +<?xml version="1.0" encoding="UTF-8" ?>
  2 +
  3 +<!-- - HGI Device Abstraction Layer - - - - - - - - - - - - - - - - - - - - -->
  4 +<!-- -->
  5 +<!-- Extends the standard build with targets for: -->
  6 +<!-- - generate XML schema the from Relax NG (xml) description -->
  7 +<!-- - validate DAL documents against the XML Schema -->
  8 +<!-- - generate HTML documentation from DAL documents -->
  9 +
  10 +<project name="importing" basedir="." default="schemas">
  11 + <import file="etc/common.xml"/>
  12 +
  13 + <!-- Read the namespace declarations from a file (to get linebreaks) - - - -->
  14 +
  15 + <loadfile property="schema.xmlns" srcFile="${basedir}/etc/schema.xmlns"/>
  16 +
  17 + <!-- The RNG file the XML and RNC schemas are generaed from - - - - - - - -->
  18 +
  19 + <property name="schema.name" value="domain"/>
  20 + <property name="schema.rng" value="${path.src}/${schema.name}.rng"/>
  21 +
  22 + <!-- HTML - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  23 + <!-- -->
  24 + <!-- Generate HTML documentation from domain definitions in the test -->
  25 + <!-- directory. The module classes included via the extends tagged are -->
  26 + <!-- included in the documentation - so an xinclude capable XSL engine is -->
  27 + <!-- needed. -->
  28 + <!-- This needs Ant version 1.8+ and it must be augmented with an current -->
  29 + <!-- version of Xerces. Download the binray distribution and place the put -->
  30 + <!-- xml-apis.jar and xercesImpl.jar in the Ant lib directory. -->
  31 +
  32 + <target name="html">
  33 + <mkdir dir="${path.genbase}" />
  34 + <xslt basedir="${basedir}/test" destdir="${basedir}/gen/html"
  35 + style="${basedir}/style/html.xsl">
  36 + <param name="destdir" expression="${basedir}/gen/html"/>
  37 + <sysproperty
  38 + key="org.apache.xerces.xni.parser.XMLParserConfiguration"
  39 + value="org.apache.xerces.parsers.XIncludeParserConfiguration"/>
  40 + </xslt>
  41 + </target>
  42 +
  43 + <!-- Schemas - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  44 + <!-- -->
  45 + <!-- The schema is specified using Relax NG (xml) and trang is used to -->
  46 + <!-- generate the XML schema. The schema is also generated in Relay NG -->
  47 + <!-- compact syntax, which is used by some validating editors (e.g. emacs) -->
  48 + <!-- The resulting schemas need some additional patching before thy are -->
  49 + <!-- usable -->
  50 +
  51 + <target name="schemas">
  52 + <java jar="${basedir}/lib/trang.jar" fork="true">
  53 + <arg value="${schema.rng}"/>
  54 + <arg value="${basedir}/etc/${schema.name}.rnc"/>
  55 + </java>
  56 +
  57 + <!-- So that the editor does not complain about include directives, the -->
  58 + <!-- resulting schema is included in another schema, which includes the -->
  59 + <!-- necessary element definitions. To be able to do this the -->
  60 + <!-- definition for Imports must be deleted from this generated schema. -->
  61 +
  62 + <replace file="${basedir}/etc/${schema.name}.rnc"
  63 + token="Imports = element Imports { Domain* }?" value=""/>
  64 +
  65 + <java jar="${basedir}/lib/trang.jar" fork="true">
  66 + <arg value="${schema.rng}"/>
  67 + <arg value="${path.src}/${schema.name}.xsd"/>
  68 + </java>
  69 +
  70 + <!-- Can't validate against the generated schema unless we add the -->
  71 + <!-- target and default namespaces ... -->
  72 +
  73 + <replace file='${path.src}/domain.xsd'
  74 + token='xmlns:xs="http://www.w3.org/2001/XMLSchema"'
  75 + value='${schema.xmlns}'/>
  76 +
  77 + <!-- In addition the xml:base tag, which is added automatically when -->
  78 + <!-- including a document, must also be permitted by out schema. -->
  79 + <!-- The schema generated from RNG is almost correct schema ... but -->
  80 + <!-- the schemaLocation is wrong. -->
  81 +
  82 + <replace file='${path.src}/domain.xsd'
  83 + token="xml.xsd" value="http://www.w3.org/2001/03/xml.xsd"/>
  84 + </target>
  85 +
  86 + <!-- Validate - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  87 + <!-- -->
  88 + <!-- Check the Device Description conforms to the Device Abstraction -->
  89 + <!-- Schema. Note that we need to activate support for XML includes -->
  90 +
  91 + <target name="validate" depends="">
  92 + <schemavalidate warn="true">
  93 + <fileset dir="${basedir}/test" includes="*.xml"/>
  94 + <attribute name="http://apache.org/xml/features/xinclude" value="true"/>
  95 + <schema namespace="http://homegatewayinitiative.org/xml/dal/3.0"
  96 + file="${path.src}/domain.xsd" />
  97 + <schema namespace="http://www.w3.org/2001/XInclude"
  98 + file="${basedir}/etc/XInclude.xsd" />
  99 + <schema namespace="http://www.w3.org/2001/XMLSchema"
  100 + file="${basedir}/etc/XMLSchema.xsd" />
  101 + </schemavalidate>
  102 + </target>
  103 +
  104 +</project>
  105 +
... ...
  1 +# Changelog
  2 +
  3 +## Changes in 4.0
  4 +
  5 +
  6 +## Changes in 3.0
  7 +- Renamed ``<RootDevice>``to ``<Device>`` and ``<Device>`` to ``<SubDevice>``,
  8 +- Added complex data types: *Struct* and *Arrays*.
  9 +- Simplified the UML diagram. Split the UML diagram into two parts, one for the base elements and one for the data types.
  10 +- In the UML diagram: Moved ``<extends>`` into the UML ``<ModuleClass>`` element (easier to read).
  11 +- Added support to specify *Units of Measurement* to data types,
  12 +- Added ``<Doc>`` to ``<Domain>`` and other elements.
  13 +- ``<Doc>`` is now always the first part of an element.
  14 +- Changed ``<DeviceInfo>`` element to a list of ``<Characteristic>``.
  15 +- Added ``<Characteristic>`` list to ``<Modules>`` and ``<ModuleClasses>``.
  16 +- The ``<data>`` element in ``<Event>`` is now optional to support events without attached or associated data.
  17 +- In Actions: Added ``<Args>`` as a surrounding list around a list of ``<Arg>``.
  18 +- Added *Constraints* to ``<DataType>``.
  19 +- Added optional *name* attribute to ``<DataType>``. This mandatory for elements of a *struct*.
  20 +- Restructured the [RNG](SDT/schema3.0/src/domain.rng) file for better readability and maintainability.
  21 +- In the [RNG](SDT/schema3.0/src/domain.rng)/[XSD](SDT/schema3.0/src/domain.xsd): Changed cardinality of the occurrence of elements that are part of a list of elements (e.g. ``<SubDevices><SubDevice>…</SubDevice></SubDevices>`` from „zero or more“ to „one or more“ when the surrounding list element itself is optional (to avoid empty lists).
  22 +
  23 +
  24 +
  25 +## Changes in 2.0.1
  26 +- Added missing "uri" data type.
  27 +
  28 +## Changes in 2.0
  29 +- Introduced RootDevice to support hierarchical embedded devices.
  30 +- Added new data types (byte, float, array, enum, date, time, datetime, blob, uri)
  31 +- Added ``readable`` and ``eventable`` to data points.
  32 +- Added optional ``<SerialNumber>``, ``<VendorURL>`` and ``<FirmwareVersion>`` elements to DeviceInfo
  33 +- Added optional ``<Doc>`` element to Event
  34 +- Changed the optionality of the ``<DataPoint>``'s ``type`` attribute to "required".
  35 +- Added [UML diagram](SDT/schema2.0/docs/SDT_Components.md)
  36 +- Changed the namespace for the XSD from "hgi.org" to "homegatewayinitiative.org".
0 37 \ No newline at end of file
... ...
  1 +# Examples and Contributions
  2 +[A simple example](#simpleExample)
  3 +[Multi Socket Electrical-Extension-Block](#mseeb)
  4 +
  5 +<a name="simpleExample"></a>
  6 +## A very simple SDT example
  7 +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.
  8 +
  9 +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/) ).
  10 +
  11 +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.
  12 +
  13 +<table>
  14 +<tr><th>Funtionality</th><th>Air Conditioner</th><th>Washing Machine</th></tr>
  15 +<tr><td>operationStatus</td><td>operates on/off</td><td>operates on/off</td></tr>
  16 +<tr><td>measuredCumulativePowerConsumption</td><td>the cumulative power consumption</td><td>the cumulative power consumption</td></tr>
  17 +<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>
  18 +<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>
  19 +</table>
  20 +
  21 +Based on the simplified example above, the two appliances will need the ModuleClasses below:
  22 +
  23 +- *air-conditioner*: operationStatus, measuredCumulativePowerConsumption, installationLocation;
  24 +- *washing-machine*: operationStatus, measuredCumulativePowerConsumption, and setTimer.
  25 +
  26 + <ModuleClass name="operationStatus">
  27 + <Data>
  28 + <DataPoint name="operationStatus" writable="true">
  29 + <Doc>This property sets/reads the ON/OFF status.</Doc>
  30 + <DataType>
  31 + <SimpleType type="boolean"/>
  32 + </DataType>
  33 + </DataPoint>
  34 + </Data>
  35 + <Events>
  36 + <Event name="operationStatus">
  37 + </Event>
  38 + </Events>
  39 + </ModuleClass>
  40 +
  41 + <ModuleClass name="measuredCumulativePowerConsumption">
  42 + <Data>
  43 + <DataPoint name="measuredCumulativePowerConsumption" writable="false">
  44 + <Doc>This indicates cumulative power consumption of the device in increments of 0.001kWh.</Doc>
  45 + <DataType>
  46 + <SimpleType type="integer"/>
  47 + </DataType>
  48 + </DataPoint>
  49 + </Data>
  50 + </ModuleClass>
  51 +
  52 + <ModuleClass name="installationLocation">
  53 + <Data>
  54 + <DataPoint name="installationLocation" writable="true">
  55 + <Doc>This property indicates the installation location</Doc>
  56 + <DataType>
  57 + <SimpleType type="string"/>
  58 + </DataType>
  59 + </DataPoint>
  60 + </Data>
  61 + <Events>
  62 + <Event name="installationLocation"> </Event>
  63 + </Events>
  64 + </ModuleClass>
  65 +
  66 + <ModuleClass name="onTimerSetting">
  67 + <DataPoint name="onTimer" writable="true">
  68 + <Doc>Timer value (HH:MM)</Doc>
  69 + <DataType>
  70 + <SimpleType type="time"/>
  71 + </DataType>
  72 + </DataPoint>
  73 + </ModuleClass>
  74 +
  75 +The structure and the according SDT now looks like this:
  76 +
  77 +<table>
  78 +<tr><td colspan="2" width="50%"><b>Example1.SDT</b></td></tr>
  79 +<tr><td> </td><td>Namespace information</td></tr>
  80 +<tr><td> </td><td>Modules (contains ModuleClasses)</td></tr>
  81 +<tr><td> </td><td>operationStatus<ul>
  82 + <li>measuredCumulativePowerConsumption</li>
  83 + <li>installationLocation</li>
  84 + <li>onTimerSetting</li></ul></td></tr>
  85 +</table>
  86 +
  87 + <?xml version="1.0" encoding="iso-8859-1"?>
  88 + <!-- Example1 SDT inspired by some Echonet Lite examples -->
  89 + <Domain xmlns="http://homegatewayinitiative.org/xml/dal/3.0"
  90 + xmlns:xi="http://www.w3.org/2001/XInclude"
  91 + id="example1.SDT">
  92 +
  93 + <Modules>
  94 + <!-- Various examples for module classes -->
  95 + <ModuleClass name="operationStatus">
  96 + <Data>
  97 + <DataPoint name="operationStatus" writable="true">
  98 + <Doc>This property sets the ON/OFF status.</Doc>
  99 + <DataType>
  100 + <SimpleType type="boolean"/>
  101 + </DataType>
  102 + </DataPoint>
  103 + </Data>
  104 + <Events>
  105 + <Event name="operationStatus">
  106 + </Event>
  107 + </Events>
  108 + </ModuleClass>
  109 +
  110 + <ModuleClass name="installationLocation">
  111 + <Data>
  112 + <DataPoint name="installationLocation" writable="true">
  113 + <Doc>This property indicates the installation location</Doc>
  114 + <DataType>
  115 + <SimpleType type="string"/>
  116 + </DataType>
  117 + </DataPoint>
  118 + </Data>
  119 + <Events>
  120 + <Event name="installationLocation"> </Event>
  121 + </Events>
  122 + </ModuleClass>
  123 +
  124 + <ModuleClass name="measuredCumulativePowerConsumption">
  125 + <Data>
  126 + <DataPoint name="measuredCumulativePowerConsumption" writable="false">
  127 + <Doc>This indicates cumulative power consumption of the device in increments of 0.001kWh.</Doc>
  128 + <DataType>
  129 + <SimpleType type="integer"/>
  130 + </DataType>
  131 + </DataPoint>
  132 + </Data>
  133 + </ModuleClass>
  134 +
  135 + <ModuleClass name="onTimerSetting">
  136 + <DataPoint name="onTimer" writable="true">
  137 + <Doc>Timer value (HH:MM)</Doc>
  138 + <DataType>
  139 + <SimpleType type="time"/>
  140 + </DataType>
  141 + </DataPoint>
  142 + </ModuleClass>
  143 + </Modules>
  144 + </Domain>
  145 +
  146 +
  147 +---
  148 +
  149 +<a name="mseeb"></a>
  150 +### Multi Socket Electrical-Extension-Block
  151 +
  152 +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
  153 +separate *SubDevice*.
  154 +
  155 +[mseeb.xml](../test/mseeb.xml)
  156 +
  157 +
  158 +---
  159 +
... ...
  1 +# Frequently Asked Questions
  2 +
  3 +## What is the HGI?
  4 +tbd
  5 +
  6 +## What is the SDT?
  7 +tbd
... ...
  1 +# Introduction to the SDT
  2 +
  3 +The SDT (Smart Device Template) is an initiative from HGI to find consensus amongst various SDOs and industry alliances to derive a common approach for device modelling. HGI and partners have the approach to agree on a set of automation commands, following a common syntax, which are sufficient to model most home appliance functions.
  4 +
  5 +At the time of writing, every software developed for home gateways or internet-of-things gateways needs to be capable of using various different protocols (ZigBee, UPnP, EchonetLite, DECT ULE, etc) to interact with a range of devices designed for the home environment. This adds extreme overheads in integrating, checking and updating code. The purpose of SDT is to describe devices and device services in a way which is independent of the LAN technology, in a format which is convenient and reliable for integration in modern code (Java, C/C++, ...).
  6 +
  7 +The key goals of the SDT are: (1) keep it simple, especially for manufacturers to contribute device information; (2) modularity for functions and device types; (3) make it easy for developers to create unified APIs; (4) be independent of underlying home-area network technologies; (4) enable extendibility of the system in place without service interruption; (5) allow a pass-through mechanism to enable use of proprietary or technology-specific functions.
  8 +
  9 +In general a description of device (or complex appliance) behaviour can be made in many ways, with various kinds of constraints:
  10 +
  11 +1. no constraints (e.g. using OWL 2.0 or even more "flexibly" RDF)
  12 +2. moderate constraints (e.g. using XML and a related extensible XSD template)
  13 +3. strict constraints (typical for a device certified to interoperate with a specific LAN protocol)
  14 +
  15 +HGI chose to use the approach "moderate constraints" (XSD based) because for software development it offers ease of use and a good compromise. In particular, if there are few or no constraints on control parameters then few automatic checks can be made to detect if the software parameters are appropriate for each device integrated. XML and XSD languages were chosen because they are familiar to many developers, can be parsed with common software tools, and can still be created and interpreted by humans if necessary.
  16 +
  17 +HGI believes that Device information models based on XML and extensible XSD need some guidelines. If every possible feature of every existing LAN technology and appliance were allowed to be described in any formally correct way, then the results would be a modern Babel, no better than today's system of widely different and wildly competing automation protocols.
  18 +
  19 +Therefore HGI proposes to recommend a certain structure (template) for the information model(s), but to allow extensions. Naturally, the more industry consensus is achieved for a single recommended template, the greater the utility for software developers (and users).
  20 +
  21 +The SDT approach is to define re-usable basic functions (or services), labelled "ModuleClass" in the figure below, which can represent the typical functions found in many home automation systems, such as "on/off", "dim a lamp", "receive events from binary sensor", "read data from sensor", etc. Each ModuleClass is composed of a (small) number of actions, datapoint read/write operations, or asynchronous events. For example, an "on/off" ModuleClass would consist perhaps of just one Action, but a "ReadKeypad" Action might have a number of possible events, each with some data value and (usually) a sequence-ID or timestamp start/stop to indicate when and how long each key was pressed.
  22 +
  23 +
  24 +![SmartHome Device Template (XSD) for a generic device (simplification)](images/SDT_simplified.png)
  25 +**SmartHome Device Template (XSD) for a generic device (simplification)**
  26 +
  27 +The SDT represents the device models introduced in the above figure by using an XSD schema to allow formal checking of compliance for XML device descriptions of specific appliances. The modularity goal in the XSD schema is achieved with re-usable XSD fragments ("ModuleClass" in the figure).
  28 +
  29 +Complex devices or appliances can then be described by an appropriate set or collection of the agreed XSD fragments (ModuleClasses), as indicated in the figure, which also shows an optional DeviceInfo XSD fragment to allow noting of static information such as device manufacturer name, device firmware version, etc etc.
  30 +
  31 +HGI has discussed with many SDOs to validate these concepts. SDT is designed to take into account the list of "services" compiled by the SAREF project (https://sites.google.com/site/smartappliancesproject/home).
  32 +
  33 +The SDT supports the use of a set of templates for generic devices or appliances (e.g. for a dimmable lamp, a basic washing machine, etc, which would be specific instances of the "Device" object , which form the basis of APIs used by application developers. These templates can also be referenced by manufacturers creating XML documents to describe their specific products. For example, the SDT enables specification of a generic washing machine template, with on/off, set-wash-temperature, pause and a few other commands, which could be referenced by a manufacturer as the schema for a XML description of a basic model washing machine. The SDT allows for vendor-specific additional commands (ModuleClasses) to suit specific product types.
  34 +
  35 +The interoperability benefits can potentially partially be obtained even without a fully complete interoperability of the SDT. For example, the most common functions can be modeled with SDT, and more particular functions can be modeled with technology-specific, proprietary, or seldom-used aspects.
  36 +
  37 +Various details about the 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.
  38 +
  39 +
  40 +## Definitions
  41 +
  42 +This section provides an overview about the SDT 4.0 definitions and element hierarchy. Terms to be described in detail in this section are:
  43 +
  44 +| Term | Definition |
  45 +|------|------------|
  46 +|Domain | Unique name, or "wrapper" which acts like a namespace, set by the organization creating the SDT, allowing reference to a package of definitions for the contained ModuleClasses and device definitions. Can be referenced when extending ModuleClasses. It has two possible uses: to select the scope of a technology domain, or to set the scope of a use case domain (like Home, SmartGrid, etc) |
  47 +| Device | Physical, addressable, identifiable appliance/sensor/actuator. |
  48 +| Sub-Device | A device (usually one of several) which may be embedded in a Device and/or is addressed via another Device. |
  49 +| ModuleClass | Specification of a single service with one or more service methods, the involved abstracted data model and related events. The expectation is that each separate service which may be used in many kinds of Devices (like PowerON/OFF, Open/Close, ...) will be described by a ModuleClass which can be re-used in many Device definitions. |
  50 +| Module | Instantiation of a ModuleClass for a specific Device or SubDevice|
  51 +
  52 +**Definitions of SDT Elements.**
  53 +
  54 +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:
  55 +
  56 +1. DataPoints which are aspects of the Device that can be read/written,
  57 +2. Actions which consist of more complex sequences of operations;
  58 +3. Events which can be signalled ("published") by devices asynchronously.
  59 +
  60 +This ModuleClass structure is shown in the figure below and is a major part of the SDT which is illustrated in detail in the following figure:
  61 +
  62 +![UML description of device functionality in terms of Actions, DataPoints and Events](images/MC.Action.DataPoint.Event.png)
  63 +**UML description of device functionality in terms of Actions, DataPoints and Events**
  64 +
  65 +## How should SDT work?
  66 +
  67 +The basic concept is that a manufacturer, organisation or global SDO would define its preferred Smart Device Template, in XML, specified by and based on an XSD. Using that XSD, manufacturers or indeed hobbyists could "describe" existing or new devices by means of XML files, specifying the capabilities and the parameters needed to control the devices.
  68 +
  69 +Assuming that the XML files conform to the specified XSD and to some guidelines described in this document, software developers could readily create APIs able to "parse" the XML-descriptions of devices and (assuming the underlying LAN technology of the device is supported by the software/hardware environment in the gateway) operate the equipment.
  70 +
  71 +The key to making software reliably interoperate with various technologies is to define in the SDT a finite and convenient to use number of functions (which is the decision of the SDO which are commonly used and can therefore be reliably re-used in software for one type of device or another.
  72 +
  73 +For the convenience of users and developers, it would also be possible to collect the device descriptions of common "modules" (types of) appliances so that the operations of "a generic air-conditioner" could be agreed and re-used often, adapting descriptions of special models with just some special features added as local extensions. Agreeing on the definition of "a generic XYZ appliance" is rather time-consuming, so such "repository" may not become standardised, however the basic approach has huge benefits even if such an archive (also known as a "hierarchical ontology") is never formally agreed.
  74 +
  75 +## Related aspects which are out of scope of the SDT
  76 +
  77 +The SDT defines the structure of all compliant XML descriptions. Each XML description of a specific device is definable at the time of manufacture of the device and can therefore only contain "static" information: (a) manufacturer data in the form of documentation elements and properties, (b) device capability information detailing the firmware operations and types/meanings of input/output variables.
  78 +
  79 +NOT directly part of this work is a related but separate aspect of every gateway software development: a "device abstraction layer" which can translate between (1) software APIs written based on a particular SDT and (2) the "commands" expected by several different LAN protocols and their hardware controllers.
  80 +
  81 +Programmers developing a "device abstraction layer" for software in a gateway need to create run-time representations of all the recognized devices, their operations and their actual states. This internal "information model" needs to be updated in real time as the devices and the users interact. Programmers may be tempted to use the SDT structure to organize their real-time information model, adding additional information elements for the current state of each device, for some kind of "history" of commands sent/acknowledged, the user etc.
  82 +
  83 +The above is an efficient approach BUT it must be clear that the real-time state information and history of events, etc, can NOT be represented in a pre-defined SDT and in the XML giving specific details for a device.
  84 +
  85 +---
  86 +
  87 +Click [here](SDT_Components.md) for detailed documentation about SDT.
  88 +
  89 +
... ...
  1 +# Links & References
  2 +- **HGI** : [http://www.homegatewayinitiative.org](http://www.homegatewayinitiative.org)
  3 +
  4 +## XML
  5 +- **RELAX NG** : [http://relaxng.org](http://relaxng.org)
  6 + - **RELAX NG Tutorial** : [http://relaxng.org/tutorial-20011203.html](http://relaxng.org/tutorial-20011203.html)
  7 +
  8 +## Tools
  9 +- **UMLet** : [http://www.umlet.com](http://www.umlet.com)
  10 +The free UML drawing tool used to draw the UML file.
  11 +- **Apache Ant** : [http://ant.apache.org](http://ant.apache.org)
  12 +Build tool
  13 +
  14 +
... ...
  1 +# Build System Libraries and Licenses
  2 +The following libraries are used in the build system for the SDT.
  3 +
  4 +## trang.jar
  5 +
  6 +[http://www.thaiopensource.com/relaxng/trang-manual.html](http://www.thaiopensource.com/relaxng/trang-manual.html)
  7 +
  8 +*Trang* takes as input a schema written in any of the following formats:
  9 +
  10 +- RELAX NG (XML syntax)
  11 +- RELAX NG (compact syntax)
  12 +- XML 1.0 DTD
  13 +
  14 +and produces as output a schema written in any of the following formats:
  15 +
  16 +- RELAX NG (XML syntax)
  17 +- RELAX NG (compact syntax)
  18 +- XML 1.0 DTD
  19 +- W3C XML Schema
  20 +
  21 +*Trang* can also infer a schema from one or more example XML documents.
  22 +
  23 +
  24 +### License
  25 +Copyright (c) 2002, 2003, 2008 Thai Open Source Software Center Ltd
  26 +All rights reserved.
  27 +
  28 +Redistribution and use in source and binary forms, with or without
  29 +modification, are permitted provided that the following conditions are
  30 +met:
  31 +
  32 +- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  33 +- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  34 +- Neither the name of the Thai Open Source Software Center Ltd nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
  35 +
  36 +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  37 +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  38 +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  39 +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
  40 +CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  41 +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  42 +PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  43 +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  44 +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  45 +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  46 +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  47 +
  48 +## Ant-Contrib Tasks
  49 +
  50 +[http://ant-contrib.sourceforge.net](http://ant-contrib.sourceforge.net)
  51 +
  52 +The *Ant-Contrib* project is a collection of tasks (and at one point maybe types and other tools) for Apache Ant.
  53 +
  54 +### License
  55 +
  56 +This Software is distributed under the Apache Software License.
  57 +
  58 +## antSetLogLevel.jar
  59 +
  60 +GUI dialog for Ant tasks.
  61 +
  62 +Source: Deutsche Telekom
  63 +
  64 +
  65 +
... ...
  1 +# SDT Build System
  2 +This document describes the SDT build system and how to build the SDT and validate new contributions.
  3 +
  4 +The files referenced in this document point to version **4.0** of the SDT.
  5 +
  6 +## Directory Structure and Important Files
  7 +- [SDT/schema4.0/](../..) : Base directory
  8 +- [SDT/schema4.0/src/](../src/) : Source files of the SDT.
  9 + - [domain.rng](../src/domain.rng) : RELAX NG file with the SDT schema definition. This is the source file that is converted to the actual schema definition *domain.xsd* during the build. See also [http://en.wikipedia.org/wiki/RELAX_NG](http://en.wikipedia.org/wiki/RELAX_NG).
  10 + **Only edit this file when one wants to make changes to the SDT!**
  11 + - [domain.xsd](../src/domain.xsd) : The SDT schema definition that is generated from *domain.rng*.
  12 + - [xml.xsd](../src/xml.xsd) : General schema definitions for the SDT
  13 +- [SDT/schema4.0/test/](../test/) : This directory contains all XML files with SDT definitions that should be validated whether they conform to the SDT schema. This could be example definitions or contributions.
  14 +- [SDT/schema4.0/build.xml](../build.xml) : This is the definition file for the ant build system.
  15 +- [SDT/schema4.0/etc/](../etc/), [SDT/schema4.0/style/](../style/) : internal directories for the build system. Please, don't make unnecessary changes to these files.
  16 +- [SDT/schema4.0/etc/](../etc), [SDT/schema4.0/style/](../style/) : internal directories for the build system. Please, don't make unnecessary changes to these files.
  17 + - [SDT/schema4.0/etc/dal.rnc](../etc/dal.rnc) : This file contains various configuration parameter to convert the file [domain.rng](../src/domain.rng) to schema file. **The important parameter to change when changing the namespace or the version number is**:
  18 +
  19 + default namespace xsl = "http://homegatewayinitiative.org/xml/dal/3.0"
  20 +
  21 + - [SDT/schema4.0/etc/schemas.xml](../etc/schemas.xml) : This file contains the header for the schema file. **This must be changed when changing the namespace or the version number.**
  22 +- [SDT/schema4.0/lib/](../lib/) : Tasks for the ant-based build system. See also [SDT Build System Components and Licenses](SDT%20Build%20System%20Components%20and%20Licenses.md).
  23 +
  24 +## Installation
  25 +- Install Java on your computer
  26 +- Download and install Apache ant from [http://ant.apache.org](http://ant.apache.org)
  27 +- Clone the SDT repository from GitHub:
  28 +
  29 + $ git clone https://github.com/Homegateway/SmartDeviceTemplate.git
  30 +
  31 +## How to Use the Build System
  32 +After cloning the repository go to the directory *SDT/schema* and run commands depending on what you want to achieve.
  33 +
  34 +### Build the Schema
  35 +Running *ant* without any parameter builds the schema definition from the rng-definition [SDT/schema4.0/src/domain.rng](../src/domain.rng) and writes it to [SDT/schema4.0/src/domain.xsd](../src/domain.xsd)
  36 +
  37 + $ cd SDT/schema
  38 + $ ant
  39 +
  40 +### Validate SDT Definitions
  41 +You can use the build system to validate new SDT definitions or changes made to existing ones by running the following command:
  42 +
  43 + $ cd SDT/schema
  44 + $ ant validate
  45 +
  46 +The output after a successful validation should look like this:
  47 +
  48 +>[schemavalidate] 2 file(s) have been successfully validated.
  49 +>BUILD SUCCESSFUL
  50 +>Total time: 1 second
  51 +
  52 +Otherwise you most likely receive a stack trace or some other error messages. Search the output for the line *BUILD FAILED*. Above this line you will find some helpful hints for the filename and line number on which the error occurred (here: file *mseeb.xml* on line 66) and a reason:
  53 +
  54 +>[schemavalidate] /Users/someone/Sources/git/SmartDeviceTemplate/SDT/schema/test/mseeb.xml:66:18: cvc-elt.1: Cannot find the declaration of element 'Domain'.
  55 +>BUILD FAILED
  56 +
  57 +---
  58 +
  59 +## Editing
  60 +As mentioned above, the actual schema definition is defined in the file [domain.rng](../src/domain.rng) and converted to the XML schema definition [domain.xsd](../src/domain.xsd) during the build process.
  61 +
  62 +**All changes to the schema must therefore be made in [domain.rng](../src/domain.rng), NOT [domain.xsd](../src/domain.xsd) !**
  63 +
  64 +You may need to make additional changes in the following files, e.g. when the name space or the version number need to be adjusted.
  65 +
  66 +PLEASE ONLY EDIT THESE FILES IF NECESSARY.
  67 +
  68 +- [SDT/schema4.0/build.xml](../build.xml)
  69 +e.g. in the *ant* target "validate"
  70 +- [SDT/schema4.0/etc/dal.rnc](../etc/dal.rnc)
  71 +e.g. the entry "default namespace xsl"
  72 +- [SDT/schema4.0/etc/schema.xmlns](../etc/schema.xmlns)
  73 +- [SDT/schema4.0/etc/schemas.xml](../etc/schemas.xml)
... ...
  1 +# SDT Components
  2 +
  3 +[Domain](#Domain)
  4 +[Device](#Device) | [SubDevice](#SubDevice)
  5 +[Property](#Property)
  6 +[Module and ModuleClass](#ModuleClass)
  7 +&nbsp;&nbsp;&nbsp;[Action](#Action)
  8 +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Arg](#Arg)
  9 +&nbsp;&nbsp;&nbsp;[DataPoint](#DataPoint)
  10 +&nbsp;&nbsp;&nbsp;[Event](#Event)
  11 +[Data Types](#Data_Types)
  12 +&nbsp;&nbsp;&nbsp;[DataType](#DataType)
  13 +&nbsp;&nbsp;&nbsp;[Constraint](#Constraint)
  14 +&nbsp;&nbsp;&nbsp;[SimpleType](#SimpleType)
  15 +&nbsp;&nbsp;&nbsp;[StructType](#StructType)
  16 +&nbsp;&nbsp;&nbsp;[ArrayType](#ArrayType)
  17 +[Doc](#Documentation)
  18 +
  19 +---
  20 +
  21 +
  22 +## SDT Overview
  23 +
  24 +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.
  25 +
  26 +![](images/SDT_UML_Basic_Elements.png)
  27 +
  28 +The key to the diagram elements of the UML diagrams above and the snippets in the following sections:
  29 +
  30 +![](images/SDT_UML_Key.png)
  31 +
  32 +<a name="Domain"></a>
  33 +
  34 +The syntax used in the diagram to model an XML Schema Definition (XSD) as an UML diagram follows the following approaches:
  35 +
  36 +- [Design XML schemas using UML](http://www.ibm.com/developerworks/library/x-umlschem/)
  37 +- [UML For W3C XML Schema Design](http://www.xml.com/pub/a/2002/08/07/wxs_uml.html)
  38 +
  39 +### Domain
  40 +
  41 +![](images/Domain.png)
  42 +
  43 +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.
  44 +
  45 +It can also be used to collect all specified [ModuleClasses](#ModuleClasses)
  46 + and [Devices](#Devices) in one referencable logical group.
  47 +
  48 +#### Attributes
  49 +- **id** : The identifier for that *Domain*. Required.
  50 +
  51 +#### Elements
  52 +- **[Doc](#Documentation)** : Documentation for the *Domain*. Optional.
  53 +- **Imports** : XML import/include of other XML files. Optional.
  54 +- **[Module](#ModuleClass)** : A list of those *Module* components that are global to the whole domain. Optional.
  55 +- **[Devices](#Device)** : a List of *Devices* components. Optional.
  56 +
  57 +#### Example
  58 +
  59 + <Domain xmlns:xi="http://www.w3.org/2001/XInclude"
  60 + xmlns="http://homegatewayinitiative.org/xml/dal/3.0"
  61 + id="org.homegatewayinitiative">
  62 + <Doc>Some documentation</Doc>
  63 + <Imports>
  64 + <!-- Import other SDTs via XInclude's include mechanism -->
  65 + <xi:include href="./dal-core.xml" parse="xml" />
  66 + </Imports>
  67 + <Modules>
  68 + <!-- List of Domain global Modules goes here -->
  69 + </Modules>
  70 + <Devices>
  71 + <!-- List of Devices goes here -->
  72 + </Devices>
  73 + </Domain>
  74 +
  75 +---
  76 +
  77 +<a name="Device"/></a>
  78 +### Device
  79 +
  80 +![](images/Device.png)
  81 +
  82 +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).
  83 +
  84 +For each physical device on the network at least one *Device* **must** be defined. If the physical device is a simple device, i.e. 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, i.e. it does contain embedded devices that can be addressed separately, the *Device* **should** contain [SubDevices](SubDevices) for each of the identifiable embedded devices.
  85 +
  86 +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".
  87 +
  88 +*Devices* may define their own [ModuleClasses](#ModuleClass) or refer to predefined ModulesClasses of the same or another [Domain](Domain).
  89 +
  90 +#### Attributes
  91 +- **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.
  92 +
  93 +#### Elements
  94 +
  95 +- **[Doc](#Documentation)** : Documentation for the *Device*. Optional.
  96 +- **[Properties](#Property)** : Further meta-data (or properties) about the *Device*. Optional.
  97 +- **[Modules](#ModuleClass)** : A list of *Module* components that are local to the *Device*. Optional.
  98 +- **[SubDevices](#SubDevice)** : A list of *SubDevice* components. Optional.
  99 +
  100 +#### Example
  101 +
  102 + <Device id="aDevice">
  103 + <Doc>Some documentation</Doc>
  104 + <Properties>
  105 + <!-- The list of Properties for the Device goes here-->
  106 + </Properties>
  107 + <Modules>
  108 + <!-- List of Modules local to the Device goes here-->
  109 + </Modules>
  110 + <SubDevices>
  111 + <!-- List of Sub-Devices of the Device goes here-->
  112 + </SubDevices>
  113 + </Device>
  114 +
  115 +---
  116 +
  117 +<a name="SubDevice"/></a>
  118 +### SubDevice
  119 +*SubDevices* are optional components of a [Device](#Device). They represent physical sub-devices and services inside another device (the *Device*).
  120 +
  121 +*SubDevices* may define their own [ModuleClasses](#ModuleClass) or extend *ModuleClasses* of it's or another [Domain](#Domain).
  122 +
  123 +![](images/SubDevice.png)
  124 +
  125 +#### Attributes
  126 +- **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.
  127 +
  128 +#### Elements
  129 +- **[Doc](#Documentation)** : Documentation for the *SubDevice*. Optional.
  130 +- **[Properties](#Property)** : Further meta-data (or properties) about the *SubDevice*. Optional.
  131 +- **[Modules](#ModuleClass)** : A list of *Module* components that are local to the *SubDevice*. Optional.
  132 +
  133 +#### Example
  134 +
  135 + <SubDevice id="aSubDevice">
  136 + <Doc>Some documentation</Doc>
  137 + <Properties>
  138 + <!-- The list of Properties for the Device goes here-->
  139 + </Properties>
  140 + <Modules>
  141 + <!-- List of Modules local to the Device goes here-->
  142 + </Modules>
  143 + </SubDevice>
  144 +
  145 +---
  146 +
  147 +<a name="Property"/></a>
  148 +### Property : Element of a *Device* or *ModuleClass*
  149 +
  150 +![](images/Property.png)
  151 +
  152 +*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.
  153 +
  154 +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 specify 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).
  155 +
  156 +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.
  157 +
  158 +#### Attributes
  159 +- **name**: Name or identifier of a *Property*.
  160 +- **optional**: Boolean that indicates whether a *Property* is optional or mandatory. Optional, the default is *false*.
  161 +- **value**: Text representation of value of a *Property*. Optional.
  162 +
  163 +#### Elements
  164 +- **[Doc](#Documentation)** : Documentation for the *Property*. Optional.
  165 +- **DataType** : The data type of the property. This must be a [SimpleType](#SimpleType).
  166 +
  167 +#### Example
  168 +
  169 + <Property name="ManufacturedDate" value="2015.10.30 10:06">
  170 + <SimpleType type="datetime" />
  171 + </Property>
  172 +
  173 +---
  174 +
  175 +<a name="ModuleClass"/></a>
  176 +### Module and ModuleClass
  177 +
  178 +![](images/ModuleClass.png)
  179 +
  180 +**Module**
  181 +
  182 +*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*.
  183 +
  184 +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.
  185 +
  186 +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.
  187 +
  188 +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.
  189 +
  190 +**ModuleClass**
  191 +
  192 +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).
  193 +
  194 +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.
  195 +
  196 +#### Attributes
  197 +- **name** : Name of the *Module* or *ModuleClass*. The name must be unique in the scope of the [Domain](#Domain). Required.
  198 +- **optional**: Boolean that indicates whether a *Module* or *ModuleClass* is optional or mandatory. Optional, the default is *false*.
  199 +
  200 +#### Elements
  201 +
  202 +- **[Doc](#Documentation)** : Documentation for the *Module* or *ModuleClass*. Optional.
  203 +- **extends** : Reference to a another *ModuleClass* or *Module* which is extended with this *ModuleClass*. Optional.
  204 +The element has the following attributes:
  205 + - **domain** : Identifier / Reference of the [Domain](#Domain) of the extended *ModuleClass*. Required for this element.
  206 + - **class** : Name of the *ModuleClass* in the [Domain](#Domain) that is extended. Required for this element.
  207 +- **[Properties](#Property)** : Further meta-data (or properties) about the *Module* or *ModuleClass*. Optional.
  208 +- **[Actions](#Action)** : A list of *Action* components, each defining a single action. Optional.
  209 +- **[Data](#DataPoint)** : A list of *DataPoint* components. Optional.
  210 +- **[Events](#Event)** : A list of *Event* components. Optional.
  211 +
  212 +#### Example
  213 +
  214 + <ModuleClass name="BooleanState">
  215 + <Doc>Some documentation</Doc>
  216 + <Actions>
  217 + <!-- List of Actions goes here-->
  218 + </Actions>
  219 + <Events>
  220 + <!-- List of Events goes here-->
  221 + </Events
  222 + <Data>
  223 + <!-- List of DataPoints goes here-->
  224 + </Data>
  225 + </ModuleClass>
  226 +
  227 +---
  228 +
  229 +<a name="DataPoint"/></a>
  230 +### DataPoint : Element of *ModuleClass* and *Event*
  231 +
  232 +![](images/DataPoint.png)
  233 +
  234 +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.
  235 +
  236 +However, *DataPoints* are not the only way of controlling devices, so further [Actions](#Action) and [Events](#Event) are described below.
  237 +
  238 +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.
  239 +
  240 +In EBNF:
  241 +
  242 + name = dataPointName | "/" path ;
  243 + path = segment "/" path | dataPointName ;
  244 + segment = string ;
  245 + dataPointName = string ;
  246 + string = (* character string excluding the character "/" *) ;
  247 +
  248 +
  249 +#### Attributes
  250 +- **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.
  251 +- **optional**: Boolean that indicates whether a *DataPoint* is optional or mandatory. Optional, the default is *false*.
  252 +- **writable** : Boolean value that indicates whether this *DataPoint* is writable by an application. Optional. Default: true.
  253 +- **readable** : Boolean value that indicates whether this *DataPoint* is readable by an application. Optional. Default: true.
  254 +- **eventable** : Boolean value that indicates whether an internal or external change of this *DataPoint* raises an event. Optional. Default: false.
  255 +
  256 +#### Elements
  257 +- **[Doc](#Documentation)** : Documentation for the *DataPoint*. Optional.
  258 +- **[DataType](#DataType)** : The type of the *DataPoint*. It must comply to the *DataType* definition. Required.
  259 +
  260 +#### Example
  261 +
  262 + <Data>
  263 + <DataPoint name="attributeName" writable="false">
  264 + <Doc>Some documentation for the DataPoint</Doc>
  265 + <DataType>
  266 + <SimpleType type="string" />
  267 + </DataType
  268 + </DataPoint>
  269 + </Data>
  270 +
  271 +---
  272 +
  273 +<a name="Action"/></a>
  274 +### Action : Element of *ModuleClass*
  275 +
  276 +![](images/Action.png)
  277 +
  278 +*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.
  279 +
  280 +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.
  281 +
  282 +#### Attributes
  283 +- **name** : The name of the *Action*. The name must be unique in the scope of the [ModuleClass](#ModuleClass). Required.
  284 +- **optional**: Boolean that indicates whether an *Action* is optional or mandatory. Optional, the default is *false*.
  285 +
  286 +#### Elements
  287 +- **[Doc](#Documentation)** : Documentation for the *Action*. Optional.
  288 +- **[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.
  289 +- **Args** : Zero or more occurances of [argument](#Arg) definitions for an *Action*. Optional.
  290 +
  291 +<a name="ActionExample"/></a>
  292 +#### Example
  293 +The following are two examples for actions implementing a getter and a setter for boolean values.
  294 +
  295 + <Action name="get" type="boolean">
  296 + <Doc>Obtain the current associated state. Example of a getter.</Doc>
  297 + </Action>
  298 +
  299 + <Action name="setTarget">
  300 + <Doc>Set the associated state to the specified value. Example of a setter.</Doc>
  301 + <Args>
  302 + <Arg name="value">
  303 + <Doc>The desired value of the associated state.</Doc>
  304 + <DataType>
  305 + <SimpleType type="boolean" />
  306 + </DataType>
  307 + </Arg>
  308 + </Args>
  309 + </Action>
  310 +
  311 +---
  312 +
  313 +<a name="Event"/></a>
  314 +### Event : Element of *ModuleClass*
  315 +
  316 +![](images/Event.png)
  317 +
  318 +*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.
  319 +
  320 +#### Attributes
  321 +- **name** : The name of the *Event*. The name must be unique in the scope of the [ModuleClass](#ModuleClass). Required.
  322 +- **optional**: Boolean that indicates whether an *Event* is optional or mandatory. Optional, the default is *false*.
  323 +
  324 +#### Elements
  325 +- **[Doc](#Documentation)** : Documentation for the *Event* Element. Optional.
  326 +- **[Data](#DataPoint)** : A list of *DataPoint* components for an event's payload. Optional.
  327 +
  328 +#### Example
  329 +
  330 + <Event name="stateChanged">
  331 + <Doc>Some documentation for the Event</Doc>
  332 + <Data>
  333 + <DataPoint name="state">
  334 + <DataType>
  335 + <SimpleType type="boolean" />
  336 + </DataType>
  337 + </DataPoint>
  338 + </Data>
  339 + </Event>
  340 +
  341 +---
  342 +
  343 +<a name="Arg"/></a>
  344 +### Arg : Element of *Action*
  345 +
  346 +![](images/Arg.png)
  347 +
  348 +The *Arg* element represents the parameter information which a device needs to carry out a required *Action*.
  349 +
  350 +The *Arg* has the following attributes and elements:
  351 +
  352 +#### Attributes
  353 +- **name** : The name of the *Arg* attribute. Required.
  354 +
  355 +#### Elements
  356 +- **[Doc](#Documentation)** : Documentation for the *argument*. Optional.
  357 +- **[DataType](#DataType)** : The return type of the *argument*. It must comply to the *DataType* definition. Required.
  358 +
  359 +#### Example
  360 +See [example above](#ActionExample).
  361 +
  362 +---
  363 +
  364 +<a name="Data_Types"/></a>
  365 +### DataType
  366 +The data type can be simple integers or string text, or rather complex, as shown below:
  367 +
  368 +![](images/SDT_UML_DataType.png)
  369 +
  370 +The various elements are described in the sections below.
  371 +
  372 +![](images/DataType.png)
  373 +
  374 +The *DataType* element is a "container" for the various aspects of a type.
  375 +
  376 +#### Attributes
  377 +- **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.
  378 +- **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.
  379 +
  380 +#### Elements
  381 +- **[Doc](#Documentation)** : Documentation for the *DataType* Element. Optional.
  382 +- **TypeChoice** : This element is actual an element from the following list of data types:
  383 + - **[SimpleType](#SimpleType)**
  384 + - **[Struct](#StructType)**
  385 + - **[Array](#ArrayType)**
  386 +- **[Constraint](#Constraint)** : A list of *Constraint* elements. Optional.
  387 +
  388 +---
  389 +
  390 +<a name="Constraint"/></a>
  391 +### Constraint : Element of DataType
  392 +
  393 +![](images/Constraint.png)
  394 +
  395 +The *Constraint* element is an optional element allowing the manufacturer to provide constraints on the permitted values of measured data or input parameters. It can significantly improve the reliability of software and validation of transmitted data.
  396 +
  397 +#### Attributes
  398 +- **name** : The name or ID that identifies the *Constraint*. Required.
  399 +- **type** : The basic data type of the constraint. Note that this may be different from the type of the [DataType](#DataType) that this *Constraint* is assigned to. For example, a *Constraint* that specifies a maximum length of a string is of type *integer*. Optional.
  400 +- **value** : A pre-assigned value for the constraint, for example the maximum number of characters in a string. Optional.
  401 +
  402 +#### Elements
  403 +- **[Doc](#Documentation)** : Documentation for the *Cosntraint* Element. Optional.
  404 +
  405 +---
  406 +
  407 +### TypeChoice : Construct of *DataType*
  408 +
  409 + ![](images/TypeChoice.png)
  410 +
  411 +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.
  412 +
  413 +---
  414 +
  415 +<a name="SimpleType"/></a>
  416 +### SimpleType : Element of *TypeChoice*
  417 +
  418 +![](images/SimpleType.png)
  419 +
  420 +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:
  421 +
  422 +1. the (technically redundant) options of *date* and *time* - to avoid problems which can arise interpreting a *datetime* value;
  423 +2. *url* because it is expected to become extremely common to provide links to other data sources;
  424 +3. the "blob" type to represent binary data of arbitrary structure.
  425 +
  426 +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):
  427 +
  428 +- **boolean** : A boolean value as defined in [http://www.w3.org/TR/xmlschema-2/#boolean](http://www.w3.org/TR/xmlschema-2/#boolean) .
  429 +- **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) .
  430 +- **integer** : An integer value as defined in [http://www.w3.org/TR/xmlschema-2/#integer](http://www.w3.org/TR/xmlschema-2/#integer) .
  431 +- **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) .
  432 +- **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) .
  433 +- **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.
  434 +- **date** : A date value as defined in [http://www.w3.org/TR/xmlschema-2/#date](http://www.w3.org/TR/xmlschema-2/#date) .
  435 +- **time** : A time value as defined in [http://www.w3.org/TR/xmlschema-2/#time](http://www.w3.org/TR/xmlschema-2/#time) .
  436 +- **datetime** : A time value as defined in [http://www.w3.org/TR/xmlschema-2/#dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) .
  437 +- **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) .
  438 +- **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) .
  439 +
  440 +---
  441 +
  442 +<a name="StructType"/></a>
  443 +### StructType : Element of *TypeChoice*
  444 +
  445 +![](images/Struct.png)
  446 +
  447 +The *StructType* element can be used to represent an ordered list of diverse DataTypes, which are represented by the *name* attribute of each [DataType](#DataType), and can be used recursively.
  448 +
  449 +#### Elements
  450 +- **[DataType](#DataType)** : A list of DataTypes elements representing the elements of a structure.
  451 +
  452 +
  453 +---
  454 +
  455 +<a name="ArrayType"/></a>
  456 +### ArrayType : Element of *TypeChoice*
  457 +
  458 +![](images/Array.png)
  459 +
  460 +The *ArrayType* element is provided for defining lists of data; the definition is recursive so that multi-dimensional arrays can be described. Note that a Constraint can be used to provide limits on Array size.
  461 +
  462 +#### Elements
  463 +- **[DataType](#DataType)** : A single DataType element that specifies the data type for the elements of the array.
  464 +
  465 +---
  466 +
  467 +<a name="Documentation"/></a>
  468 +### Doc : Element for all Documentation
  469 +
  470 +![](images/Doc.png)
  471 +
  472 +*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).
  473 +
  474 +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:
  475 +
  476 +
  477 + Doc = "<Doc>" docContent "</Doc" ;
  478 + docContent = docText | { paragraph | image } ;
  479 + docText = { text | emphasizedText | boldText | monotypeText } ;
  480 + emphasizedText = "<em>" text "</em>" ;
  481 + boldText = "<b>" text "</b>" ;
  482 + monotypeText = "<tt>" text "</tt>" ;
  483 + paragraph = "<p>" docText "</p>" ;
  484 + image = "<img src=" url ">" "<caption>" text "</caption>" "</img>" ;
  485 + url = "\"" (* valid URL *) "\"" ;
  486 + text = (* XML text element *) ;
  487 +
  488 +
  489 +The intended use for each element is:
  490 +
  491 +- **emphasizedText** : Emphasize the included text, e.g. printing it in italics font.
  492 +- **boldText** : Print the included text in bold font.
  493 +- **monotypeText** : Print the included text in a monospaced fonttype, e.g. to emphasize source code.
  494 +- **paragraph** : Structure the text in paragraphs.
  495 +- **image** : Include an image in the text. The image is loaded from the specified URL and must include a caption text.
  496 +
... ...
  1 +<?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2 +<diagram program="umlet" version="13.3">
  3 + <help_text/>
  4 + <zoom_level>7</zoom_level>
  5 + <element>
  6 + <id>UMLNote</id>
  7 + <coordinates>
  8 + <x>21</x>
  9 + <y>427</y>
  10 + <w>217</w>
  11 + <h>182</h>
  12 + </coordinates>
  13 + <panel_attributes>bg=#FAF8C8
  14 +fontsize=12
  15 +/@ optional elementAttribute/
  16 +/@ optional elementAttribute = default value/
  17 +*@ mandatoryElementAttribute*
  18 +- mandatory element : Subclass (exact one)
  19 +/- optionalElement : SubClass (zero or one)/
  20 +/* optionalElement : SubClass (zero or many)/
  21 +
  22 +"Depends" Relation
  23 +and Cardinality
  24 +
  25 +Subclassing
  26 +
  27 +Cardinalities:
  28 +0,1 : zero or one
  29 +1 : exact one
  30 +0..* : zero or many
  31 +1..* : at least one or many
  32 +</panel_attributes>
  33 + <additional_attributes/>
  34 + </element>
  35 + <element>
  36 + <id>Relation</id>
  37 + <coordinates>
  38 + <x>105</x>
  39 + <y>497</y>
  40 + <w>77</w>
  41 + <h>28</h>
  42 + </coordinates>
  43 + <panel_attributes>lt=&lt;.
  44 +fontsize=10
  45 +m1=0..*
  46 +</panel_attributes>
  47 + <additional_attributes>90.0;20.0;10.0;20.0</additional_attributes>
  48 + </element>
  49 + <element>
  50 + <id>Relation</id>
  51 + <coordinates>
  52 + <x>105</x>
  53 + <y>525</y>
  54 + <w>77</w>
  55 + <h>21</h>
  56 + </coordinates>
  57 + <panel_attributes>lt=&lt;&lt;-
  58 +fontsize=10</panel_attributes>
  59 + <additional_attributes>90.0;10.0;10.0;10.0</additional_attributes>
  60 + </element>
  61 + <element>
  62 + <id>UMLClass</id>
  63 + <coordinates>
  64 + <x>651</x>
  65 + <y>770</y>
  66 + <w>105</w>
  67 + <h>154</h>
  68 + </coordinates>
  69 + <panel_attributes>&lt;&lt;enumeration&gt;&gt;
  70 +BasicType
  71 +--
  72 +boolean
  73 +byte
  74 +integer
  75 +float
  76 +string
  77 +enum
  78 +date
  79 +time
  80 +datetime
  81 +blob
  82 +uri</panel_attributes>
  83 + <additional_attributes/>
  84 + </element>
  85 + <element>
  86 + <id>Relation</id>
  87 + <coordinates>
  88 + <x>357</x>
  89 + <y>833</y>
  90 + <w>98</w>
  91 + <h>56</h>
  92 + </coordinates>
  93 + <panel_attributes>lt=&lt;&lt;.
  94 +m1= 0,1
  95 +</panel_attributes>
  96 + <additional_attributes>120.0;50.0;60.0;50.0;60.0;10.0;10.0;10.0</additional_attributes>
  97 + </element>
  98 + <element>
  99 + <id>Relation</id>
  100 + <coordinates>
  101 + <x>357</x>
  102 + <y>777</y>
  103 + <w>98</w>
  104 + <h>56</h>
  105 + </coordinates>
  106 + <panel_attributes>lt=&lt;&lt;.
  107 +m1= 0,1
  108 +</panel_attributes>
  109 + <additional_attributes>120.0;10.0;40.0;10.0;40.0;60.0;10.0;60.0</additional_attributes>
  110 + </element>
  111 + <element>
  112 + <id>UMLClass</id>
  113 + <coordinates>
  114 + <x>21</x>
  115 + <y>777</y>
  116 + <w>133</w>
  117 + <h>84</h>
  118 + </coordinates>
  119 + <panel_attributes>DataType
  120 +--
  121 +/@ name : text/
  122 +/@ unitOfMeasure : text/
  123 +/- Doc : Doc/
  124 +- TypeChoice
  125 +/* Constraints : Constraint/
  126 +fg=blue</panel_attributes>
  127 + <additional_attributes/>
  128 + </element>
  129 + <element>
  130 + <id>Relation</id>
  131 + <coordinates>
  132 + <x>126</x>
  133 + <y>735</y>
  134 + <w>490</w>
  135 + <h>91</h>
  136 + </coordinates>
  137 + <panel_attributes>lt=&lt;&lt;.
  138 +m2=1..*
  139 +</panel_attributes>
  140 + <additional_attributes>10.0;60.0;10.0;20.0;680.0;20.0;680.0;100.0;640.0;100.0</additional_attributes>
  141 + </element>
  142 + <element>
  143 + <id>Relation</id>
  144 + <coordinates>
  145 + <x>126</x>
  146 + <y>735</y>
  147 + <w>490</w>
  148 + <h>133</h>
  149 + </coordinates>
  150 + <panel_attributes>lt=&lt;&lt;.
  151 +m2=1
  152 +</panel_attributes>
  153 + <additional_attributes>10.0;60.0;10.0;20.0;680.0;20.0;680.0;160.0;640.0;160.0</additional_attributes>
  154 + </element>
  155 + <element>
  156 + <id>UMLClass</id>
  157 + <coordinates>
  158 + <x>441</x>
  159 + <y>861</y>
  160 + <w>133</w>
  161 + <h>35</h>
  162 + </coordinates>
  163 + <panel_attributes>SimpleType
  164 +--
  165 +*@ type : BasicType*
  166 +fg=blue</panel_attributes>
  167 + <additional_attributes/>
  168 + </element>
  169 + <element>
  170 + <id>Relation</id>
  171 + <coordinates>
  172 + <x>567</x>
  173 + <y>875</y>
  174 + <w>98</w>
  175 + <h>35</h>
  176 + </coordinates>
  177 + <panel_attributes>lt=&lt;&lt;-
  178 +m1= 1
  179 +</panel_attributes>
  180 + <additional_attributes>120.0;20.0;10.0;20.0</additional_attributes>
  181 + </element>
  182 + <element>
  183 + <id>UMLClass</id>
  184 + <coordinates>
  185 + <x>441</x>
  186 + <y>917</y>
  187 + <w>133</w>
  188 + <h>70</h>
  189 + </coordinates>
  190 + <panel_attributes>Constraint
  191 +--
  192 +*@ name : text*
  193 +/@ type : BasicType/
  194 +/@ value : text/
  195 +/- Doc : Doc/
  196 +fg=blue</panel_attributes>
  197 + <additional_attributes/>
  198 + </element>
  199 + <element>
  200 + <id>Relation</id>
  201 + <coordinates>
  202 + <x>147</x>
  203 + <y>847</y>
  204 + <w>308</w>
  205 + <h>98</h>
  206 + </coordinates>
  207 + <panel_attributes>lt=&lt;.
  208 +m1=0..*
  209 +</panel_attributes>
  210 + <additional_attributes>420.0;110.0;340.0;110.0;340.0;10.0;10.0;10.0</additional_attributes>
  211 + </element>
  212 + <element>
  213 + <id>Relation</id>
  214 + <coordinates>
  215 + <x>567</x>
  216 + <y>917</y>
  217 + <w>147</w>
  218 + <h>56</h>
  219 + </coordinates>
  220 + <panel_attributes>lt=&lt;&lt;-
  221 +m1=1
  222 +</panel_attributes>
  223 + <additional_attributes>190.0;10.0;190.0;60.0;10.0;60.0</additional_attributes>
  224 + </element>
  225 + <element>
  226 + <id>UMLClass</id>
  227 + <coordinates>
  228 + <x>441</x>
  229 + <y>777</y>
  230 + <w>133</w>
  231 + <h>35</h>
  232 + </coordinates>
  233 + <panel_attributes>StructType
  234 +--
  235 +- DataType : DataType
  236 +fg=blue</panel_attributes>
  237 + <additional_attributes/>
  238 + </element>
  239 + <element>
  240 + <id>UMLClass</id>
  241 + <coordinates>
  242 + <x>441</x>
  243 + <y>819</y>
  244 + <w>133</w>
  245 + <h>35</h>
  246 + </coordinates>
  247 + <panel_attributes>ArrayType
  248 +--
  249 +- DataType : DataType
  250 +fg=blue</panel_attributes>
  251 + <additional_attributes/>
  252 + </element>
  253 + <element>
  254 + <id>Relation</id>
  255 + <coordinates>
  256 + <x>357</x>
  257 + <y>812</y>
  258 + <w>98</w>
  259 + <h>35</h>
  260 + </coordinates>
  261 + <panel_attributes>lt=&lt;&lt;.
  262 +m1= 0,1
  263 +
  264 +</panel_attributes>
  265 + <additional_attributes>120.0;20.0;10.0;20.0</additional_attributes>
  266 + </element>
  267 + <element>
  268 + <id>UMLClass</id>
  269 + <coordinates>
  270 + <x>21</x>
  271 + <y>672</y>
  272 + <w>735</w>
  273 + <h>28</h>
  274 + </coordinates>
  275 + <panel_attributes>halign=center
  276 +SDT 3.0 - DataType
  277 +fontsize=24
  278 +bg=gray
  279 +lw=0.1</panel_attributes>
  280 + <additional_attributes/>
  281 + </element>
  282 + <element>
  283 + <id>UMLClass</id>
  284 + <coordinates>
  285 + <x>21</x>
  286 + <y>7</y>
  287 + <w>840</w>
  288 + <h>28</h>
  289 + </coordinates>
  290 + <panel_attributes>SDT 3.0 - Basic Elements
  291 +halign=center
  292 +fontsize=24
  293 +bg=gray
  294 +lw=0.1</panel_attributes>
  295 + <additional_attributes/>
  296 + </element>
  297 + <element>
  298 + <id>UMLClass</id>
  299 + <coordinates>
  300 + <x>259</x>
  301 + <y>126</y>
  302 + <w>154</w>
  303 + <h>133</h>
  304 + </coordinates>
  305 + <panel_attributes>ModuleClass
  306 +--
  307 +*@ name : text*
  308 +/@ optional : boolean = false/
  309 +/- Doc : Doc/
  310 +/- extends/
  311 +/ @domain : IDRF/
  312 +/ @class : text /
  313 +/* Properties : Property/
  314 +/* Actions : Action/
  315 +/* Data : DataPoint/
  316 +/* Events : Event/
  317 +fg=blue
  318 +</panel_attributes>
  319 + <additional_attributes/>
  320 + </element>
  321 + <element>
  322 + <id>UMLClass</id>
  323 + <coordinates>
  324 + <x>497</x>
  325 + <y>126</y>
  326 + <w>154</w>
  327 + <h>77</h>
  328 + </coordinates>
  329 + <panel_attributes>Action
  330 +--
  331 +*@ name : text*
  332 +/@ optional : boolean = false/
  333 +/- Doc : Doc/
  334 +/- DataType : DataType/
  335 +/* Args : Arg/
  336 +fg=blue</panel_attributes>
  337 + <additional_attributes/>
  338 + </element>
  339 + <element>
  340 + <id>UMLClass</id>
  341 + <coordinates>
  342 + <x>742</x>
  343 + <y>189</y>
  344 + <w>119</w>
  345 + <h>56</h>
  346 + </coordinates>
  347 + <panel_attributes>Arg
  348 +--
  349 +*@ name ; text*
  350 +/- Doc : Doc/
  351 +- DataType : DataType
  352 +fg=blue</panel_attributes>
  353 + <additional_attributes/>
  354 + </element>
  355 + <element>
  356 + <id>Relation</id>
  357 + <coordinates>
  358 + <x>644</x>
  359 + <y>189</y>
  360 + <w>112</w>
  361 + <h>28</h>
  362 + </coordinates>
  363 + <panel_attributes>lt=&lt;.
  364 +m1= 0..*</panel_attributes>
  365 + <additional_attributes>140.0;10.0;10.0;10.0</additional_attributes>
  366 + </element>
  367 + <element>
  368 + <id>UMLClass</id>
  369 + <coordinates>
  370 + <x>21</x>
  371 + <y>126</y>
  372 + <w>154</w>
  373 + <h>77</h>
  374 + </coordinates>
  375 + <panel_attributes>Domain
  376 +--
  377 +*@ id : ID*
  378 +/- Doc : Doc/
  379 +/* imports/
  380 +/* Modules : ModuleClass/
  381 +/* Devices : Device/
  382 +fg=blue</panel_attributes>
  383 + <additional_attributes/>
  384 + </element>
  385 + <element>
  386 + <id>Relation</id>
  387 + <coordinates>
  388 + <x>168</x>
  389 + <y>126</y>
  390 + <w>105</w>
  391 + <h>63</h>