diff --git a/SDT/schema4.0/docs/Introduction.md b/SDT/schema4.0/docs/Introduction.md index 08ad356e43eb82a7356e39e7bed122420ba085d9..43421c43d49d3c181b8eb356f50ebd8f41d2683a 100644 --- a/SDT/schema4.0/docs/Introduction.md +++ b/SDT/schema4.0/docs/Introduction.md @@ -46,6 +46,7 @@ This section provides an overview about the SDT 4.0 definitions and element hier |Domain | Unique name, or "wrapper" which acts like a namespace, set by the organization creating the SDT, allowing reference to a package of definitions for the contained ModuleClasses and device definitions. Can be referenced when extending ModuleClasses. It has two possible uses: to select the scope of a technology domain, or to set the scope of a use case domain (like Home, SmartGrid, etc) | | Device | Physical, addressable, identifiable appliance/sensor/actuator. | | Sub-Device | A device (usually one of several) which may be embedded in a Device and/or is addressed via another Device. | +| Product| A concrete device model with deterministic Device Properties and ModuleClasses (no optionality). It's deemed as an specialized implementation of a DeviceClass but not yet an device instance. Examples are the shopping items (e.g. a smart watch) in an online digital store that can be ordered (but not necessarily manufactured) by a customer. | | ModuleClass | Specification of a single service with one or more service methods, the involved abstracted data model and related events. The expectation is that each separate service which may be used in many kinds of Devices (like PowerON/OFF, Open/Close, ...) will be described by a ModuleClass which can be re-used in many Device definitions. | | Module | Instantiation of a ModuleClass for a specific Device or SubDevice| diff --git a/SDT/schema4.0/docs/SDT_Components.md b/SDT/schema4.0/docs/SDT_Components.md index bac78e0a486bdf17bfa377f36efe0921e021ef8e..28c4403f411f7d7857b946322edb727e78e7abdd 100644 --- a/SDT/schema4.0/docs/SDT_Components.md +++ b/SDT/schema4.0/docs/SDT_Components.md @@ -2,6 +2,7 @@ [Domain](#Domain) [Device](#Device) | [SubDevice](#SubDevice) +[Product](#Product) [Property](#Property) [Module and ModuleClass](#ModuleClass) [Action](#Action) @@ -75,6 +76,7 @@ It can also be used to collect all specified [ModuleClasses](#ModuleClasses) --- <a name="Device"/></a> + ### Device  @@ -115,6 +117,7 @@ An example for a compound device is a connected power-strip where each of the s --- <a name="SubDevice"/></a> + ### SubDevice *SubDevices* are optional components of a [Device](#Device). They represent physical sub-devices and services inside another device (the *Device*). @@ -143,8 +146,114 @@ An example for a compound device is a connected power-strip where each of the s </SubDevice> --- +<a name="Product"/></a> + +### Product + + + +In real life of device manufacturing, there is an important concept of *Product* under a certain *DeviceClass*. For example, oneM2M may specify a generic *DeviceClass* called 'deviceSmartBracelt' with many fancy features (*ModuleClasses*). Based on the same *DeviceClass*, company A may design a *Product* called 'X-Fit' with only the *ModuleClass* of 'stepCounter' and the instantiated *Property* value of 'Manufacturer = Company A', while company B may design a *Product* called 'Y-Wristband' with the *ModuleClasses* of 'stepCounter' and 'heartRateMonitor' and the instantiated *Property* value of 'Manufacturer = Company B'. Those two *Products* are different but follow the same *DeviceClass*. + +On the other hand, a *Product* is **NOT** yet a real device instance of that ��DeviceClass��. It may not have an instantiated *Properties* like device-id, date-of-manufacturing, and the firmware/software-version, etc. It can be ��ordered�� by the customers, but not necessarily instantiated or manufactured. + +In short, a *Product* is a concrete device model with deterministic Device Properties and ModuleClasses (no optionality). It's deemed as an specialized implementation of a *DeviceClass* but not yet an device instance. Examples are the shopping items in an online digital store that can be ordered (but not necessarily manufactured) by a customer. + +A *Product* can be defined by inheriting from an existing *DeviceClass* (e.g. removing unimplemented optional *Properties* and *ModuleClasses*), extending from an existing *DeviceClass* (adding new *Properties* and *ModuleClasses*), or from scratch (without basing on any *DeviceClass*). + +#### Attributes +- **id** : The identifier for that *Product*. The identifier must be unique at least in the scope of the domain, but the final scope is also influenced by implementing technologies. Required. + +#### Elements +All elements of *DeviceClass* can be reused in *Product*, but the *optional* attribute of those elements is not applicable (ignored if present). + +- **[Doc](#Documentation)** : Documentation for the *Product*. Optional. +- **[Properties](#Property)** : Further meta-data (or properties) about the *Product*. Optional. +- **[ModuleClasses](#ModuleClass)** : A list of *Module* components that are local to the *Product*. Optional. +- **[SubDevices](#SubDevice)** : A list of *SubDevice* components. Optional. +- **Extends** : Reference to a *DeviceClass* which is extended with this *Product*. Optional. +The element has the following attributes: + - **domain** : Identifier / Reference of the [Domain](#Domain) of the extended *DeviceClass*. Required for this element. + - **class** : Name of the *DeviceClass* in the [Domain](#Domain) that is extended. Required for this element. +The element has the following child elements: + - **ImplementModuleClasses** : A list of names of the implemented optional [ModuleClasses](#ModuleClass) in the [DeviceClass](#DeviceClass) that is extended. Optional. If not present, only mandatory [ModuleClasses](#ModuleClass) are implemented. If present, both the listed optional [ModuleClasses](#ModuleClass) and the mandatory [ModuleClass](#ModuleClass) are implemented. + - **ImplementProperties** : A list of name-value pairs of the implemented optional device [Properties](#Property) in the [DeviceClass](#DeviceClass) that is extended. Optional. If not present, only mandatory [Properties](#Property) are implemented. If present, both the listed optional [Properties](#Property) and the mandatory [Properties](#Property) are implemented, and the values of those [Properties](#Property) are initiated as provided. In the case that the value of the [Properties](#Property) should not be initiated, the value can be omitted. + +**Note**: New extended *Properties* and *ModuleClasses* **should** have different names from those in the inherited *DeviceClass*. In case the names conflict, the newly defined *Properties* and *ModuleClasses* shall override the inherited ones. + +*Editor's Note: the description of the optionality of the datapoints, properties, actions, events in the inherited ModuleClass is FFS* + +#### XML Example +``` +<Product id="myMseebProduct"> + <Extends domain="org.exampleDomain" class="MSEEB.root"> + <ImplementProperty> + <Property name="name" value="product-abc"/> + <Property name="vendor" value="xyz"/> + <Property name="SerialNumber"/> + </ImplementProperty> + <ImplementModuleClasses> + <MoudleClass name="rootPowerOnOff"/> + <MoudleClass name="power" /> + </ImplementModuleClasses> + </Extends> + <Properties name="someNewProperty" value="someValue"> + <Doc>...</Doc> + <SimpleType type="string" /> + </Properties> + <ModuleClasses name="someNewModuleClass"> + <Actions> + <!-- List of Actions goes here--> + </Actions> + <Events> + <!-- List of Events goes here--> + </Events> + <DataPoints> + <!-- List of DataPoints goes here--> + </DataPoints> + </ModuleClasses> +</Product> +``` + +#### JSON Example +``` +{ + "Product": { + "id": "myMseebProduct", + "Extends": { + "domain": "org.exampleDomain", + "class": "MSEEB.root", + "ImplementProperties": [{ + "name": "name", + "value": "product-abc" + }, + { + "name": "Vendor", + "value": "xyz" + }, + { + "name": "SerialNumber" + }], + "ImplementModuleClasses": ["rootPowerOnOff","power"] + }, + "Properties": [{ + "name": "someNewProperty", + "value": "someValue", + "Doc": "...", + "DataType": "..." + }], + "ModuleClasses": [{ + "name": "someNewModuleClass", + "Actions": [], + "DataPoints": [], + "Events": [] + }] + } +} +``` +--- <a name="Property"/></a> + ### Property : Element of a *Device* or *ModuleClass*  @@ -173,6 +282,7 @@ Since the *Properties* are highly varied, depending on industry segment, no atte --- <a name="ModuleClass"/></a> + ### Module and ModuleClass  @@ -227,6 +337,7 @@ The element has the following attributes: --- <a name="DataPoint"/></a> + ### DataPoint : Element of *ModuleClass* and *Event*  @@ -271,6 +382,7 @@ In EBNF: --- <a name="Action"/></a> + ### Action : Element of *ModuleClass*  @@ -289,6 +401,7 @@ Note that systems which rely on RESTful operations need to carry out such comple - **Args** : Zero or more occurances of [argument](#Arg) definitions for an *Action*. Optional. <a name="ActionExample"/></a> + #### Example The following are two examples for actions implementing a getter and a setter for boolean values. @@ -311,6 +424,7 @@ The following are two examples for actions implementing a getter and a setter fo --- <a name="Event"/></a> + ### Event : Element of *ModuleClass*  @@ -341,6 +455,7 @@ The following are two examples for actions implementing a getter and a setter fo --- <a name="Arg"/></a> + ### Arg : Element of *Action*  @@ -362,6 +477,7 @@ See [example above](#ActionExample). --- <a name="Data_Types"/></a> + ### DataType The data type can be simple integers or string text, or rather complex, as shown below: @@ -388,6 +504,7 @@ The *DataType* element is a "container" for the various aspects of a type. --- <a name="Constraint"/></a> + ### Constraint : Element of DataType  @@ -413,6 +530,7 @@ The *TypeChoice* construct is required for syntactic reasons in the UML diagram --- <a name="SimpleType"/></a> + ### SimpleType : Element of *TypeChoice*  @@ -440,6 +558,7 @@ If not stated otherwise datatypes should comply to the equivalent datatypes defi --- <a name="StructType"/></a> + ### StructType : Element of *TypeChoice*  @@ -453,6 +572,7 @@ The *StructType* element can be used to represent an ordered list of diverse Dat --- <a name="ArrayType"/></a> + ### ArrayType : Element of *TypeChoice*  @@ -465,6 +585,7 @@ The *ArrayType* element is provided for defining lists of data; the definition i --- <a name="Documentation"/></a> + ### Doc : Element for all Documentation 