Internet-Draft | NIPC | October 2024 |
Brinckman, et al. | Expires 24 April 2025 | [Page] |
This memo specifies RESTful application layer interface for gateways providing operations against non-IP devices. The described interface is extensible. This memo initially describes Bluetooth Low Energy and Zigbee as they are the most commonly deployed.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 24 April 2025.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Low-power sensors, actuators and other connected devices introduced in environments and use cases such as building management, healthcare, workplaces, manufacturing, logistics and hospitality are often battery-powered. Often they do not support wireless of wired interfaces that support the IP protocol. Most of these environments however mainly support IP-based networking infrastructure. Therefore, applications on the IP network that aim to communicate or receive telemetry from these non-IP low-power devices must do so through a gateway function on the IP network. This gateway functions then translates the communication to the non-IP protocol that the low-power device supports. Promiment examples of such protocols are [BLE53] and [Zigbee22].¶
There have been efforts to define Gateway functions for devices that support a particular protocol, such as a BLE GATT REST API for BLE Gateways https://www.bluetooth.com/bluetooth-resources/gatt-rest-api/, however they have been limited to a single protocol or a particular use case. In abscence of an open standard describing how applications on an IP network communicate with non-IP devices, bespoke and vendors specifia implementations have proliferated. This results in parallel infrastructure of both gateways and non-IP networks being deployed on a case by case basis, each connecting separately into the IP network, with a distinct set of APIs. At the same time, wireless access points supporting IP-based wireless connectivity are deployed ubiquitiouslyr. Many of these wireless access points are equipped with multiple wireless radios, of different types. These radios can transmit and receive different frame types, such as [BLE53] and [Zigbee22]. This specification aims to define a Gateway API for these Non-IP protocols that can be leveraged by this wireless infrastructure in order to connect Non-IP devices into IP networks.¶
A standardized Non-IP Gateway interface has following benefits: - Avoid the need for parallel Non-IP infrastructure. - Avoid the need for Applications to perform bespoke integrations for different environments. - Faster and more cost-effective adoption of Non-IP devices in IP network environments.¶
A non-IP gateway MUST provide at least following functions: - Authentication and authorization of application clients that will leverage the gateway API to communicate with Non-IP devices. - The ability to onboard Non-IP devices on the Non-IP Gateway. Onboarding ensures that the Non-IP Gateway can identify a device and has sufficient context about the device to service gateway API requests. It also ensures segmentation of devices that were onboarded by particular applications. - A persistent inventory of onboarded devices mapping to the application that onboarded them and the access point/radio that is serving them. - An API that allows for bi-directional communication to non-IP devices. - One or more channels to process requests, responses, and asymmetric communications with the non-IP radio resources (Access Points) in its inventory. - The ability to stream telemetry received from non-IP devices in real-time to applications on the IP network.¶
The onboarding function is out of scope of this document, but can be provided by a provisioning interface such as [RFC7644] leveraging [I-D.ietf-scim-device-model]. All other defined functions are supported by Non IP-Control (NIPC).¶
The Application gateway is a network functions, so its goal is to proxy payloads between Non-IP and IP networks. It is not intended to be a middleware functioni that interprets, decodes or modifies these payloads.¶
Figure 2 shows us applications, the application layer gateway (ALG), an access point (AP), and a device (D). The applications, application layer gateway and access point are deployed on an IP-Network. The AP also has a Non-IP interface, which it uses to communicate with the device. The Application is deployed in a different administrative domain than the network elements (ALG & AP). The role of the ALG is to provide a gateway function to applications wishing to communicate with non-IP devices in the network domain served by the ALG. Applications implementing Non-IP Control can leverage RESTful interfaces to communicate with Non-IP devices in the network domain and subscribe to events levering MQTT.¶
In order to enable a network wishing to offer NIPC ALG functions, the network
administrator authorizes application(s) to perform operations on the Gateway.
This happens out of band and may be accomplished by means of exchanging tokens
or public keys.
Authorization can be role-based. The 3 primary roles are:
1. Onboarding: Authorize an onboarding application against a SCIM server
co-located with the gateway.
2. Control: Authorize applications that may control devices.
3. Data: Authorize applications that may receive telemetry.
It is possible to further refine roles down to an API basis.¶
Applications can perform the API requests they were authorized for. In order for application to perform a NIPC operation on a device, the device must be first onboarded, for example by means of SCIM.¶
Previous steps are prerequisites and not within the scope of this specification, but are provided for context.i Subsequent operations are defined by NIPC.¶
An application authorized for Control can perform NIPC calls to the gateway in order to establish bi-directional communication to one or more devices. Optionally, also set up a publish/subcribe topic to receive streaming data from a device (telemetry interface).¶
An application authorized can receive streaming data on a pub/sub topic configured by the control interface (telemetry interface).¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
Non-IP protocols, such as BLE or Zigbee, typically define a number of basic operations that are similar across protocols. Examples of this are read and write data. NIPC leverages a unified API to support those operations.¶
NIPC defines actions, which are implemented as REST over HTTP request-response APIs. NIPC Also defines events, which are implemented as MQTT topics.¶
In case NIPC is not leveraged in combination with a data model such as ASDF [I-D.ietf-asdf-sdf], which can define the properties of a devices, NIPC also support registrationsr. REgistrations perform mapping of properties to protocol-specific attributes.¶
All operations pertain to a devices or a group of devices, which are addressed by UUIDs. These UUID's were generated at time of onboarding and returned to the application, for example in a SCIM response.¶
NIPC adheres to nomenclature defined by Semantic Definition Format (SDF) for Data and Interactions of Things [I-D.ietf-asdf-sdf]. Therefore NIPC defines actions and events on properties.¶
NIPC supports 3 types of action: - connection: Allows an application to establish to manage connections with a device (if so required by the technology). - property: Allows applications to read or write device properties. In case the property supports streaming data, a subscription property can be managed. - broadcast: This allows the application to send a broadcast message to a device or group of devices.¶
In absence of a model such as SDF that defines device properties, NIPC allows an application to register them. NIPC defines 2 types of registrations: - property: Manage registrations of properties and their protocol mappings. For example, a property called temperature can be mapped to a BLE Service Characteristic. - event: Manage registrations of events and their MQTT properties such as MQTT topic definition.¶
The final set of operations are not fundamental NIPC operations, but are extensions. Extensions are compound API's. They leverage basic NIPC operations but combine multiple operations in to one API call for efficiency. An example of this is the the bulk operation, allowing to send multiple operations is one operation. extension allows for extensions, either generic extensions that anre IANA registered, or vendor specific extensions¶
NIPC actions, registrations and extensions are request/response APIs. They makes use of a JSON schema over RESTful HTTP[RFC9114].¶
NIPC events are encoded in CBOR ([RFC8949]) and delivered over MQTT.¶
Most operations (except registations) are executed against a device or a group. NIPC operations refer to either of these as "Object" with an ID as an identifier. The common schema for Object is defined as follows:¶
Attribute | Req | Type | Example |
---|---|---|---|
id | T | uuid | 12345678-1234-5678-1234-56789abcdef4 |
type | T | enum | device, group |
technology | F | enum | ble, zigbee |
where- - id is the unique uuid of the device. This is generated when registering the device, for example against a SCIM server. As such this ID is known both to the application as well as the NIPC Server. - type is either "group" or "device". - technology is the radio technology supported by the device. The mappings defined in this spec are "ble" or "zigbee". Mappings are extendable to new technologies.¶
Example device object:¶
An object can support one or more communications protocols. Even though Non-IP communications protocols all perform operations on properties, implementations differ between protocols. For example BLE will address a property as a service characteristic, while a property in Zigbee is addressed as a property in a cluster of an endpoint.¶
In order for NIPC to support protocol-agnostic APIs, a property mapping is required between a NIPC property and a protocol-specific property. A property mapping can be done by means of a property registration API.¶
Property mapping allows for integration of new protocols in NIPC, new mappings can be created without the need to update the base schema.¶
As shown in Figure 4, protocol-specific properties must be described in a protocol object, for example a "ble" or a "zigbee" object.¶
Attribute | Req | Type | Example |
---|---|---|---|
ble | T | object | an object with BLE-specific attributes |
zigbee | T | object | an object with Zigbee-specific attributes |
where-¶
"ble" is an object containing properties that are specific to the BLE protocol.¶
"zigbee" is an object containing properties that are specific to the Zigbee protocol.¶
Other protocol mapping objects can be added by creating a new protocol object¶
Example property mapping:¶
Protocol mapping allows applications to perform a one-time registration to a propertyID for a property, and leverage the propertyID in all API calls that perform an operation on this property. It might be useful for applications to directly use protocol objects in action API's as well, therefore there are a limited set of API's avaialbe that have protocol objects directly embedded in the API, in ordur to perform operations on properties without having to first register them.¶
As most operations have a common base schema, based on a device ID and a property, so do responses. Every NIPC API returns a status in the response, as well as a requestID, which allows for tracking and logging of requests and responses. If the operation was performed on a device or group, the ID is also returned. If the operation is to read or write a property, the resulting value is also returned.¶
Success response:¶
Attribute | Req | Type | Example |
---|---|---|---|
status | T | enum | SUCCESS |
id | F | uuid | 12345678-1234-5678-1234-56789abcdef4 |
requestID | F | uuid | abcd0987-1234-5678-1234-56789abcdef4 |
Example success response:¶
Failure responses additionally include an error code and optionally a reason, which contains a textual explanation of the error.¶
Failure response:¶
Attribute | Req | Type | Example |
---|---|---|---|
status | T | enum | SUCCESS |
id | F | uuid | 12345678-1234-5678-1234-56789abcdef4 |
requestID | F | uuid | abcd0987-1234-5678-1234-56789abcdef4 |
errorCode | T | int | 12 |
reason | T | string | "Not Found" |
where-¶
status is the status of the request, either "SUCCESS" or "FAILURE". In case of failure an error code and reason are added.¶
id is the id the operation was executed against, found in the request¶
requestID is a correlation ID that can be used for end-to-end tracing.¶
errorCode is a numerical value representing the error.¶
reason is a human readable explanation of why the error occurred.¶
Example failure response:¶
The primary goal of NIPC actions is to exchange data with a Non-IP device, by means of reading, writing or streaming NIPC properties to applications. An explicit connection may be required, which is also an action. An application may also want to transmit a broadcast.¶
A connection is an operation that establishes or tears down an association or connection with a device. Optionally during connection setup properties supported by a device can be discovered.¶
/action/connection¶
The connection API allows an application to request to connect to a device.¶
Operations:¶
Method: POST /action/connection¶
Description: Connect to a device¶
Parameters: None¶
Request Body: - an Object, as defined in Table 1 - optionally a set of properties to be discovered. These are supplied in protocol objects, as defined in Table 2. In the case of BLE, if no protocol object is included, service discovery is performed to discover all supported properties when connecting to a device. Optionally, service discovery may be limited to properties defined in the "ble" protocol extension. The services to be discovered can be added in an array. Property discover can be buffered across connections, so the API also supports caching parameters. - Connection retry parameters¶
Example body of a connection without specific discovery of properties:¶
where-¶
"id", "type" and "technology" are part of the object definition (device or group), as defined in Table 1.¶
"retries" defines the number of retries in case the operations does not succeed¶
"retryMultipleAPs" can be used in case there is an infrastructure with multiple access points or radios that can reach the device. If set to "true" a different access point may be used for retries.¶
In case the application would like to discover specific properties of a device, a protocol object can be added that defines what properties should be discovered.¶
Example body of a BLE connection with specific discovery of properties:¶
where in the BLE protocol object:¶
"services" is an array of services defined by their serviceIDs.¶
"cached" refers to whether the services need to be cached for subsequent connects, in order not to perform service discovery on each request.¶
"cacheIdlepurge" defines how long the cache should be maintained before purging¶
some devices support notifications on changes in services, "autoUpdate" allows the network to update services based on notification (on by default)¶
"bonding" allows you to override the bonding method configured when onboarding the device¶
Response: Success responses include standard success response properties as defined in Table 3 as well as a protocol object with an array of discovered properties, as defined in the specific protocol. For example, for BLE, this is an array of supported services, which in turn contains an array of charateristics, which in turn contains an array of descriptors, as shown in Figure 10.¶
Example of a BLE connection response with BLE discovered properties:¶
where in the BLE protocol object:¶
"id", "requestID" and "technology" are part of hte standard Table 3 definition¶
"ble" protocol object conatins an Array of BLE services as shown in Figure 10¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: GET /action/connection¶
Description: Returns one or more active connections, based on ids provided in parameters (none = return all connections).¶
Parameters, in query: One of following options: - None: return all active connections for this application - single id: return connection status for this id - comma separated ids: return connection status for multiple ids¶
Response: A standard success (Figure 6)i or failure (Figure 7) response, including an array of device objects and their connection status. Success if hte device is connected, failure if the device is not connected.¶
Example get connection response:¶
In this example, status of 2 connections was requested. The request was successfully executed, 1 of the 2 connections was found active, the other one not.¶
Method: DELETE /action/connection¶
Description: Disconnect one or more devices, based on ids provided in parameters¶
Parameters, in query: One of following options: - None: Disconnect all devices for connections this application made - single id: disconnect device with id - comma separated ids: disconnect multiple devices with ids¶
Response: The response for the DELETE function is the same as the response for the GET function. See Figure 6 for success response, and Figure 11 for failed responses.¶
Property APIs allow applictions to read and write property values from/to devices.¶
/action/property¶
Operations:¶
Method: POST /action/property/¶
Description: Writes a value to a property¶
Parameters: None¶
Request Body: - an Object, as defined in Table 1 - A propertyID to write to - A value to be written - optional parameters¶
Example body writing a property:¶
where- - "id", "type" and "technology" are part of the object definition (device or group), as defined in Table 1 - "propertyID" is the ID of a previously registered property mapping - "value" is the value to be written - "forcedresponse" requests a specific response behavior of the device that is not the default¶
Response: Success responses include standard success response properties as defined in Table 3 as well as the propertyID and the value written.¶
Example of a write property response:¶
where-¶
"id", "requestID" and "technology" are part of the standard Table 3 definition¶
"propertyID" is the ID of a previously registered property mapping¶
"value" is the value to be written¶
"propertyID" is the proper¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: PUT /action/property¶
Description: Updates a value of a property¶
Parameters: None¶
Request Body: - an Object, as defined in Table 1 - A propertyID to write to - A value to be written - optional parameters¶
Example body updating a property:¶
where- - "id", "type" and "technology" are part of the object definition (device or group), as defined in Table 1 - "propertyID" is the ID of a previously registered property mapping - "value" is the value to be updated - "forcedresponse" requests a specific response behavior of the device that is not the default¶
Response: Success responses include standard success response properties as defined in Table 3 as well as the propertyID and the value updated.¶
Example of a write property response:¶
where-¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: GET /action/property/{property}¶
Description: Read a property from a device¶
Parameters, in path: A propertyID {property} that needs to be read.¶
Parameters, in query: An id of a device on which the property has to be read.¶
Response: Success responses include standard success response properties as defined in Table 3 as well as the propertyID and the value read.¶
Example of a read property response:¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: DELETE /action/property/{property}¶
Description: Delete a property value from a device¶
Parameters, in path: A propertyID {property} that needs to be deleted..¶
Parameters, in query: An id of a device on which the property has to be deleted.¶
Response: Success responses include standard success response properties as defined in Table 3 as well as the propertyID and the value deleted.¶
Example of a delete property response:¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
/action/property/subscription¶
Subscriptions are properties that deliver a data stream instead of a single value. The property subscription API allows an application to manage these data streams.¶
Operations:¶
Start a subscription data stream: POST¶
Get status of a subscription data stream: GET¶
Stop a subscription data stream: DELETE¶
Method: POST /action/property/subscription¶
Description: Start a subcription data stream pertaining to a specific property¶
Parameters: None¶
Request Body: - an Object, as defined in Table 1 - A propertyID for which to start the subscription - optional parameters¶
Example body for starting a subscription of a property:¶
where- - "id", "type" and "technology" are part of the object definition (device or group), as defined in Table 1 - "propertyID" is the ID of a previously registered property mapping - "forcedAck" requests a specific response behavior of the device that is not the default¶
Response: Success responses is a standard success response when the subscription is started, as defined in Table 3.¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: GET /action/property/subscription/{property}¶
Description: Gets the status of a subscription data stream, success if active, failure if not active¶
Parameters, in path: A propertyID {property} for the subscription.¶
Parameters, in query: An id of a device on which the subscription has to be started.¶
Response: Success responses is a standard success response when the subscription is started, as defined in Table 3.¶
A failure to find the subscription will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: DELETE /action/property/subscription/{property}¶
Description: stops a subscription data stream¶
Parameters, in path: A propertyID {property} for the subscription.¶
Parameters, in query: An id of a device on which the subscription has to be started.¶
Response: Success response is a standard success response when the subscription is deleted, as defined in Table 3.¶
A failure to delete the subscription will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
NIPC allows an application to register properties to use in action API's. NIPC supports 2 types of registrations: Registrations for properties and registrations for events.¶
/registration/event¶
The event registration API allows an application to register an event for a data application to a specified property. This event is mapped to an MQTT pub/sub topic. By activating a subscription on one or more device(s) for that property, streaming data will get published to the associated pub/sub topic on MQTT.¶
Operations:¶
Register an event: POST¶
Update an event: PUT¶
Get configuration of one or more events: GET¶
Delete an event: DELETE¶
Method: POST /registration/event¶
Description: Register an event to a property¶
Parameters: None¶
Request Body: - An event name that matches to an MQTT pub/sub topic - The data format the event should be delivered in - The device or group id the event is valid for - Whether the event needs to be cached for replay - the data applications that can consume the events¶
Example body registering an event:¶
where- - "event" is the event identifier, which also maps to the MQTT topic name - "eventFormat" is the format the data stream is delivered in, either default (decorated with id and property) or just the payload - "replay" defines whether the event should be cached for replay or not - "id" is hte id of the device or group the event is valid for - "type" is the type if the id, either device or group - "dataApps" is an array of data appplications that can subscribe to the event - "propertyID" is the propertyID that will be used in action APIs to activate this event¶
The dataApps array consists of following- - "dataAppID" is the identity of the data application either configured administratively or through SCIM. - "mqtt" optional MQTT broker connection parameters, in case an external MQTT needs to be configured¶
Response: Success responses include standard success response properties as defined in Table 3 as well as all the attributes that were configured from the request.¶
Example of a register event response:¶
where-¶
"id", "requestID" and "technology" are part of the standard Table 3 definition¶
"event" is the event identifier, which also maps to the MQTT topic name¶
"eventFormat" is the format the data stream is delivered in, either default (decorated with id and property) or just the payload¶
"replay" defines whether the event should be cached for replay or not¶
"dataApps" is an array of data appplications that can subscribe to the event¶
"propertyID" is the propertyID that will be used in action APIs to activate this event¶
The dataApps array consists of following- - "dataAppID" is the identity of the data application either configured administratively or through SCIM. - "mqtt" optional MQTT broker connection parameters, in case an external MQTT needs to be configured¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: PUT /registration/event¶
Description: Update an existing event¶
Parameters: None¶
Request Body: - An event name that matches to an MQTT pub/sub topic - The data format the event should be delivered in - The device or group id the event is valid for - Whether the event needs to be cached for replay - the data applications that can consume the events¶
Example body updating an event:¶
where- - "event" is the event identifier, which also maps to the MQTT topic name - "eventFormat" is the format the data stream is delivered in, either default (decorated with id and property) or just the payload - "replay" defines whether the event should be cached for replay or not - "id" is hte id of the device or group the event is valid for - "type" is the type if the id, either device or group - "dataApps" is an array of data appplications that can subscribe to the event - "propertyID" is the propertyID that will be used in action APIs to activate this event¶
The dataApps array consists of following- - "dataAppID" is the identity of the data application either configured administratively or through SCIM. - "mqtt" optional MQTT broker connection parameters, in case an external MQTT needs to be configured¶
The propertyID gets mapped to a protocol-specific property with a property mapping, through a protocol object-¶
Response: Success responses include standard success response properties as defined in Table 3 as well as all the attributes that were configured from the request.¶
Example of an update register event response:¶
where-¶
"id", "requestID" and "technology" are part of the standard Table 3 definition¶
"event" is the event identifier, which also maps to the MQTT topic name¶
"eventFormat" is the format the data stream is delivered in, either default (decorated with id and property) or just the payload¶
"replay" defines whether the event should be cached for replay or not¶
"dataApps" is an array of data appplications that can subscribe to the event¶
"propertyID" is the propertyID that will be used in action APIs to activate this event¶
The dataApps array consists of following- - "dataAppID" is the identity of the data application either configured administratively or through SCIM. - "mqtt" optional MQTT broker connection parameters, in case an external MQTT needs to be configured¶
The propertyID gets mapped to a protocol-specific property with a property mapping, through a protocol object-¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: GET /registration/event¶
Description: Gets the configuration of one or more events¶
Parameters: An event name. Multiple events can be added by comma-separated attributes. If no parameters are present, all events are returned.¶
Response: A success response as in Table 3 with a "events" object containing an array of returned event names with attributes defined in Figure 22.¶
Example of a get event response:¶
where- - "id", "requestID" and "technology" are part of the standard Table 3 definition - "events" is an array of events¶
where an event- - "event" is the event identifier, which also maps to the MQTT topic name - "eventFormat" is the format the data stream is delivered in, either default (decorated with id and property) or just the payload - "replay" defines whether the event should be cached for replay or not - "id" is hte id of the device or group the event is valid for - "type" is the type if the id, either device or group - "dataApps" is an array of data appplications that can subscribe to the event - "propertyID" is the propertyID that will be used in action APIs to activate this event¶
The dataApps array consists of following- - "dataAppID" is the identity of the data application either configured administratively or through SCIM. - "mqtt" optional MQTT broker connection parameters, in case an external MQTT needs to be configured¶
The propertyID gets mapped to a protocol-specific property with a property mapping, through a protocol object-¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: DELETE /registration/event¶
Description: Delete one or more events¶
Parameters: An event name. Multiple events can be added by comma-separated attributes. If no parameters are present, all events are returned.¶
Response: A success response as in Table 3 with a "events" object containing an array of returned event names with attributes defined in Figure 22.¶
Example of a delete event response:¶
where- - "id", "requestID" and "technology" are part of the standard Table 3 definition - "events" is an array of events¶
where an event- - "event" is the event identifier, which also maps to the MQTT topic name - "eventFormat" is the format the data stream is delivered in, either default (decorated with id and property) or just the payload - "replay" defines whether the event should be cached for replay or not - "id" is hte id of the device or group the event is valid for - "type" is the type if the id, either device or group - "dataApps" is an array of data appplications that can subscribe to the event - "propertyID" is the propertyID that will be used in action APIs to activate this event¶
The dataApps array consists of following- - "dataAppID" is the identity of the data application either configured administratively or through SCIM. - "mqtt" optional MQTT broker connection parameters, in case an external MQTT needs to be configured¶
The propertyID gets mapped to a protocol-specific property with a property mapping, through a protocol object-¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
/registration/property¶
The property registration API allows an application to register a property mapping against a protocol-specific property as decribed in Section 2.4.2¶
Operations:¶
Method: POST /registration/property¶
Description: Register a property mapping to a protocol-specific property¶
Parameters: None¶
Request Body: - a property ID - a protocol object containing a protocol mapping¶
Example body registering a property:¶
where- - "propertyID" is the propertyID that will be used in action APIs to refer to this property mapping - A protocol object with a protocol-specific property map, as decribed in Section 2.4.2¶
Response: Success responses include standard success response properties as defined in Table 3 as well as all the attributes that were configured from the request.¶
Example of a register property response:¶
where-¶
"id", "requestID" and "technology" are part of the standard Table 3 definition¶
"propertyID" is the propertyID that will be used in action APIs to refer to this property mapping¶
A protocol object with a protocol-specific property map, as decribed in Section 2.4.2¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: PUT /registration/property¶
Description: Update a property mapping to a protocol-specific property¶
Parameters: None¶
Request Body: - a property ID - a protocol object containing a protocol mapping¶
Example body updating a property:¶
where- - "propertyID" is the propertyID that will be used in action APIs to refer to this property mapping - A protocol object with a protocol-specific property map, as decribed in Section 2.4.2¶
Response: Success responses include standard success response properties as defined in Table 3 as well as all the attributes that were configured from the request.¶
Example of ain update property response:¶
where-¶
"id", "requestID" and "technology" are part of the standard Table 3 definition¶
"propertyID" is the propertyID that will be used in action APIs to refer to this property mapping¶
A protocol object with a protocol-specific property map, as decribed in Section 2.4.2¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: GET /registration/property¶
Description: Gets the property mapping of one or more properties¶
Parameters: A property name. Multiple properties can be added by comma-separated parameters. If no parameters are present, all properties are returned.¶
Response: A success response as in Table 3 with an array of properties, containing propertyID with protocol object containing a protocol-specific property mapping¶
Example of a get property response:¶
where- - "id", "requestID" and "technology" are part of the standard Table 3 definition - "properties" is an array of properties¶
where a property- - "id", "requestID" and "technology" are part of the standard Table 3 definition - "propertyID" is the propertyID that will be used in action APIs to refer to this property mapping - A protocol object with a protocol-specific property map, as decribed in Section 2.4.2¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
Method: DELETE /registration/property¶
Description: Deletes the property mapping of one or more properties¶
Parameters: A property name. Multiple properties can be added by comma-separated parameters. If no parameters are present, all properties are deleted.¶
Response: A success response as in Table 3 with an array of properties,
containing propertyID with protocol object containing a protocol-specific
property mapping¶
Example of a delete property response:¶
where- - "id", "requestID" and "technology" are part of the standard Table 3 definition - "properties" is an array of properties¶
where a property- - "id", "requestID" and "technology" are part of the standard Table 3 definition - "propertyID" is the propertyID that will be used in action APIs to refer to this property mapping - A protocol object with a protocol-specific property map, as decribed in Section 2.4.2¶
A failure will generate a standard failed response. Please refer to Table 4 definition of failed response.¶
NIPC is extensible in two ways:¶
Protocol mapping: New protocol mapping can extend NIPC with support for new non-IP protocols¶
API extensions: API extensions leverage compound statements of basic NIPC action APIs to simplify common operations for applications.¶
As described in Section 2.4.2 NIPC supports mapping protocol specific mapping to NIPC properties. BLE and Zigbee are used as examples, but protocol mapping is extensible to other protocols, so noew non-IP protocols can be supported by NIPC without a schema change.¶
As shown in Figure 32, a protocol mapping can be added by adding a new technology specific extension to the schema.¶
This is performed by adding the new protocol to the technology enum in the base object definition Table 1¶
Furthermore, the protocol objects need to be extended with the new protocol as well. Protocol objects will be extended as follows:¶
Attribute | Req | Type | Example |
---|---|---|---|
ble | T | object | an object with BLE-specific properties |
zigbee | T | object | an object with Zigbee-specific properties |
newProtocol | T | object | an object with newProtocol-specific props |
In the new protocol object, protocol specific properties can be added.¶
Protocol mappings need to be IANA registered.¶
/extension¶
The extension APIs allow for extensibility of the APIs, either IANA registered extensions or vendor-specific extensions. Extension APIs must leverage the basic NIPC defined APIs and combine them in compound statements in order to streamline application operation against devices, make operations more expediant and convenient in one API call. In principle they do not add any basic functionality. In the OpenAPI model Figure 38 below, we have defined a few example extensions.¶
The publish/subscribe interface, or data streaming interface, is an MQTT publishing interface. Pub/sub topics can be created and managed by means of the /registration/event NIPC element.¶
In this memo, we propose the data format to be CBOR [RFC8949].¶
We have a CDDL [RFC8610] definition where we define the DataSubscription struct that will be used by all the messages published to the MQTT broker.¶
The DataSubscription struct is a CBOR map that will contain the raw data in bytes and a timestamp of the data. Optionally, the message will also have a deviceId that corresponds to the SCIM ID of the device if the payload is associated to a known device.¶
Other fields in the CDDL such as apMacAddress and rssi can be optionally included but these fields can expose the underlying network topology.¶
Each message also has a subscription choice group that will define the type of data that is being published.¶
DataSubscription = { data: bytes, timestamp: float, ; epoch in seconds ? deviceId: text, ? apMacAddress: text, subscription } subscription = ( bleSubscription: BleSubscription // bleAdvertisement: BleAdvertisement // bleConnectionStatus: BleConnectionStatus // zigbeeSubscription: ZigbeeSubscription // rawPayload: RawPayload ) BleSubscription = { serviceId: text, characteristicId: text } BleAdvertisement = { macAddress: text, ? rssi: nint, } BleConnectionStatus = { macAddress: text, connected: bool, ? reason: int } ZigbeeSubscription = { endpointId: int, clusterId: int, attributeId: int attributeType: int } RawPayload = { contextId: text }¶
This section contains a few examples of the DataSubscription struct depicted in CBOR diagnostic notation.¶
This section contains a few examples on how applications can leverage NIPC operations to communicate with BLE and Zigbee devices.¶
In this example, we will onboard a device, and setup an advertisement subscription event for that device.¶
The sequence of operations for this are:¶
In this example, we will connect to a BLE device and read and write from a property.¶
The sequence of operations for this are:¶
In this example, we will connect a zigbee device to a Zigbee mesh and read and write from a property¶
The sequence of operations for this are:¶
Onboard a device using the SCIM Interface (out of scope of this memo)¶
Connect the Zigbee device POST /action/connection¶
Read a property from the Zigbee device GET /action/property¶
Write to a property on the Zigbee device POST /action/property¶
Disconnect from the Zigbee device DELETE /action/connection¶
This section provides guidance to the Internet Assigned Numbers Authority (IANA) regarding registration of values related to NIPC, in accordancei with [RFC5226].¶
The following non-normative model is provide for convenience of the implementor.¶