Skip to content

GitLab

Commit ee9cd4a6 authored by ankraft's avatar ankraft
Browse files

More updates of documentations

parent 51659538
Hide whitespace changes
Inline Side-by-side
Showing with 163 additions and 107 deletions
LICENSE
View file @ ee9cd4a6
......@@ -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.
SDT/schema4.0/docs/Changelog.md
View file @ ee9cd4a6
# 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>``,
......
SDT/schema4.0/docs/Examples.md
View file @ ee9cd4a6
# Examples and Contributions
[A simple example](#simpleExample)
[Multi Socket Electrical-Extension-Block](#mseeb)
## Table of Contents
1. [A simple example](#simpleExample)
2. [Multi Socket Electrical-Extension-Block](#mseeb)
<a name="simpleExample"></a>
## A very simple SDT example
In the ideal case, a large organization or SDO would define a widely-applicable set of [ModuleClasses](SDT_Components.md#ModuleClass), each of which could be used as needed to compose the description of a complex device. In order to show the appoach, this section will create a few example ModuleClasses based on - or inspired by - featues in the Echonet Lite protocol. Please note that the examples shown in this document are very "cut down" and by no means represent a true representation of Echonet Lite.
## A simple SDT example
In the ideal case, a large organization or SDO would define a widely-applicable set of [ModuleClasses](SDT_Components.md#ModuleClass), each of which could be used as needed to compose the description of a complex device. In order to show the appoach, this section will create a few example ModuleClasses based on - or inspired by - featues in the Echonet Lite protocol. Please note that the examples shown in this document are very "cut down" and by no means represent a true representation of Echonet Lite[^echonet].
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/) ).
[^echonet]: The Echonet Consortium has standardized their specifications within IEC/ISO (IEC62394, ISO/IEC24767-1, ISO/IEC24767-2, IEC62480, ISO/IEC14543-4-1, ISO/IEC14543-4-2, IEC62457) and they provide a comprehensive collection of various types of home appliances relevant to SmartGrid applications as ECHONET Device objects (see [https://echonet.jp/spec_object_rf_en/](https://echonet.jp/spec_object_rf_en/) ).
For the example in this document, to show re-use of ModuleClass definitions, two complex devices are chosen which have some common features and hence could be expected to both use some of the same ModuleClasses: an air conditioner and a washing machine.
For the example in this section, to show re-use of ModuleClass definitions, two complex devices are chosen which have some common features and hence could be expected to both use some of the same ModuleClasses: an air conditioner and a washing machine.
<table>
<tr><th>Funtionality</th><th>Air Conditioner</th><th>Washing Machine</th></tr>
<tr><td>operationStatus</td><td>operates on/off</td><td>operates on/off</td></tr>
<tr><td>measuredCumulativePowerConsumption</td><td>the cumulative power consumption</td><td>the cumulative power consumption</td></tr>
<tr><td>installationLocation</td><td>this sets/reads a string text describing the location (room) of the air-conditioner.</td><td>this sets/reads a string text describing the location (room) of the washing machine.</td></tr>
<tr><td>setTimer</td><td>(not applicable. there is no preset start for an air-conditioner)</td><td>This sets/reads use the on/off timer</td></tr>
</table>
|Funtionality | Air Conditioner | Washing Machine |
|:------------|:----------------|:----------------|
|operationStatus |operates on/off |operates on/off |
|measuredCumulativePowerConsumption |the cumulative power consumption |the cumulative power consumption |
|installationLocation |this sets/reads a string text describing the location (room) of the air-conditioner |this sets/reads a string text describing the location (room) of the washing machine |
|setTimer |(not applicable. there is no preset start for an air-conditioner) |This sets/reads use the on/off timer |
Based on the simplified example above, the two appliances will need the ModuleClasses below:
- *air-conditioner*: operationStatus, measuredCumulativePowerConsumption, installationLocation;
- *washing-machine*: operationStatus, measuredCumulativePowerConsumption, and setTimer.
<ModuleClass name="operationStatus">
<Data>
<DataPoint name="operationStatus" writable="true">
<Doc>This property sets/reads the ON/OFF status.</Doc>
<DataType>
<SimpleType type="boolean"/>
</DataType>
</DataPoint>
</Data>
<Events>
<Event name="operationStatus">
</Event>
</Events>
</ModuleClass>
<ModuleClass name="measuredCumulativePowerConsumption">
<Data>
<DataPoint name="measuredCumulativePowerConsumption" writable="false">
<Doc>This indicates cumulative power consumption of the device in increments of 0.001kWh.</Doc>
<DataType>
<SimpleType type="integer"/>
</DataType>
</DataPoint>
</Data>
</ModuleClass>
- *washing-machine*: operationStatus, measuredCumulativePowerConsumption, setTimer.
<ModuleClass name="installationLocation">
<Data>
<DataPoint name="installationLocation" writable="true">
<Doc>This property indicates the installation location</Doc>
<DataType>
<SimpleType type="string"/>
</DataType>
</DataPoint>
</Data>
<Events>
<Event name="installationLocation"> </Event>
</Events>
</ModuleClass>
<ModuleClass name="onTimerSetting">
<DataPoint name="onTimer" writable="true">
<Doc>Timer value (HH:MM)</Doc>
```XML
<ModuleClass name="operationStatus">
<Data>
<DataPoint name="operationStatus" writable="true">
<Doc>This property sets/reads the ON/OFF status.</Doc>
<DataType>
<SimpleType type="time"/>
<SimpleType type="boolean"/>
</DataType>
</DataPoint>
</ModuleClass>
</DataPoint>
</Data>
<Events>
<Event name="operationStatus">
</Event>
</Events>
</ModuleClass>
<ModuleClass name="measuredCumulativePowerConsumption">
<Data>
<DataPoint name="measuredCumulativePowerConsumption" writable="false">
<Doc>This indicates cumulative power consumption of the device in increments of 0.001kWh.</Doc>
<DataType>
<SimpleType type="integer"/>
</DataType>
</DataPoint>
</Data>
</ModuleClass>
<ModuleClass name="installationLocation">
<Data>
<DataPoint name="installationLocation" writable="true">
<Doc>This property indicates the installation location</Doc>
<DataType>
<SimpleType type="string"/>
</DataType>
</DataPoint>
</Data>
<Events>
<Event name="installationLocation"> </Event>
</Events>
</ModuleClass>
<ModuleClass name="onTimerSetting">
<DataPoint name="onTimer" writable="true">
<Doc>Timer value (HH:MM)</Doc>
<DataType>
<SimpleType type="time"/>
</DataType>
</DataPoint>
</ModuleClass>
```
The structure and the according SDT now looks like this:
<table>
<tr><td colspan="2" width="50%"><b>Example1.SDT</b></td></tr>
<tr><td> </td><td>Namespace information</td></tr>
<tr><td> </td><td>Modules (contains ModuleClasses)</td></tr>
<tr><td> </td><td>operationStatus<ul>
<li>measuredCumulativePowerConsumption</li>
<li>installationLocation</li>
<li>onTimerSetting</li></ul></td></tr>
</table>
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Example1 SDT inspired by some Echonet Lite examples -->
<Domain xmlns="http://homegatewayinitiative.org/xml/dal/3.0"
xmlns:xi="http://www.w3.org/2001/XInclude"
id="example1.SDT">
<Modules>
|Example1.SDT |
|:--------------|
|Namespace information |
|Modules (contains ModuleClasses) |
|operationStatus <ul><li>measuredCumulativePowerConsumption</li><li>installationLocation</li><li>onTimerSetting</li></ul> |
```xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Example1 SDT inspired by some Echonet Lite examples -->
<Domain xmlns="http://www.onem2m.org/xml/sdt/4.0"
xmlns:xi="http://www.w3.org/2001/XInclude"
id="example1.SDT">
<ModuleClasses>
<!-- Various examples for module classes -->
<ModuleClass name="operationStatus">
<Data>
<DataPoint name="operationStatus" writable="true">
......@@ -140,9 +141,12 @@ The structure and the according SDT now looks like this:
</DataType>
</DataPoint>
</ModuleClass>
</Modules>
</Domain>
</ModuleClasses>
</Domain>
```
TODO Implementation in Device
---
......
SDT/schema4.0/docs/Introduction.md
View file @ ee9cd4a6
# Introduction to the Smart Device Template
## 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)
<a name="Introduction"/></a>
## Introduction
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.
......@@ -44,7 +53,7 @@ The interoperability benefits can potentially partially be obtained even without
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 high-level SDT 4.0 definitions and element hierarchy. Terms to be described in detail in this section are:
......@@ -69,6 +78,7 @@ The ModuleClass structure is a major part of the SDT which is illustrated in det
![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.
......@@ -79,6 +89,7 @@ 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, and (b) device capability information detailing the firmware operations and types/meanings of input/output variables.
......
SDT/schema4.0/docs/Links.md
View file @ ee9cd4a6
# 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
......
SDT/schema4.0/docs/SDT Build System Components and Licenses.md
View file @ ee9cd4a6
# SDT Build System Components and Licenses
The following libraries are used in the build system for the SDT.
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/schema4.0/docs/SDT Build System.md
View file @ ee9cd4a6
......@@ -3,23 +3,33 @@ This document describes the SDT build system and how to build the SDT and valida
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 you want to make changes to the SDT!** See also [Editing](#Editing) below.
**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 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 [Validate SDT Templates](#Validate) below.
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 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](#Editing) below.
- [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
### Prerequisites
......@@ -30,18 +40,20 @@ This could be example definitions or new templates and contributions. If you wan
- 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/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/schema4.0
$ ant
<a name="Validate"/></a>
### Validate SDT Templates
<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/schema4.0
......@@ -58,10 +70,8 @@ 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
## 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.
**All changes to the schema must only be made to [src/domain.rng](../src/domain.rng), NOT [src/domain.xsd](../src/domain.xsd) !**
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment