5.2 Design Principle of the Harmonised Information Model
5.2.1 Basic design principle of information modelling
Editor's note: this clause has to be updated (removed specific references to Home). Also, text added for this clause
The design principle of the oneM2M abstract information model of home appliance, is to use SDT4.0 originally introduced in oneM2M TR0017 [i.2]. Note that those terms starting with a capital letter in this clause are SDT terms and are explained in [1].
Domain is a unique name which acts like a namespace (e.g., "org.oneM2M.home.modules"). It is set by the organization creating the SDT, allowing reference to a package of definitions for the contained ModuleClasses and DeviceClass models.
ModuleClasses specifies a single service (e.g., audioVolume, powerOn/Off) with one or more Actions, Properties, DataPoints and Events. Each service which is described as a ModuleClass can be re-used in many DeviceClasses.
DeviceClass model is a physical, addressable, identifiable appliance, sensor and actuator with one or more ModuleClasses, Properties and SubDevices.
SubDevice is a device which may be embedded in a DeviceClass and/or is addressed via another DeviceClass.
Figure 5.2.1-1 depicts the basic structure of SDT 4.0. Further details about SDT 4.0 and its elements can be found in [1].
Specifications of new DeviceClass models and ModuleClasses are encouraged to re-use the definitions specified in the present document as much as possible. If re-use is not possible and new DeviceClass and/or ModuleClases definitions are necessary, it is strongly advised to closely follow the guidelines and definition style from the present document.
Figure 5.2.1-1: Design Structure of the Home Appliance Information Model using SDT 4.0-
The R/W column of the ModuleClasses' data point tables in clause 5.3 reflects the intentions of how a data point in a ModuleClass shall be used semantically. This is a "behavioural contract" between applications or users of the modelled devices on the semantic level. Further, the devices or IPE's (for NoDN) are expected to implement and control the mappings in clause 5.2.2 to implement this "behavioural contract".
5.2.2 Description rules for Module Classes and DeviceClasses
When the Home Appliances Information Model is described based on SDT, the following rules shall be applied:
-
Rule 1: CamelCase rule:
- When naming each element, lowerCamelCase shall be used as the Java coding rules [2].
- Element names shall only contain upper and lower case alphanumerical characters in the ranges "a..z", "A..Z" and "0..9" as defined in [22], and the underscore character "_". Element names shall not contain whitespace characters.
- The underscore character "_" shall only be used as a separator in element names that contain only uppercase characters.
-
Rule 2: Rule for description of Action, DataPoint:
- DataPoint shall be used to represent stateless operations. (e.g. powerState of binarySwitch for on/off operations).
- Action shall be used when describing stateful condition, handling unknown internal state conditions (e.g. upVolume/downVolume by increasing/decreasing the audioVolume in steps, handling transactional procedures, or checking integrity using username plus password at the same time).
-
Rule 3: Rule for description of DataPoint and Property:
- Non-functional information shall be described as a Property. Functional information shall be described as a DataPoint. (E.g. non-functional information: version, id; functional information: targetTemperature, targetVolume).
-
Rule 4: Definition of the Domain:
- The Domains are specified as "org.onem2m.[domain]", where [domain] is one of the domain names defined in 6.4.1. The name is chosen according to the domain in which the element is defined.
- The sub-domains for DeviceClasses, SubDevices, ModuleClasses and Actions shall be specified as "org.onem2m.[domain].device", "org.onem2m.[domain].subdevice", "org.onem2m.[domain].moduleclass", and "org.onem2m.[domain].action" respectively.
-
Rule 5: Naming rule for the element:
- the name of each element should be concise and avoid repeating its parent element name; but
- it may include the name of its parent element for readability. (e.g., lightDimmerUp, lightDimmerDown under lightDimmer);
- all DeviceClasses, SubDevices, ModuleClasses, and Actions of a domain shall be uniquely named.
-
Rule 6: Criteria for marking elements as optional or mandatory:
- An element shall only be defined as mandatory if it is foreseen to be universally mandatory to all implementing technologies.
-
Rule 7: Enumeration type:
- When describing the meaning of values for enumeration type elements, they may be described under clause 5.6.
- The enumeration types for the harmonized information model are based on <xs:integer>, and the numeric values are interpreted as specified in clause 5.6.
- The name of an enumeration type shall start with the prefix "enum". This prefix shall not be used with non-enumeration type names.
- All enumeration types are defined under the same domain called Horizontal Domain, which does not contain any other entity. They also shall use the same XSD name space identifiers as defined in clause 6.5.1. Even if an enumeration type is used in multiple module classes from different domains, this enumeration type is defined only once.
-
Rule 8: Rule for unit in documentation :
- SI (International Systems of Units in [20]) measurement (e.g. metre, kilogram, second) should be considered as first candidate.
- Otherwise, it may be kept consistency with implementing technologies such as other SDO's specification.
- Units of measures shall be given in the form of a shortcut compliant to table 5.2.2-1.
Table 5.2.2-1: Shortcuts for units
| Original name | Short name | Explanation |
|---|---|---|
| Ampere | A | |
| Ampere Hour | Ah | |
| Bar | bar | |
| Celsius | °C | |
| Centimetres | cm | |
| Cubic metre | m3 | |
| Cubic metre per hour | m3/h | |
| Decibel | dB | |
| Decibel-milliwatts | dBm | |
| Degrees | deg | |
| Dots per inch | dpi | dpi is the common unit for spatial dot density |
| g-force | g-f | |
| Grams | g | |
| Hertz | Hz | |
| Kilocalories | kcal | |
| Kilocalories per hour | kcal/h | |
| Kilograms per square metre | kg/m2 | |
| Kilopascal | kPa | |
| kilovar | kvar | |
| Kilowatt | kW | |
| Megabyte | MB | 1 MB = 1 024 x 1 024 bytes |
| MegaHertz | MHz | |
| Metre | m | |
| Metres per second | m/s | |
| Milligram per cubic metre | mg/m3 | |
| Microgram per cubic metre | µg/m3 | |
| Milligram per decilitre | mg/dl | |
| Milligram per litre | mg/L | |
| Millimetre | mm | |
| Millimetre of mercury | mmHg | |
| Milliseconds | ms | |
| Milliwatt per cubic centimetre | mW/cm2 | |
| Minute | min | |
| Odour unit per cubic metre | OU/m3 | |
| Ohm | ohm | |
| Parts per million | ppm | |
| Percent | pct | |
| Picofarad | pF | |
| Pixel | px | |
| Seconds | s | |
| Siemens per metre | S/m | |
| Volt | V | |
| Watt | W | |
| Watt hour | Wh |
NOTE: Popular unit in particular industrial domain should be considered (e.g. cm for human height, calories for energy consumption in healthcare domain). It should be made coherent in the present document, as possible.
-
Rule 9: Rule for type :
- Measured and/or calculated values should be represented in float (without taking care of resolution of values).
NOTE: It should be made coherent in the document, as possible. Unit should not be fixed as a rule but be decided with correspondence to each DeviceClass or ModuleClass.
-
Rule 10: Inheritance of ModuleClasses :
- A ModuleClass may inherit from another existing ModuleClass in order to provide additional functionalities based on the existing ModuleClass. However, inheritance from multiple ModuleClasses is not allowed (due to the "diamond problem" [i.6]).
- Inheritance of ModuleClass shall only be used in the case that extending an existing ModuleClass is not appropriate, i.e. the functionality to be added is irrelevant to the original design purpose of the existing ModuleClass (e.g. adding a 'time' DataPoint to a 'binarySwitch' ModuleClass).
-
Rule 11: When to differentiate between current and target Data Points in ModuleClasses:
- Device operations, which are executed when setting data points to specific values, may take some time to reach the desired result. For example, setting a new temperature to a heater does not immediately change the room temperature, but it may take some time for the heater to increase the temperature. Therefore, it is sometimes necessary to distinguish between current and target data points.
- A ModuleClass shall provide an additional "target" data point when the "current" data point ...
- is writable, and
- the functionality that is mapped to the data point is an operation, not a configuration function, and
- the operation may take some time to start and/or to complete, or reach the desired result.
- When a ModuleClass provides current and target data points then the name for the current data point shall have the prefix "current", and the name for the target data point shall have the prefix "target". Both data points shall have the same suffix, for example "currentTemperature" and "targetTemperature".
-
Rule 12: Algorithm to generate short names for DeviceClasses, ModuleClasses, Data Points, Actions:
- Every domain in oneM2M defines their own short names, i.e. there may exist the same short name in more than one domain, but these short names are distinguished by the domain prefix.
- Previous defined short names of the home domain, e.g. from a previous version of the specification, shall be taken into account. They are assigned to the same original names.
- The algorithm to generate the short names from the original names works as follows:
- The maximum length of a short name for TS-0023 is 5 characters. This length includes the optional appended distinguishing number (see below), but not the suffix for announced resources.
- If the length of the original name is equal or less than 5 characters, then store the original name as an intermediate result.
- Else, if the length of the original name is greater than 5 characters, then perform the following procedure:
- The first and the last character of the original name are stored as first and second character as an intermediate result.
- All the upper-case characters of the original name, starting with the first upper-case character, are inserted one by one before the last character of the intermediate result, up to a total length of 5 characters of the intermediate result.
- In case the length of the intermediate result after these steps is less than 5 characters, then the intermediate result is filled with characters from the original string until the length of the intermediate result is 5 characters, following this procedure: the second character of the original name is inserted as the second character of the intermediate result while shifting all characters from the intermediate result by one character forward. This is repeated with the third, fourth, etc., character from the original name.
- The intermediate result is now compared with all existing short names. If the intermediate result can be found in the list of existing short names, then execute the following steps until the intermediate result cannot be found in the list of previously defined short names:
- Replace the last character of the intermediate result with an integer number, starting with 0. If the number becomes a two-digit number, then replace the last two characters of the intermediate result, and so forth.
- Repeat the check described above. If the intermediate result is still the same as an existing short name, then the appended integer number is increased by 1, and the check is repeated.
- The intermediate result is now stored as a new short name in the list of existing short names.
- Short names for announced resources are created by taking the regular short name of the entity and appending the characters "Annc" to it. Short names for announced resources therefore have a maximum length of 9 characters.
- Short names for [FlexContainerInstance] specializations for ModuleClasses, DeviceClasses, SubDeviceClasses, and Actions are created by taking the regular short name of the entity and appending the characters "Inst" to it. Short names for these resources therefore have a maximum length of 9 characters.
Table 5.2.2-2 provides some examples for short names that have been created by the described algorithm.
Table 5.2.2-2: Examples for original name to short name mappings
| Original name | short name |
|---|---|
| co2 | co2 |
| clock | clock |
| currentJobMode | cuJMe |
| absoluteStartTime | abSTe |
| absoluteStopTime | abST0 |
| impactSensor | impSr |
| impactSensorAnnc | impSrAnnc |
-
Rule 13: Rule for R/W column:
- The value used in this column defines the interface as it applies to the user of this module. The entity that this module represents (device AE or IPE AE) can read or write to any or all of the datapoints as needed in order to implement the defined interface to the user. <accessControlPolicy> resources shall be defined to enforce access control to the datapoints of the module defined such that R in the R/W column has RETRIEVE accessControlOperations and RW in the R/W column has RETRIEVE and UPDATE accessControlOperations.
-
Rule 14: Rule for Optional and Multiplicity:
- The value used in the "Optional" column of ModuleClass definitions is mapped to the "optional" element attribute for SDT DataPoint elements.
- The value used in the "Multiplicity" column of DeviceClass and SubDevice definitions is mapped to "minOccurs" and "maxOccurs" element attribute for SDT DeviceClass elements as follows:
- 1 : minOccurs = 1, maxOccurs = 1
- 0..1 : minOccurs = 0, maxOccurs = 1
- 0..N : minOccurs = 0, maxOccurs = unbound
- 1..N : minOccurs = 1, maxOccurs = unbound