Skip to content
Snippets Groups Projects
Commit ff366ff9 authored by ankraft's avatar ankraft
Browse files

reworked examples. Added Simple example.

parent ee9cd4a6
No related branches found
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
SDT/schema4.0/docs/Examples.md
+ 331
− 56
View file @ ff366ff9
# Examples and Contributions # Examples and Contributions
## Table of Contents ## Table of Contents
1. [A simple example](#simpleExample)
2. [Multi Socket Electrical-Extension-Block](#mseeb) 1. [A simple SDT example](#simpleExample)
2. [A more sophisticated example](#echonetExample)
1. [ModuleClasses Definition](#echonetExampleMC)
2. [DeviceClass Definition](#echonetExampleDC)
3. [The full SDT](#echonetExampleFull)
<a name="simpleExample"></a> <a name="simpleExample"></a>
## A simple SDT example ## 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 following example shows a very simple device that represents a light that can be switched on and off. It contains just a single ModuleClass "Switch", which contains a single boolean data point "status" to control the on/off status of the device.
It is a stand-alone definition without using previously defined ModuleClasses. A more sophisticated use is presented in the next example.
The structure and the according SDT looks like this:
|SimpleExample.xml | |
|:--------------|-|
|Namespace information | SimpleExample |
|DeviceClasses |<ul><li>Light</li><ul><li>Switch<ul><li>status</li></ul></li></ul></ul>|
The following code section shows the fully integrated template. The source code can be found in [SimpleExample.xml](../test/SimpleExample.xml) in the "test" directory.
```xml
<?xml version="1.0" encoding="iso-8859-1"?>
<Domain xmlns="http://www.onem2m.org/xml/sdt/4.0" id="SimpleExample" >
<DeviceClasses>
<DeviceClass id="Light">
<Doc>This is a very simple device representing a light.</Doc>
<ModuleClasses>
<ModuleClass name="Switch">
<Data>
<DataPoint name="status" readable="true" writable="true">
<Doc>This property indicates the ON/OFF status.</Doc>
<DataType>
<SimpleType type="boolean" />
</DataType>
</DataPoint>
</Data>
</ModuleClass>
</ModuleClasses>
</DeviceClass>
</DeviceClasses>
</Domain>
```
<a name="echonetExample"></a>
## A more sophisticated 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 approach, this section will create a few example ModuleClasses based on - or inspired by - features 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].
[^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/) ).
The source code can be found in [EchonetLiteExamples.xml](../test/EchonetLiteExamples.xml) in the "test" directory.
<a name="echonetExampleMC"></a>
### ModuleClasses
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. 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.
|Funtionality | Air Conditioner | Washing Machine | |Functionality | Air Conditioner | Washing Machine |
|:------------|:----------------|:----------------| |:------------|:----------------|:----------------|
|operationStatus |operates on/off |operates on/off | |operationStatus |operates on/off |operates on/off |
|measuredCumulativePowerConsumption |the cumulative power consumption |the cumulative power consumption | |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 | |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 | |setTimer |(not applicable. there is no preset start for an air-conditioner) |This sets/reads use the on/off timer |
|temperatureSensorDataPoints | this reads the measured temperature | this reads the measured temperature |
Based on the simplified example above, the two appliances will need the ModuleClasses below: Based on the simplified example above, the two appliances will need the ModuleClasses below:
- *air-conditioner*: operationStatus, measuredCumulativePowerConsumption, installationLocation; - *air-conditioner*: operationStatus, measuredCumulativePowerConsumption, installationLocation;
- *washing-machine*: operationStatus, measuredCumulativePowerConsumption, setTimer. - *washing-machine*: operationStatus, measuredCumulativePowerConsumption, setTimer, temperatureSensorDataPoints.
```XML ```xml
<ModuleClass name="operationStatus"> <ModuleClass name="operationStatus">
<Data> <Data>
<DataPoint name="operationStatus" writable="true"> <DataPoint name="operationStatus" writable="true">
...@@ -36,6 +86,7 @@ Based on the simplified example above, the two appliances will need the ModuleCl ...@@ -36,6 +86,7 @@ Based on the simplified example above, the two appliances will need the ModuleCl
</Data> </Data>
<Events> <Events>
<Event name="operationStatus"> <Event name="operationStatus">
<!-- Event payload not shown here -->
</Event> </Event>
</Events> </Events>
</ModuleClass> </ModuleClass>
...@@ -65,52 +116,175 @@ Based on the simplified example above, the two appliances will need the ModuleCl ...@@ -65,52 +116,175 @@ Based on the simplified example above, the two appliances will need the ModuleCl
</Events> </Events>
</ModuleClass> </ModuleClass>
<ModuleClass name="onTimerSetting"> <ModuleClass name="temperatureSensorDataPoints">
<DataPoint name="onTimer" writable="true"> <Data>
<DataPoint name="measuredTemperatureValue" readable="true" writable="false">
<Doc>This property indicates the measured temperature value in units of 0.1C.</Doc>
<DataType unitOfMeasure="celsius">
<SimpleType type="integer" />
</DataType>
</DataPoint>
</Data>
</ModuleClass>
```
<a name="echonetExampleDC"></a>
### DeviceClass
To define a device one would now reference those ModuleClass definitions in a new DeviceClass. For the sake of simplicity only the "SimpleWashingMachine" is implemented here.
In addition to the previously defined ModuleClasses this "SimpleWashingMachine" DeviceClass extends the existing ModuleClass "operationStatus" with an event. It also adds a new ModuleClass "washingMachineDataPoints" with model-specific DataPoints.
At the beginning of the definition some device Properties are defined.
```xml
<DeviceClass id="SimpleWaschingMachine">
<!-- Device Properties -->
<Properties>
<Property name="Name" value="washing machine">
<SimpleType type="string" />
</Property>
<Property name="Vendor" value="ACME">
<SimpleType type="string" />
</Property>
</Properties>
<ModuleClasses>
<!-- Inheriting ModuleClasses from the global generic ModuleClasses -->
<ModuleClass name="installationLocation">
<Extend domain="example.based.on.echonetLite" entity="installationLocation"/>
</ModuleClass>
<ModuleClass name="measuredInstantaneousPowerConsumption">
<Extend domain="example.based.on.echonetLite" entity="measuredInstantaneousPowerConsumption"/>
</ModuleClass>
<ModuleClass name="temperatureSensorDataPoints">
<Extend domain="example.based.on.echonetLite" entity="temperatureSensorDataPoints"/>
</ModuleClass>
<!-- The following Module inherits and extends a global generic ModuleClass with an event. Therefore, it is renamed to express the change of name. -->
<ModuleClass name="washingMachineOperationStatus">
<Extend domain="example.based.on.echonetLite" entity="operationStatus"/>
<!-- This Module extends the global one with an event. -->
<Events>
<Event name="washingMachineOperationStatus">
<!-- Event payload not shown here -->
</Event>
</Events>
</ModuleClass>
<!-- Data points local to the washing machine device -->
<ModuleClass name="washingMachineDataPoints">
<Data>
<DataPoint name="door_CoverOpen_CloseStatus" readable="true" writable="false">
<Doc>This property indicates whether the door/cover is open or closed.</Doc>
<DataType>
<SimpleType type="boolean" />
</DataType>
</DataPoint>
<DataPoint name="washingMachineSetting" readable="true" writable="true">
<Doc>Washing machine setting</Doc>
<DataType>
<SimpleType type="string" />
</DataType>
</DataPoint>
<DataPoint name="currentStageOfWashingCycle" readable="true" writable="false">
<Doc>This property indicates the current stage of the washing cycle.</Doc>
<DataType>
<SimpleType type="string" />
</DataType>
</DataPoint>
<DataPoint name="timeRemainingToCompleteWashingCycle" readable="true" writable="false">
<Doc>This property indicates the time remaining to complete the current washing cycle in the HH:MM:SS format.</Doc>
<DataType>
<SimpleType type="time" />
</DataType>
</DataPoint>
<!-- These three data points actually would make a good
example to be moved to a separate ModuleClass for
generalization so that they can be used by any device
that would make use of a timer. -->
<DataPoint name="onTimerReservationSetting" readable="true" writable="true">
<Doc>Reservation ON/OFF</Doc>
<DataType>
<SimpleType type="boolean" />
</DataType>
</DataPoint>
<DataPoint name="onTimerSetting" readable="true" writable="true">
<Doc>Timer value (HH:MM)</Doc> <Doc>Timer value (HH:MM)</Doc>
<DataType> <DataType>
<SimpleType type="time" /> <SimpleType type="time" />
</DataType> </DataType>
</DataPoint> </DataPoint>
<DataPoint name="relativeTimeBasedOnTimerSetting" readable="true" writable="true">
<Doc>Timer value (HH:MM)</Doc>
<DataType>
<SimpleType type="time" />
</DataType>
</DataPoint>
</Data>
</ModuleClass> </ModuleClass>
</ModuleClasses>
</DeviceClass>
``` ```
<a name="echonetExampleFull"></a>
### The full SDT
The structure and the according SDT now looks like this: The structure and the according SDT now looks like this:
|Example1.SDT | |EchonetLiteExamples.xml | |
|:--------------| |:--------------|-|
|Namespace information | |Namespace information | example.based.on.echonetLite |
|Modules (contains ModuleClasses) | |ModuleClasses |<ul><li>operationStatus<ul><li>operationStatus</li></ul></li><li>measuredCumulativePowerConsumption<ul><li>measuredInstantaneousPowerConsumption</li></ul></li><li>installationLocation<ul><li>installationLocation</li></ul></li><li>temperatureSensorDataPoints<ul><li>measuredTemperatureValue</li></ul></li></ul>|
|operationStatus <ul><li>measuredCumulativePowerConsumption</li><li>installationLocation</li><li>onTimerSetting</li></ul> | |DeviceClasses |<ul><li>SimpleWaschingMachine</li><ul><li>installationLocation --> installationLocation</li><li>measuredCumulativePowerConsumption --> measuredCumulativePowerConsumption</li><li>temperatureSensorDataPoints --> temperatureSensorDataPoints</li><li>operationStatus --> washingMachineOperationStatus</li><li>washingMachineDataPoints</li><ul><li>door_CoverOpen_CloseStatus</li><li>washingMachineSetting</li><li>currentStageOfWashingCycle</li><li>timeRemainingToCompleteWashingCycle</li><li>onTimerReservationSetting</li><li>onTimerSetting</li><li>relativeTimeBasedOnTimerSetting</li></ul></ul></ul>|
The following code section shows the fully integrated template.
```xml ```xml
<?xml version="1.0" encoding="iso-8859-1"?> <?xml version="1.0" encoding="iso-8859-1"?>
<!-- Example1 SDT inspired by some Echonet Lite examples --> <!-- Example1 SDT inspired by some Echonet Lite examples -->
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Example SDT definition taken from EchonetLite https://github.com/ECHONET-Consortium -->
<Domain xmlns="http://www.onem2m.org/xml/sdt/4.0" <Domain xmlns="http://www.onem2m.org/xml/sdt/4.0"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
id="example1.SDT"> id="example.based.on.echonetLite">
<ModuleClasses>
<!-- Various examples for module classes --> <!-- Various examples for module classes -->
<ModuleClasses>
<ModuleClass name="operationStatus"> <ModuleClass name="operationStatus">
<Data> <Data>
<DataPoint name="operationStatus" writable="true"> <DataPoint name="operationStatus" readable="true" writable="true">
<Doc>This property sets the ON/OFF status.</Doc> <Doc>This property indicates the ON/OFF status.</Doc>
<DataType> <DataType>
<SimpleType type="boolean" /> <SimpleType type="boolean" />
</DataType> </DataType>
</DataPoint> </DataPoint>
</Data> </Data>
<Events>
<Event name="operationStatus">
</Event>
</Events>
</ModuleClass> </ModuleClass>
<!-- runtime property -->
<ModuleClass name="installationLocation"> <ModuleClass name="installationLocation">
<Data> <Data>
<DataPoint name="installationLocation" writable="true"> <DataPoint name="installationLocation" readable="true" writable="true">
<Doc>This property indicates the installation location</Doc> <Doc>This property indicates the installation location</Doc>
<DataType> <DataType>
<SimpleType type="string" /> <SimpleType type="string" />
...@@ -118,46 +292,147 @@ The structure and the according SDT now looks like this: ...@@ -118,46 +292,147 @@ The structure and the according SDT now looks like this:
</DataPoint> </DataPoint>
</Data> </Data>
<Events> <Events>
<Event name="installationLocation"> </Event> <Event name="installationLocation">
<!-- Event payload not shown here -->
</Event>
</Events> </Events>
</ModuleClass> </ModuleClass>
<ModuleClass name="measuredCumulativePowerConsumption"> <!-- sensor readout -->
<ModuleClass name="measuredInstantaneousPowerConsumption">
<Data> <Data>
<DataPoint name="measuredCumulativePowerConsumption" writable="false"> <DataPoint name="measuredInstantaneousPowerConsumption" readable="true" writable="false">
<Doc>This indicates cumulative power consumption of the device in increments of 0.001kWh.</Doc> <Doc>This property indicates the instantaneous power consumption of the device in watts.</Doc>
<DataType> <DataType unitOfMeasure="watts">
<SimpleType type="integer" /> <SimpleType type="integer" />
</DataType> </DataType>
</DataPoint> </DataPoint>
</Data> </Data>
</ModuleClass> </ModuleClass>
<ModuleClass name="onTimerSetting"> <ModuleClass name="temperatureSensorDataPoints">
<DataPoint name="onTimer" writable="true"> <Data>
<Doc>Timer value (HH:MM)</Doc> <DataPoint name="measuredTemperatureValue" readable="true" writable="false">
<DataType> <Doc>This property indicates the measured temperature value in units of 0.1C.</Doc>
<SimpleType type="time"/> <DataType unitOfMeasure="celsius">
<SimpleType type="integer" />
</DataType> </DataType>
</DataPoint> </DataPoint>
</Data>
</ModuleClass> </ModuleClass>
</ModuleClasses> </ModuleClasses>
</Domain>
```
TODO Implementation in Device
--- <!-- Very simple example for a washing machine definition -->
<DeviceClasses>
<DeviceClass id="SimpleWaschingMachine">
<!-- Device Properties -->
<Properties>
<Property name="Name" value="washing machine">
<SimpleType type="string" />
</Property>
<Property name="Vendor" value="ACME">
<SimpleType type="string" />
</Property>
</Properties>
<ModuleClasses>
<!-- Inheriting ModuleClasses from the global generic ModuleClasses -->
<ModuleClass name="installationLocation">
<Extend domain="example.based.on.echonetLite" entity="installationLocation"/>
</ModuleClass>
<ModuleClass name="measuredInstantaneousPowerConsumption">
<Extend domain="example.based.on.echonetLite" entity="measuredInstantaneousPowerConsumption"/>
</ModuleClass>
<ModuleClass name="temperatureSensorDataPoints">
<Extend domain="example.based.on.echonetLite" entity="temperatureSensorDataPoints"/>
</ModuleClass>
<!-- The following Module inherits and extends a global generic ModuleClass with an event. Therefore, it is renamed to express
the change of name. -->
<ModuleClass name="washingMachineOperationStatus">
<Extend domain="example.based.on.echonetLite" entity="operationStatus"/>
<!-- This Module extends the global one with an event. -->
<a name="mseeb"></a> <Events>
### Multi Socket Electrical-Extension-Block <Event name="washingMachineOperationStatus">
<!-- Event payload not shown here -->
</Event>
</Events>
This example is a specification for an imaginged device, a connected extension block with multiple power socket where each of the sockets are modeled as a </ModuleClass>
separate *SubDevice*.
[mseeb.xml](../test/mseeb.xml)
<!-- Data points local to the washing machine device -->
--- <ModuleClass name="washingMachineDataPoints">
<Data>
<DataPoint name="door_CoverOpen_CloseStatus" readable="true" writable="false">
<Doc>This property indicates whether the door/cover is open or closed.</Doc>
<DataType>
<SimpleType type="boolean" />
</DataType>
</DataPoint>
<DataPoint name="washingMachineSetting" readable="true" writable="true">
<Doc>Washing machine setting</Doc>
<DataType>
<SimpleType type="string" />
</DataType>
</DataPoint>
<DataPoint name="currentStageOfWashingCycle" readable="true" writable="false">
<Doc>This property indicates the current stage of the washing cycle.</Doc>
<DataType>
<SimpleType type="string" />
</DataType>
</DataPoint>
<DataPoint name="timeRemainingToCompleteWashingCycle" readable="true" writable="false">
<Doc>This property indicates the time remaining to complete the current washing cycle in the HH:MM:SS format.</Doc>
<DataType>
<SimpleType type="time" />
</DataType>
</DataPoint>
<!-- These three data points actually would make a good
example to be moved to a separate ModuleClass for
generalization so that they can be used by any device
that would make use of a timer. -->
<DataPoint name="onTimerReservationSetting" readable="true" writable="true">
<Doc>Reservation ON/OFF</Doc>
<DataType>
<SimpleType type="boolean" />
</DataType>
</DataPoint>
<DataPoint name="onTimerSetting" readable="true" writable="true">
<Doc>Timer value (HH:MM)</Doc>
<DataType>
<SimpleType type="time" />
</DataType>
</DataPoint>
<DataPoint name="relativeTimeBasedOnTimerSetting" readable="true" writable="true">
<Doc>Timer value (HH:MM)</Doc>
<DataType>
<SimpleType type="time" />
</DataType>
</DataPoint>
</Data>
</ModuleClass>
</ModuleClasses>
</DeviceClass>
</DeviceClasses>
</Domain>
```
SDT/schema4.0/test/EchonetLiteExamples.xml
+ 5
− 6
View file @ ff366ff9
...@@ -69,6 +69,9 @@ ...@@ -69,6 +69,9 @@
<DeviceClasses> <DeviceClasses>
<DeviceClass id="SimpleWaschingMachine"> <DeviceClass id="SimpleWaschingMachine">
<!-- Device Properties -->
<Properties> <Properties>
<Property name="Name" value="washing machine"> <Property name="Name" value="washing machine">
<SimpleType type="string" /> <SimpleType type="string" />
...@@ -119,21 +122,18 @@ ...@@ -119,21 +122,18 @@
<DataPoint name="door_CoverOpen_CloseStatus" readable="true" writable="false"> <DataPoint name="door_CoverOpen_CloseStatus" readable="true" writable="false">
<Doc>This property indicates whether the door/cover is open or closed.</Doc> <Doc>This property indicates whether the door/cover is open or closed.</Doc>
<DataType> <DataType>
<!-- <SimpleType type="enum" /> --> <SimpleType type="boolean" />
<SimpleType type="string" />
</DataType> </DataType>
</DataPoint> </DataPoint>
<DataPoint name="washingMachineSetting" readable="true" writable="true"> <DataPoint name="washingMachineSetting" readable="true" writable="true">
<Doc>Washing machine setting</Doc> <Doc>Washing machine setting</Doc>
<DataType> <DataType>
<!-- <SimpleType type="enum" /> -->
<SimpleType type="string" /> <SimpleType type="string" />
</DataType> </DataType>
</DataPoint> </DataPoint>
<DataPoint name="currentStageOfWashingCycle" readable="true" writable="false"> <DataPoint name="currentStageOfWashingCycle" readable="true" writable="false">
<Doc>This property indicates the current stage of the washing cycle.</Doc> <Doc>This property indicates the current stage of the washing cycle.</Doc>
<DataType> <DataType>
<!-- <SimpleType type="enum" /> -->
<SimpleType type="string" /> <SimpleType type="string" />
</DataType> </DataType>
</DataPoint> </DataPoint>
...@@ -152,7 +152,6 @@ ...@@ -152,7 +152,6 @@
<DataPoint name="onTimerReservationSetting" readable="true" writable="true"> <DataPoint name="onTimerReservationSetting" readable="true" writable="true">
<Doc>Reservation ON/OFF</Doc> <Doc>Reservation ON/OFF</Doc>
<DataType> <DataType>
<!-- <SimpleType type="enum" /> -->
<SimpleType type="boolean" /> <SimpleType type="boolean" />
</DataType> </DataType>
</DataPoint> </DataPoint>
...@@ -168,9 +167,9 @@ ...@@ -168,9 +167,9 @@
<SimpleType type="time" /> <SimpleType type="time" />
</DataType> </DataType>
</DataPoint> </DataPoint>
</Data> </Data>
</ModuleClass> </ModuleClass>
</ModuleClasses> </ModuleClasses>
</DeviceClass> </DeviceClass>
</DeviceClasses> </DeviceClasses>
......
SDT/schema4.0/test/SimpleExample.xml 0 → 100644
+ 20
− 0
View file @ ff366ff9
<?xml version="1.0" encoding="iso-8859-1"?>
<Domain xmlns="http://www.onem2m.org/xml/sdt/4.0" id="SimpleExample" >
<DeviceClasses>
<DeviceClass id="Light">
<Doc>This is a very simple device representing a light.</Doc>
<ModuleClasses>
<ModuleClass name="Switch">
<Data>
<DataPoint name="status" readable="true" writable="true">
<Doc>This property indicates the ON/OFF status.</Doc>
<DataType>
<SimpleType type="boolean" />
</DataType>
</DataPoint>
</Data>
</ModuleClass>
</ModuleClasses>
</DeviceClass>
</DeviceClasses>
</Domain>
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment