Commit ff65d14c authored by ankraft's avatar ankraft
Browse files

Merge branch 'WI-0081-Smart_Device_Template_4_0' into...

Merge branch 'WI-0081-Smart_Device_Template_4_0' into RDM-2019-0003-SDT_4_0_–_Proposed_Changes_to_XSD
parents 4d34f5bd 26fd5342
Copyright 2018, oneM2M Partners Type 1
Copyright 2019, oneM2M Partners Type 1
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
......@@ -8,4 +8,4 @@ Redistribution and use in source and binary forms, with or without modification,
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.
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.
\ No newline at end of file
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.
# Smart Device Template
Repository for the Smart Device Template (SDT).
Repository and documentation for the Smart Device Template (SDT).
**Version 4.0**
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).
The Smart Device Template is available 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).
Any contributions made to this project must comply with the aforementioned license.
Any contributions made to the Smart Device Template format must comply with the aforementioned license. Models defined by using the Smart Device Template can be published under different licenses.
## 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.
![](SDT/schema4.0/docs/images/SDT_simplified.png)
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/schema4.0/docs/Introduction.md)
## Quick Links
- ['domain.xsd' Version 4.0](SDT/schema4.0/src/domain.xsd)
- [UML Diagram of the SDT 4.0](SDT/schema4.0/docs/UML%20Diagram.md) ([source](SDT/schema4.0/docs/SDT_UML.uxf))
- [UML Diagram of the SDT 4.0](SDT/schema4.0/docs/UML%20Diagram.md) ([Umlet source](SDT/schema4.0/docs/SDT_UML.uxf)) : This UML diagram describes the various components of the SDT and their relations.
- ['domain.xsd' Version 4.0](SDT/schema4.0/src/domain.xsd) : This is the XSD schema file that defines the SDT XML Schema.
## Content
## Documentation
You can find further Information here:
- [Introduction to the SDT](SDT/schema4.0/docs/Introduction.md)
- [SDT Components](SDT/schema4.0/docs/SDT_Components.md)
- [JSON Serializatoin](SDT/schema4.0/docs/SDT_JSON.md)
- [SDT Build System](SDT/schema4.0/docs/SDT%20Build%20System.md)
- [JSON Serialization](SDT/schema4.0/docs/SDT_JSON.md)
- [Examples](SDT/schema4.0/docs/Examples.md)
- [SDT Build System](SDT/schema4.0/docs/SDT%20Build%20System.md)
## Further Readings
- [Links & References](SDT/schema4.0/docs/Links.md)
- [FAQ](SDT/schema4.0/docs/FAQ.md)
- [Changelog](SDT/schema4.0/docs/Changelog.md)
- [SDT Build System Components and Licenses](SDT/schema4.0/docs/SDT%20Build%20System%20Components%20and%20Licenses.md)
- [LICENSE](LICENSE)
<?xml version="1.0" encoding="UTF-8" ?>
<!-- - HGI Device Abstraction Layer - - - - - - - - - - - - - - - - - - - - -->
<!-- SDT - Smart Device Template Build File -->
<!-- -->
<!-- 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 -->
<!-- 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"/>
......
# Changelog
## Changes in 4.0
- Rename 'Device' to 'DeviceClass' [(issue#2)](https://git.onem2m.org/MAS/SDT/issues/2)
- Remove 'Module' to simplify the SDT model [(issue#1)](https://git.onem2m.org/MAS/SDT/issues/1)
- Introduced 'Product' for concrete model definition of real products. [(issue#6)](https://git.onem2m.org/MAS/SDT/issues/6)
- Support JSON serialization [(issue#5)](https://git.onem2m.org/MAS/SDT/issues/5)
- Support inheritance of 'DeviceClass' [(issue#3)](https://git.onem2m.org/MAS/SDT/issues/3)
- Enum type ...
- Data Type Facets ... [(issue#4)](https://git.onem2m.org/MAS/SDT/issues/4)
- ...
*Editor's note: the current change log is just an examplary list (a projection), which lists some initial thoughts that the group is working on based on previous discussion. It needs to be revisited according to all implemented features before SDT4.0 publication.*
- Renamed ``<Device>`` to ``<DeviceClass``>.
- Removed ``<Module>`` to simplify the SDT model.
- Introduced ``<ProductClass`` for concrete model definition of real products.
- Introduced complex ``<EnumType>`` data type. Removed ``enum`` data type from ``BasicTypes``.
- Added ``void`` from ``BasicTypes``.
- Introduced inheritance / extending of ``<DataType>``.
- Added support for defining ``<DataType>`` on ``<Domain>`` level.
- Changed ``<Extend>`` mechanism. Now one can explicitly include or exclude certain sub-components from the parent.
- Added support of ``semanticURL`` attribute for all components.
- Added ``optional`` attribute to ``<Arg>``.
- Added ``default`` attribute to ``<Arg>``.
- Added ``default`` attribute to ``<DataPoint``.
- Unified all component identifiers, names etc to XSD type ``name``.
- Introduced JSON serialization guidelines.
- Changed case of ``<Imports>`` element.
- Added more test cases and example templates to the [test](../test) directory.
- Changed the license to [3-Clause BSD License](https://opensource.org/licenses/BSD-3-Clause).
## Changes in 3.0
- Renamed ``<RootDevice>``to ``<Device>`` and ``<Device>`` to ``<SubDevice>``,
......
This diff is collapsed.
# Frequently Asked Questions
## What is the HGI?
tbd
## What is the SDT?
tbd
1. [General](#general)
1. [What is the SDT?](#WhatistheSDT)
2. [What is oneM2M?](#echonetExampleMC)
2. [Working with the SDT](#working)
1. [What is the SDT?](#build)
2. [How to validate own templates](#validate)
3. [Are there tools to work with the SDT?](#tools)
<a name="general"></a>
## General
<a name="WhatistheSDT"></a>
### What is 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.
<a name="WhatisoneM2M"></a>
### What is oneM2M?
oneM2M is a global organization that creates requirements, architecture, API specifications, security solutions and interoperability for Machine-to-Machine and IoT technologies.
The purpose and goal of oneM2M is to develop technical specifications which address the need for a common M2M Service Layer that can be readily embedded within various hardware and software, and relied upon to connect the myriad of devices in the field with M2M application servers worldwide. A critical objective of oneM2M is to attract and actively involve organizations from M2M-related business domains such as: telematics and intelligent transportation, healthcare, utilities, industrial automation, smart homes, etc. Initially, oneM2M shall prepare, approve and maintain the necessary set of Technical Specifications and Technical Reports for:
- Use cases and requirements for a common set of Service Layer capabilities;
Service Layer aspects with high level and detailed service architecture, in light of an access independent view of end-to-end services;
- Protocols/APIs/standard objects based on this architecture (open interfaces & protocols);
- Security and privacy aspects (authentication, encryption, integrity verification);
- Reachability and discovery of applications;
- Interoperability, including test and conformance specifications;
- Collection of data for charging records (to be used for billing and statistical purposes);
- Identification and naming of devices and applications;
- Information models and data management (including store and subscribe/notify functionality);
- Management aspects (including remote management of entities); and
- Common use cases, terminal/module aspects, including Service Layer interfaces/APIs between:
- Application and Service Layers;
- Service Layer and communication functions
[http://www.onem2m.org](http://www.onem2m.org)
<a name="working"></a>
## Working with the SDT
<a name="working"></a>
### How to build the SDT
Please follow the instructions for the [SDT Build System](SDT/schema4.0/docs/SDT%20Build%20System.md).
In short:
- In a terminal, go to the directoy *SDT/schema4.0*
- Run the command:
```sh
$ ant
```
<a name="validate"></a>
### How to validate own templates
Please follow the instructions for the [SDT Build System](SDT/schema4.0/docs/SDT%20Build%20System.md).
In short:
- Copy your template to the directory *SDT/schema4.0/test*
- In a terminal, go to the directoy *SDT/schema4.0*
- Run the command:
```sh
$ ant validate
```
<a name="tools"></a>
### Are there tools to work with the SDT?
You can use the SDTTool to read and convert templates in SDT format to various output formats, e.g. XSD, SVG, markdown, Java code, etc.
[https://github.com/Homegateway/SDTTool](https://github.com/Homegateway/SDTTool)
# Introduction to the SDT
# Introduction to the Smart Device Template
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.
## Table of Contents
1. [Introduction](#Introduction)
2. [Definitions](#Definitions)
3. [How should SDT work?](#Work)
4. [Related aspects which are out of scope of the SDT](#related)
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++, ...).
<a name="Introduction"/></a>
## Introduction
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.
The Smart Device Template (SDT) is an initiative from [oneM2M](http://www.onem2m.org) to find consensus amongst various SDOs and industry alliances to derive a common approach for device modeling. oneM2M and partners have the approach to agree on a set of automation functionalities, following a common syntax, which are sufficient to model most device functions.
Originally initiated by the [Home Gateway Initiative (HGI)](http://www.homegatewayinitiative.org), oneM2M is now the owner and maintainer of the SDT.
At the time of writing, every software developed for Internet-of-Things gateways, for example gateways for home automation, needs to be capable of using various different protocols (ZigBee, ZWave, KNX, OPC UA, EchonetLite, DECT ULE, etc) to interact with a range of devices designed for the IoT 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 and protocols, in a format which is convenient and reliable for integration in modern code (Java, C/C++, Go, Python, ...).
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 LAN technologies and protocols;
5. enable extendibility of the system in place without service interruption;
6. allow a pass-through mechanism to enable use of proprietary or technology-specific functions.
In general a description of device (or complex appliance) behaviour can be made in many ways, with various kinds of constraints:
......@@ -12,57 +30,55 @@ In general a description of device (or complex appliance) behaviour can be made
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.
oneM2M 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 and validated with common software tools, and can still be created and interpreted by humans if necessary. SDT intended use is for modeling, not as a presentation layer protocol, therefore the size of individual templates is not important.
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.
oneM2M 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).
Therefore oneM2M proposes to recommend a certain structure (or 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 in the end users and customers).
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.
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 IoT systems, such as "on/off", "dim a lamp", "receive events from sensor", "read data from sensor", etc. Each ModuleClass is composed of a (preferable 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.
![SmartHome Device Template (XSD) for a generic device (simplification)](images/SDT_simplified.png)
**SmartHome Device Template (XSD) for a generic device (simplification)**
![SmartHome Device Template for a generic device (UML, basic entities)](images/SDT_simplified.png)
**SmartHome Device Template for a generic device (UML, basic entities)**
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).
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 schema is achieved with re-usable XML fragments (for example the "ModuleClass" in the figure).
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.
Complex devices or appliances can then be described by an appropriate set or collection of the agreed ModuleClasses, as indicated in the figure, which also shows an optional "Property" fragment to allow noting of static information such as device manufacturer name, device firmware version, etc.
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).
oneM2M 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).
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.
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 "DeviceClass", 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 and extended by a manufacturer as the schema for an XML description of a specific washing machine product. The SDT allows for vendor-specific additional commands (ModuleClasses) to suit specific product types.
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.
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.
Various details about the recommended structure for SDTs are described in the next sections. The key point to keep in mind is that oneM2M 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 name="Definitions"/></a>
## Definitions
This section provides an overview about the SDT 4.0 definitions and element hierarchy. Terms to be described in detail in this section are:
This section provides an overview about high-level SDT 4.0 definitions and element hierarchy. Terms to be described in detail in this section are:
| Term | Definition |
|------|------------|
|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) |
| Device | Physical, addressable, identifiable appliance/sensor/actuator. |
| Sub-Device | A device (usually one of several) which may be embedded in a Device and/or is addressed via another Device. |
| Product| A concrete device model with deterministic Device Properties and ModuleClasses (no optionality). It's deemed as an specialized implementation of a DeviceClass but not yet an device instance. Examples are the shopping items (e.g. a smart watch) in an online digital store that can be ordered (but not necessarily manufactured) by a customer. |
| 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. |
|Domain | Unique name, or "wrapper" which acts like a namespace, set by the organization, company, or project creating the template, allowing reference to a package of definitions for the contained ModuleClasses and device definitions. Can be referenced when extending Products, ModuleClasses, and data types. 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) |
|ProductClass | A concrete device model with deterministic device Properties and ModuleClasses, without optionality. It is deemed as a specialized implementation of a DeviceClass that can be manufactured. |
|DeviceClass | A physical, addressable, identifiable appliance, sensor, or actuator. |
|Sub-Device | A device (usually one of several) which may be embedded in or attached to a (full) device. It is not designed to be operated as a standalone device. |
| 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 *DeviceClass* or *ProductClass* definitions. |
**Definitions of SDT Elements.**
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:
A major decision, facilitating validation of code and signaling, was to describe services (functionality) of devices in terms of ModuleClasses made up of combinations of three kinds of elements:
1. DataPoints which are aspects of the Device that can be read/written,
1. DataPoints which are aspects of a functionality that can be read and/or written,
2. Actions which consist of more complex sequences of operations;
3. Events which can be signalled ("published") by devices asynchronously.
3. Events which can be signaled ("published") by devices asynchronously.
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:
The ModuleClass structure is a major part of the SDT which is illustrated in detail in the following figure:
![UML description of device functionality in terms of Actions, DataPoints and Events](images/MC.Action.DataPoint.Event.png)
**UML description of device functionality in terms of Actions, DataPoints and Events**
![UML description of device functionality in terms of DataPoints, Actions, and Events](images/MC.Action.DataPoint.Event.png)
**UML description of device functionality in terms of DataPoints, Actions, and Events**
<a name="Work"/></a>
## 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.
......@@ -73,11 +89,12 @@ The key to making software reliably interoperate with various technologies is to
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.
<a name="related"/></a>
## Related aspects which are out of scope of the SDT
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.
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, and (b) device capability information detailing the firmware operations and types/meanings of input/output variables.
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.
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 (a) software APIs written based on a particular SDT and (b) 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.
......@@ -85,6 +102,4 @@ The above is an efficient approach BUT it must be clear that the real-time state
---
Click [here](SDT_Components.md) for detailed documentation about SDT.
The detailed documentation about SDT components can be found [here](SDT_Components.md).
# Links & References
## Smart Device Template
- **SDT Repository** : [https://git.onem2m.org/MAS/SDT](https://git.onem2m.org/MAS/SDT)
## Further Information
- **TR-0039 Introduction to IPE and SDT** : [http://www.onem2m.org/tr-0039/ipe-and-sdt](http://www.onem2m.org/tr-0039/ipe-and-sdt)
- **The oneM2M Smart Device Template (SDT)** (BrightTALK) : [https://www.brighttalk.com/webcast/11949/340004/the-onem2m-smart-device-template-sdt](https://www.brighttalk.com/webcast/11949/340004/the-onem2m-smart-device-template-sdt)
## Organisations
- **oneM2M** : [http://www.onem2m.org](http://www.onem2m.org)
- **HGI** : [http://www.homegatewayinitiative.org](http://www.homegatewayinitiative.org)
## XML
## Tools
- **SDTTool** : [https://github.com/Homegateway/SDTTool](https://github.com/Homegateway/SDTTool)
SDTTool is a utility to read and convert SDT definitions.
- **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.
A free UML drawing tool used to draw the UML file.
- **Apache Ant** : [http://ant.apache.org](http://ant.apache.org)
Build tool
......
# Build System Libraries and Licenses
The following libraries are used in the build system for the SDT.
# SDT Build System Components and Licenses
The following third-party libraries and components are used in the build system for the Smart Device Template.
## Table of Contents
1. [trang.jar](#trang)
2. [Ant-Contrib Tasks](#antcontrib)
3. [antSetLogLevel.JAR](#antSetLogLevel)
<a name="trang"/></a>
## trang.jar
[http://www.thaiopensource.com/relaxng/trang-manual.html](http://www.thaiopensource.com/relaxng/trang-manual.html)
[https://relaxng.org/jclark/trang.html](https://relaxng.org/jclark/trang.html)
[https://github.com/relaxng/jing-trang](https://github.com/relaxng/jing-trang)
*Trang* takes as input a schema written in any of the following formats:
......@@ -45,6 +53,7 @@ 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.
<a name="antcontrib"/></a>
## Ant-Contrib Tasks
[http://ant-contrib.sourceforge.net](http://ant-contrib.sourceforge.net)
......@@ -55,6 +64,7 @@ The *Ant-Contrib* project is a collection of tasks (and at one point maybe types
This Software is distributed under the Apache Software License.
<a name="antSetLogLevel"/></a>
## antSetLogLevel.jar
GUI dialog for Ant tasks.
......
# SDT Build System
This document describes the SDT build system and how to build the SDT and validate new contributions.
This document describes the SDT build system and how to build the SDT and validate new templates and contributions.
The files referenced in this document point to version **4.0** of the SDT.
## Table of Contents
1. [Directory Structure and Important Files](#Structure)
2. [Installation](#Installation)
3. [Building](#Building)
1. [Building the Schema](#BuildingSchema)
2. [Validating SDT Templates](#BuildingValidate)
4. [Editing the Schema](#Editing)
<a name="Structure"/></a>
## Directory Structure and Important Files
- [SDT/schema4.0/](../..) : Base directory
- [SDT/schema4.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*.
**Only edit this file when you want to make changes to the SDT!** See also [Editing the Schema](#Editing) below.
- [domain.xsd](../src/domain.xsd) : The actual SDT schema definition that is generated from *domain.rng*.
- [xml.xsd](../src/xml.xsd) : General schema definitions for the SDT
- [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.
- [SDT/schema4.0/test/](../test/) : This directory contains XML files with SDT definitions that should be validated whether they conform to the SDT schema.
This could be example definitions or new templates and contributions. If you want to validate your newly created template put it into this directory and follow the steps descripted in [Validating SDT Templates](#BuildingValidate) below.
- [SDT/schema4.0/build.xml](../build.xml) : This is the definition file for the ant build system.
- [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.
- [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.
- [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**:
default namespace xsl = "http://homegatewayinitiative.org/xml/dal/3.0"
- [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.**
- [SDT/schema4.0/etc/](../etc/), [SDT/schema4.0/style/](../style/) : internal directories for the build system. Please, don't make changes to these files.
- [SDT/schema4.0/etc/](../etc), [SDT/schema4.0/style/](../style/) : internal directories for the build system. Only the following files should be changed if necessray. See the section [Editing the Schema](#Editing) below.
- [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.
- [SDT/schema4.0/etc/schemas.xml](../etc/schemas.xml) : This file contains the header for the schema file.
- [SDT/schema4.0/etc/schema.xmlns](../etc/schema.xmlns) : This file defines the target namespace for the schema.
- [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).
<a name="Installation"/></a>
## 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
### Prerequisites
- Java
- Ant (at least version 1.8). See [http://ant.apache.org](http://ant.apache.org).
### Installing SDT
- Clone the SDT repository from oneM2M's GitLab:
$ git clone https://git.onem2m.org/MAS/SDT.git
<a name="Building"/></a>
## 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.
After cloning the repository go to the directory *SDT/schema4.0* and run commands depending on what you want to achieve.
### Build the Schema
<a name="BuildingSchema"/></a>
### Building the Schema
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)
$ cd SDT/schema
$ cd SDT/schema4.0
$ ant
### Validate SDT Definitions
<a name="BuildingValidate"/></a>
### Validating SDT Templates
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
$ cd SDT/schema4.0
$ ant validate
The output after a successful validation should look like this:
The output after a successful validation should look similar this:
>[schemavalidate] 2 file(s) have been successfully validated.
>BUILD SUCCESSFUL
......@@ -54,20 +70,30 @@ Otherwise you most likely receive a stack trace or some other error messages. Se
>[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
---
<a name="Editing"/></a>
## Editing the Schema
As mentioned above, the actual schema definition is defined in the file [src/domain.rng](../src/domain.rng) and converted to the XML schema definition [src/domain.xsd](../src/domain.xsd) during the build process.
## 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) !**
**All changes to the schema must only be made to [src/domain.rng](../src/domain.rng), NOT [src/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.
PLEASE EDIT THESE FILES ONLY IF NECESSARY.
- [SDT/schema4.0/build.xml](../build.xml)
e.g. in the *ant* target "validate"
e.g. change the *ant* target "validate" when you want to set another directory for the files for validation.
- [SDT/schema4.0/etc/dal.rnc](../etc/dal.rnc)
e.g. the entry "default namespace xsl"
- [SDT/schema4.0/etc/schema.xmlns](../etc/schema.xmlns)
- [SDT/schema4.0/etc/schemas.xml](../etc/schemas.xml)
The important parameter to update when changing the namespace or the version number is:
default namespace xsl = "http://www.onem2m.org/xml/sdt/4.0"
- [SDT/schema4.0/etc/schema.xmlns](../etc/schema.xmlns)
This file must be updated when changing the namespace or the version number:
targetNamespace="http://www.onem2m.org/xml/sdt/4.0"
xmlns="http://www.onem2m.org/xml/sdt/4.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
- [SDT/schema4.0/etc/schemas.xml](../etc/schemas.xml)
Upate the namespace when changing the namespace or the version number:
<namespace ns="http://www.onem2m.org/xml/sdt/4.0" typeId="DAL"/>
This diff is collapsed.
# JSON Serialization
## Table of Contents
1. [Introduction](#introduction)
2. [SDT mapping to JSON](#mappings)
1. [Elements](#elements)
2. [Attributes](#attributes)
1. [ExtendType](#ExtendType)
3. [Imports](#imports)
4. [Data Types](#dataTypes)
1. [SimpleType](#SimpleType)
2. [ArrayType](#ArrayType)
3. [StructType](#StructType)
4. [EnumType](#EnumType)
5. [Extending DataTypes](#extendingDatatypes)
<a name="introduction"/></a>
## Introduction
When SDT was introduced, XML was the favorite encoding format for schemas. Since then, JSON became more popular in the developers' communities, especially in the context of RESTful implementation.
JSON is more concise and human-readable comparing to XML, but has less capability of formal schema definition and validation (such as the XML Schema as defined in [domain.xsd](SDT/schema4.0/src/domain.xsd)).
JSON is more concise and human-readable comparing to XML, but has less capability of formal schema definition and validation (such as the XML Schema as defined in [domain.xsd](../src/domain.xsd)).
For these reasons, JSON serialization is supported since SDT4.0.
For these reasons, JSON serialization is supported since SDT version 4.0.
There are some open tools such as [JSON Schema](http://json-schema.org/) that might be useful for describing and validating the JSON serialization of SDT, but it's not yet a formal standard and is still under development.
In this release, we chose to define the JSON serialization by the documentation below, while borrowing some valuable aspects from JSON Schema (e.g. data types and validation keywords). Full endorsement of [JSON Schema](http://json-schema.org/) may be considered in future.
In this release, we chose to define the JSON serialization by the documentation below, while borrowing some valuable aspects from JSON Schema (e.g. data types and validation keywords). Full endorsement of [JSON Schema](http://json-schema.org/) may be considered in the future.
The general JSON structure follows the general SDT structure presented in [SDT_UML.md](SDT_UML.md) and described in [SDT_Components.md](SDT_Components.md).
<a name="mappings"/></a>
## SDT mapping to JSON
<a name="elements"/></a>
### Elements mapping
| SDT XML Elements | JSON Key Words | Remark |
|------------------|----------------|--------|
|Action | Action | |
|Actions | Actions | This element is an array of *Action* structures. |
|Arg | Arg | |
|Args | Args | This element is an array of *Arg* structures. |
|Constraint | Constraint | |
|Constraints | Constraints | This element is an array of *Constraint* structures. |
|Data | Data | This element is an array of *DataPoint* structures. |
|DataPoint | DataPoint | |
|DataType | DataType | |
|DataTypes | DataTypes | This element is an array of *DataType* structures. |
|DeviceClass | DeviceClass | |
|DeviceClasses | DeviceClasses | This element is an array of *DeviceClass* structures. |
|Doc |Doc | |
|Domain | Domain | |
|Event | Event | |
|Events | Events | This element is an array of *Event* structures. |
|Exclude | Exclude | |
|Extend | Extend | |
|Imports |Imports| This element is an array of *Include* structures. |
|Include | Include | |
|ModuleClass | ModuleClass | |
|ModuleClasses | ModuleClasses | This element is an array of *ModuleClass* structures. |
|ProductClass | ProductClass | |
|ProductClasses | ProductClasses | This element is an array of *ProductClasses* structures. |
|Properties | Properties | This element is an array of *Property* structures. |
|Property | Property | |
|SubDevice | SubDevice | |
|SubDevices | SubDevices | This element is an array of *SubDevice* structures. |
Some JSON examples can be found in [SDT Components](SDT/schema4.0/docs/SDT_Components.md) and a full exmaple can be found in [JSON Example](SDT/schema4.0/docs/JSON_Example.md)