6.2 Specification of the IPE for Ontology-based Interworking

6.2.1 Initialization of the Ontology-based Interworking IPE

6.2.1.1 General functionality of a Ontology-based Interworking IPE

Ontology-based Interworking Interworking supports the interworking variant with full mapping of the semantic of the non-oneM2M data model to Mca as indicated in clause F.2 of oneM2M TS-0001 [2].

The non-oneM2M data model is described in the form of a oneM2M compliant ontology which is derived (as sub-classes and sub-properties) from the oneM2M Base Ontology and may be available in a formal description language (e.g. OWL).

A oneM2M compliant ontology can describe an external technology (e.g. ZigBee) for which a standardized interworking with oneM2M is required or it could describe a model of consensus that is shared by large industry sector (like SAREF, referenced in [i.2]) that facilitates the matching of existing assets (standards/protocols/datamodels, etc.). An IPE that provides Ontology-based Interworking with a non-oneM2M system (e.g. an M2M Area Network) shall instantiate the classes, object- and data properties of the ontology describing the non-oneM2M data model of the M2M Area Network as oneM2M resources, according to the instantiation described below.

In the following clauses it is assumed that the oneM2M compliant ontology describing the non-oneM2M data model is available as a formal description (e.g. in OWL format). The location (URI) where the formal description of the ontology can be retrieved by the IPE needs to be configured in the IPE - either preconfigured or through administrative means.

6.2.1.2 Initialization sequence of a Ontology-based Interworking IPE

After registration of the IPE's <AE> resource the IPE shall do the following:

1. The IPE shall retrieve the formal description of the ontology and parse it.
2. The IPE shall create a child-resource of its <AE> resource of type <container>, subsequently called 'XSD-storage'
   This <container> is will hold the XSDs that are needed to specialize the <flexContainer> s that are used in the oneM2M resource representation of entities of the non-oneM2M interworked solution:
   • The resource name of the <container> resource shall be identical to the name of the ontology, omitting "http://" and changing each "/" (slash) into "_" (underscore).
   • The attribute ontologyRef of that <container> shall contain the reference (URI) to the used ontology.

3. For each class of the ontology the IPE shall create a resource of type <contentInstance> as child resource of this <container>. That <contentInstance> shall hold the XSD for instantiating the class as <flexContainer> specialization in oneM2M.
   The specification how the IPE shall create XSDs from an ontology is described in clause 7.

   • The resource name of each <contentInstance> resource shall be identical to the class name of the ontology, followed by ".xsd".
   • The attribute ontologyRef of that <contentInstance> shall contain the reference (URI) to the class of the ontology.

   EXAMPLE:

   For ontology 'http://www.someOrganization.org/someOntology' the IPE would create a <container> resource with resource name "www.someOrganization.org_someOntology".
   Its ontologyRef would contain the URI: 'http://www.someOrganization.org/someOntology'.

   If the ontology defines a class 'http://www.someOrganization.org/someOntology#someService' then the IPE needs to create a <contentInstance> as child resource of that "www.someOrganization.org_someOntology" <container> . The resource name of that_<contentInstance> would be "someService.xsd".
   Its _ontologyRef would contain the URI: 'http://www.someOrganization.org/someOntology#someService'.

4. If supported by the technology of the non-oneM2M solution the IPE shall create <flexContainer> s according to clause 6.2.2.4 for its own (network) services (e.g. broadcast services...) that are provided by the IPE.

5. If supported by the technology of the non-oneM2M solution the IPE shall discover the devices in the non-oneM2M solution, including their supported services. Alternatively, information about the devices in the the non-oneM2M solution may be manually configured in the IPE or obtained by other means.

6.2.2 Interworked Device and Service discovery

6.2.2.1 General handling of Interworked Device discovery

• If supported by the technology of the non-oneM2M solution the IPE shall continue to discover the devices in the non-oneM2M solution.
• If supported by the technology of the non-oneM2M solution the IPE shall continue to discover services that are provided by the devices in the non-oneM2M solution.

6.2.2.2 Creation of resources for the Proxied Device

6.2.2.2.1 General on the creation of resources for the Proxied Device by the IPE

For each discovered Interworked Device in the non-oneM2M solution the IPE shall:

• either:
  • create a <flexContainer> child-resource of the IPE's own <AE> to represent the non-oneM2M Interworked Device in the oneM2M System.
    • This option should be chosen in most cases, in particular when the individual representations for Interworked Devices - the Proxied Devices - do not need to be distinguished with regard to service subscription, charging, etc. as these are derived from the IPE'S <AE> .
• or
  • register an <AE> resource with the IPE's hosting CSE. That <AE> resource represents the non-oneM2M Interworked Device in the oneM2M System.
    • This option should be chosen if the interworked devices need to be identifiable for the purpose of service subscription, charging, differentiation during access control enforcement, authentication, App-ID registry, etc.

Note

The resource (<flexContainer> or <AE>) that represents the non-oneM2M Interworked Device in the oneM2M System, together with its child resources, and together with the IPE functionality to execute CRUDN operations on these resources is called 'Proxied Device' (see definitions clause).

6.2.2.2.2 Creation of resources for the Proxied Device when Interworked Devices are represented as <flexContainer> s

If the IPE creates <flexContainer> s for Proxied Devices the following rules apply.

For each discovered device in the non-oneM2M solution the IPE shall create a specialized <flexContainer> resource as child-resource of the <AE> resource of the IPE.

• The specialization type of the <flexContainer> is determined by the XSD file - a <contentInstance> in the XSD-storage - that correlates to the class of the sub-device in the ontology.
• It is recommended that the resourceName of an <flexContainer> resource that represents an Interworked Device should be derived and resemble the address (e.g. MAC address) of the Interworked Device in the non-oneM2M solution.
  As the formats of such addresses are very diverse no general rule for that derivation can be given.
• The attribute ontologyRef shall contain the reference (URI) to the class of the ontology that specifies the type of the Interworked Device.
• The labels attribute of the <flexContainer> may contain the following key- vale pairs:
  • Key: "Iwked-Technology" Value: the name of the ontology, omitting "http://" and changing each "/" (slash) into "_" (underscore).
  • Key: "Iwked-Entity-Type" Value: Class name of the class in the ontology (i.e. a sub-class of class InterworkedDevice of the oneM2M Base OntologyBase Ontology) that specifies the type of the Interworked Device
• The resourceID of a <node> resource that stores the node specific information where this Interworked Device resides may be contained in the nodeLink attribute of the <flexContainer> of the Device.

Note

Such a <node> resource is required if the device management tasks can be performed via the oneM2M solution.

• The IPE may create a <semanticDescriptor> child-resource for the <flexContainer>_ resource that represents an Interworked Device (see clause 7 in [3]).

6.2.2.2.3 Creation of resources for the Proxied Device when Interworked Devices are represented as <AE> s

If the IPE registers individual <AE> s for Proxied Devices the following rules apply:

• As the IPE registers the <AE> as a proxy for the Interworked Device it should either:
  • not create a Security Association Establishment procedure, or
  • create a Security Association Establishment procedure between the Node on which the IPE <AE> is hosted and the Registrar CSE. In this case only the Node from which the registration request is received at the Registrar CSE is authenticated. Thus the IPE, which handles communication for all the Proxied Devices, can communicate over either a single Security Association or over individual Security Associations for each Proxied Device.

Note

1: The Node authentication as described above (see also oneM2M TS-0001 [1] clause 10.2.2.2) is applicable as the IPE performs AE functionality for all its Proxied Devices, as if their (virtual) individual AEs were resident on the same node as the IPE AE.

• The APP-ID of the <AE> shall be the APP-ID of the IPE.
• It is recommended that the AE-ID of an <AE> resource that represents an Interworked Device should be derived and resemble an identifier of the Interworked Device in the non-oneM2M solution.
  As the formats of such identifiers are very diverse no general rule for that derivation can be given.
• It is recommended that the resourceName of an <AE> resource that represents an Interworked Device should be derived and resemble the address of the Interworked Device in the non-oneM2M solution.
  As the formats of such addresses are very diverse no general rule for that derivation can be given.
• The attribute ontologyRef shall contain the reference (URI) to the class of the ontology that specifies the type of the Interworked Device.
• The labels attribute of may contain the following key- vale pairs:
  • Key: "Iwked-Technology" Value: the name of the ontology, omitting "http://" and changing each "/" (slash) into "_" (underscore).
  • Key: "Iwked-Entity-Type" Value: Class name of the class in the ontology (i.e. a sub-class of class InterworkedDevice of the oneM2M Base OntologyBase Ontology) that specifies the type of the Interworked Device.
• The resourceID of a <node> resource that stores the node specific information where this Device resides may be contained in the nodeLink attribute of the <AE> of the Device.

Note

2: Such a <node> resource is required if the device management tasks can be performed via the oneM2M solution.

• The IPE may create a <semanticDescriptor> child-resource for the <AE> (see clause 7 in [3]).

6.2.2.3 Creation of resources for sub-devices

A Device can consist of (i.e. be composed) of several (sub-) Devices. In the oneM2M Base OntologyBase Ontology the Object Property: consistsOf links a device class to a class of its sub-devices.

For each sub-device of a discovered device in the non-oneM2M solution the IPE shall create a specialized <flexContainer> resource as child-resource of the <AE> or <flexContainer> resource of the Proxied Device/:

• The specialization type of the <flexContainer> is determined by the XSD file - a <contentInstance> in the XSD-storage - that correlates to the class of the sub-device in the ontology.
• The resourceName of the <flexContainer> resource of the sub-device shall be identical to the class name of the (ontology specific sub-class of) class:Device of the sub-device in the ontology.
  Example: "switchingSubDevice".
  • If multiple sub-device instances of the same class exist then the resourceName shall be appended by '_' (underline) and followed by a number to distinguish individual <flexContainer> resources for multiple (sub-)devices of the same type.
    Example: "subDeviceCuff_02" when the device is a blood pressure monitor containing 4 individual cuffs for measuring blood pressure as sub-devices.

Note

The creation of <flexContainer> resources for sub-devices of a device is basically analogous to the creation of <flexContainer> resources for Services of a device (see next clause).

• The attribute ontologyRef shall contain the reference (URI) to the class of the ontology that specifies the type of the sub-device.
• The labels attribute of may contain the following key- vale pairs:
  • Key: "Iwked-Technology" Value: the name of the ontology, omitting "http://" and changing each "/" (slash) into "_" (underscore).
  • Key: "Iwked-Entity-Type" Value: Class name of the class of the sub-device in the ontology (i.e. a sub-class of class:InterworkedDevice of the oneM2M Base OntologyBase Ontology).
• The IPE may create a <semanticDescriptor> child-resource.

6.2.2.4 Creation of resources for Services

For each service, that is supported by a device or sub-device the IPE shall create a specialized <flexContainer> resource, representing the service. The <flexContainer> shall be a child-resource of the Proxied Device representation (<AE> or <flexContainer> resource in case of an interworked Device, specialized <flexContainer> in case of a sub-device):

• The services that can be supported by a device or sub-device are specified in the ontology by Object Property: hasService:
  • If a service is mandatory for a specific device then Object Property:hasService (or a sub-property) of the ontology has a Restriction on cardinality: "exactly 1".
    In this case the IPE shall create the specialized <flexContainer> for the Service.
  • If a service is optional for a specific device and can have only one instance on the device then Object Property:hasService (or a sub-property) has a restriction on cardinality: "max 1".
    In this case the IPE shall create the specialized <flexContainer> for the Service only if the the IPE can determine (using methods of the interworked solution) that the (sub)device actually supports the service.

  • A service can have multiple instances on a device. In this case Object Property:hasService (or a sub-property) has no restriction on cardinality or a restriction: e.g. "min [x]" with x>1:

    • The ontology may specify that the same service of a device exposes multiple, different Functions (Object Property:exposesFunction). In this case multiple instances of the same service might be distinguishable by the Function they expose.
    • If the ontology does not specify the Function that is exposed by the Service or if multiple Services with the same Function exist in the device then these are semantically indistinguishable
      Example: a connector strip containing 5 individual switching services.

    In this case the IPE may create multiple specialized <flexContainer> instances for the Service. - The specialization type of the <flexContainer> is determined by the XSD file - a <contentInstance> in the XSD-storage - that correlates with the class of the service in the ontology.

Note

The XSD file for the service also includes XSD descriptions for the service's DataPoints - which are represented as customAttribute s of the_<flexContainer>_ for the Service.

• The resourceName of the <flexContainer> resource of the service shall be identical to the class name of the (ontology specific sub-class of) class:Service in the ontology
  Example: "liquidRemaining".
  • If multiple service instances of the same class:Service exist but expose different Functions (via Object Property:exposesFunction) then the resourceName shall be appended by '_' (underline), followed by the class name of the function in the ontology.
    Example: "liquidRemaining_waterStatus", "liquidRemaining_milkStatus".
  • If multiple service instances of the same class:Service exist that expose the same function then the resourceName shall be appended by '_' (underline), followed by a number to distinguish individual <flexContainer> resources for multiple services of the same type.
    Example: "liquidRemaining_waterStatus_01", "liquidRemaining_waterStatus_02".
• The attribute ontologyRef shall contain the reference (URI) to the class of the ontology that specifies the type of the service.
• The labels attribute of may contain the following key-value pairs:
  • Key: "Iwked-Technology" Value: the name of the ontology, omitting "http://" and changing each "/" (slash) into "_" (underscore).
  • Key: "Iwked-Entity-Type" Value: Class name of the class of the service in the ontology (i.e. a sub-class of class:Service of the oneM2M Base Ontology).
• The IPE may set access rights for the <flexContainer> resource of the service to restrict/allow AEs to use (UTDATE and / or RETRIEVE and SUBSCRIBE to) the the <flexContainer> that represents the Service.
• The IPE may create a <semanticDescriptor> child-resource of the <flexContainer> resource of the service.

6.2.2.5 Creation of resources for operations of a service of a device

6.2.2.5.1 Introduction

An Operation is the means of a Service to communicate in a procedure-type manner.

In general an operation is invoked by the communicating entity and can - but need not - have OperationInput parameters. As a result of the Operation result parameters can - but need not - be returned.

An operation can also be invoked by the Interworked Device and can - but need not - have OperationOutput parameters. In this case no operation results are envisaged.

Note

Analogous to operation invocation by the communicating entity at the Interworked Device also operation invocation by the Interworked Device at another device (oneM2M native or interworked) can happen. This case is not supported in the current release.

Operations are represented in the oneM2M System with one or two types of resources, both of them being specialized <flexContainer> resources.

• The first type exists for every operation and is used to invoke the operation:
  • In the case the operation is invoked by the communicating entity it only contains OperationInput parameters, if they exist for this type of operation.
  • In the case the operation is invoked by the Interworked Device it only contains OperationOutput parameters, if they exist for this type of operation.
• The second type is a child-resource of the first type and only exists if the operation had been invoked by the communicating entity and only for operations that can produce OperationOutput parameters. This type contains both, the OperationInput parameters, if they exist, and the OperationOutput parameters, if they exist.

6.2.2.5.2 Creation of resources for operation invocation

For each operation, that is supported by a service of a device the IPE shall create a specialized <flexContainer> resource, representing the operation. The <flexContainer> shall be a child-resource of the specialized <flexContainer> of the service.

The IPE shall subscribe to all specialized <flexContainer> resources representing operations, that it creates.

