An Application Layer Interface for Non-IP device control (NIPC)
Internet-Draft draft-ietf-asdf-nipc-00
Bart Brinckman
Cisco Systems
Brussels
Belgium
bbrinckm@cisco.com
Rohit Mohan
Cisco Systems
170 West Tasman Drive
San Jose
95134
USA
rohitmo@cisco.com
Braeden Sanford
Philips
Cambridge
USA
braeden.sanford@philips.com
24 July 2024
Internet-Draft
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.
Introduction
Use cases in building management, healthcare, workplaces, manufacturing, logistics and hospitality have introduced low-power devices into these environments. These devices typically do not support IP-based interfaces, hence there is a need for gateway functions to allow these devices to communicate with the applications that manage them.
Gateway for non-IP Devices

    +-------------+              +---------+              +--------+
    | Application |<------------>| Gateway |<------------>| Non-IP |
    |    app      |   IP-based   |         |    Non-IP    | Device |
    +-------------+   Operation  +---------+   Operation  +--------+

In abscence of a standard describing how applications communicate with such non-IP devices, vertically integrated infrastructure prolifilates and applications have bespoke integrations with that infrastructure for every use case. The Application interfaces are non-standard. This stunts the eco-system growth. At the same time, wireless access points have been deployed nearly everywhere, many of which have soft or separate radios that can transmit and receive different frame types, such as [BLE53] and [Zigbee22]. To avoid the need for parallel infrastructure and bespoke application integration, a standardized gateway function is necessary.
The gateway provides at a minimum the following functions:
- authentication and authorization of application clients that will access devices
- the ability to onboard devices that are intended to be deployed within the use case
- maintenance of an inventory of onboarded devices that are intended to access and be accessed by the deployment and applications.
- interfaces that allow for bi-directional communication to non-IP devices
- one or more channels to process requests, responses, and asymmetric communciations with the non-IP radio resources (Access Points) in the system.
Combined with a provisioning interface such as [I-D.shahzad-scim-device-model], this specification supports these aspects, specifically focusing on providing bi-directional communication with non-IP devices.
Basic Architecture

                            +-----------------------------------+
                            |                                   |
    +-----------+   Request |  +---------+                      |
    | onboarding|------------->|  SCIM   |                      |
    |    app    |<-------------| Server  |                      |
    +-----------+  Ctrl Endpt  +---------+                      |
                            |                                   |
    +-----------+           |  +------------+  +-------+  +--+  |
    |  Control  |>...REST...|.>|            |..|  AP   |..|D |  |
    |     &     |           |  |   Gateway  |  +-------+  +--+  |
    | Telemetry |<...MQTT...|.<|            |                   |
    |    Apps   |           |  +------------+                   |
    +-----------+           |                                   |
                            |       Network Deployment          |
                            +-----------------------------------+

Figure 2 shows us the application layer gateway (ALG), an access point (AP), and a device (D) in the enterprise environment. The role of the ALG is to provide a application gateway to non-IP devices connecting into one or more AP. Applications implementing this memo can leverage RESTful interfaces to communicate with these devices and subscribe to streaming data or broadcasts levering MQTT.
The flow of operations are as follows:
1. The operator of the network deployment 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:
a. Authorize an onboarding application against a SCIM endpoint supported by the gateway.
b. Provision and authorize applications that may control devices.
c. Provision and authorize applications that may receive telemetry.
2. The authorized application can now provision one or more devices on the gateway leveraging SCIM.
Steps 1 and 2 are not within the scope of this specification, but are provided for context.
1. The authorized application can perform RESTful calls to the gateway in order to establish bi-directional communication to one or more devices. Optionally, set up a publish/subcribe topic to receive streaming data from a device (telemetry interface).
2. Optionally, an application can receive streaming data on a pub/sub topic configured by the control interface (telemetry interface).
Step 3 and 4 are the subject of this memo.
This specification is organized into three sections:
- Basic non-IP control functions described in narrative.
- Extensibility of the interfaces.
- A specification that can be mapped to a publication/subscribe interface, such as MQTT.
- Examples of use cases leveraging both BLE and Zigbee-based devices.
- OpenAPI definitions for the control interface and Protobuf definitions for the streaming data interface
Terminology
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 Control Functions
This section will describe a standardized protocol-agnostic interface that allows the application to establish bi-directional communication with a non-IP device, such as a BLE or Zigbee device. The interface will be supported on a gateway as show in Figure 2.
Approach
In non-IP protocols such as BLE or Zigbee, a number of basic operations are defined that are similar across protocols. Examples of this are read and write data. Devices may choose to implement all of the operations or a subset. For example in BLE a device may choose to implement a binding, but could also allow connection without a binding. In this memo we have therefore defined a control interface that exposes these basic operations with a communications protocol-agnostic schema, with protocol specific extensions to transmit and receive attributes that are specific to the communications protocol supported by the device. This enables extensions to integrate new non-ip communications protocols, without the need to update the base schema.
Extensible Schema

    ID
     - device/group attributes
        |
        |> BLE
        |     - BLE attributes
        |
        |> Zigbee
              - Zigbee attributes

As shown in Figure 3, the control interface addresses device and group objects as IDs, hence the requirement to declare a device to the gateway before addressing a NIPC operation to the device. This is done by means of SCIM. A NIPC operation can either be performed against a device-id or a group-id. The gateway will leverage information from the SCIM object to execute a specific NIPC operation. For example, keying material found in the SCIM object may be required to connect to a device. Please refer to [I-D.shahzad-scim-device-model] for more information on SCIM device objects.
Apart from enabling bi-directional communication with non-ip devices, NIPC also allows an application to register pub/sub topics in order to support a programmable data streaming interface.
Common base schema
As described, most operations are executed against a device or a group. Control operations refer to either of these as "Object" with an ID as an identifier. The common schema for Object is defined as follows:
Definition of an Object
Attribute | Req | Type | Example
id | T | uuid | 12345678-1234-5678-1234-56789abcdef4
type | T | enum | device
technology | F | enum | ble
where-
- id is the id returned in the response when registering a device against a SCIM server.
- type is either "group" or "device".
- technology is the radio technology extension(s) supported by the device, in this memo either "ble" or "zigbee".
Protocol extensions
An object can support one or more communications protocols. These attributes must be described in a protocol object, for example a "ble" or a "zigbee" object.
Protocol extensions
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 attributes that are specific to the BLE protocol.
- "zigbee" is an object containing attributes that are specific to the Zigbee protocol.
- Other protocol extensions can be added
Response
As most operations have a common base schema, so do responses. As mandatory, a status is returned, optionally also device id and request id.
Success response:
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
Failure response:
Failure response
Attribute | Req | Type | Example
status | T | enum | SUCCESS
errorCode | T | int | 12
reason | T | string | "Not Found"
requestID | F | uuid | abcd0987-1234-5678-1234-56789abcdef4
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
Categories of operations supported
The common operations are categorized in common categories that describe high level sets of functionalities. Each of the NIPC operations belong to a category. The categories are:
- /connectivity: Allows an application to establish connectivity with a device (if so required by the technology)
- /data: Allows applications to exchange data with a device
- /registrations: Allows an application to make registrations in the network, for example to register a pub/sub topic
- /extensions: This is a category of operations that leverage basic connectivity, data or registration operations, but are optimized for application usage, allowing applications to perform functions with a reduced number of round-trips. An example of this is the the bulk operation, allowing to send multiple operations is one operation. This category also allows for further extensions based on the basic operations.
Connecting to the Non-IP Control Interface
NIPC makes use of RESTful HTTP[RFC9114]. The connection endpoint is provided out of band, most likely through the SCIM devices model extension, in which an authorized application can be registered for a SCIM object. Similarly authentication of the interface can be specified using that SCIM interface. It may be based on a device certificate or an authorization token.
Connectivity
/connectivity
Connectivity elements are elements that allow operations that establish or tear down associations & connectivity with devices. They also allow discovery of services that can be accessed during the connection.
Binding
/connectivity/binding
The binding element allows an application to request a binding or association to a device.
Operations:
- Create binding: POST
- Return active bindings: GET
- Delete binding: DELETE
Create a Binding
Method: POST /connectivity/binding
Description: Creates a binding with a device
Parameters: None
Request Body: an Object as defined in Table 1
Response: See Table 3 for success, and Table 4 for failed responses.
Return active bindings
Method: GET /connectivity/binding
Description: Returns one or more bindings, based on ids provided in parameters (none = return all)
Parameters: One of following options: - None: return all bindings this application made - single id: return binding for this id - comma separated ids: return bindings for multiple ids
Response: An Array of bindings with contents as shown in Table 5 below or Table 4 for failed responses.
Binding response
Attribute | Req | Type | Example
status | T | enum | SUCCESS
requestID | F | uuid | abcd0987-1234-5678-1234-56789abcdef4
bindings | T | array | Array of BLE or Zigbee ids
Delete a binding
Method: DELETE /connectivity/binding
Description: Delete one or more bindings, based on ids provided in parameters
Parameters: One of following options: - None: delete all bindings this application made - single id: delete binding for this id - comma separated ids: delete bindings for multiple ids
Response: See Table 3 for success, and Table 4 for failed responses.
Binding by id
/connectivity/binding//id/{id}
The binding by id element allows an application to request a binding or association to a device by id, which provides a simpler interface than standard binding element, but pertains to a single device only.
Operations:
- Create binding by id: POST
- Return active binding by id: GET
- Delete binding by id: DELETE
Create a Binding by id
Method: POST /connectivity/binding/id/{id}
Description: Creates a binding by id
Parameters: id
Response: See Table 3 for success, and Table 4 for failed responses.
Return active binding by id
Method: GET /connectivity/binding//id/{id}
Description: Returns a binding by id Parameters: id
Response: See Table 3 for success, and Table 4 for failed responses.
Delete binding by id
Method: DELETE /connectivity/binding/id/{id}
Description: Delete a binding by id
Parameters: id
Response: See Table 3 for success, and Table 4 for failed responses.
Connection
/connectivity/connection
The connection element allows an application to request to connect to a device.
Operations:
- Connect to a device: POST
- Return active connections: GET
- Disconnect a device: DELETE
Connect to a device
Method: POST /connectivity/connection
Description: Connect to a device
Parameters: None
Request Body: - an Object, as defined in Table 1 - optionally a set of services to be discovered. These are supplied in protocol-specific extensions, as defined in Table 2. In the case of BLE, service discovery is performed when connecting to a device. Optionally, service discovery may be limited to services defined in the "ble" protocol extension. The services to be discovered can be added in an array, as well as optional caching parameters. Please see table below Table 6 for a definition of the content of the BLE protocol extension for limited service discovery
Service Discovery
Attribute | Req | Type | Example
services | T | array | Array of serviceIDs to be discovered
cached | F | boolean | no
cacheIdlePurge | F | int | 3600
autoUpdate | F | boolean | yes
where-
- "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)
Response: Success responses include standard success response attributes as defined in Table 3 and also include cwan array of supported services. This array of supported services in turn contains an array of charateristics, which in turn contains an array of descriptors, as shown Figure 4. For a description of the attributes found in this array, please refer to Table 7 below. Please refer to Table 4 for failed responses.
Services

    services
     - serviceID
        |
        |> characteristics
            - charactericID
            - flags
               |
               |> Descriptors
                   - descriptorID

Attributes in the array of services:
Service Discovery Response Attributes
Attribute | Req | Type | Example
serviceID | F | uuid | abcd0987-1234-5678-1234-56789abcdef4
characteristicID | F | uuid | abcd0987-1234-5678-1234-56789abcdef4
flags | F | enum | write
descriptorID | F | uuid | abcd0987-1234-5678-1234-56789abcdef4
Return active connections
Method: GET /connectivity/connection
Description: Returns one or more active connections, based on ids provided in parameters (none = return all).
Parameters: 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: An Array of connections with attributes as defined in Table 8 or in case of a failed response, the attributes in Table 4.
Connection response
Attribute | Req | Type | Example
status | T | enum | SUCCESS
requestID | F | uuid | abcd0987-1234-5678-1234-56789abcdef4
connections | T | array | Array of connections
Disconnect a device
Method: DELETE /connectivity/connection
Description: Disconnect one or more devices, based on ids provided in parameters
Parameters: 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: See Table 3 for success, and Table 4 for failed responses.
Connections by id
/connectivity/connection/id/{id}
The connection by id element allows an application to request a connection to a device by id, which provides a simpler interface than standard connection element, but pertains to a single device only.
Operations:
- Connect device by id: POST
- Return connection state by id: GET
- Disconnect device by id: DELETE
Connect device by id
Method: POST /connectivity/connection/id/{id}
Description: Creates a connection by id
Parameters: id
Response: See Table 3 for success, and Table 4 for failed responses.
Return connection state by id
Method: GET /connectivity/connection/id/{id}
Description: Returns connection state by id Parameters: id
Response: See Table 3 for success, and Table 4 for failed responses.
Delete connection by id
Method: DELETE /connectivity/connection/id/{id}
Description: Delete a binding by id
Parameters: id
Response: See Table 3 for success, and Table 4 for failed responses.
Discover services supported by a device
/connectivity/services
The services element allows an application to request a service discovery for a device, possibly to update a cache
Operations:
- Discover services: GET
Discover services supported by a device
Method: GET /connectivity/service
Description: Discover services supported by a device, this updates cache in case services caching is enabled for a connection.
Parameters: an Object as defined in Table 1 and optionally a set of services to be discovered in case not all services should be discovered. These services need to be provided in protocol-specific extensions as defined in Table 2. The services to be discovered can be added in this extension in an array, as well as optional caching parameters, as described in Table 6.
Response: A successful response will contain success attributes from Table 3 with an array of supported services characteristics and descriptors, as shown in Figure 4, with attributes defined in Table 7. Failure Response is the standard response as defined in Table 4
Discover services supported by a device by id
/connectivity/services/id/{id}
The services element allows an application to request a service discovery for a device by id, possibly to update a cache
Operations:
- Discover services by id: GET
Discover services supported by a device by id
Method: GET /connectivity/service/id/{id}
Description: Discover services supported by a device, this updates cache in case services caching is enabled for a connection. This method does not support partial service discovery, all services are discovered.
Parameters: an Object id
Response: A successful response will contain success attributes from Table 3 with an array of supported services, characteristics and descriptors, as shown in Figure 4, with attributes defined in Table 7. Failure Response is the standard response as defined in Table 4.
Data
/data
Data elements are elements that allow operations to exchange data with a device. This could be reading or writing attributes or enabling streaming data.
Attribute
/data/attribute
The attribute element allows an application get an attribute value, write, update or delete a value.
Operations:
- Write value: POST
- Update value: PUT
- Read value: GET
- Delete value: DELETE
Writing a value
Method: POST /data/attribute
Description: Writes a value to an attribute
Parameters: None
Request Body: an Object as defined in Table 1, a value to be written, as defined in Table 9 below and an attribute definition in a protocol extension from Table 2. The protocol extension for BLE is defined in Table 10 below. The protocol extension for Zigbee is defined in Table 11 below.
Value
Attribute | Req | Type | Example
value | T | array | 100
forcedResponse | F | boolean | no
where-
- value is the value to be written
- forcedresponse requests a specific response behavior of the device
Contents of the BLE protocol extension defining an attribute:
BLE Attribute
Attribute | Req | Type | Example
serviceID | T | uuid | abcd0987-1234-5678-1234-56789abcdef4
characteristicID | T | uuid | abcd0987-1234-5678-1234-56789abcdef4
long | F | boolean | no
where-
- serviceID defines the Service
- characteristic ID defines the service characteristic
- long is an optional attribute that allows to force a write type
Contents of the Zigbee protocol extension defining an attribute:
Zigbee Attribute
| endpointID | T | int | 16
| clusterID | T | int | 6
| attributeID | T | int | 12
| type | T | int | 1
where-
- endpointID defines the Zigbee endpoint that contains a cluster of attributes
- clusterID defines the Zigbee cluster that contains the attribute
- attributeID defines the Zigbee attribute
- type defines the Zigbee attribute type
Response: A successful response will contain success attributes from Table 3 with optionally the value written as shown in Table 9. Failure Response is the standard response as defined in Table 4
Updating a value
Method: PUT /data/attribute
Description: Updates a value to an attribute
Parameters: None
Request Body: an Object as defined in Table 1, a value to be written, as defined in Table 9 and an attribute definition in a protocol extension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11.
Response: A successful response will contain success attributes from Table 3 with optionally the value written as shown in Table 9. Failure Response is the standard response as defined in Table 4
Read an attribute
Method: GET /data/attribute
Description: Reads an attribute from a device
Parameters: an Object as defined in Table 1 and an attribute definition in a protocol extension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11.
Response: A successful response will contain success attributes from Table 3 with the value read as shown in Table 9. Failure Response is the standard response as defined in Table 4
clear the value from an attribute
Method: DELETE /data/attribute
Description: Clear the value from an attribute of a device
Parameters: an Object as defined in Table 1 and an attribute definition in a protocol extension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11.
Response: A successful response will contain success attributes from Table 3 with the optionally the value as null as shown in Table 9. Failure Response is the standard response as defined in Table 4
Subscription
/data/subscription
The subscription element allows an application to ask a device to start streaming data attached to a certain attribute.
Operations:
- Start a subscription data stream: POST
- Update a subscription data stream value: PUT
- Get status of a subscription data stream: GET
- Stop a subscription data stream: DELETE
Starting a subscription data stream
Method: POST /data/subscription
Description: Start a subcription data stream pertaining to a specific attribute
Parameters: None
Request Body: an Object as defined in Table 1 and an attribute definition in a protocol extension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11. Optionally a pub/sub topic can be included in the request as defined in Table 12 below. Including a topic allows the app to skip the topic registration process.
Topic attributes:
Topic
Attribute | Req | Type | Example
topic | F | string | "enterprise/hospital/pulse"
dataFormat | F | enum | "default"
replay | F | boolean | no
forced_ack | F | boolean | no
where-
- topic is the pub/sub topic the subscription can be consumed on
- dataFormat is the data format in which the pub/sub topic is delivered
- replay is a boolean which defines whether data should be replayed in case of application disconnection
- forced ack ignores the attribute definition and forces packet ack behavior to the device
Response: See Table 3 for success, and Table 4 for failed responses.
Updating a subscription data stream
Method: PUT /data/subscription
Description: Update parameters of a subscription data stream pertaining to a specific attribute
Parameters: None
Request Body: an Object as defined in Table 1 and an attribute definition in a protocol extension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11. Optionally a pub/sub topic can be included in the request as defined in Table 12.
Response: See Table 3 for success, and Table 4 for failed responses.
Get status of a subscription data stream
Method: GET /data/subscription
Description: Gets the status of a subscription data stream, success if active, failure if not active
Parameters: an Object as defined in Table 1 and an attribute definition in a protocol extension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11. Optionally a pub/sub topic can be included in the request as defined in Table 12.
Response: See Table 3 for success, and Table 4 for failed responses.
stop a subscription data stream
Method: DELETE /data/subscription
Description: stops a subscription data stream
Parameters: an Object as defined in Table 1 and an attribute definition in a protocol extension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11. Optionally a pub/sub topic can be included in the request as defined in Table 12.
Response: See Table 3 for success, and Table 4 for failed responses.
Subscriptions by id
/data/subscription/id/{id}
The subscription by id element allows an application to operate on all subscriptions of a specific id.
Operations:
- Return active subscriptions by id: GET
- Terminate all subscriptions of an id: DELETE
Return active subscriptions by id
Method: GET /data/subscription/id/{id}
Description: Returns connection state by id
Parameters: id
Response: Success response as defines in Table 3 and an object called "subscriptions" which contains an Array of active subscriptions. Each of these include an object as defined in Table 1 and a subscription attribute definition in a protocolextension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11. Failure Response is the standard response as defined in Table 4
Stop active subscriptions by id
Method: DELETE /data/subscription/id/{id}
Description: Delete active subscriptions for an id
Parameters: id
Response: Success response as defines in Table 3 and an object called "subscriptions" which contains an Array of active subscriptions. Each of these include an object as defined in Table 1 and a subscription attribute definition in a protocolextension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11. Failure Response is the standard response as defined in Table 4
Subscriptions by topic
/data/subscription/topic/{topic}
The subscription by topic element allows an application to operate on all subscriptions of a specific topic.
Operations: - Return active subscriptions by topic: GET - Terminate all subscriptions active on a topic: DELETE
Return active subscriptions by topic
Method: GET /data/subscription/topic/{topic}
Description: Returns connection state by topic
Parameters: topic
Response: Success response as defines in Table 3 and an object called "subscriptions" which contains an Array of active subscriptions. Each of these include an object as defined in Table 1 and a subscription attribute definition in a protocolextension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11. Failure Response is the standard response as defined in Table 4
Stop active subscriptions by topic
Method: DELETE /data/subscription/topic/{topic}
Description: Delete all active subscriptions for a topic
Parameters: topic
Response: Success response as defines in Table 3 and an object called "subscriptions" which contains an Array of active subscriptions. Each of these include an object as defined in Table 1 and a subscription attribute definition in a protocolextension from Table 2. The protocol extension for BLE is defined in Table 10. The protocol extension for Zigbee is defined in Table 11. Failure Response is the standard response as defined in Table 4
Broadcast
/data/broadcast
The broadcast element allows an application to broadcast a message to a specific device. Note that broadcasts can be heard by other devices on the same L2 network.
Operations:
- Broadcast message: POST
Broadcasting a message
Method: POST /data/broadcast
Description: Broadcasts a message to a device
Parameters: None
Request Body: an Object as defined in Table 1 along with broadcast parameters, defined below in Table 13. Defining broadcast attributes is mandatory and is done by adding an array of broadcast attributes in a protocol extension from Table 2. The protocol extension for BLE broadcasts is defined in Table 14 below.
Broadcast parameters:
Broadcast parameters
Attribute | Req | Type | Example
cycle | T | enum | single
broadcastTime | F | int | 30
broadcastInterval | F | int | 5
where-
- cycle determines the repetitiveness of the broadcast, and is either single or repeat
- broadcastTime is the maximum time in seconds the broadcast should run
- broadcastInterval is the time between broadcasts in seconds
Protocol-specific extensions are supplied to identify the attributes to be broadcasted.
BLE Broadcast Attribute
Attribute | Req | Type | Example
adType | T | byte | ff
adData | T | byte | 4c00
where-
- adType is the BLE advertisement attribute type
- adData is the BLE advertisement attribute data
Response: See Table 3 for success, and Table 4 for failed responses.
Registrations
/registation
Registration elements are elements that do not directly execute operations on devices but register attributes on the gateway that support operations, such attributes are topics for data streaming and files to write files.
Topic registration
/registration/topic
The topic registration element allows an application to register a pub/ sub topic for the data interface. By activating a subscription on one or more device(s), the application can then publish streaming data to that topic.
Operations:
- Register a topic: POST
- Update a topic: PUT
- Get configuration of one or more topics: GET
- Delete a topic: DELETE
Registering a topic
Method: POST /registration/topic
Description: Register a pub/sub topic
Parameters: None
Request Body: A topic, including data apps that can subscribe to the topic as defined in Table 12 and protocol-specific extensions as per Table 2 that describe the attributes that will be reported on the topic. In the case of BLE, these are either BLE subscription attributes as in Table 10, device connection status, or Broadcast (advertisement) data as in Table 14. For Zigbee, these are Zigbee attributes as described in Table 11.
Response: See Table 3 with a topic name as in Table 15 below for success, and Table 4 for failed responses.
Topic name that was registered:
Topic Name
Attribute | Req | Type | Example
topic | T | string | "enterprise/hospital/pulse"
Updating a topic
Method: PUT /registration/topic
Description: Update a pub/sub topic
Parameters: None
Request Body: A topic, including data apps that can subscribe to the topic as defined in Table 12 and protocol-specific extensions as per Table 2 that describe the attributes that will be reported on the topic. In the case of BLE, these are either BLE subscription attributes as in Table 10, device connection status, or Broadcast (advertisement) data as in Table 14. For Zigbee, these are Zigbee attributes as described in Table 11.
Response: See Table 3 with a topic name as in Table 15 below for success, and Table 4 for failed responses.
Get configuration of one or more topics
Method: GET /registration/topic
Description: Gets the configuration of one or more topics
Parameters: A topic name. Multiple topics can be added by comma-separated attributes.
Response: A success response as in Table 3 with a "topics" object containing an array of returned topics names with attribute defined in Table 15. For failed responses see Table 4.
Delete one or more topics
Method: DELETE /registration/topic
Description: Delete one or more topics
Parameters: A topic name. Multiple topics can be added by comma-separated attributes.
Response: A success response as in Table 3 with a "topics" object containing an array of returned topics names with attribute defined in Table 15. For failed responses see Table 4.
Topic registrations by id
/registration/topic/id/{id}
The topic registration by id element allows an application to get or delete topic registrations for a specific id.
Operations:
- Return active topics by id: GET
- Delete all topics for an id: DELETE
Return active topics by id
Method: GET /registration/topic/id/{id}
Description: Returns active topics by id
Parameters: id
Response: A success response as in Table 3 with a "topics" object containing an array of returned topics names with attribute defined in Table 15. For failed responses see Table 4.
Delete active topics by id
Method: DELETE /registration/topic/id/{id}
Description: Deletes active topics by id, will delete all topics that are associated with a specific object id.
Parameters: id
Response: A success response as in Table 3 with a "topics" object containing an array of returned topics names with attribute defined in Table 15. For failed responses see Table 4.
Topic registrations by data app
/registration/topic/data-app/{data-app}
The topic registration by data-app element allows an application to get or delete topic registrations for which a specific data-application is registered.
Operations:
- Return active topics by data-app: GET
- Delete all topics for an data-app: DELETE
Return active topics by data-app
Method: GET /registration/topic/data-app/{data-app}
Description: Returns active topics by data-app
Parameters: data-app
Response: A success response as in Table 3 with a "topics" object containing an array of returned topics names with attribute defined in Table 15. For failed responses see Table 4.
Delete active topics by data-app
Method: DELETE /registration/topic/data-app/{data-app}
Description: Deletes active topics by data-app, will delete all topics the specified data app is registered for.
Parameters: data-app
Response: A success response as in Table 3 with a "topics" object containing an array of returned topics names with attribute defined in Table 15. For failed responses see Table 4.
Topic registrations by topic name
/registration/topic/{topic}
The topic registration by topic element allows an application to get or delete a topic registration by topic name.
Operations:
- Return active topics by topic name: GET
- Delete all topics for a topic name: DELETE
Return active topics by topic name
Method: GET /registration/topic/{topic}
Description: Returns active topics by topic name
Parameters: topic
Response: A success response as in Table 3 with a topic name as defined in Table 15. For failed responses see Table 4.
Delete active topics by topic name
Method: DELETE /registration/topic/{topic}
Description: Deletes active topics by topic name
Parameters: topic
Response: A success response as in Table 3 with a topic name as defined in Table 15. For failed responses see Table 4.
File registration
/registration/file
The file registration element allows an application to register a file. a file can be used in operations to devices (such as an attribute)
Operations:
- Register a file: POST
- Update a file: PUT
- Check if a file exists: GET
- Delete a file: DELETE
Registering a file
Method: POST /registration/file
Description: Register a file
Parameters: None
Request Body: a file or URL point to a file, as described in Table 16 below.
File definition:
File
Attribute | Req | Type | Example
filename | T | string | "firmware.dat"
file | F | binary | file
bindings | F | string | "https://domain.com/firmware.dat"
Response: See Table 3 for success, and Table 4 for failed responses.
Updating a file
Method: PUT /registration/file
Description: Update a file
Parameters: None
Request Body: a file or URL point to a file, as described in Table 16 below.
Response: See Table 3 for success, and Table 4 for failed responses.
check presence of a registered file
Method: GET /registration/file
Description: Check the presence of a specific file or get all files if no file name os present in parameters
Parameters: filename
Response: Success as in Table 3 including a "filesnames" object with an array of file names as shown in Table 17 or a Failure Response as described in Table 4.
A filenames object with an Array of file names:
File name
Attribute | Req | Type | Example
filename | T | string | "firmware.dat"
delete a registered file
Method: DELETE /registration/file
Description: Delete a registered file
Parameters: filename
Response: See Table 3 for success, and Table 4 for failed responses.
file registrations by file name
/registration/file/{filename}
The file registration by file name element allows an application to get or delete file registrations by file name.
Operations:
- Return file registrations by file name: GET
- Delete file registrations by file name: DELETE
Return file registrations by file name
Method: GET /registration/file/{filename}
Description: Checks the presence of a file and returns its name
Parameters: filename
Response: Success as in Table 3 including a file name as shown in Table 17 or a Failure Response as described in Table 4.
Delete file registrations by file name
Method: DELETE /registration/file/{filename}
Description: Delete file registrations by file name
Parameters: filename
Response: See Table 3 for success, and Table 4 for failed responses.
NIPC Extensibility
NIPC is extensible in two ways:
- Protocol extensions: Protocol extensions can extend NIPC with support for new non-IP protocols
- interface extensions: Interface extensions allow extensions that leverage compound statements of basic elements to simplify common operations for applications.
Protocol extensions
As described in Figure 3 the NIPC interface supports protocol specific extensions that allow bi-directional communication of attributes that are specific to the protocol supported by the device. This allows for extensions to the schema to integrate new non-ip communications protocols, without the need to update the base schema.
Extended Schema

    ID
     - device/group attributes
        |
        |> BLE
        |     - BLE attributes
        |
        |> Zigbee
        |     - Zigbee attributes
        |
        |> Protocol extension
        |     - Protocol extension attributes

