Skip to content

GitLab

Commit ff366ff9 authored by ankraft's avatar ankraft
Browse files

reworked examples. Added Simple example.

parent ee9cd4a6
Show whitespace changes
Inline Side-by-side
Showing with 356 additions and 62 deletions
SDT/schema4.0/docs/Examples.md
View file @ ff366ff9
# Examples and Contributions
## 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 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/) ).
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.
|Funtionality | Air Conditioner | Washing Machine |
|Functionality | 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 |
|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:
- *air-conditioner*: operationStatus, measuredCumulativePowerConsumption, installationLocation;
- *washing-machine*: operationStatus, measuredCumulativePowerConsumption, setTimer.
- *washing-machine*: operationStatus, measuredCumulativePowerConsumption, setTimer, temperatureSensorDataPoints.
```XML
```xml
<ModuleClass name="operationStatus">
<Data>
<DataPoint name="operationStatus" writable="true">
......@@ -36,6 +86,7 @@ Based on the simplified example above, the two appliances will need the ModuleCl
</Data>
<Events>
<Event name="operationStatus">
<!-- Event payload not shown here -->
</Event>
</Events>
</ModuleClass>
......@@ -65,99 +116,323 @@ Based on the simplified example above, the two appliances will need the ModuleCl
</Events>
</ModuleClass>
<ModuleClass name="onTimerSetting">
<DataPoint name="onTimer" writable="true">
<ModuleClass name="temperatureSensorDataPoints">
<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>
<DataType>
<SimpleType type="time"/>
<SimpleType type="time" />
</DataType>
</DataPoint>
</ModuleClass>
<DataPoint name="relativeTimeBasedOnTimerSetting" readable="true" writable="true">
<Doc>Timer value (HH:MM)</Doc>
<DataType>
<SimpleType type="time" />
</DataType>
</DataPoint>
</Data>
</ModuleClass>
</ModuleClasses>
</DeviceClass>
```
<a name="echonetExampleFull"></a>
### The full SDT
The structure and the according SDT now looks like this:
|Example1.SDT |
|:--------------|
|Namespace information |
|Modules (contains ModuleClasses) |
|operationStatus <ul><li>measuredCumulativePowerConsumption</li><li>installationLocation</li><li>onTimerSetting</li></ul> |
|EchonetLiteExamples.xml | |
|:--------------|-|
|Namespace information | example.based.on.echonetLite |
|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>|
|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 version="1.0" encoding="iso-8859-1"?>
<!-- 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"
xmlns:xi="http://www.w3.org/2001/XInclude"
id="example1.SDT">
id="example.based.on.echonetLite">
<ModuleClasses>
<!-- Various examples for module classes -->
<ModuleClasses>
<ModuleClass name="operationStatus">
<Data>
<DataPoint name="operationStatus" writable="true">
<Doc>This property sets the ON/OFF status.</Doc>
<DataPoint name="operationStatus" readable="true" writable="true">
<Doc>This property indicates the ON/OFF status.</Doc>
<DataType>
<SimpleType type="boolean"/>
<SimpleType type="boolean" />
</DataType>
</DataPoint>
</Data>
<Events>
<Event name="operationStatus">
</Event>
</Events>
</ModuleClass>
<!-- runtime property -->
<ModuleClass name="installationLocation">
<Data>
<DataPoint name="installationLocation" writable="true">
<DataPoint name="installationLocation" readable="true" writable="true">
<Doc>This property indicates the installation location</Doc>
<DataType>
<SimpleType type="string"/>
<SimpleType type="string" />
</DataType>
</DataPoint>
</Data>
<Events>
<Event name="installationLocation"> </Event>
<Event name="installationLocation">
<!-- Event payload not shown here -->
</Event>
</Events>
</ModuleClass>
<ModuleClass name="measuredCumulativePowerConsumption">
<!-- sensor readout -->
<ModuleClass name="measuredInstantaneousPowerConsumption">
<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"/>
<DataPoint name="measuredInstantaneousPowerConsumption" readable="true" writable="false">
<Doc>This property indicates the instantaneous power consumption of the device in watts.</Doc>
<DataType unitOfMeasure="watts">
<SimpleType type="integer" />
</DataType>
</DataPoint>
</Data>
</ModuleClass>
<ModuleClass name="onTimerSetting">
<DataPoint name="onTimer" writable="true">
<Doc>Timer value (HH:MM)</Doc>
<DataType>
<SimpleType type="time"/>
<ModuleClass name="temperatureSensorDataPoints">
<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>
</ModuleClasses>
</Domain>
```
TODO Implementation in Device
---
<!-- Very simple example for a washing machine definition -->
<DeviceClasses>
<DeviceClass id="SimpleWaschingMachine">
<!-- Device Properties -->
<a name="mseeb"></a>
### Multi Socket Electrical-Extension-Block
<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>
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
separate *SubDevice*.
[mseeb.xml](../test/mseeb.xml)
<!-- 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>
<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
View file @ ff366ff9
......@@ -69,6 +69,9 @@
<DeviceClasses>
<DeviceClass id="SimpleWaschingMachine">
<!-- Device Properties -->
<Properties>
<Property name="Name" value="washing machine">
<SimpleType type="string" />
......@@ -119,21 +122,18 @@
<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="enum" /> -->
<SimpleType type="string" />
<SimpleType type="boolean" />
</DataType>
</DataPoint>
<DataPoint name="washingMachineSetting" readable="true" writable="true">
<Doc>Washing machine setting</Doc>
<DataType>
<!-- <SimpleType type="enum" /> -->
<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="enum" /> -->
<SimpleType type="string" />
</DataType>
</DataPoint>
......@@ -152,7 +152,6 @@
<DataPoint name="onTimerReservationSetting" readable="true" writable="true">
<Doc>Reservation ON/OFF</Doc>
<DataType>
<!-- <SimpleType type="enum" /> -->
<SimpleType type="boolean" />
</DataType>
</DataPoint>
......@@ -168,9 +167,9 @@
<SimpleType type="time" />
</DataType>
</DataPoint>
</Data>
</ModuleClass>
</ModuleClasses>
</DeviceClass>
</DeviceClasses>
......
SDT/schema4.0/test/SimpleExample.xml 0 → 100644
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
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