• The operations that can be supported by a service are specified in the ontology by Object Property:hasOperation.
  • An Operation for a specific Service can only have at most a single instance at a time. Unless the operation is optional, i.e. Object Property:hasOperation (or a sub-property) has a restriction on cardinality: "max 1" the IPE shall create the specialized <flexContainer> that represents the Operation.

Note

1: It is quite well possible, that the Interworked Device supports execution of multiple operation instances of the same operation type at a time. However, mutiple invocations of the same operation type is achieved in oneM2M by consecutively UPDATEing a single specialized <flexContainer> resource that represents the Operation input. Thus a single <flexContainer> resource is sufficient to invoke multiple, concurrent operation instances of that operation in the Interworked Device.

Similarly, also returning OperationOutput parameters is done through a single UPDATE operation on the specialized <flexContainer> resource that represents the Operation output. - If an operation is optional for a specific service then Object Property:hasOperation (or a sub-property) has a restriction on cardinality: "max 1".
In this case the IPE shall create the specialized <flexContainer> for the Operation only if the the IPE can determine (using methods of the interworked solution) that the Service actually supports the operation.

• The specialization type of the <flexContainer> is determined by the XSD file - a <contentInstance> in the XSD-storage - that correlates with the class of the operation in the ontology.

Note

2: The XSD file for the operation also includes XSD descriptions for the operation's OperationInput parameters which are represented as customAttribute s of the_<flexContainer>_ for the operation.

When the IPE creates the <flexContainer> resource it may ignore customAttribute s that represent the operation's OperationOutput parameters.

• The resourceName of the <flexContainer> resource of the operation shall be identical to the class name of the (ontology specific sub-class of) class:Operation in the ontology.
  Example: "toggle" as an operation of a service of a light switch, "upVolume" as an operation of a service of a audio device.
• The attribute ontologyRef shall contain the reference (URI) to the class of the ontology that specifies the type of the operation.
• The labels attribute of may contain the following key- vale pairs:
  • Key: "Iwked-Technology" Value: the name of the ontology, omitting "http://" and changing each "/" (slash) into "_" (underscore).
  • Key: "Iwked-Entity-Type" Value: Class name of the class of the operation in the ontology (i.e. a sub-class of class:Operation of the oneM2M Base Ontology).
• The IPE may set access rights for the <flexContainer> resource of the service to restrict/allow AEs to use (UTDATE and / or RETRIEVE and SUBSCRIBE to) the the <flexContainer> that represents the Operation.
• The IPE may create a <semanticDescriptor> child-resource of the <flexContainer> resource of the Operation.

6.2.2.5.3 Creation of resources for returning operation results

For each operation, that can produce operation result parameters (i.e. its class:Operation is related via Object Property: hasOutput to some class:OperationOutput) the IPE shall create a specialized <flexContainer> resource, representing the result of the operation for a set of invocation parametes. The <flexContainer> shall be a child-resource of the specialized <flexContainer> resource for operation invocation (described in clause 6.2.2.3.2).

The IPE shall subscribe to this specialized <flexContainer> resource:

• The specialization type of the <flexContainer> is determined by the XSD file - a <contentInstance> in the XSD-storage - that correlates with the class of the operation in the ontology.

Note

The XSD file for the operation also includes XSD descriptions for the operation's OperationInput and OperationOutput parameters which are represented as customAttribute s of the <flexContainer>.

• The resourceName of the <flexContainer> resource of the operation shall be identical to the class name of the (ontology specific sub-class of) class:Operation in the ontology, appended by '_result'.
  Example: "upVolume_result" as the result of an operation that e.g. returns the current volume level as OperationOutput parameter.
• The attribute ontologyRef shall contain the reference (URI) to the class of the ontology that specifies the type of the operation.
• The labels attribute of may contain the following key- vale pairs:
  • Key: "Iwked-Technology" Value: the name of the ontology, omitting "http://" and changing each "/" (slash) into "_" (underscore).
  • Key: "Iwked-Entity-Type" Value: Class name of the class of the operation in the ontology (i.e. a sub-class of class:Operation of the oneM2M Base Ontology).
