Skip to content

GitLab

Commit f1208039 authored by Andreas Kraft's avatar Andreas Kraft
Browse files

Merge pull request #12 from ankraft/sdt3 

Pull request for SDT3 publication
parents 4c6327a9 6990b451
Hide whitespace changes
Inline Side-by-side
Showing with 1624 additions and 21 deletions
README.md
View file @ f1208039
......@@ -2,37 +2,33 @@
Repository for the Smart Device Template (SDT).
**Version 3.0**
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)
Any contributions made to this project must comply with the forementioned license.
Any contributions made to this project must comply with the aforementioned license.
## Quick Introduction
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.
[Read the full Introduction.](SDT/schema3.0/docs/Introduction.md)
## Quick Links
- ['domain.xsd' Version 2.0](SDT/schema2.0/src/domain.xsd)
- [UML Diagram of the SDT 2.0](SDT/schema2.0/docs/images/SDT2.0_UML.png) ([source](SDT/schema2.0/docs/SDT_UML.uxf))
- ['domain.xsd' Version 3.0](SDT/schema3.0/src/domain.xsd)
- [UML Diagram of the SDT 3.0](SDT/schema3.0/docs/UML%20Diagram.md) ([source](SDT/schema3.0/docs/SDT_UML.uxf))
## Content
You can find further Information here:
- [SDT Components](SDT/schema2.0/docs/SDT_Components.md)
- [SDT Build System](SDT/schema2.0/docs/SDT%20Build%20System.md)
- [Examples](SDT/schema2.0/docs/Examples.md)
- [FAQ](SDT/schema2.0/docs/FAQ.md)
- [Links & References](SDT/schema2.0/docs/Links.md)
- [Backlog & Issues](SDT/schema2.0/docs/Backlog.md)
- [Introduction to the SDT](SDT/schema3.0/docs/Introduction.md)
- [SDT Components](SDT/schema3.0/docs/SDT_Components.md)
- [SDT Build System](SDT/schema3.0/docs/SDT%20Build%20System.md)
- [Examples](SDT/schema3.0/docs/Examples.md)
- [Links & References](SDT/schema3.0/docs/Links.md)
- [Changelog](SDT/schema3.0/docs/Changelog.md)
- [LICENSE](LICENSE)
## Changes in 2.0.1
- Added missing "uri" data type.
## Changes in 2.0
- Introduced RootDevice to support hierarchical embedded devices.
- Added new data types (byte, float, array, enum, date, time, datetime, blob, uri)
- Added ``readable`` and ``eventable`` to data points.
- Added otional ``<SerialNumber>``, ``<VendorURL>`` and ``<FirmwareVersion>`` elements to DeviceInfo
- Added optional ``<Doc>`` element to Event
- Changed the optionality of the ``<DataPoint>``'s ``type`` attribute to "required".
- Added [UML diagram](SDT/schema2.0/docs/SDT_Components.md)
- Changed the namespace for the XSD from "hgi.org" to "homegatewayinitiative.org".
SDT/schema2.0/test/EchonetLiteExamples.xml 0 → 100644
View file @ f1208039
<?xml version="1.0" encoding="utf-8"?>
<!-- Example SDT definition taken from EchonetLite https://github.com/ECHONET-Consortium -->
<Domain id="jp.echonet" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns="http://homegatewayinitiative.org/xml/dal/2.0">
<!-- Various examples for module classes -->
<Modules>
<!-- actuator -->
<ModuleClass name="operationStatus">
<Data>
<DataPoint name="operationStatus" type="boolean" writable="true">
<Doc>This property indicates the ON/OFF status.</Doc>
</DataPoint>
</Data>
<Events>
<Event name="operationStatus">
<Data>
</Data>
</Event>
</Events>
</ModuleClass>
<!-- runtime property -->
<ModuleClass name="installationLocation">
<Data>
<DataPoint name="installationLocation" type="string" writable="true">
<Doc>This property indicates the installation location</Doc>
</DataPoint>
</Data>
<Events>
<Event name="installationLocation">
<Data>
</Data>
</Event>
</Events>
</ModuleClass>
<!-- sensor readout -->
<ModuleClass name="measuredInstantaneousPowerConsumption">
<Data>
<DataPoint name="measuredInstantaneousPowerConsumption" type="integer" writable="false">
<Doc>This property indicates the instantaneous power consumption of the device in watts.</Doc>
</DataPoint>
</Data>
</ModuleClass>
<ModuleClass name="temperatureSensorDataPoints">
<Data>
<DataPoint name="measuredTemperatureValue" type="integer" writable="false">
<Doc>This property indicates the measured temperature value in units of 0.1C.</Doc>
</DataPoint>
</Data>
</ModuleClass>
</Modules>
<!-- Very simple example for a washing machine definition -->
<RootDevices>
<RootDevice id="SimpleWaschingMachine">
<DeviceInfo>
<Name>washing machine</Name>
<Vendor>Echonet</Vendor>
</DeviceInfo>
<!-- Inheriting from the global operating status -->
<Modules>
<Module name="washingMachineOperationStatus">
<extends domain="jp.echonet" class="operationStatus"/>
</Module>
<!-- Data points local to the wasching machine device -->
<Module name="washingMachineDataPoints">
<Data>
<DataPoint name="door/CoverOpen/CloseStatus" type="enum" writable="false">
<Doc>This property indicates whether the door/cover is open or closed.</Doc>
</DataPoint>
<DataPoint name="washingMachineSetting" type="enum" writable="true">
<Doc>Washing machine setting</Doc>
</DataPoint>
<DataPoint name="currentStageOfWashingCycle" type="enum" writable="false">
<Doc>This property indicates the current stage of the washing cycle.</Doc>
</DataPoint>
<DataPoint name="timeRemainingToCompleteWashingCycle" type="time" writable="false">
<Doc>This property indicates the time remaining to complete the current washing cycle in the HH:MM:SS format.</Doc>
</DataPoint>
<DataPoint name="onTimerReservationSetting" type="enum" writable="true">
<Doc>Reservation ON/OFF</Doc>
</DataPoint>
<DataPoint name="onTimerSetting" type="time" writable="true">
<Doc>Timer value (HH:MM)</Doc>
</DataPoint>
<DataPoint name="relativeTimeBasedOnTimerSetting" type="time" writable="true">
<Doc>Timer value (HH:MM)</Doc>
</DataPoint>
</Data>
</Module>
</Modules>
</RootDevice>
</RootDevices>
</Domain>
\ No newline at end of file
SDT/schema3.0/build.xml 0 → 100644
View file @ f1208039
<?xml version="1.0" encoding="UTF-8" ?>
<!-- - HGI Device Abstraction Layer - - - - - - - - - - - - - - - - - - - - -->
<!-- -->
<!-- Extends the standard build with targets for: -->
<!-- - generate XML schema the from Relax NG (xml) description -->
<!-- - validate DAL documents against the XML Schema -->
<!-- - generate HTML documentation from DAL documents -->
<project name="importing" basedir="." default="schemas">
<import file="etc/common.xml"/>
<!-- Read the namespace declarations from a file (to get linebreaks) - - - -->
<loadfile property="schema.xmlns" srcFile="${basedir}/etc/schema.xmlns"/>
<!-- The RNG file the XML and RNC schemas are generaed from - - - - - - - -->
<property name="schema.name" value="domain"/>
<property name="schema.rng" value="${path.src}/${schema.name}.rng"/>
<!-- HTML - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- -->
<!-- Generate HTML documentation from domain definitions in the test -->
<!-- directory. The module classes included via the extends tagged are -->
<!-- included in the documentation - so an xinclude capable XSL engine is -->
<!-- needed. -->
<!-- This needs Ant version 1.8+ and it must be augmented with an current -->
<!-- version of Xerces. Download the binray distribution and place the put -->
<!-- xml-apis.jar and xercesImpl.jar in the Ant lib directory. -->
<target name="html">
<mkdir dir="${path.genbase}" />
<xslt basedir="${basedir}/test" destdir="${basedir}/gen/html"
style="${basedir}/style/html.xsl">
<param name="destdir" expression="${basedir}/gen/html"/>
<sysproperty
key="org.apache.xerces.xni.parser.XMLParserConfiguration"
value="org.apache.xerces.parsers.XIncludeParserConfiguration"/>
</xslt>
</target>
<!-- Schemas - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- -->
<!-- The schema is specified using Relax NG (xml) and trang is used to -->
<!-- generate the XML schema. The schema is also generated in Relay NG -->
<!-- compact syntax, which is used by some validating editors (e.g. emacs) -->
<!-- The resulting schemas need some additional patching before thy are -->
<!-- usable -->
<target name="schemas">
<java jar="${basedir}/lib/trang.jar" fork="true">
<arg value="${schema.rng}"/>
<arg value="${basedir}/etc/${schema.name}.rnc"/>
</java>
<!-- So that the editor does not complain about include directives, the -->
<!-- resulting schema is included in another schema, which includes the -->
<!-- necessary element definitions. To be able to do this the -->
<!-- definition for Imports must be deleted from this generated schema. -->
<replace file="${basedir}/etc/${schema.name}.rnc"
token="Imports = element Imports { Domain* }?" value=""/>
<java jar="${basedir}/lib/trang.jar" fork="true">
<arg value="${schema.rng}"/>
<arg value="${path.src}/${schema.name}.xsd"/>
</java>
<!-- Can't validate against the generated schema unless we add the -->
<!-- target and default namespaces ... -->
<replace file='${path.src}/domain.xsd'
token='xmlns:xs="http://www.w3.org/2001/XMLSchema"'
value='${schema.xmlns}'/>
<!-- In addition the xml:base tag, which is added automatically when -->
<!-- including a document, must also be permitted by out schema. -->
<!-- The schema generated from RNG is almost correct schema ... but -->
<!-- the schemaLocation is wrong. -->
<replace file='${path.src}/domain.xsd'
token="xml.xsd" value="http://www.w3.org/2001/03/xml.xsd"/>
</target>
<!-- Validate - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- -->
<!-- Check the Device Description conforms to the Device Abstraction -->
<!-- Schema. Note that we need to activate support for XML includes -->
<target name="validate" depends="">
<schemavalidate warn="true">
<fileset dir="${basedir}/test" includes="*.xml"/>
<attribute name="http://apache.org/xml/features/xinclude" value="true"/>
<schema namespace="http://homegatewayinitiative.org/xml/dal/3.0"
file="${path.src}/domain.xsd" />
<schema namespace="http://www.w3.org/2001/XInclude"
file="${basedir}/etc/XInclude.xsd" />
<schema namespace="http://www.w3.org/2001/XMLSchema"
file="${basedir}/etc/XMLSchema.xsd" />
</schemavalidate>
</target>
</project>
SDT/schema3.0/docs/Changelog.md 0 → 100644
View file @ f1208039
# Changelog
## Changes in 3.0
- Renamed ``<RootDevice>``to ``<Device>`` and ``<Device>`` to ``<SubDevice>``,
- Added complex data types: *Struct* and *Arrays*.
- Simplified the UML diagram. Split the UML diagram into two parts, one for the base elements and one for the data types.
- In the UML diagram: Moved ``<extends>`` into the UML ``<ModuleClass>`` element (easier to read).
- Added support to specify *Units of Measurement* to data types,
- Added ``<Doc>`` to ``<Domain>`` and other elements.
- ``<Doc>`` is now always the first part of an element.
- Changed ``<DeviceInfo>`` element to a list of ``<Characteristic>``.
- Added ``<Characteristic>`` list to ``<Modules>`` and ``<ModuleClasses>``.
- The ``<data>`` element in ``<Event>`` is now optional to support events without attached or associated data.
- In Actions: Added ``<Args>`` as a surrounding list around a list of ``<Arg>``.
- Added *Constraints* to ``<DataType>``.
- Added optional *name* attribute to ``<DataType>``. This mandatory for elements of a *struct*.
- Restructured the [RNG](SDT/schema3.0/src/domain.rng) file for better readability and maintainability.
- 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).
## Changes in 2.0.1
- Added missing "uri" data type.
## Changes in 2.0
- Introduced RootDevice to support hierarchical embedded devices.
- Added new data types (byte, float, array, enum, date, time, datetime, blob, uri)
- Added ``readable`` and ``eventable`` to data points.
- Added optional ``<SerialNumber>``, ``<VendorURL>`` and ``<FirmwareVersion>`` elements to DeviceInfo
- Added optional ``<Doc>`` element to Event
- Changed the optionality of the ``<DataPoint>``'s ``type`` attribute to "required".
- Added [UML diagram](SDT/schema2.0/docs/SDT_Components.md)
- Changed the namespace for the XSD from "hgi.org" to "homegatewayinitiative.org".
\ No newline at end of file
SDT/schema3.0/docs/Examples.md 0 → 100644
View file @ f1208039
# Examples and Contributions
## HGI
### Multi Socket Electrical-Extension-Block
[mseeb.xml](../test/mseeb.xml)
![Multi Socket Electrical-Extension-Block Structure](images/examples/hgi_mseeb.png)
## DECT ULE
## Echonet
## EnOcean
\ No newline at end of file
SDT/schema3.0/docs/FAQ.md 0 → 100644
View file @ f1208039
# Frequently Asked Questions
## What is the HGI?
tbd
## What is the SDT?
tbd
SDT/schema3.0/docs/Introduction.md 0 → 100644
View file @ f1208039
# Introduction to the SDT
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.
## The goal
Interoperability for smart-home and other IoT-related applications and Internet-of-Things devices and services is a key objective that is not currently easy to meet, because of the many types of technology specific device interfaces in wide deployment. There is no accepted standard.
A major goal for service providers is that software developers should be able to write application software which would handle most of the commonly used functions for any device, irrespective of the device technology. Furthermore, software developers should not have to make major changes to the software in case a new device of similar function but of a different interface technology is used.
If these goals were fully or even partly met, major advantages can be obtained:
- Service Providers would be more able to deploy and support select new technology types of devices, because existing software application code could be more easily adapted to the new device technology.
- Devices of multiple technology types could be deployed and supported by the same platform (e.g. a Home Gateway), and applications could more easily communicate with them simultaneously.
- Devices of multiple technology types could be deployed by a service provider in different regions or homes, but common application code could be used to support applications. For example, a home automation application could support ECHONET devices in one set of homes, and ZigBee devices in another
- Makers of software application code can more easily support multiple device technology types
- Vendors using newer device technologies could more easily bring their products to new markets.
The interoperability benefits can potentially partially obtain 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.
## How should SDT work?
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.
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.
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.
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.
The sections below explain this in more detail.
## How does the SDT approach simplify software development?
Simplification is achieved in software development by first developing methods to handle common or general functions, then treating necessary "uncommon" functions as extensions; treating each functionality as an individual special case does not scale. Identifying the general functions is often called "abstracting".
There are four major levels of progressively greater abstraction in the signaling and software along the path between a sensor (or actuator) and a software application installed in the cloud:
1. a LAN protocol can provide a common set of signaling methods for all compatible sensors/actuators/devices (abstraction at the LAN-controller)
2. a local gateway software can provide common functions to operate diverse kinds of LAN-controllers (abstraction in the local gateway)
3. an IoT platform in the WAN can interoperate with a number of WAN protocols supported by different kinds of gateways (abstraction at the IoT platform)
4. software in the Cloud can interact with diverse IoT platforms and other software applications (abstraction in the Cloud)
The concept of the SDT was created in order to make life easier for the software developer working particularly at the second level, creating software for local gateways to interact with devices connected by various kinds of (wireless) LAN technologies/protocols. The same information written into XML instantiations of the SDT do describe sensors or appliances can also be very valuable, however, to applications in the Cloud, helping to interpret the data.
Currently 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++, ...).
In general a description of device (or complex appliance) behaviour can be made in many ways, with various kinds of constraints:
1. no constraints (e.g. using OWL 2.0 or even more "flexibly" RDF)
2. moderate constraints (e.g. using XML and a related extensible XSD template)
3. strict constraints (typical for a device certified to interoperate with a specific LAN protocol)
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.
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.
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).
## Related aspects which are out of scope of the SDT
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.
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. This 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 not in an XML giving specific details for a device.
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.
SDT/schema3.0/docs/Links.md 0 → 100644
View file @ f1208039
# Links & References
- **HGI** : [http://www.homegatewayinitiative.org](http://www.homegatewayinitiative.org)
## XML
- **RELAX NG** : [http://relaxng.org](http://relaxng.org)
- **RELAX NG Tutorial** : [http://relaxng.org/tutorial-20011203.html](http://relaxng.org/tutorial-20011203.html)
## Tools
- **UMLet** : [http://www.umlet.com](http://www.umlet.com)
The free UML drawing tool used to draw the UML file.
- **Apache Ant** : [http://ant.apache.org](http://ant.apache.org)
Build tool
SDT/schema3.0/docs/SDT Build System Components and Licenses.md 0 → 100644
View file @ f1208039
# Build System Libraries and Licenses
The following libraries are used in the build system for the SDT.
## trang.jar
[http://www.thaiopensource.com/relaxng/trang-manual.html](http://www.thaiopensource.com/relaxng/trang-manual.html)
*Trang* takes as input a schema written in any of the following formats:
- RELAX NG (XML syntax)
- RELAX NG (compact syntax)
- XML 1.0 DTD
and produces as output a schema written in any of the following formats:
- RELAX NG (XML syntax)
- RELAX NG (compact syntax)
- XML 1.0 DTD
- W3C XML Schema
*Trang* can also infer a schema from one or more example XML documents.
### License
Copyright (c) 2002, 2003, 2008 Thai Open Source Software Center Ltd
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- 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.
- 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.
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 REGENTS 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.
## Ant-Contrib Tasks
[http://ant-contrib.sourceforge.net](http://ant-contrib.sourceforge.net)
The *Ant-Contrib* project is a collection of tasks (and at one point maybe types and other tools) for Apache Ant.
### License
This Software is distributed under the Apache Software License.
## antSetLogLevel.jar
GUI dialog for Ant tasks.
Source: Deutsche Telekom
SDT/schema3.0/docs/SDT Build System.md 0 → 100644
View file @ f1208039
# SDT Build System
This document describes the SDT build system and how to build the SDT and validate new contributions.
The files referenced in this document point to version **3.0** of the SDT.
## Directory Structure and Important Files
- [SDT/schema3.0/](../..) : Base directory
- [SDT/schema3.0/src/](../src/) : Source files of the SDT.
- [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).
**Only edit this file when one wants to make changes to the SDT!**
- [domain.xsd](../src/domain.xsd) : The SDT schema definition that is generated from *domain.rng*.
- [xml.xsd](../src/xml.xsd) : General schema definitions for the SDT
- [SDT/schema3.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.
- [SDT/schema3.0/build.xml](../build.xml) : This is the definition file for the ant build system.
- [SDT/schema3.0/etc/](../etc/), [SDT/schema3.0/style/](../style/) : internal directories for the build system. Please, don't make unnecessary changes to these files.
- [SDT/schema3.0/etc/](../etc), [SDT/schema3.0/style/](../style/) : internal directories for the build system. Please, don't make unnecessary changes to these files.
- [SDT/schema3.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**:
default namespace xsl = "http://homegatewayinitiative.org/xml/dal/3.0"
- [SDT/schema3.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.**
- [SDT/schema3.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).
## Installation
- Install Java on your computer
- Download and install Apache ant from [http://ant.apache.org](http://ant.apache.org)
- Clone the SDT repository from GitHub:
$ git clone https://github.com/Homegateway/SmartDeviceTemplate.git
## How to Use the Build System
After cloning the repository go to the directory *SDT/schema* and run commands depending on what you want to achieve.
### Build the Schema
Running *ant* without any parameter builds the schema definition from the rng-definition [SDT/schema3.0/src/domain.rng](../src/domain.rng) and writes it to [SDT/schema3.0/src/domain.xsd](../src/domain.xsd)
$ cd SDT/schema
$ ant
### Validate SDT Definitions
You can use the build system to validate new SDT definitions or changes made to existing ones by running the following command:
$ cd SDT/schema
$ ant validate
The output after a successful validation should look like this:
>[schemavalidate] 2 file(s) have been successfully validated.
>BUILD SUCCESSFUL
>Total time: 1 second
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:
>[schemavalidate] /Users/someone/Sources/git/SmartDeviceTemplate/SDT/schema/test/mseeb.xml:66:18: cvc-elt.1: Cannot find the declaration of element 'Domain'.
>BUILD FAILED
---
## Editing
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.
**All changes to the schema must therefore be made in [domain.rng](../src/domain.rng), NOT [domain.xsd](../src/domain.xsd) !**
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.
PLEASE ONLY EDIT THESE FILES IF NECESSARY.
- [SDT/schema3.0/build.xml](../build.xml)
e.g. in the *ant* target "validate"
- [SDT/schema3.0/etc/dal.rnc](../etc/dal.rnc)
e.g. the entry "default namespace xsl"
- [SDT/schema3.0/etc/schema.xmlns](../etc/schema.xmlns)
- [SDT/schema3.0/etc/schemas.xml](../etc/schemas.xml)
SDT/schema3.0/docs/SDT_Components.md 0 → 100644
View file @ f1208039
# SDT Components
[Domain](#Domain)
[RootDevice](#RootDevice) | [Device](#Device)
&nbsp;&nbsp;&nbsp;[DeviceInfo](#DeviceInfo)
[ModuleClass](#ModuleClass)
&nbsp;&nbsp;&nbsp;[Action](#Action)
&nbsp;&nbsp;&nbsp;[Data / DataPoint](#Data)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[DataType](#DataType)
&nbsp;&nbsp;&nbsp;[Event](#Event)
[Doc](#Documentation)
---
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.
![](images/SDT_UML_Basic_Elements.png)
The [DataType](#DataType) strukture is shown in the following UML diagram:
![](images/SDT_UML_DataType.png)
The key to the diagram elements of the UML diagrams above and the snippets in the following sections:
![](images/SDT_UML_Key.png)
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