i. Abstract

The OGC SensorThings API [OGC 15-078r6] provides an open, geospatial-enabled and unified way to interconnect the Internet of Things (IoT) devices, data, and applications over the Web. At a high level, the OGC SensorThings API provides two main functions and each function is handled by the Sensing part or the Tasking part. The Sensing part provides a standard way to manage and retrieve observations and metadata from heterogeneous IoT sensor systems. The Tasking part provides a standard way for parameterizing - also called tasking - of taskable IoT devices, such as individual sensors and actuators, composite consumer / commercial / industrial / smart cities in-situ platforms, mobile and wearable devices, or even unmanned systems platforms such as drones, satellites, connected and autonomous vehicles, etc. This document specifies core of the SensorThings Tasking part.

ii.          Keywords

The following are keywords to be used by search engines and document catalogues.

ogcdoc, OGC document, ogc documents, iot, internet of things, sensor things, sensors, swe, sensor webs, sensor web enablement, sensor networks

iii.          Preface

The OGC SensorThings API is an open standard. This means that anyone can implement the standard on a non-discriminatory, royalty-free basis. The standard is also platform independent. Although SensorThings is a new standard, the requirements build on a rich set of proven-working and widely-adopted open standards, such as Web protocols and the OGC Sensor Web Enablement (SWE) standards, including the ISO/OGC Observation and Measurement data model [OGC 10-004r3 and ISO 19156:2011]. As a result, the OGC SensorThings API is extensible and can be applied to not only simple but also complex use cases.

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

iv.          Submitting organizations

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

• SensorUp Inc., Canada
• University of Calgary, Canada
• Fraunhofer-Gesellschaft, Germany
• CGI Federal, USA

v.          Submitters

All questions regarding this submission should be directed to the editor or the submitters:

1.    Scope

The OGC SensorThings API provides an open standard-based and geospatial-enabled framework to interconnect the Internet of Things (IoT) devices, data, and applications over the Web. The Tasking part provides a standard way for parameterizing - also called tasking - of taskable IoT devices, such as individual sensors and actuators, composite consumer / commercial / industrial / smart cities in-situ platforms, mobile and wearable devices, or even unmanned systems platforms such as drones, satellites, connected and autonomous vehicles, etc. This document is the core of the SensorThings Tasking part. This document follows the CRUD functions, semantics and also query options from OGC SensorThings API part 1: Sensing.

2.    Conformance

Conformance with this standard shall be checked using all the relevant tests specified in Annex A (normative) of this document. All requirements-classes and conformance-classes described in this document are owned by the standard(s) identified.

The following table lists the requirements classes defined in this standard.

NOTE: The content of Requirements column in the following table is the path fragment that appended to the following URI: http://www.opengis.net/spec/iot_tasking/1.0/, and it provides the URI that can be used to unambiguously identify the requirement and the conformance class.

3.    References

The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.

OGC: OGC 08-094r1, OGC SWE Common Data Model Encoding Standard, 2011

OGC: OGC 15-078r6, OGC SensorThings API — Part 1: Sensing, 2016

OGC: OGC 17-011r2, JSON Encoding Rules SWE Common / SensorML, 2018

OASIS: OASIS MQTT Version 3.1.1, 2014

ISO: ISO 8601:2004 Data elements and interchange formats – Information interchange - Representation of dates and times, 2004

OGC: OGC 10-004r3 and ISO 19156:2011(E), OGC Abstract Specification Topic 20: Geographic information — Observations and Measurements, 2010

OASIS: OASIS OData Version 4.0 Part 1: Protocol Plus Errata 02, 2014

OASIS: OASIS OData Version 4.0 Part 2: URL Conventions Plus Errata 02, 2014

OASIS: OASIS OData JSON Format Version 4.0 Plus Errata 02, 2014

OASIS: OASIS OData ABNF Construction Rules Errata 02, 2014

IETF: RFC 2616, Hypertext Transfer Protocol – HTTP/1.1, 1999

OGC: OGC 12-000, OGC® SensorML: Model and XML Encoding Standard, 2014

4.    Terms and Definitions

This document uses the terms defined in Sub-clause 5.3 of [OGC 06-121r9], which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this standard.

For the purposes of this document, the following additional terms and definitions apply.

4.1      Actuator

A type of transducer that converts a signal to some real-world action or phenomenon. [OGC 12-000]

4.2       Collection

Sets of Resources, which can be retrieved in whole or in part. [RFC5023]

4.3       Entity

Entities are instances of entity types. [OASIS OData Version 4.0 Part 1: Protocol Plus Errata 02]

Note: Thing, Actuator, Task are some example entity types of the OGC SensorThings API.

4.4       Entity sets

Entity sets are named collections of entities (e.g. Tasks is an entity set containing Task entities). An entity’s key uniquely identifies the entity within an entity set. Entity sets provide entry points into an OGC SensorThings API service. [OASIS OData Version 4.0 Part 1: Protocol Plus Errata 02]

4.5       (Internet of) Thing

A thing is an object of the physical world (physical things) or the information world (virtual things) that is capable of being identified and integrated into communication networks. [ITU-T Y.2060]

4.6       Measurement

A set of operations having the object of determining the value of a quantity [OGC 10-004r3 / ISO 19156:2011]

4.7       Observation

Act of measuring or otherwise determining the value of a property [OGC 10-004r3 / ISO 19156:2011]

4.8       Observation Result

Estimate of the value of a property determined through a known observation procedure [OGC 10-004r3 / ISO 19156:2011]

4.9       Resource

A network-accessible data object or service identified by an URI, as defined in [RFC 2616]

4.10       REST

The Representational State Transfer (REST) style is an abstraction of the architectural elements within a distributed hypermedia system. REST focuses on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements. It encompasses the fundamental constraints upon components, connectors, and data that define the basis of the Web architecture, and thus the essence of its behavior as a network-based application. An API that conforms to the REST architectural principles/constraints is called a RESTful API. [OGC 15-078r6]

4.11       Sensor

An entity capable of observing a phenomenon and returning an observed value. Type of observation procedure that provides the estimated value of an observed property at its output. [OGC 12-000]

5.    Conventions

This section provides details and examples for any conventions used in the document. Examples of conventions are symbols, abbreviations, use of XML schema, or special notes regarding how to read the document.

5.1    Identifiers

The normative provisions in this specification are denoted by the URI

http://www.opengis.net/spec/iot_tasking/1.0/

All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

6.    Symbols and abbreviated terms

API                          Application Programming Interface

CAV                        Connected and Autonomous Vehicles

CRUD                      Create, Read, Update, and Delete

HTML                      HyperText Markup Language

HTTP                       Hypertext Transfer Protocol

IoT                          Internet of Things

ISO                          International Organization for Standardization

JSON                       JavaScript Object Notation

MQTT                      Message Queuing Telemetry Transport

OData                       the Open Data Protocol

OGC                        Open Geospatial Consortium

REST                       REpresentational State Transfer

SensorML                 Sensor Model Language

SWE                        Sensor Web Enablement

UML                        Unified Modeling Language

UxS                         Unmanned Systems (aerial, underwater, and other unmanned vehicle platforms)

XML                        eXtensible Markup Language

7.    The SensorThings API Tasking Entities

TaskingCapability, Actuator, and Task are the main entities for Tasking core. These entities SHALL be listed in the response to a GET request to the root URL as described Sensing part. In case the server implementation only has Tasking part, the index SHALL contain Things, TaskingCapabilities, Tasks, and Actuators.

7.1    The Tasking Entities

The SensorThings API Tasking core’s Entities are depicted in Figure 1.

In this section, the properties for each entity types and the direct relation to the other entity types are explained. In addition, for each entity type we show an example of the associated JSON encoding.

7.1.1    Thing

This entity is from Sensing part. We add the information here to make this documentation complete in case a server is only implementing the Tasking core. Please note that if the server is implementing both Sensing and Tasking parts, the direct relationship for Thing entity is the combination of the relationship defined in this document with the relationships defined in the Sensing part.

The OGC SensorThings API follows the ITU-T definition, i.e., with regard to the Internet of Things, a thing is an object of the physical world (physical things) or the information world (virtual things) that is capable of being identified and integrated into communication networks [ITU-T Y.2060].

Example 1 an example of a Thing entity implementing the Tasking core

  {
    "@iot.id": 1,
    "@iot.selfLink":
  "http://example.org/v1.0/Things(1)",
    "TaskingCapabilities@iot.navigationLink":
  "Things(1)/TaskingCapabilities",
    "name": "LinkitSmart
  with LED",
    "description": "LinkitSmart device with the LED that can be turned on/off and the color can be changed."
  }

7.1.2    TaskingCapability

The TaskingCapability entity contains information about the capabilities of the taskable device. It contains all the parameters that can be used for controlling the device. SWE Common JSON encoding rules [OGC17-011r2] are used to define these parameters for TaskingCapability.

Example 2 an example of a TaskCapability entity

{
  “@iot.id”: 1,
  "@iot.selfLink“:”http://example.org/v1.0/TaskingCapabilities(1)",
  "Thing@iot.navigationLink“:”TaskingCapabilities(1)/Thing",
  "Actuator@iot.navigationLink“:”TaskingCapabilities(1)/Actuator",
  "Tasks@iot.navigationLink“:”TaskingCapabilities(1)/Tasks",
  “name”: “Control Light”,
  “description”: “Turn the light on and off, as well as specifying light color.”,
  "taskingParameters": {
    “type”: "DataRecord",
    “field”: [
      {
        “name”: “status”,
        “label”: “On/Off status”,
        “description”: “Specifies turning the light On or Off”,
        “type”: “Category”,
        “constraint”: {
          “type”: "AllowedTokens",
          “value”: [
            "on“,”off"
          ]
        }
      },
      {
        “name”: “color”,
        “label”: “Light Color”,
        “description”: “Specifies the light color in RGB HEX format. Example: #FF11A0”,
        “type”: “Text”,
        “constraint”: {
          “type”: "AllowedTokens",
          “pattern”: "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
        }
      }
    ]
  }
}

7.1.3    Task

Task entity contains the parameter detail of the control action that should be run on the task-able device.

Example 3 an example of a Task entity

{ 
  “@iot.id”: 2,
  "@iot.selfLink“:”http://example.org/v1.0/Tasks(1)",
  "TaskingCapability@iot.navigationLink“:”Tasks(2)/TaskingCapability",
  "creationTime“:”2017-01-01T00:00:00.000Z",
  "taskingParameters": {
    “status”: “on”,
    “color”: “#FF0000”
  }
}

7.1.4    Actuator

An Actuator is a device that can be controlled/tasked. The Actuator entity contains information and metadata about taskable actuator. Each TaskingCapability has one Actuator and defines the parameters that can be set/tasked for the Actuator.

The Actuator encodingType allows clients to know how to interpret metadata’s value(s). Currently, the SensorThings API defines two common Actuator metadata encodingTypes. Most sensor manufacturers provide their sensor datasheets in a PDF format. As a result, PDF is a Sensor encodingType supported by SensorThings API. The second Sensor encodingType is SensorML.

Example 4 an example of an Actuator entity

{
  “@iot.id”: 3,
  "@iot.selfLink“:”http://example.org/v1.0/Actuators(3)",
  "TaskingCapabilities@iot.navigationLink“:”Actuators(3)/TaskingCapabilities",
  “name”: "Linkit Smart 7688 Duo Board with LED",
  “description”: "Linkit Smart 7688 Duo Board that has an LED which can be tasked as on/off with different color.",
  "encodingType“:”application/pdf",
  “metadata”: “http://example.org/linkit_7688.pdf”
}