• The IPE may set access rights for RETRIEVEing the <flexContainer> resource of the operation.
• The IPE may create a <semanticDescriptor> child-resource of the <flexContainer> resource of the operation.

6.2.2.6 Subscription to the created resources

The IPE shall subscribe to all specialized <flexContainer> resources representing services, that it creates.
In particular it shall subscribe to the <flexContainer> resources representing Services and <flexContainer> resources for the Operation invocation. The attribute notification_ContentType of the <subscription> needs to be set to "modified-attributes".

6.2.3 Handling of DataPoints by the IPE

• When the IPE receives a request by the interworked non-oneM2M device via the non-oneM2M reference point to write an OutputDataPoint belonging to a Service of the device the IPE shall:
  • de-serialize the received data; and
  • UPDATE the OutputDataPoint customAttribute of the <flexContainer> resource of the Service with the output data.
• When the IPE receives a request by the interworked non-oneM2M device via the non-oneM2M reference point to read an InputDataPoint belonging to a Service of the device the IPE shall:
  • RETRIEVE data from the InputDataPoint customAttribute of the <flexContainer> resource of the Service;
  • serialize the data; and
  • return them to the non-oneM2M device.
• When the IPE is notified by the CSE that a customAttribute of the <flexContainer> resource of the Service of the Proxied Device has been changed the IPE shall:
  • read the data of the changed customAttribute; and
  • invoke the Service, parameterized with data of the InputDataPoint, via the non-oneM2M reference point in the interworked non-oneM2M device.

6.2.4 Handling of Operations by the IPE

When the IPE receives notification from the CSE about an UPDATE of the <flexContainer> resource of the operation the IPE shall perform the following actions:

1. If the operation has OperationInput data the IPE shall RETRIEVE the OperationInput data of the operation (contained in the customAttribute s of the <flexContainer> resource of the operation).
2. The IPE shall serialize OperationInput data and invoke the related operation in the non-oneM2M device via the non-oneM2M reference point.
3. If the operation allows OperationOutput data (i.e. a <flexContainer> resource for returning operation results exists as a child-resource of the operation <flexContainer> ) the IPE shall handle the result of the operation, when received from the Interworked Device via the non-oneM2M reference point:
   • The IPE shall de-serialize OperationOutput data.
   • The IPE shall UPDATE the <flexContainer> resource for returning operation results. The UPDATE primitive shall contain:
     • the customAttribute s with the values for the OperationInput data with which the operation had been invoked, and
     • the customAttribute s with the values for the OperationOutput data that had been received as result of the operation.

Note

The IPE needs to await the operation results by the Interworked Device for an operation transaction only for a configurable timespan that may depend on the technology of the non-oneM2M solution. The duration of that timespan is out of scope of the current specification.

When the the non-oneM2M device invokes an operation in the IPE - which may or may not contain OperationInput data - via the non-oneM2M reference point (e.g. when the device reacts on some external event and publishes related output data):

1. The IPE shall de-serialize these data and perform the following actions:
   • If the operation invocation contained no OperationInput data the IPE shall UPDATE the <flexContainer> resource for the operation with NULL values for all customAttribute s.
   • If the operation invocation contained OperationOutput data then:
     • The IPE shall de-serialize OperationOutput data.
     • The IPE shall UPDATE the OperationOutput customAttribute s of the <flexContainer> resource for the operation with the values received.

6.2.5 Removing of resources for Proxied Devices

• When a Interworked Device in the non-oneM2M solution becomes unavailable the IPE shall delete the resource for its Proxied Device and all its child-resources.
• When the IPE detects that an Interworked Device stopped to support a Service (in case such detection is supported by the technology of the non-oneM2M solution) then the IPE shall delete the <flexContainer> resource for the service and all its child-resources.