diff --git a/SDT/schema4.0/docs/Examples.md b/SDT/schema4.0/docs/Examples.md index a51d0e6a487e162a462ca3c4b5a1fb8f5eebd660..182255574361e8247f3eda30b3b8df62df25b992 100644 --- a/SDT/schema4.0/docs/Examples.md +++ b/SDT/schema4.0/docs/Examples.md @@ -1,30 +1,80 @@ # 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"> - <Doc>Timer value (HH:MM)</Doc> - <DataType> - <SimpleType type="time"/> - </DataType> - </DataPoint> +<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" /> + </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> +``` + +<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 --> + <!-- Various examples for module classes --> + <ModuleClasses> <ModuleClass name="operationStatus"> <Data> - <DataPoint name="operationStatus" writable="true"> - <Doc>This property sets the ON/OFF status.</Doc> - <DataType> - <SimpleType type="boolean"/> - </DataType> + <DataPoint name="operationStatus" readable="true" writable="true"> + <Doc>This property indicates the ON/OFF status.</Doc> + <DataType> + <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"/> - </DataType> - </DataPoint> + <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> -``` + + + <!-- Very simple example for a washing machine definition --> + + <DeviceClasses> + <DeviceClass id="SimpleWaschingMachine"> -TODO Implementation in Device + <!-- Device Properties --> ---- + <Properties> + <Property name="Name" value="washing machine"> + <SimpleType type="string" /> + </Property> + <Property name="Vendor" value="ACME"> + <SimpleType type="string" /> + </Property> + </Properties> -<a name="mseeb"></a> -### Multi Socket Electrical-Extension-Block + <ModuleClasses> + + <!-- Inheriting ModuleClasses from the global generic ModuleClasses --> -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*. + <ModuleClass name="installationLocation"> + <Extend domain="example.based.on.echonetLite" entity="installationLocation"/> + </ModuleClass> -[mseeb.xml](../test/mseeb.xml) + <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" /> + </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> + +``` diff --git a/SDT/schema4.0/test/EchonetLiteExamples.xml b/SDT/schema4.0/test/EchonetLiteExamples.xml index e87de7a63e29f9275de5db6a4592c2b17bac490c..fd411ca72f383e31be7f26b24e0fb7f8bb162268 100644 --- a/SDT/schema4.0/test/EchonetLiteExamples.xml +++ b/SDT/schema4.0/test/EchonetLiteExamples.xml @@ -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> diff --git a/SDT/schema4.0/test/SimpleExample.xml b/SDT/schema4.0/test/SimpleExample.xml new file mode 100644 index 0000000000000000000000000000000000000000..d9d097068c985de8ab86096407aeddf619a6e843 --- /dev/null +++ b/SDT/schema4.0/test/SimpleExample.xml @@ -0,0 +1,20 @@ +<?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