Merge branch 'RDM-2020-0021-SDT_4_0_-_New_documentation' into WI-0081-Smart_Device_Template_4_0

LICENSE

-Copyright 2019, oneM2M Partners Type 1
+Copyright 2020, 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:
 

README.md

@@ -12,12 +12,12 @@ Any contributions made to the Smart Device Template format must comply with the
 
 ![](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.
+The Smart Device Template (SDT) is a template method 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) for applications that need to interact with connected devices. Usually, these applications would communicate to devices using an abstraction or service layer, or cloud platform as an intermediary logic. This layer usually "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
-- [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.
+- [UML Diagrams of the SDT 4.0](SDT/schema4.0/docs/UML%20Diagram.md) ([Umlet source](SDT/schema4.0/docs/SDT_UML.uxf)) : These 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.
 
 

SDT/schema4.0/docs/Changelog.md

@@ -13,6 +13,7 @@
 - Added ``optional`` attribute to ``<Arg>``.
 - Added ``default`` attribute to ``<Arg>``.
 - Added ``default`` attribute to ``<DataPoint``.
+- Added `minOccurs`` and ``maxOccurs`` to SubDevice and ModuleClass
 - Unified all component identifiers, names etc to XSD type ``name``.
 - Introduced JSON serialization guidelines.
 - Changed case of ``<Imports>`` element.

SDT/schema4.0/docs/Examples.md

@@ -7,29 +7,30 @@
 	1. [ModuleClasses Definition](#echonetExampleMC)
 	2. [DeviceClass Definition](#echonetExampleDC)
 	3. [The full SDT](#echonetExampleFull)
+3. [More examples](#moreExamples) 
 
 
 <a name="simpleExample"></a>
 ## A simple SDT example
 
-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.
+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](SDT_Components.md#ModuleClass) "Switch", which contains a single boolean [data point](SDT_Components.md#DataPoint) "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.
+It is a stand-alone definition without using previously defined [ModuleClasses](SDT_Components.md#ModuleClass). 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>|
+|DeviceClasses |<ul><li>Light ([DeviceClass](SDT_Components.md#DeviceClass))</li><ul><li>Switch ([ModuleClass](SDT_Components.md#ModuleClass))<ul><li>status ([DataPoint](SDT_Components.md#DataPoint)</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.
+The following code section shows the fully integrated template. The source code can be found in [SimpleExample.xml](../test/SimpleExample.xml) in the [test](../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">
+		<DeviceClass name="Light">
 			<Doc>This is a very simple device representing a light.</Doc>
 			<ModuleClasses>
 				<ModuleClass name="Switch">
@@ -51,7 +52,7 @@ The following code section shows the fully integrated template. The source code
 <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].
+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](SDT_Components.md#ModuleClass) 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/) ).
 
@@ -59,17 +60,17 @@ The source code can be found in [EchonetLiteExamples.xml](../test/EchonetLiteExa
 
 <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](SDT_Components.md#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](SDT_Components.md#ModuleClass): an air conditioner and a 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 |
+|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](SDT_Components.md#ModuleClass) below:
 
 - *air-conditioner*: operationStatus, measuredCumulativePowerConsumption, installationLocation;
 - *washing-machine*: operationStatus, measuredCumulativePowerConsumption, setTimer, temperatureSensorDataPoints.
@@ -131,9 +132,9 @@ Based on the simplified example above, the two appliances will need the ModuleCl
 
 <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.
+To define a device one would now reference those [ModuleClass](SDT_Components.md#ModuleClass) definitions in a new [DeviceClass](SDT_Components.md#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.
+In addition to the previously defined [ModuleClasses](SDT_Components.md#ModuleClass) this "SimpleWashingMachine" [DeviceClass](SDT_Components.md#DeviceClass) extends the existing [ModuleClass](SDT_Components.md#ModuleClass) "operationStatus" with an event. It also adds a new [ModuleClass](SDT_Components.md#ModuleClass) "washingMachineDataPoints" with model-specific [DataPoints](SDT_Components.md#DataPoint).
 
 At the beginning of the definition some device Properties are defined.
 
@@ -249,8 +250,8 @@ The structure and the according SDT now looks like this:
 |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>|
+|[ModuleClasses](SDT_Components.md#ModuleClass) |<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](SDT_Components.md#DeviceClass) |<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.
 
@@ -433,6 +434,8 @@ The following code section shows the fully integrated template.
 		</DeviceClass>
 	</DeviceClasses>
 </Domain>
-
 ```
 
+<a name="moreExample"></a>
+## More Examples
+More examples that also show specific features of the SDT are available in the [test](../test) directory.

SDT/schema4.0/docs/FAQ.md

@@ -47,6 +47,8 @@ Please follow the instructions for the [SDT Build System](SDT/schema4.0/docs/SDT
 
 In short:
 
+- Clone the SDT repository from [https://git.onem2m.org/MAS/SDT.git](https://git.onem2m.org/MAS/SDT.git)
+- Install Apache ant
 - In a terminal, go to the directoy *SDT/schema4.0*
 - Run the command:
 ```sh 

SDT/schema4.0/docs/Links.md

@@ -3,9 +3,6 @@
 
 ## 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)
 

SDT/schema4.0/docs/SDT Build System.md

 # SDT Build System
-This document describes the SDT build system and how to build the SDT and validate new templates and contributions.
+This document describes the SDT build system and how to build the SDT schema and validate new templates and contributions.
 
 The files referenced in this document point to version **4.0** of the SDT.
 
@@ -16,7 +16,8 @@ The files referenced in this document point to version **4.0** of the SDT.
 - [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 the Schema](#Editing) below.
+	**Only edit this file when you want to make changes to the SDT! Changes to XSD file will be overwritten the next time you run the *ant* command.**  
+	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.  
@@ -65,7 +66,7 @@ The output after a successful validation should look similar this:
 >BUILD SUCCESSFUL  
 >Total time: 1 second
 
-Otherwise you most likely receive a stack trace or some other error messages. Search the output for the line *BUILD FAILED*. Above this line you will find some helpful hints for the filename and line number on which the error occurred (here: file *mseeb.xml* on line 66) and a reason:	
+Otherwise you most likely receive a stack trace and some other error messages. Search the output for the line *BUILD FAILED*. Above this line you will find some helpful hints for the filename and line number on which the error occurred (here: file *mseeb.xml* on line 66) and a reason:	
 
 >[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

SDT/schema4.0/docs/UML Diagram.md

@@ -8,12 +8,18 @@ The source for the diagrams below can be found [here (SDT_UML.uxf)](SDT_UML.uxf)
 
 ## Basic Elements
 
+This diagram presents the main functional elements of the Smart Device Template.
+
 ![](images/SDT_UML_Basic_Elements.png)
 
 ## Data Types
 
+This diagram shows how data types are specified in the Smart Device Temple.
+
 ![](images/SDT_UML_DataType.png)
 
 ## Extend
 
+Some elements of the Smart Device Template can be extended. This diagram presents the elements that are used to extend elements as well as to include and exclude certain attributs and sub-elements when extending.
+
 ![](images/SDT_UML_Extend.png)