Newer
Older
|oneM2M<br/>Technical Specification |oneM2M<br />Technical Specification |
|-|-|
|Document Name: |oneM2M-SensorThings Interworking<br /> |
|Abstract: |< An abstract of the specification and information that may be used in subsequent electronic searches> |
|Template Version: | January 2020 (do not modify) |
The present document is provided for future development work within oneM2M only. The Partners accept no liability for any use of this specification.
The present document has not been subject to any approval process by the oneM2M Partners Type 1. Published oneM2M specifications and reports for implementation should be obtained via the oneM2M Partners' Publications Offices.
<br />About oneM2M
The purpose and goal of oneM2M is to develop technical specifications which address the need for a common M2M Service Layer that can be readily embedded within various hardware and software, and relied upon to connect the myriad of devices in the field with M2M application servers worldwide.
More information about oneM2M may be found at: http//www.oneM2M.org
Copyright Notification
(c) 2024, oneM2M Partners Type 1 (ARIB, ATIS, CCSA, ETSI, TIA, TSDSI, TTA, TTC).
All rights reserved.
The copyright extends to reproduction in all media.
Notice of Disclaimer & Limitation of Liability
The information provided in this document is directed solely to professionals who have the appropriate degree of experience to understand and interpret its contents in accordance with generally accepted engineering or other professional standards and applicable regulations. No recommendation as to products or vendors is made or should be implied.
NO REPRESENTATION OR WARRANTY IS MADE THAT THE INFORMATION IS TECHNICALLY ACCURATE OR SUFFICIENT OR CONFORMS TO ANY STATUTE, GOVERNMENTAL RULE OR REGULATION, AND FURTHER, NO REPRESENTATION OR WARRANTY IS MADE OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR AGAINST INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS. NO oneM2M PARTNER TYPE 1 SHALL BE LIABLE, BEYOND THE AMOUNT OF ANY SUM RECEIVED IN PAYMENT BY THAT PARTNER FOR THIS DOCUMENT, WITH RESPECT TO ANY CLAIM, AND IN NO EVENT SHALL oneM2M BE LIABLE FOR LOST PROFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES. oneM2M EXPRESSLY ADVISES ANY AND ALL USE OF OR RELIANCE UPON THIS INFORMATION PROVIDED IN THIS DOCUMENT IS AT THE RISK OF THE USER.
# Contents
# 1 Scope
The present document ...
`EXAMPLE: The present document provides the necessary adaptions to the endorsed document.`
<mark>The Scope **shall not** contain requirements.</mark>
# 2 References
<mark>The following text block applies.</mark>
References are either specific (identified by date of publication and/or edition number or version number) or nonspecific. For specific references,only the cited version applies. For non-specific references, the latest version of the referenced document (including any amendments) applies.
## 2.1 Normative references
- <a name="_ref_1">[1]</a> OGC SensorThings API "Part 1: Sensing Version 1.1" (http://www.opengis.net/doc/is/sensorthings/1.1)
- <a name="_ref_2">[2]</a> oneM2M TS-0033 (V3.0.0): "Interworking Framework"
- <a name="_ref_3">[3]</a> oneM2M TS-0001 (V4.23.0): "Functional Architecture"
## 2.2 Informative references
<mark>Clause 2.2 shall only contain informative references which are cited in the document itself.</mark>
The following referenced documents are not necessary for the application of the present document but they assist the user with regard to a particular subject area.
- Use the **EX** style, add the letter "i" (for informative) before the number (which shall be in square brackets) and separate this from the title with a tab (you may use sequence fields for automatically numbering references).
- <a href="#_ref_i.1">[i.1]</a> oneM2M Drafting Rules (http://www.onem2m.org/images/files/oneM2M-Drafting-Rules.pdf)
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
# 3 Definition of terms, symbols and abbreviations
<mark>Delete from the above heading the word(s) which is/are not applicable.</mark>
## 3.1 Terms
<mark>Clause numbering depends on applicability.</mark>
<mark>- A definition shall not take the form of, or contain, a requirement.</mark>
<mark>- The form of a definition shall be such that it can replace the term in context. Additional information shall be given only in the form of examples or notes (see below).</mark>
<mark>- The terms and definitions shall be presented in alphabetical order.</mark>
For the purposes of the present document, the [following] terms and definitions [given in ... and the following] apply:
<mark>Definition format</mark>
<defined term>: <definition>
<mark>If a definition is taken from an external source, use the format below where [N] identifies the external document which must be listed in Section 2 References.</mark>
<defined term>[N]: <definition>
example 1: text used to clarify abstract rules by applying them literally
> NOTE: This may contain additional information.
## 3.2 Symbols
<mark>Clause numbering depends on applicability.</mark>
For the purposes of the present document, the [following] symbols [given in ... and the following] apply:
<mark>Symbol format</mark>
<symbol> <Explanation>
<2nd symbol> <2nd Explanation>
<3rd symbol> <3rd Explanation>
## 3.3 Abbreviations
<mark>Abbreviations should be ordered alphabetically.</mark>
<mark>Clause numbering depends on applicability.</mark>
For the purposes of the present document, the [following] abbreviations [given in ... and the following] apply:
<mark>Abbreviation format</mark>
<ABREVIATION1> <Explanation>
<ABREVIATION2> <Explanation>
<ABREVIATION3> <Explanation>
# 4 Conventions
The key words "Shall", "Shall not", "May", "Need not", "Should", "Should not" in this document are to be interpreted as described in the oneM2M Drafting Rules <a href="#_ref_i.1">[i.1]</a>
The SensorThings API (STA) is a standard of the Open Geospatial Consortium (OGC). It provides a framework for communication and exchanging data between sensors and applications. The standard is devided in two parts. SensorThings API Part 1 is dedicated to sensing and was published in 2016 and updated in 2021.
A STA-based architecture works in client/server mode. A sensor device pushes data to the SensorThings Server via HTTP. A SensorThings Server may also support MQTT protocol to support publish and subscribe capabilities. An interested application can subscribe to the MQTT-Broker, in order to get notified about new sensor events.
**Figure 5-1 STA message flow**
The data in the SensorThings server are organized as according to **Sensing Entities** (see Figure 5-2: Sensing Entities data model.
**Figure 5-2 STA Sensing Entities Data Model**
In the Sensing Entities Data Model events or sensor data are called "observations". Before a sensor is able to push an observation to the server it needs at least a 'Thing' and a 'Datastream' entity. This has to be created beforehand. One 'Thing' might have different 'Sensors', one 'Location' or many 'HistoricalLocations'.
The Sensing Entities data model and the purpose of data within the data model discloses mainly two data characteristics, associated with a 'thing':
- Data observations originated by sensors or commands sent to interact with actuators may be seen as IoT data from oneM2M point of view.
While:
- Data embedded in the Sensing Entities Data Model, like "historic locations" should be seen as data for documentation purposes.
Figure 6.0-1 shows an architecture approach for an Interworking Proxy Entity (IPE) between oneM2M and the OGC SensorThings API. The IPE is located between a oneM2M CSE and an OGC/SensorThings API (STA)-Server.
The basic interworking enables applications that are connected to an oneM2M-based system to get data from sensors that are connected to an OGC/STA server. Furthermore, an application that is connected to an OGC/STA server will be able to get data from sensors that are connected to an oneM2M-based system. The communication flow of the IPE shall rely on HTTP and MQTT. The MQTT protocol enables publish-subscribe functionality for the OGC side, as specified in the MQTT extension of the SensorThings API <a href="#_ref_i.1">[i.1]</a>.
**Figure 6.0-1: IPE architecture overview**
According to oneM2M TS-0033 <a href="#_ref_2">[2]</a> a representation of a non-oneM2M Proximal IoT function/device in a oneM2M-specified resource instance is to be synchronized with the entity that it represents. Thus the OGC/STA data model has to be represented in the hosting CSE. The SensorThings data model is comprehensive and should be regarded as a n:m relational database structure, holding both:
- sensor (IoT-data); and
- administrative data (like historic locations or historic products IDs).
The IPE shall map the 'result' attribute of an OGC/STA 'Observation' to the 'content' attribute of a oneM2M `<contentInstance>`, and vice versa as shown in Figure 6.1-1. The data type of the 'result' field of an "Observation" is according to SensorThings API <a href="#_ref_i.1">[i.1]</a> 'any' and depends on the 'observationType' defined in the associated "Datastream". The 'content' attribute of an oneM2M instance may be stringified data <a href="#_ref_3">[3]</a> understandable with the help of the 'contentInfo' attribute. The 'contentInfo' attribute on the oneM2M side may be added by the IPE. The original timestamps, present in the "Observation" as 'phenomenonTime' and in the `<contentInstance>` as "creationTime," shall be discarded. These timestamps are to be reset by the OGC /STA server and the CSE. They may be transmitted for informational purposes as part of the 'result' or the 'content' fields.
**Figure 6.1-1: OGC / STA-to-oneM2M data model mapping**
## 6.2 Communication Flow
Figure 6.2-1 shows the oneM2M-to-OGC/STA direction. In order to transfer data from a oneM2M sensor to the OGC/STA server the IPE creates a `<subscription>` to the `<container>` resource in the CSE containing the desired data. Triggered by a sensor event a new `<contentInstance>` is added to the `<container>` by the `<AE>`. The IPE gets a `<notification>` containing the `<contentInstance>` resource.
The IPE constructs an "Observation" creation request and copies the 'content' attribute of the `<contentInstance>` to the 'result' attribute of the "Observation" and sends it to a "Datastream" to be created as detailed in Section 6.3.1 at the OGC/STA server. The OGC/STA applcation gets the sensor data either by polling the OGC/STA server or subscribing to the corresponding "Datastream" at the MQTT broker of the OGC/STA server.
**Figure 6.2-1: Communication oneM2M-to-OGC/STA direction**
Figure 6.2-2 shows the OGC/STA-to-oneM2M direction. The IPE subscribes to the desired "Datastream" of the MQTT-Broker at the OGC/STA server. The OGC/STA server publishes a new "Observation" via the MQTT broker triggered by a OGC/STA sensor. The IPE creates a `<contentInstance>` in a container, to be created as detailed in Section 6.3.2 in the CSE and copies the 'result' attribute of the "Observation" to the 'content' attribute of the `<contentInstance>`. The oneM2M applcation gets the sensor data either by polling the CSE or subscribing to the desired `<container>` at the CSE.
**Figure 6.2-2: Communication OGC/STA-to-oneM2M direction**
<mark>The following text is to be used when appropriate:</mark>
## 6.3 Configuration Aspects
### 6.3.0 Introduction
To enable interworking, preparation is required for both the oneM2M-CSE and the OGC/STA server (see Figure 6.3.0-1). As described in Section 6.0, the IPE maps data from an OGC/STA "Observation" to a oneM2M `<contentInstance>` and vice versa. This specification defines a 1-to-1 relationship in each direction between the "Datastream" associated with the "Observation" and the `<container>` associated with the `<contentInstance>`. An IPE may implement multiple 1-to-1 relationships.
#### 6.3.1.0 Overview
Both directions of the data flow between the OGC/STA server and the IPE require their own configuration steps.
#### 6.3.1.1 Communication direction OGC/STA Server towards IPE
In Figure 6.3.1.1-1, an OGC/STA client is connected to an OGC/STA server, and its data is forwarded to the IPE. The OGC/STA client publishes data to the OGC/STA server via an HTTP-POST message.
An "Observation" according to STA Sensing Entities Data Model <a href="#_ref_i.1">[i.1]</a> belongs to a "Datastream" (see Figure 5-2). The IPE shall subscribe to the "Datastream" containing the observations to be forwarded to the oneM2M side at the MQTT broker of the OGC/STA server using its specific URL or topic, e.g., {sta-example-server-address.com/v1.0/Datastreams(8715)}. Upon successful subscription, the IPE will receive every "Observation" pushed to that "Datastream".
**Figure 6.3.1.1-1: Message flow from OGC/STA Client to OGC/STA Server to IPE**
#### 6.3.1.2 Communication direction IPE towards OGC/STA Server
The IPE requires a destination-"Datastream" to send an "Observation" containing data from the oneM2M side. If no associated "Datastream" exists on the OGC/STA server, it shall be created. This can be done beforehand or at the IPE's start-up, depending on the implementation.
When a "Datastream" is created on the OGC/STA server, a reference ID (e.g. {"@iot.id:3635353"}) is returned. This reference is required by the IPE to associate an "Observation" with a "Datastream" and shall be available during IPE operation. In addition to the "Datastream" other entities of the STA Sensing Entities Data Model <a href="#_ref_i.1">[i.1]</a>, such as "Location" or "Sensor," may be created.
The creation of entities like "Datastream" and "Thing" requires several mandatory properties that shall be known at configuration time (e.g., 'name' and 'description'). These property fields may be automatically derived, for example, from the "Label" or "ResourceName" attributes of the corresponding oneM2M `<container>` resource or if existing, from the corresponding `<AE>` resource during IPE configuration. The OGC/STA procedures for creating OGC entities are described in SensorThing API documentation <a href="#_ref_i.1">[i.1]</a>.
Once the destination-"Datastream" is created, the IPE can send an "Observation" to the OGC/STA server as HTTP POST message. An interested OGC/STA client can subscribe to the destination-"Datastream" at the MQTT Broker of the OGC/STA server to receive each "Observation" forwarded by the IPE (see Figure 6.3.1.2-1). Alternatively, the OGC/STA client may use an HTTP-GET request to retrieve the data as needed.
**Figure 6.3.1.2-1: Message flow from IPE to OGC/STA Server to OGC/STA Client**
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
# Proforma copyright release text block
<mark>This text box shall immediately follow after the heading of an element (i.e. clause or annex) containing a proforma or template which is intended to be copied by the user. Such an element shall always start on a new page.</mark>
|Notwithstanding the provisions of the copyright clause related to the text of the present document, oneM2M grants that users of the present document may freely reproduce the <proformatype> proforma in this {clause\|annex} so that it can be used for its intended purposes and may further publish the completed <proformatype>.|
|----|
<mark><PAGE BREAK></mark>
## <mark>Annexes</mark>
<mark>Each annex shall start on a new page (insert a page break between annexes A and B, annexes B and C, etc.).</mark>
<mark>Use the Heading 9 style for the title and the Normal style for the text.</mark>
# Annex <A> (Informative/Normative):<mark>Remove Informative or Normative as appropriat</mark> Title of annex <mark>(style H9)</mark>
<Text>
<mark><PAGE BREAK></mark>
# Annex <B> (Informative/Normative):<mark>Remove Informative or Normative as appropriat</mark> Title of annex <mark>(style H9)</mark>
<Text>
## B.1 First clause of the annex <mark>(style H1)</mark>
<Text>
### B.1.1 First subdivided clause of the annex <mark>(style H2)</mark>
<Text>
<mark><PAGE BREAK></mark>
<mark>The following text is to be used when appropriate:</mark>
# Annex <y>:<br />Bibliography
<mark>The annex entitled "Bibliography" is optional.</mark>
<mark>It shall contain a list of standards, books, articles, or other sources on a particular subject which are not mentioned in the document itself</mark>
<mark>It shall not include references mentioned in the document.</mark>
<mark>Use the Heading 9 style for the title and B1+ or Normal for the text.</mark>
- <Publication>: "<Title>".
OR
<Publication>: "<Title>".
<mark><PAGE BREAK></mark>
# History
<mark>This clause shall be the last one in the document and list the main phases (all additional information will be removed at the publication stage).</mark>
|Publication history |Publication history |Publication history |
|-|-|-|
|V1.x.x |<yyyy-mm-dd > |<Milestone> |
| | | |
| | | |
| | | |
| | | |
|Version (to be removed on publication) |Date (to be removed on publication) |Draft history (to be removed on publication) |
|V5.0.0 | 2024-03-01|Includes the following contributions agreed during SDS#58 meeting: SDS-2023-0219R01-initial_OGC_intro|
|V5.1.0 | 2024-09-13|Includes the following contributions agreed during SDS#66 meeting: SDS-2024-0064R02_architecture_model and editorials agreed during SDS66|