8.    SensorThings Tasking Create

The SensorThings API Tasking part SHALL support creating Task entities. The server checks the taskingParamaters to be compliant to the corresponding TaskingCapability. If the taskingParameters are correct, the Task will be created.

This specification contains only the core functionalities for Tasking part. All other entities than Task, including TaskingCapabilities, Actuators, and Things are pre-provisioned to the Server and the client can only create Tasks.

8.1    Link to existing entities when creating a Task entity

Each Task has one TaksingCapability. There are two approaches to create a Task. (1) The corresponding TaskingCapability is specified in the request with its @iot.id; and (2) The corresponding TaskingCapability is specified in the POST URL, i.e., /v1.0/TaskingCapabilities({id})/Tasks.

HTTP Method: POST

URI Pattern:SERVICE_ROOT_URI/Tasks

Header: Content-Type: application/json

Message Body: A single valid Task entity representation.

Example 5 create a Task entity, which links to an existing TaskingCapability entity (whose id is 1).

  POST /v1.0/Tasks HTTP/1.1
   
  Host: example.org/
  Content-Type: application/json
   
  {
      "taskingParameters": {
       
  "status": "on",
       
  "color": "#FF0000"
      },
      "TaskingCapability":
  {
        "@iot.id": 1
   
  }
  }

HTTP Method: POST

URI Pattern:SERVICE_ROOT_URI/TaskingCapabilities({id})/Tasks

Header: Content-Type: application/json

Message Body: A single valid Task entity representation.

Example 6 create a Task entity, which links to an existing TaskingCapability entity (whose id is 1) by specifying TaskingCapability id in URL.

  POST /v1.0/TaskingCapabilities(1)/Tasks
  HTTP/1.1
   
  Host: example.org/
  Content-Type: application/json
   
  {
    "taskingParameters": {
      "status":
  "on",
     
  "color": "#FF0000"
    }
  }

9.    SensorThings Tasking MQTT Extension

In addition to support HTTP protocol, a SensorThings service MAY support the Message Queuing Telemetry Transport (MQTT) protocol[1] to enhance the SensorThings service publish and subscribe capabilities. This section describes the SensorThings MQTT extension.

9.1    Create a SensorThings Task with MQTT Publish

The SensorThings MQTT extension provides the capability of creating Task entity using MQTT protocol. To create a Task entity in MQTT, the client sends a MQTT Publish request to the SensorThings service and the MQTT topic is the Tasks resource path. The MQTT application message contains a single valid Task entity representation. Figure 2 contains the sequence diagram for creating Task using MQTT publish as well as MQTT sending notifications for Task creation.

If the MQTT topic for the Task is a navigationLink from TaskingCapability, the new Task entity is automatically linked to that TaskingCapability respectively.

Similar to creating Tasks with HTTP POST, creating Tasks with MQTT Publish follows the integrity constraints for creating Task as listed in Table 8.

9.1.1    Link to existing entities when creating a Task entity

To link to existing entities when creating a Task entity with MQTT, the conditions specified in Section 8  are applied.

9.2    Receive updates with MQTT Subscribe

To receive notifications from a SensorThings service when some tasking entities are updated, a client can send a MQTT Subscribe request to the SensorThings service. The SensorThings API defines the following MQTT subscription use cases.

Receiving notifications from a SensorThings service follows the requirement http://www.opengis.net/spec/iot_sensing/1.0/req/receive-updates-via-mqtt of the Sensing part.

When the SensorThings MQTT extension is being used for controlling an Actuator, the actuator (gateway) can subscribe to Tasks and whenever it receives a Task over MQTT, it can perform it. Figure 3 shows a sequence diagram of this process.