Skip to content
Snippets Groups Projects
Commit 48ce2e3f authored by Andreas Kraft's avatar Andreas Kraft
Browse files

Changed anchors

parent 600de362
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 67 additions and 67 deletions
SDT/schema4.0/docs/Examples.md
+ 7
− 7
View file @ 48ce2e3f
......@@ -10,7 +10,7 @@
3. [More examples](#moreExamples)
<a id="simpleExample"></a>
<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](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.
......@@ -30,7 +30,7 @@ The following code section shows the fully integrated template. The source code
<?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">
......@@ -49,7 +49,7 @@ The following code section shows the fully integrated template. The source code
</Domain>
```
<a id="echonetExample"></a>
<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](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].
......@@ -58,7 +58,7 @@ In the ideal case, a large organization or SDO would define a widely-applicable
The source code can be found in [EchonetLiteExamples.xml](../test/EchonetLiteExamples.xml) in the "test" directory.
<a id="echonetExampleMC"></a>
<a name="echonetExampleMC"></a>
### ModuleClasses
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.
......@@ -130,7 +130,7 @@ Based on the simplified example above, the two appliances will need the [ModuleC
```
<a id="echonetExampleDC"></a>
<a name="echonetExampleDC"></a>
### DeviceClass
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.
......@@ -243,7 +243,7 @@ At the beginning of the definition some device Properties are defined.
</DeviceClass>
```
<a id="echonetExampleFull"></a>
<a name="echonetExampleFull"></a>
### The full SDT
The structure and the according SDT now looks like this:
......@@ -436,6 +436,6 @@ The following code section shows the fully integrated template.
</Domain>
```
<a id="moreExample"></a>
<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
+ 7
− 7
View file @ 48ce2e3f
......@@ -9,14 +9,14 @@
2. [How to validate own templates](#validate)
3. [Are there tools to work with the SDT?](#tools)
<a id="general"></a>
<a name="general"></a>
## General
<a id="WhatistheSDT"></a>
<a name="WhatistheSDT"></a>
### What is the SDT?
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.
<a id="WhatisoneM2M"></a>
<a name="WhatisoneM2M"></a>
### What is oneM2M?
oneM2M is a global organization that creates requirements, architecture, API specifications, security solutions and interoperability for Machine-to-Machine and IoT technologies.
......@@ -38,10 +38,10 @@ Service Layer aspects with high level and detailed service architecture, in ligh
[http://www.onem2m.org](http://www.onem2m.org)
<a id="working"></a>
<a name="working"></a>
## Working with the SDT
<a id="working"></a>
<a name="working"></a>
### How to build the SDT
Please follow the instructions for the [SDT Build System](SDT/schema4.0/docs/SDT%20Build%20System.md).
......@@ -55,7 +55,7 @@ In short:
$ ant
```
<a id="validate"></a>
<a name="validate"></a>
### How to validate own templates
Please follow the instructions for the [SDT Build System](SDT/schema4.0/docs/SDT%20Build%20System.md).
......@@ -68,7 +68,7 @@ In short:
$ ant validate
```
<a id="tools"></a>
<a name="tools"></a>
### Are there tools to work with the SDT?
You can use the SDTTool to read and convert templates in SDT format to various output formats, e.g. XSD, SVG, markdown, Java code, etc.
......
SDT/schema4.0/docs/Introduction.md
+ 4
− 4
View file @ 48ce2e3f
......@@ -6,7 +6,7 @@
3. [How should SDT work?](#Work)
4. [Related aspects which are out of scope of the SDT](#related)
<a id="Introduction"/></a>
<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.
......@@ -56,7 +56,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 id="Definitions"/></a>
<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:
......@@ -83,7 +83,7 @@ This [ModuleClass](SDT_Components.md#ModuleClass) structure is a major part of t
![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 id="Work"/></a>
<a name="Work"/></a>
## How should SDT work?
The basic concept is that a manufacturer, organisation, service provider 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.
......@@ -94,7 +94,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 id="related"/></a>
<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/SDT Build System Components and Licenses.md
+ 3
− 3
View file @ 48ce2e3f
......@@ -7,7 +7,7 @@ The following third-party libraries and components are used in the build system
3. [antSetLogLevel.JAR](#antSetLogLevel)
<a id="trang"/></a>
<a name="trang"/></a>
## trang.jar
[https://relaxng.org/jclark/trang.html](https://relaxng.org/jclark/trang.html)
......@@ -53,7 +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 id="antcontrib"/></a>
<a name="antcontrib"/></a>
## Ant-Contrib Tasks
[http://ant-contrib.sourceforge.net](http://ant-contrib.sourceforge.net)
......@@ -64,7 +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 id="antSetLogLevel"/></a>
<a name="antSetLogLevel"/></a>
## antSetLogLevel.jar
GUI dialog for Ant tasks.
......
SDT/schema4.0/docs/SDT Build System.md
+ 6
− 6
View file @ 48ce2e3f
......@@ -11,7 +11,7 @@ The files referenced in this document point to version **4.0** of the SDT.
2. [Validating SDT Templates](#BuildingValidate)
4. [Editing the Schema](#Editing)
<a id="Structure"/></a>
<a name="Structure"/></a>
## Directory Structure and Important Files
- [SDT/schema4.0/](../..) : Base directory
- [SDT/schema4.0/src/](../src/) : Source files of the SDT.
......@@ -30,7 +30,7 @@ This could be example definitions or new templates and contributions. If you wan
- [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 id="Installation"/></a>
<a name="Installation"/></a>
## Installation
### Prerequisites
......@@ -42,18 +42,18 @@ This could be example definitions or new templates and contributions. If you wan
$ git clone https://git.onem2m.org/MAS/SDT.git
<a id="Building"/></a>
<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.
<a id="BuildingSchema"/></a>
<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 id="BuildingValidate"/></a>
<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:
......@@ -71,7 +71,7 @@ Otherwise you most likely receive a stack trace and some other error messages. S
>[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 id="Editing"/></a>
<a name="Editing"/></a>
## 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.
......
SDT/schema4.0/docs/SDT_Components.md
+ 28
− 28
View file @ 48ce2e3f
......@@ -46,12 +46,12 @@ The syntax used in the diagrams to model an XML Schema Definition (XSD) as an UM
- [UML For W3C XML Schema Design](http://www.xml.com/pub/a/2002/08/07/wxs_uml.html)
<a id="BasicComponents"></a>
<a name="BasicComponents"></a>
## Basic Elements
![](images/SDT_UML_Basic_Elements.png)
<a id="Domain"></a>
<a name="Domain"></a>
### Domain
![](images/Domain.png)
......@@ -95,7 +95,7 @@ Note, that when using **Imports** one must include the following namespace in th
---
<a id="ModuleClass"/></a>
<a name="ModuleClass"/></a>
### ModuleClass
Element of [Domain](#Domain) and [Product](#Product).
......@@ -151,7 +151,7 @@ Also note, that if both *minOccurs* and *maxOccurs* are specified, then *maxOccu
---
<a id="DataPoint"/></a>
<a name="DataPoint"/></a>
### DataPoint
Element of [ModuleClass](#ModuleClass) and [Event](#Event).
......@@ -202,7 +202,7 @@ string = (* character string excluding the character "/" *) ;
---
<a id="Action"/></a>
<a name="Action"/></a>
### Action
Element of [ModuleClass](#ModuleClass).
......@@ -223,7 +223,7 @@ Note, that systems which rely on RESTful operations need to carry out such compl
- **[DataType](#DataType)** : The return type of the *Action*. It must comply to the *DataType* definition. Optional. If no *DataType* is specified the *Action* does not return a value.
- **[Args](#Arg)** : Zero or more occurances of argument definitions for an *Action*. Optional.
<a id="ActionExample"/></a>
<a name="ActionExample"/></a>
#### Example
The following are two examples for actions implementing a getter and a setter for boolean values.
```xml
......@@ -246,7 +246,7 @@ The following are two examples for actions implementing a getter and a setter fo
---
<a id="Arg"/></a>
<a name="Arg"/></a>
### Arg
Element of [Action](#Action).
......@@ -271,7 +271,7 @@ See [the Action example above](#ActionExample).
---
<a id="Event"/></a>
<a name="Event"/></a>
### Event
Element of [ModuleClass](#ModuleClass).
......@@ -303,7 +303,7 @@ Element of [ModuleClass](#ModuleClass).
```
---
<a id="DeviceClass"/></a>
<a name="DeviceClass"/></a>
### DeviceClass
Element of [Domain](#Domain) and [Product](#Product).
......@@ -348,7 +348,7 @@ An example for a compound device is a connected power-strip where each of the s
---
<a id="SubDevice"/></a>
<a name="SubDevice"/></a>
### SubDevice
Element of [DeviceClass](#DeviceClass) and [Product](#Product).
......@@ -386,7 +386,7 @@ Also note, that if both *minOccurs* and *maxOccurs* are specified, then *maxOccu
```
---
<a id="ProductClass"/></a>
<a name="ProductClass"/></a>
### ProductClass
Element of [Domain](#Domain).
......@@ -447,7 +447,7 @@ All elements of [DeviceClass](#DeviceClass) can be reused in *ProductClass*, but
---
<a id="Property"/></a>
<a name="Property"/></a>
### Property
Element of a [ProductClass](#ProductClass), [DeviceClass](#DeviceClass), [SubDevice](#SubDevice), and [ModuleClass](#ModuleClass).
......@@ -478,7 +478,7 @@ Since the *Properties* are highly varied, depending on industry segment, no atte
---
<a id="DataTypes"/></a>
<a name="DataTypes"/></a>
## Data Types
......@@ -491,7 +491,7 @@ The various elements of *DataType* are described in the following sections.
*DataTypes* can be rather complex and it might be reasonable to define them on the [Domain](#Domain) level. This way the only need to be defined once and can be references through the [Extend](#Extend) element later, and also across [Domains](#Domain).
<a id="DataType"/></a>
<a name="DataType"/></a>
### DataType
Element of a [Domain](#Domain), [Property](#Property), [Action](#Action), [Arg](#Arg), [DataPoint](#DataPoint), [Event](#Event), [StructType](#StructType), and [ArrayType](#ArrayType).
......@@ -516,7 +516,7 @@ The *DataType* element is a "container" for the various aspects of a type.
---
<a id="Constraint"/></a>
<a name="Constraint"/></a>
### Constraint
Element of [DataType](#DataType).
......@@ -544,7 +544,7 @@ The *TypeChoice* construct is required for syntactic reasons in the UML diagram
---
<a id="SimpleType"/></a>
<a name="SimpleType"/></a>
### SimpleType
Element of [DataType](#DataType).
......@@ -583,7 +583,7 @@ If not stated otherwise datatypes should comply to the equivalent datatypes defi
```
---
<a id="StructType"/></a>
<a name="StructType"/></a>
### StructType
Element of [DataType](#DataType).
......@@ -612,7 +612,7 @@ The *StructType* element can be used to represent an ordered list of diverse Dat
---
<a id="ArrayType"/></a>
<a name="ArrayType"/></a>
### ArrayType
Element of [DataType](#DataType).
......@@ -638,7 +638,7 @@ The *ArrayType* element is provided for defining lists of data; the definition i
```
---
<a id="EnumType"/></a>
<a name="EnumType"/></a>
### EnumType
Element of [DataType](#DataType).
......@@ -649,7 +649,7 @@ The *EnumType* element is provided for defining an enumeration data type; it def
#### Elements
- **[EnumValue](#EnumValue)** : A list of *EnumValue" element that specifies the data type for the elements of the array.
<a id="EnumTypeExample"/></a>
<a name="EnumTypeExample"/></a>
#### Example
```xml
<DataPoint name="enumDataPoint">
......@@ -665,7 +665,7 @@ The *EnumType* element is provided for defining an enumeration data type; it def
---
<a id="EnumValue"/></a>
<a name="EnumValue"/></a>
### EnumValue
Element of [EnumType](#EnumType).
......@@ -687,7 +687,7 @@ See [example in *EnumType*](#EnumTypeExample).
---
<a id="Extending"/></a>
<a name="Extending"/></a>
## Extending (Inheriting)
The SDT supports inhering for certain element types. This is done by extending a parent element definition.
......@@ -698,7 +698,7 @@ Extension across [Domains](#Domain) is supported and encouraged.
![](images/SDT_UML_Extend.png)
<a id="ExtendExample"/></a>
<a name="ExtendExample"/></a>
#### Example
The following example defines two [ModuleClasses](#ModuleClass), where the second definition extends to first one, but explicitly excludes one of the [DataPoints](#DataPoint).
......@@ -725,7 +725,7 @@ The following example defines two [ModuleClasses](#ModuleClass), where the secon
---
<a id="Extend"/></a>
<a name="Extend"/></a>
### Extend
Element of [ProductClass](#ProductClass), [ModuleClass](#ModuleClass) and [DataType](#DataType).
......@@ -749,7 +749,7 @@ See [example in *Extending (Inheriting)*](#ExtendExample).
---
<a id="ExtendInclude"/></a>
<a name="ExtendInclude"/></a>
### Include
Element of [Extend](#Extend).
......@@ -764,7 +764,7 @@ This element specifies a single element from the parent that will be included wh
---
<a id="ExtendExclude"/></a>
<a name="ExtendExclude"/></a>
### Exclude
Element of [Extend](#Extend).
......@@ -778,7 +778,7 @@ This element specifies a single element from the parent that will be excluded wh
---
<a id="ExtendType"/></a>
<a name="ExtendType"/></a>
### ExendType
Element of [ExtendInclude](#ExtendInclude) and [ExtendExclude](#ExtendExclude).
......@@ -788,7 +788,7 @@ This is an enumeration of element types for inclusion or exclusion while extendi
---
<a id="Documentation"/></a>
<a name="Documentation"/></a>
## Documentation (Doc)
Element for documentation in all elements.
......
SDT/schema4.0/docs/SDT_JSON.md
+ 12
− 12
View file @ 48ce2e3f
......@@ -17,7 +17,7 @@
<a id="introduction"/></a>
<a name="introduction"/></a>
## Introduction
When the Smart Device Template was introduced, XML was the favorite encoding format for schemas. Since then, JSON became more popular in developers' communities, especially in the context of RESTful implementations.
......@@ -32,10 +32,10 @@ In this release, we chose to define the JSON serialization by the documentation
The general JSON structure follows the general SDT structure presented in [SDT_UML.uxf](SDT_UML.uxf) and described in [SDT_Components.md](SDT_Components.md).
<a id="mappings"/></a>
<a name="mappings"/></a>
## SDT mapping to JSON
<a id="elements"/></a>
<a name="elements"/></a>
### Elements mapping
| SDT XML Elements | JSON Key Words | Remark |
......@@ -134,7 +134,7 @@ The following example defines a simple *Light* device.
}
```
<a id="attributes"/></a>
<a name="attributes"/></a>
### Attributes mapping
There are common attributes (e.g. *@id, @name, @optional*) used in several SDT components (e.g. in *DeviceClass, ModuleClass*) as well as attributes used only in certain components (e.g. *@entity* in *Extend*). XML attributes are represented as normal fields in JSON. The mapping of those attributes to JSON follows the rules as below.
......@@ -159,7 +159,7 @@ There are common attributes (e.g. *@id, @name, @optional*) used in several SDT c
| @writable | writable |
<a id="imports"/></a>
<a name="imports"/></a>
### Import mapping
The imports are mapped to an array of *Include* structures. Each *Include* structure contains a *href* and a *parse* element.
......@@ -184,7 +184,7 @@ A parser must make sure to import and regard the definitions in the referenced f
]
```
<a id="ExtendType"/></a>
<a name="ExtendType"/></a>
### ExtendType mapping
In the *Include* and *Exclude* elements one may specify the type of the element to be included or excluded. The following table shows the mapping of [ExtendType](SDT_Components.md#ExtendType).
......@@ -199,14 +199,14 @@ In the *Include* and *Exclude* elements one may specify the type of the element
| subdevice | subdevice |
<a id="dataTypes"/></a>
<a name="dataTypes"/></a>
### Data Type mapping
Data types are defined in [SDT_Components.md](SDT_Components.md).
The mapping of the different kind of data types to JSON happens directly to JSON structures. The identifier for the data type kind is the name of that structure. This means that the data type definition is not wrapped by a *DataType* structure.
<a id="SimpleType"/></a>
<a name="SimpleType"/></a>
### SimpleType
Note for [SimpelType](SDT_Components.md#SimpelType): For simplicity, if there is no other attribute present then the type value of [SimpelType](SDT_Components.md#SimpelType) can be directly put as the value of parent [DataType](SDT_Components.md#DataType) key, e.g. ```"DataType":"string"```
......@@ -263,7 +263,7 @@ A simple data type with additional attributes:
}
```
<a id="ArrayType"/></a>
<a name="ArrayType"/></a>
### ArrayType
An [ArrayType](SDT_Components.md#ArrayType) definition is mapped to an *Array* JSON structure. The content of the structure is only one element that defines the type of the array. This could be any [SimpleType](#SimpleType), [ArrayType](#ArrayType), [StructType](#StructType), or [EnumType](#EnumType).
......@@ -292,7 +292,7 @@ A simple data type with additional attributes:
}
```
<a id="StructType"/></a>
<a name="StructType"/></a>
### StructType
A [StructType](SDT_Components.md#StructType) definition is mapped to a *Struct* JSON array. The content of the array are the individual data types for the structure. These could be any [SimpleType](#SimpleType), [ArrayType](#ArrayType), [StructType](#StructType), or [EnumType](#EnumType).
......@@ -374,7 +374,7 @@ A more complex structured data type (a structure that contains an indentifier va
]
```
<a id="EnumType"/></a>
<a name="EnumType"/></a>
### EnumType
A [EnumType](SDT_Components.md#EnumType) definition is mapped to an *Enum* JSON structure. The content of the structure are the individual enum values of the enum.
......@@ -407,7 +407,7 @@ An *Enum* that defines three [EnumValues](SDT_Components.md#EnumValues). The fir
]
```
<a id="extendingDatatypes"/></a>
<a name="extendingDatatypes"/></a>
### Extending Data Types
Extending [DataTypes](SDT_Components.md#DataTypes) are mapped the same way as extending, for example, [ModuleClasses](SDT_Components.md#ModuleClass). However, since the [DataType](SDT_Components.md#DataTypes) is open, the generic form [DataType](SDT_Components.md#DataTypes) must be used for JSON serialization. It maps to a structure that contains a single [Extend](SDT_Components.md#Extending) structure. This structure contains the two attributes *domain* and *entity*.
......
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