As shown in Figure 5, a protocol extension 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 objext definition Table 1
Furthermore, the protocol objects need to be extended with the new protocol as well. Protocol objects will be extended as follows:
Adding Protocol extensions
Attribute | Req | Type | Example
ble | T | object | an object with BLE-specific attributes
zigbee | T | object | an object with Zigbee-specific attributes
newProtocol | T | object | an object with newProtocol-specific attr
In the new protocol object, protocol specific attributes can be added.
Interface extensions
/extensions
The interface extension elements are freely extendible interfaces. These elements leverage the basic NIPC defined elements 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 6 below, we have defined a few example extensions, and we will describe them here at a high level to provide some context on other possible extensions.
Write file
/extension/write/file
This extension make use of multiple write operations (attribute post) to write an entire file to an attribute. The interface allows the application to define the chunk size.
Operations:
- Write file: POST
Read conditional file
/extension/read/conditional
This extension performs a read operation sequentially for a defined amount of time until a specified value is read.
Operations:
- Read Conditional: POST
Bulk
/extension/bulk
This extension allows you to create a compound operation made out of multiple connection and data operations that are to be executed sequentially until they all succeed or there is a failure. Supported operations are:
- /extension/connection/create
- /extension/connection/delete
- /extension/attribute/read
- /extension/attribute/write
- /extension/attribute/write/file
- /extension/attribute/write/blob
- /extension/attribute/read/conditional
Operations:
- Bulk: POST
Publish/Subscribe Interface
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 /register/topic NIPC element.
In this memo we propose the data format to be protocol buffers, as fully described in the Figure 7 protobuf definition.
Examples
This section contains a few examples on how applications can leverage NIPC operations to communicate with BLE and Zigbee devices.
BLE Advertisement
In this example, we will onboard a device, and setup an advertisement subscription topic for that device.
The sequence of operations for this are:
- Onboard a device using the SCIM Interface (out of scope of this memo)
- Register a topic with the device id to subscribe to advertisements POST /register/topic
- Subscribe to the topic from the data receiver app MQTT subscribe topic
BLE Attribute Read/Write
In this example, we will connect to a BLE device (BLE device does not require binding) and read and write from an attribute
The sequence of operations for this are:
- Onboard a device using the SCIM Interface (out of scope of this memo)
- Connect to the BLE device POST /connectivity/connection
- Read an attribute from the BLE device GET /data/attribute
- Write to an attribute on the BLE device POST /data/attribute
- Disconnect from the BLE device DELETE /connectivity/connection
Zigbee Attribute Read/Write
In this example, we will bind a zigbee device to a Zigbee mesh and read and write from an attribute
The sequence of operations for this are:
- Onboard a device using the SCIM Interface (out of scope of this memo)
- Bind the Zigbee device POST /connectivity/binding
- Read an attribute from the Zigbee device GET /data/attribute
- Write to an attribute on the Zigbee device POST /data/attribute
- Disconnect from the Zigbee device DELETE /connectivity/connection
Security Considerations
TBD.
IANA Considerations
TBD.
References
Normative References
[I-D.shahzad-scim-device-model]

Device Schema Extensions to the SCIM model
Muhammad Shahzad
North Carolina State University
HASSAN IQBAL
North Carolina State University
Eliot Lear
Cisco Systems
2 June 2023
Internet-Draft draft-shahzad-scim-device-model-05
[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels
S. Bradner
March 1997
BCP 14
RFC 2119
DOI 10.17487/RFC2119
[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
B. Leiba
May 2017
BCP 14
RFC 8174
DOI 10.17487/RFC8174
[RFC9114]

HTTP/3
M. Bishop, Ed.
June 2022
RFC 9114
DOI 10.17487/RFC9114
Informative References
[BLE53]

Bluetooth Core Specification, Version 5.3
Bluetooth SIG
2021
[Zigbee22]

zigbee Specification, Version 22 1.0
Connectivity Standards Alliance
2017
OpenAPI definition
The following non-normative model is provide for convenience of the implementor.

{::include nipc-openapi/NIPC_REST.yaml}

Protobuf definition
The following non-normative protocol buffer definition is provide for convenience of the implementor.

{::include proto/data_app.proto}