]> Cisco Systems

Brussels Belgium bbrinckm@cisco.com

Cisco Systems

170 West Tasman Drive San Jose 95134 USA rohitmo@cisco.com

Philips

Cambridge USA braeden.sanford@philips.com

Internet-Draft This memo describes an API that allows applications to perform operations against a gateway serving one or more devices described by an SDF model. The document describes a RESTful application layer interface to perform operations on those devices, as well as a CBOR-based publish-subscribe interface for streaming data.

Introduction

Motivation 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. With limited power budget, they may not be able to support the IP protocol on their wired or wireless interfaces, hence they support protocols that require a lower power budget. Prominent examples of such protocols are and . These devices typically need to communicate with devices or applications that are connected to IP-based networking infrastructure. Therefore, applications on the IP network that need 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 function then translates the communication to the non-IP protocol that the low-power device supports.

| Gateway |<------------>| Non-IP | | | IP-based | | Non-IP | Device | +-------------+ Operation +---------+ Operation +--------+ ]]>

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 (), however they have been limited to a single protocol or a particular use case. In absence of an open standard describing how applications on an IP network communicate with non-IP devices, bespoke and vendor-specific implementations have proliferated. The implication of this is that every use case deployment requires implementation of a new API, and possibly requires its own gateway, which results in proliferation of network infrastructure. This specification aims to define a Gateway API for these Non-IP protocols that can be leveraged by a Network Gateway connected to a wireless network. The API aims to enable a Gateway to support any non-IP protocol. The gateway can simultaneously support multiple applications and multiple non-IP protocols as well as different versions of the same protocol. The specification is extensible, in order to support existing and future non-IP protocols. A standardized Non-IP Gateway interface has following benefits: Avoid the need for applications to perform new and bespoke integrations for different environments. Avoid having to deploy multiple Gateway functions to support multiple non-IP use cases. Faster and more cost-effective adoption of Non-IP devices in IP network environments.

Non-IP Gateway A non-IP gateway is an application layer gateway that allows Applications on IP networks to communicate with Non-IP devices leveraging NIPC APIs. NIPC APIs consist of reading or writing properties of devices, performing actions on devices, as well as enabling or disabling events on devices. In order to perform NIPC operations on a device, 2 prerequisites must be fulfilled: - The device must be onboarded on the gateway. Onboarding declares a device instance to the gateway. This allows the NIPC Gateway to retrieve the device object, identified by an id referenced in the path of the NIPC API. The definition of the onboarding function is out of scope of this document, but can be provided by a provisioning interface such as leveraging . - An interaction model for the class of devices must be registered with the gateway. This allows the gateway to understand how to interact with the device in a protocol-neutral way. The interaction model is provided to the gateway by means of an SDF model, described in . A non-IP gateway provides following functions: Authentication and authorization of application clients that will leverage the gateway API to communicate with Non-IP devices. Access to a database of onboarded devices. The ability to consume an interaction model for a class of devices. An API that allows for reading or writing properties of devices, performing actions on devices, as well as enabling or disabling events on devices. The ability to manage connections to Non-IP devices, either implicitly when performing a NIPC operation, or explicitly by means of a connection management API. The ability to stream events from Non-IP devices to applications on the IP network by means of a publish/subscribe interface. One or more channels to process requests, responses, and asymmetric communications with the non-IP radio resources (Access Points) at its disposal. The Application gateway is a network function, so its goal is to proxy payloads between Non-IP and IP networks. It is not intended to be a middleware function that interprets, decodes or modifies these payloads.

| SCIM | | | app |<--------------+ Server | | +-----------+ Ctrl Endpt| +---------+ | | | +-----------+ | +------------+ +-------+ +--------+ | | Control +----REST------>| NIPC +-->| AP +-->| Device | | | & | | | Gateway | +-------+ +--------+ | | Telemetry |<--pub/sub-----+ | | | Apps | | +------------+ | +-----------+ | | | Network Deployment | +------------------------------------------+ ]]>

shows us applications, the NIPC 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 supports 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 application layer gateway is to provide a gateway function to applications wishing to communicate with non-IP devices in the network domain served by the gateway. Applications implementing Non-IP Control can leverage RESTful interfaces to communicate with Non-IP devices in the network domain and subscribe to events leveraging a CBOR-based pub/sub 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 when, and only when, they appear in all capitals, as shown here.

Glossary NIPC: Non-IP Control, the application layer interface defined in this document. NIPC Gateway: An application layer gateway that implements the NIPC interface. SDF: Semantic Device Format, a standardized format to describe devices and their interaction models, as defined in . SDF Affordance: An interaction point on a device as defined in an SDF model. Examples of affordances are properties, actions & events. SDF Global Name: Absolute URI (with fragment) identifying an SDF affordance. SCIM: System for Cross-domain Identity Management, a standardized protocol to manage identity information, as defined in . ALG: Application Layer Gateway. Non-IP Device: Device using a non-IP protocol (e.g. BLE, Zigbee) requiring a gateway for IP interaction. Protocol Mapping / sdfProtocolMap: Mapping from protocol-neutral SDF affordances to protocol-specific operations. BLE: Bluetooth Low Energy protocol. Zigbee: Low-power mesh networking protocol. GATT: Generic Attribute Profile used in BLE for services/characteristics/descriptors. Service (BLE): Top-level GATT grouping of characteristics. Characteristic (BLE): GATT data element supporting read/write/notify. Descriptor (BLE): Metadata element attached to a characteristic. Bonding (BLE): Procedure to establish trusted, reusable security keys. Service Discovery (BLE): Procedure to enumerate GATT services/characteristics/descriptors. Device Onboarding: Registration of a device identity and metadata before NIPC operations. Device ID / Group ID: UUID identifying a device or a group of devices. UUID: Universally unique identifier (128-bit). Data Application / Data App: Registered application receiving streamed event data. MQTT: Publish/subscribe messaging protocol used for streaming. Webhook: HTTP callback endpoint for push delivery. Websocket: Bidirectional TCP-based message channel over HTTP. Publish/Subscribe Interface: Streaming channel for events (CBOR-encoded payloads). CBOR: Concise Binary Object Representation; compact binary data format. CDDL: Concise Data Definition Language; schema language for CBOR data. JSON: JavaScript Object Notation; text encoding used for API payloads. Access Point (AP): Network element with non-IP radio interface communicating with devices.

Architecture

Overview 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 provides a unified API to support those operations. To perform NIPC operations on a device, the gateway has 2 prerequisites: Information about the instance of the device or thing: The device must be onboarded on the gateway (e.g. by means of SCIM with ). This allows the NIPC Gateway to retrieve the device object, identified by an ID referenced in the path of the NIPC API. Information about the interaction model: The Gateway must be able to perform protocol-neutral operations, and hence requires a mapping of protocol-neutral operations to protocol specific operations. These are supplied to the gateway by means of an SDF model, described in .

| | +------------+ | NIPC Operation | | - Property | | - Action | +------------+ | - Event | | SDF +---------->| | | model | +----------------+ +------------+ ]]>

Once these 2 prerequisites have been fulfilled, applications that are authorized can perform NIPC operations on device IDs. Please review for more information on authorization. NIPC operations are operations on properties, or constitute actions or events on devices, as per the affordances defined in an SDF model.

Onboarding In order to perform a NIPC operation on a device, the device has to have its identity declared to the NIPC gateway. We refer to this as 'onboarding'. Apart from the device identity, it is also necessary that the device object contains all required information to bootstrap trust with the device, as well as establish connectivity, as NIPC operations assume that connectivity can be set up without explicitly calling an API. Although onboarding could theoretically be performed in different ways, it is strongly recommended to leverage with , as the SCIM device schema has been developed to contain all necessary attributes and extensions to support NIPC.

Registrations NIPC registration APIs allow applications to declare information about a device class, or an application authorization. These APIs do not perform any operations on a specific device. NIPC supports 2 types of registrations: - Registering an SDF model for a class of devices. - Registering an authorization for a data application. This authorizes an application to receive streaming event data from devices. Optionally a pointer to the model and the data-app registration can be included in the SCIM object for the device. See and for more information.

SDF model registrations The SDF model for a class of devices determines how a gateway may interact with these devices in a protocol-neutral way. In order to do that, the SDF model must contain protocol mappings, mapping protocol-neutral SDF affordances to protocol-specific ones as defined in . The SDF affordances supported by the device, as well as its protocol-mappings, are provided to the gateway by means of an SDF model registration. SDF models are described in .

Data application registrations An application authorized to perform NIPC operations on devices needs to be able to define which applications can receive streaming event data from the gateway. The data-app registrations API allows mapping of an event to a data app as well as a protocol.

NIPC Operations NIPC operations are protocol-neutral operations on SDF affordances, more specifically properties, actions & events. NIPC operations can happen against affordances that were registered in an SDF model. If connection management is required to execute a NIPC operation, it is assumed that the gateway implicitly establishes and tears down required connections. The NIPC APIs that perform NIPC operations are organized in 3 main categories: Properties APIs: These APIs allow applications to perform operations on properties, such as to read or write values to them. Actions APIs: These APIs perform actions on devices, such as enabling or disabling a feature on a device. Events APIs: These APIs allow apps to enable or disable event reporting on devices. Events are reported over the events publish/subscribe interface.

Connection management for NIPC Operations For protocols that require connection management before executing an operation, a NIPC gateway will perform implicit connection management. When executing a NIPC operation, a NIPC Gateway can set up a connection with a device as well as tear down the connection after the operation has completed. A NIPC Gateway may support explicit connection management as well. Explicit connection management can be used by an app that wants to perform multiple NIPC operations in a single connection. Explicit connection management can be performed by calling the APIs in . After establishing an explicit connection to a device, an application calls a NIPC Operation, the Gateway will leverage the existing connection and will also not tear the connection down after the operation completes. The app will have to explicitly close the connection.

Extensions NIPC is extendable as a NIPC gateway may want to provide a way to execute a complex set of NIPC operations in a single API call, or may want to perform an operation that can deliver an outcome more efficiently than a NIPC API. An example of an extension that uses compound operation is the bulk API. Extensions must leverage the /extensions path element. In order to assure inter-operability, extensions must be IANA registered in the registry in .

Events publish subscribe interface Events are published on a publish/subscribe interface. Events can be of different types: Streaming data from devices: Streaming data is activated/deactivated with the NIPC events API Broadcasts from devices Connection events: Devices connecting & disconnecting

Protocols

NIPC APIs NIPC is a protocol that is based on RESTful HTTP . Along with HTTP headers and URIs, NIPC uses JSON payloads to convey NIPC operations, such as registrations, actions, event and property operations. This is the case for both request and response parameters, as well as errors. NIPC uses the JSON media type "application/nipc+json" that is registered in , except for the SDF model registrations APIs, where the media type reflects the content as an SDF model, and hence is media type "application/sdf+json". The NIPC property APIs also support the use of other media types to describe the content of the property.

NIPC publish/subscribe events NIPC publish/subscribe events are encoded in CBOR () and can be delivered over either: MQTT Webhook Websocket CBOR was selected for the publish/subscribe interface as Non-IP payloads are typically binary. CBOR encodes binary payloads efficiently, and is more compact than JSON, therefore reducing the amount of data that needs to be transmitted to the application.

Paths

General The NIPC HTTP protocol is described in terms of a path relative to a Base URI. The Base URI MUST NOT contain a query string, as clients MAY append additional path information and query parameters as part of forming the request. The base URI is a URL that most often consists of the "https" protocol scheme, a domain name, and an initial path . That initial path for NIPC is recommended to be /nipc. For example:

Additionally a version number may be added, for example:

After the base or version number, the path must contain a collection identifier. The collection identifier can be one of the following: /registrations: for NIPC registration APIs /devices: for NIPC operations on devices /groups: for NIPC operations on groups of devices /extensions: for NIPC extension APIs The well-known URI /.well-known/nipc defined in can be used to discover the base path of the NIPC APIs and the supported versions and extensions. The response to a GET request on this URI MUST be a JSON document that contains the base path, and optionally the supported versions and
extension APIs. The paths MUST be a URI template as defined in . The following is an example of a template defining the NIPC base path as well as supported extensions on a server.

A formal CBOR definition of the well-known response is as follows:

NIPC Registrations Registrations leverage the base path + /registrations. NIPC supports SDF model registrations and data-app registrations. paths: /registrations/models /registrations/data-apps

NIPC Operations Every NIPC Operations API pertains to either a device or group of devices, identified by an ID, hence the ID will be reflected as the first parameter in the path. For example:

The second parameter in the path refers to the NIPC operation that the API will perform on the device. This can be: properties events actions extensions These are described in .

Schema The NIPC schema leans heavily on the SDF schema, as defined in . NIPC operations map directly to SDF affordances.

SDF model registrations In order to perform a NIPC operation on a device, an SDF interaction model needs to be declared that provides protocol mappings for the SDF affordances the operations will be performed on. The SDF model can be registered by means of a registrations API POST with the SDF model in the body of the request. A registered SDF model can be fetched by a registrations API GET with an sdfReference.

NIPC Operations NIPC operations require 2 key parameters: 1) A device ID identifying the device the operation should be executed on 2) an SDF name for the SDF affordance the operation pertains to

Device ID All NIPC operations are executed against a device or a group of devices. Devices or groups of devices are identified by a unique UUID, adhering to the . Attribute Type Example id uuid 12345678-1234-5678-1234-56789abcdef4 ID is the unique UUID of the device. This ID is generated when onboarding the device, for example by a SCIM server. This identifier is returned to the application. As such, this ID is a common identifier, known both to the application as well as the NIPC Server. If the server is not collocated with the SCIM server, the NIPC server will have to retrieve the device object from the SCIM server by means of the ID.

SDF Name NIPC operations happen against SDF affordances and are referenced with an global sdfName, which is the full path including the namespace. The operations are either Properties, Events or Actions and their references are of type string For example: NIPC Operation Example SDF Name used in the API Property https://example.com/heartrate#/
sdfObject/thermostat/sdfProperty/temperature Event https://example.com/heartrate#
/sdfObject/healthsensor/sdfEvent/fallDetected Action https://example.com/heartrate#/
sdfObject/thermostat/sdfAction/resetThermostat

Responses A NIPC Gateway will respond to a NIPC operation request synchronously, and provide the result of the completed operation in the HTTP response. The exception to the above are NIPC extensions, . These contain compound statements, and thus require the gateway to execute multiple NIPC operations. In this case the NIPC gateway will return HTTP status code 202 after receiving the request and verifying it is able to execute it. The client can then perform an HTTP GET of the extensions API to get the execution status for the request. If a callback URL address was defined in the request, the NIPC Gateway can optionally perform a callback with a response to the compound request after the compound statement completes. Actions also follow an asynchronous pattern, returning HTTP status code 202 when the action is accepted, along with a Location header pointing to the action instance for status tracking. A failure response will consist of a HTTP status code of 4xx or 5xx, and will follow the Problem Details format with application/problem+json media type. The response will contain a type field with a URI identifying the error type, and a human-readable detail field. The type field is a URI and is described in . Failure response: Example of a failure response:

where- "type" is a URI identifying the specific error type "status" is the HTTP status code "title" is a brief, human-readable summary of the error type "detail" is a human-readable explanation specific to this occurrence

NIPC Registrations NIPC allows an application to register an SDF model for a class of devices, as well as a data application that will receive streaming data from the gateway.

SDF model registrations APIs These APIs allow applications to register an SDF model for a class of devices. These APIs use the application/sdf+json media type, as described in .

Register an SDF model Method: POST /registrations/models Description: Registers one or more SDF models for a class of devices Request Body: an SDF document in JSON format containing one or more sdfThings or sdfObjects, similar to the example in . Response: Example of a response:

where- "sdfName" is the name of the top-level sdfThing or sdfObject in the SDF model The sdfName in the response is wrapped in an object to allow for future extensions to the response.

Get all SDF models Method: GET /registrations/models Description: Gets all SDF models registered with the gateway Response: Example of a response:

where- "sdfName" is the name of the top-level sdfThing or sdfObject in the SDF model

Get an SDF model Method: GET /registrations/models{?sdfName} Description: Gets an SDF model registered with the gateway Query Parameters: sdfName: the name of the top-level sdfThing or sdfObject in the SDF model. Response: The SDF model is returned in JSON format, similar to the example in .

Delete an SDF model Method: DELETE /registrations/models{?sdfName} Description: Deletes an SDF model registered with the gateway Query Parameters: sdfName: the name of the top-level sdfThing or sdfObject in the SDF model. Response: Example of a response:

where- "sdfName" is the name of the top-level sdfThing or sdfObject in the SDF model

Update an SDF model Method: PUT /registrations/models{?sdfName} Description: Updates an SDF model registered with the gateway Query Parameters: sdfName: the name of the top-level sdfThing or sdfObject in the SDF model. Request Body: an SDF model in JSON format, similar to the example in . Response: Example of a response:

where- "sdfName" is the name of the top-level sdfThing or sdfObject in the SDF model

Data application registrations APIs These APIs allow applications to register a data application that will receive streaming data from the gateway. These APIs operate on a data app ID. This ID corresponds to the endpoint app ID of the telemetry endpoint app that is registered with the SCIM server. The endpoint app is defined in . Apart from the endpoint app ID, the API also registers the protocol the data-app supports. These can be one of the following: mqttClient: The data-app is an MQTT client, which means that the gateway is an MQTT broker. mqttBroker: The data-app is an MQTT broker. The registration API has to include the MQTT broker configuration data, such as the URI, credentials and MQTT topic to publish to. webhook: The data-app supports a webhook the gateway can publish to. The registration API has to include the webhook URI & credentials. websocket: The data-app supports a websocket interface. The registration API has to include the websocket URI & credentials.

Register a data application Method: POST /registrations/data-apps{?dataAppId} Description: Registers a data application with the gateway Query Parameters: dataAppId: the ID of the data application Request Body: events: a list of events that the data application wants to receive streaming data for. The request body also contains one of the following: mqttClient: a boolean that denotes that the data application is an MQTT client that will receive streaming data over MQTT mqttBroker: an object that contains the MQTT broker information where the broker will publish the streaming data. URI: the URI of the MQTT broker. username: the username to authenticate with the MQTT broker password: the password to authenticate with the MQTT broker brokerCACert: the base64-encoded CA certificate of the MQTT broker (optional) customTopic: By default, the topic will be composed of data-app/<dataAppId>/<namespace>/<json_pointer_to_sdf_event>, as described in . You can configure a custom topic to publish the streaming data to (optional) webhook: an object that contains a webhook URL along with any credentials that are required to authenticate the webhook. The webhook URL is the endpoint where the streaming data will be sent. URI: the webhook URL. The URL MUST include the scheme used by the webhook server (e.g., "https://"). It is up to the implementation to support different schemes. If a scheme is not supported, the NIPC gateway MUST return an error response with type "https://www.iana.org/assignments/nipc-problem-types#unsupported-uri-scheme". headers: An object that contains the headers to be sent with the webhook request. The headers can contain any authentication information required by the webhook server. Each header is represented as a key-value pair in the object. serverCACert: the CA certificate of the webhook server, encoded as per and newlines encoded as '\n' (optional) websocket: an object that contains a websocket URL along with any credentials that are required to authenticate the websocket. The websocket URL is the endpoint where the streaming data will be sent. URI: the websocket URL. The URL MUST include the scheme used by the websocket server (e.g., "wss://"). It is up to the implementation to support different schemes. If a scheme is not supported, the NIPC gateway MUST return an error response with type "https://www.iana.org/assignments/nipc-problem-types#unsupported-uri-scheme". headers: An object that contains the headers to be sent with the websocket request. The headers can contain any authentication information required by the websocket server. Each header is represented as a key-value pair in the object. serverCACert: the CA certificate of the websocket server, encoded as per and newlines encoded as '\n' (optional) Example of a request body:

Example of a request body for a data application that is an MQTT broker:

Response: If successful, the response will be identical to the request body.

Update a data application Method: PUT /registrations/data-apps{?dataAppId} Description: Updates a data application with the gateway Query Parameters: dataAppId: the ID of the data application Request Body: Same as the request body for the register data application API. Response: If successful, the response will be identical to the request body.

Get a data application Method: GET /registrations/data-apps{?dataAppId} Description: Gets a data application registered with the gateway Query Parameters: dataAppId: the ID of the data application Response: The response will be identical to the request body for the register data application API.

Delete a data application Method: DELETE /registrations/data-apps{?dataAppId} Description: Deletes a data application registered with the gateway Query Parameters: dataAppId: the ID of the data application Response: The response will be identical to the request body for the register data application API.

NIPC APIs The primary goal of the NIPC APIs is to perform operations on SDF Affordances, such as properties, events & actions.This allows a user of the NIPC API to get or update properties of devices, perform actions on devices, and consume events from devices. The NIPC APIs consist of three main collections which reflect SDF Affordances as defined in : NIPC Property APIs: These APIs allow applications to get and update device properties. NIPC Event APIs: These APIs allow applications to enable or disable event reporting on devices. NIPC Action APIs: These APIs allow applications to perform actions on devices. One or more SDF models must be registered in order to use these NIPC Property, Event and Action APIs. The SDF models can be a top-level sdfThing with multiple sdfObjects or a top-level sdfObject. These APIs depend on the SDF affordances (i.e. sdfProperty, sdfEvent and sdfAction) defined in the SDF model and a device ID that is defined in . An SDF affordance can be referenced using the global name of the SDF affordance as described in . The SDF global name will be used against the registered SDF model to determine the protocol-specific protocolmap that the NIPC API will operate on. The SDF global name is also percent-encoded as per .

NIPC Property APIs These APIs allow applications to get and update device properties. These operations may require a connection to the device to be established. This connection can be established as part of the same API call implicitly. If a connection is already active for this device, the existing connection will be leveraged without modifying it. These APIs support multiple media types based on Content-Type and Accept headers to accommodate different data formats. When using application/nipc+json, the request and response bodies follow the format shown in the examples above, with binary data encoded as base64 in the "value" field. For other content types, the data is transmitted according to the specific format requirements of that media type.

Write multiple values Method: PUT /devices/{id}/properties{?propertyName} Description: Write values to one or more properties on a device Parameters: id: the ID of the device Query Parameters: propertyName: a single property to update. If this parameter is provided, the request body can contain any content type payload with the value to write to the property. If this parameter is not provided, the request body MUST contain an application/nipc+json payload with an array of properties to update, each containing a property and a value. Request Body: If the query parameter propertyName is provided, the request body can contain any content type payload with the value to write to the property. The value is encoded as per the content type of the payload. or an array of properties to update, each containing a property and a value. The value is the raw binary data, encoded in base64 with padding as per . Example body updating multiple properties:

Response: If the Accept header is set to application/nipc+json, the response will be an array with a status field set to 200 for each property that was updated, or a problem type object for each property that failed to update. If the Accept header is set to any other media type and the propertyName query parameter is provided, the response will be 204 No Content with no body. Example of a response:

where- "properties" is an array of properties that were updated, each containing a property and a value A failure will generate a standard failed response. Please refer to definition of failed response.

Read multiple values Method: GET /devices/{id}/properties{?propertyName*} Description: Read values from one or more properties on a device Parameters: id: the ID of the device Query Parameters: propertyName: The property to read. This can be a single property or multiple properties. If multiple properties are provided, the request body MUST contain an application/nipc+json payload with an array of properties to read. Response: If the Accept header is set to application/nipc+json, the response will be an array of properties, each containing a property and a value. The value is the raw binary data read from the property, encoded in base64 with padding as per . Example of a response:

where- "property" is the property that was read from "value" is the bytes that were read in base64 encoding A failure will generate a standard failed response. Please refer to definition of failed response.

NIPC Event APIs These APIs allow applications to enable or disable event reporting on devices. These operations may require a connection to the device to be established. This connection can be established as part of the same API call implicitly. If a connection is already active for this device, the existing connection will be leveraged without modifying it. The event is the global name of an sdfEvent. The ID in the path is the ID of the device or group of devices. An event can be enabled on a group of devices if it is supported by the underlying protocol. For example, if the underlying protocol is BLE, the event can be enabled on a group of devices if the event is an advertisement event or connection status event. If the data application registered for this event is an MQTT broker or client, the event is used to construct the MQTT topic for the event. The topic is constructed using the data application ID, the default namespace for the event, and the event itself. For example, if the data application ID is "12345678-1234-5678-1234-56789abcdef4" and the event is "https://example.com/thermometer#/sdfThing/thermometer/sdfEvent/isPresent", the topic will be:

// data-app/12345678-1234-5678-1234-56789abcdef4/thermometer/sdfThing/\ thermometer/sdfEvent/isPresent ]]>

A data application can subscribe to this topic using the topic or it can use MQTT wildcards to subscribe to data-app/+/temperature/# to receive all events for the temperature namespace. If a custom topic is provided for an MQTT broker, the custom topic is used as the MQTT topic instead.

Enable event reporting Method: POST /devices/{id}/events{?eventName} Description: Enables an event on a specific device Parameters: id: the ID of the device Query Parameters: eventName: the event to enable The eventName is a URL encoded string that is the absolute URI that is the global name of an sdfEvent. Response: Returns HTTP status code 201 Created with a Location header pointing to the created event instance. Example of a successful response:

The Location header contains the URI for the created event instance, which can be used to check status or disable the event. A failure will generate a standard failed response. Please refer to definition of failed response.

Disable event reporting Method: DELETE /devices/{id}/events{?instanceId} Description: Disables an event on a specific device Parameters: id: the ID of the device or group of devices Query Parameters: instanceId: the instance ID of the event to disable (obtained from the Location header when the event was enabled) Response: Returns HTTP status code 204 No Content on successful disable.

A failure will generate a standard failed response. Please refer to definition of failed response.

Get status of one or more events Method: GET /devices/{id}/events{?instanceId*} Description: Get the status of one or more events on a specific device Parameters: id: the ID of the device or group of devices Query Parameters: instanceId: a comma separated list of event instance IDs to filter by (optional) Response: Example of a response:

where- "instanceId" is the unique instance ID for each enabled event "event" is the event URI for each enabled event A failure will generate a standard failed response. Please refer to definition of failed response.

Enable event reporting on a group of devices Method: POST /groups/{id}/events Description: Enables an event on a group of devices Parameters: id: the ID of the group of devices Query Parameters: eventName: the event to enable The eventName is a URL encoded string that is the absolute URI that is the global name of an sdfEvent. Response: Returns HTTP status code 201 Created with a Location header pointing to the created event instance. Example of a successful response:

The Location header contains the URI for the created event instance, which can be used to check status or disable the event. A failure will generate a standard failed response. Please refer to definition of failed response.

Disable event reporting on a group of devices Method: DELETE /groups/{id}/events{?instanceId} Description: Disables an event on a group of devices Parameters: id: the ID of the group of devices Query Parameters: instanceId: the instance ID of the event to disable (obtained from the Location header when the event was enabled) Response: Returns HTTP status code 200 with a list of the event status for the group of devices. If the event was successfully disabled on a device, the response will contain the device ID and SDF event name for that device. If the event could not be disabled on a device, the response will contain a problem type error response for that device.

A failure will generate a standard failed response. Please refer to definition of failed response.

Get event status on a group of devices Method: GET /groups/{id}/events{?instanceId} Description: Get the status of one or more events on a group of devices Parameters: id: the ID of the group of devices Query Parameters: instanceId: The instance ID of the event to get the status for Response: Returns HTTP status code 200 with a list of the event status for the group of devices. If the event was successfully enabled on a device, the response will contain the device ID and SDF event name for that device. If the event could not be enabled on a device, the response will contain a problem type error response for that device. Example of a response:

where- "instanceId" is the unique instance ID for each enabled event "event" is the event URI for each enabled event A failure will generate a standard failed response. Please refer to definition of failed response.

NIPC Action APIs These APIs allow applications to perform actions on devices. These operations may require a connection to the device to be established. This connection can be established as part of the same API call implicitly. If a connection is already active for this device, the existing connection will be leveraged without modifying it.

Perform an action Method: POST /devices/{id}/actions{?actionName} Description: Perform an action on a specific device Parameters: id: the ID of the device Query Parameters: actionName: the action to perform Request Body: The request body is optional and may contain a value. The media type of the value can be defined by the underlying protocol, for example it could be octet-stream for binary data. Response: Actions are performed asynchronously. A successful request returns HTTP status code 202 Accepted with a Location header pointing to the action instance for status checking. Example of a successful response:

The Location header contains the URI for the action instance, which can be used to check the action status.

Check action status Method: GET /devices/{id}/actions{?instanceId} Description: Check the status of an action on a specific device Parameters: id: the ID of the device Query Parameters: instanceId: the instance ID of the action (obtained from the Location header) Response: Example of a response:

where "status" indicates the current state of the action (e.g., "IN_PROGRESS" or "COMPLETED"). A failure will generate a standard failed response. Please refer to definition of failed response.

NIPC explicit connections management APIs Many protocols do not require connection management, so for these protocols, these APIs will not apply. NIPC Gateways perform implicit connection management for protocols that require connection management (such as BLE), so in principle the user of the NIPC API does not have to perform connection management. In some cases however, a user might want to keep a connection open, perform an action, evaluate the result and perform a second action based on that result. In this case it is useful to perform explicit connection management so the connection remains established to execute subsequent actions. These APIs allow applications to explicitly manage device connections. The examples in this section will be based on BLE, which requires connection management.

Connect to a device Method: POST /devices/{id}/connections Description: Connect to a device Parameters: id: the ID of the device Request Body: Connection retry parameters A protocol map object. In the case of BLE, if no protocol map 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 discovery can be buffered across connections, so the API also supports caching parameters. Example body of a connection without specific discovery of properties:

where- "retries" defines the number of retries in case the operation 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 mapping 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 (in seconds) 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 a protocol mapping 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 characteristics, which in turn contains an array of descriptors, as shown in .

characteristics - characteristicID - flags | |> Descriptors - descriptorID ]]>

Example of a response:

where- "id" is the ID of the device "sdfProtocolMap" contains an Array of BLE services as shown in A failure will generate a standard failed response. Please refer to definition of failed response.

Update a connection Method: PUT /devices/{id}/connections Description: Update cached ServiceMap for a device. Full service discovery will be performed, unless specific services are described in the API body. Parameters: id: the ID of the device Request Body: A protocol map object. In the case of BLE, if no protocol map 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 discovery can be buffered across connections, so the API also supports caching parameters. Example body of an update connection:

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) Response: Success responses include a protocol mapping 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 characteristics, which in turn contains an array of descriptors, as shown in . Example of a response:

where- "id" is the ID of the device "sdfProtocolMap" contains an Array of BLE services as shown in A failure will generate a standard failed response. Please refer to definition of failed response.

Disconnect from a device Method: DELETE /devices/{id}/connections Description: Disconnect from a device Parameters: id: the ID of the device Response: Returns HTTP status code 200 OK with device ID on successful disconnect. Example of a response:

where "id" is the ID of the device. A failure will generate a standard failed response. Please refer to definition of failed response.

Get connection status Method: GET /devices/{id}/connections Description: Get connection status for a device. Success when device(s) is/are connected, includes service map for the device if available. Failure when a device is not connected. Parameters: id: the ID of the device Response: Example of a response:

where- "id" is the ID of the device "sdfProtocolMap" contains an Array of BLE services as shown in A failure will generate a standard failed response. Please refer to definition of failed response.

NIPC Extensibility 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.

Protocol extensions NIPC supports mapping protocol specific properties to NIPC properties as described in . BLE and Zigbee are used as examples, but protocol mapping is extensible to other protocols, so now non-IP protocols can be supported by NIPC without a schema change. The protocol objects need to be extended with the new protocol as well. Protocol objects will be extended as follows: Attribute Type Example ble object an object with BLE-specific properties zigbee object an object with Zigbee-specific properties newProtocol object an object with newProtocol-specific props In the new protocol object, protocol specific properties can be added.

API extensions /extensions The extension APIs allow for extensibility of the APIs. Extensions must be IANA registered. Extension APIs can leverage the basic NIPC defined APIs and combine them in compound statements in order to streamline application operation against devices, make operations more expedient and convenient in one API call. An example of this is the bulk API extension. They can also introduce new functionality that is specific to a use case or protocol, such as the BLE transmit API. the OpenAPI model below, we have defined a few example extensions. The extensions can contain long running operations, such as firmware updates, or other bulk operations that can be performed on a device. For long running operations, the extension API will return a 202 Accepted status code and a location header with the URL to check the status of the operation. The status of the operation can be checked by calling the status extension API with the same device ID. The status extension API will return a 200 OK status code when the operation is in progress. When the operation is complete, the status extension API will return a 303 See Other status code with a location header with the URL to check the status of the operation. The GET operation on the extension API will return a 200 OK status code with the actual response once the operation is complete.

NIPC Error Handling The error types in the NIPC APIs use URI-based error type identifiers as defined in . The error types can be generic or specific to the API category. The error types are organized into the following categories: Generic: Broadly applicable errors, including authorization, invalid identifiers, and generic failures. Property APIs: Errors related to property APIs (read/write). Event APIs: Errors related to event APIs (enable/disable). Protocol specific: Errors related to protocol-specific operations. Extension APIs: Errors related to extension APIs. The specific error types are defined in the table below: Error Type Description Category invalid-id Invalid device ID or gateway doesn't recognize the ID Generic invalid-sdf-url Invalid SDF URL or SDF affordance not found Generic extension-operation-not-executed Operation was not executed since the previous operation failed Generic sdf-model-already-registered SDF model already registered Generic sdf-model-in-use SDF model in use Generic unsupported-uri-scheme Unsupported URI scheme Generic property-not-readable Property not readable Property APIs property-not-writable Property not writable Property APIs event-already-enabled Event already enabled Event APIs event-not-enabled Event not enabled Event APIs event-not-registered Event not registered for any data application Event APIs protocolmap-ble-already-connected Device already connected Protocol specific protocolmap-ble-no-connection No connection found for device Protocol specific protocolmap-ble-connection-timeout BLE connection timeout Protocol specific protocolmap-ble-bonding-failed BLE bonding failed Protocol specific protocolmap-ble-connection-failed BLE connection failed Protocol specific protocolmap-ble-service-discovery-failed BLE service discovery failed Protocol specific protocolmap-ble-invalid-service-or-characteristic Invalid BLE service or characteristic ID Protocol specific protocolmap-zigbee-connection-timeout Zigbee connection timeout Protocol specific protocolmap-zigbee-invalid-endpoint-or-cluster Invalid Zigbee endpoint or cluster ID Protocol specific extension-transmit-invalid-data Invalid transmit data Transmit APIs extension-firmware-rollback Firmware rollback Extension APIs extension-firmware-update-failed Firmware update failed Extension APIs The appropriate HTTP status code is returned in the response.

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 /registrations/data-apps API. In this memo, we propose the data format to be CBOR .

CDDL Definition We have a CDDL 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. Each MQTT message can be a collection of DataSubscription structs. This collection is represented as DataBatch in the CDDL.

CBOR Examples This section contains a few examples of the DataSubscription struct depicted in CBOR diagnostic notation.

Examples This section contains a few examples on how applications can leverage NIPC operations to communicate with BLE and Zigbee devices.

Property Read/Write In this example, we will connect to a device 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) Register an SDF model for the device

Request Body: JSON object with the SDF model, from Read a property from the BLE device

Write to a property on the BLE device

Enabling an Event on a Device In this example, we will onboard a device, and setup an advertisement subscription event for that device. The sequence of operations for this are: Onboard a device and endpoint app using the SCIM Interface (out of scope of this memo) Register an SDF model for the device

Request Body: JSON object with the SDF model, from Register the data app with the event

Enable the advertisement event

Check the status of the event

Enabling an Event on a Group of Devices In this example, we will enable an advertisement subscription event for a group of devices. The sequence of operations for this are: Onboard devices and endpoint app using the SCIM Interface (out of scope of this memo) Register an SDF model for the devices

Request Body: JSON object with the SDF model, from Register the data app with the event

Enable the advertisement event on a group of devices

Check the status of the event

Security Considerations

API authorization 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: Onboarding: Authorize an onboarding application against a SCIM server co-located with the gateway. Control: Authorize applications that may control devices. Data: Authorize applications that may receive telemetry.
It is possible to further refine roles down to an API basis.

IANA Considerations This section provides guidance to the Internet Assigned Numbers Authority (IANA) regarding registration of values related to NIPC, in accordance with .

Media Type Registration This document registers the "application/nipc+json" media type for messages of the NIPC APIs defined in this document carrying parameters encoded in JSON. Type name: application Subtype name: nipc+json Required parameters: none Optional parameters: none Encoding considerations: Encoding considerations are identical to those specified for the "application/json" media type. Security considerations: See the section of this document. Interoperability considerations: none Published specification: This document, the NIPC API specification. Applications that use this media type: Fragment identifier considerations: none Additional information: Deprecated alias names for this type: none Magic number(s): none File extension(s): none Macintosh file type code(s): none Person & email address to contact for further information: Intended usage: LIMITED USE Restrictions on usage: To be used for NIPC APIs as defined in this document. Author: Change controller: IETF

API extensions IANA is requested to create a new registry called "NIPC API extensions". The registry must contain following attributes: Extension URI Extension name Description Openapi model describing the extension. This model must be reviewed by an expert. Following API extensions are described in this document: Extension URI Extension name Description Model reference /extensions/{id}/bulk Bulk API Call multiple NIPC's in a single request /extensions/{id}/properties/file File write API Write a file with multiple property ops /extensions/{id}/properties/blob Binary write API Write a binary blob with multiple property ops /extensions/{id}/properties/read/conditional Read conditional API Read a property until a condition is fulfilled /extensions/{id}/events/conditional Event conditional API Enable an event until a condition is fulfilled /extensions/{id}/transmit Transmit API Transmits a payload to a device

Well-known URIs IANA is requested to register the following well-known URI in the "Well-Known URIs" registry as defined by : URI Suffix Change Controller Specification Document nipc IETF This document, The well-known URI for NIPC is:

Problem Details for NIPC APIs IANA is requested to create a new registry, the "NIPC Problem Type" registry, with following URL: . Registrations MUST use the prefix for the type URI. The registration requests MUST use the template defined in . IANA is requested to register the following URIs in the "NIPC Problem Type" registry: Problem Type URI Description Reference https://www.iana.org/assignments/nipc-problem-types#invalid-id Invalid device ID or gateway doesn't recognize the ID This document https://www.iana.org/assignments/nipc-problem-types#invalid-sdf-url Invalid SDF URL or SDF affordance not found This document https://www.iana.org/assignments/nipc-problem-types#extension-operation-not-executed Operation was not executed since the previous operation failed This document https://www.iana.org/assignments/nipc-problem-types#sdf-model-already-registered SDF model already registered This document https://www.iana.org/assignments/nipc-problem-types#sdf-model-in-use SDF model in use This document https://www.iana.org/assignments/nipc-problem-types#unsupported-uri-scheme Unsupported URI scheme This document https://www.iana.org/assignments/nipc-problem-types#property-not-readable Property not readable This document https://www.iana.org/assignments/nipc-problem-types#property-read-failed Property read failed This document https://www.iana.org/assignments/nipc-problem-types#property-not-writable Property not writable This document https://www.iana.org/assignments/nipc-problem-types#property-write-failed Property write failed This document https://www.iana.org/assignments/nipc-problem-types#event-already-enabled Event already enabled This document https://www.iana.org/assignments/nipc-problem-types#event-not-enabled Event not enabled This document https://www.iana.org/assignments/nipc-problem-types#event-not-registered Event not registered for any data application This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-already-connected Device already connected This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-no-connection No connection found for device This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-connection-timeout BLE connection timeout This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-bonding-failed BLE bonding failed This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-connection-failed BLE connection failed This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-service-discovery-failed BLE service discovery failed This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-ble-invalid-service-or-characteristic Invalid BLE service or characteristic ID This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-zigbee-connection-timeout Zigbee connection timeout This document https://www.iana.org/assignments/nipc-problem-types#protocolmap-zigbee-invalid-endpoint-or-cluster Invalid Zigbee endpoint or cluster ID This document https://www.iana.org/assignments/nipc-problem-types#extension-broadcast-invalid-data Invalid transmit data This document https://www.iana.org/assignments/nipc-problem-types#extension-firmware-rollback Firmware rollback This document https://www.iana.org/assignments/nipc-problem-types#extension-firmware-update-failed Firmware update failed This document Each Problem Type URI is intended for use as the "type" member in Problem Details responses as described.

&RFC7644; &I-D.ietf-scim-device-model; &I-D.ietf-asdf-sdf; &RFC2119; &RFC8174; &I-D.ietf-asdf-sdf-protocol-mapping; &RFC9114; &RFC7159; &RFC8949; &RFC3986; &RFC6570; &RFC9562; &RFC9457; &RFC7468; &RFC4648; &RFC8610; &RFC8126; &RFC8615; Bluetooth SIG Connectivity Standards Alliance Bluetooth SIG

OpenAPI definition The following non-normative model is provide for convenience of the implementor.

file "openapi.yml" =============== NOTE: '\\' line wrapping per RFC 8792 =============== # yaml-language-server: $schema=https://json-schema.org/draft/2020-1\ \2/schema openapi: 3.0.3 info: title: Non IP Device Control (NIPC) API description: |- This API specifies RESTful application layer interface for gateways providing operations against non-IP devices. The described interface is extensible. The examples includes leverage Bluetooth Low Energy and Zigbee as they are commonly deployed. termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.14.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ servers: - url: "{gw_host}/nipc/draft-14" variables: gw_host: default: localhost description: Gateway Host tags: - name: NIPC property APIs description: |- APIs that allow apps to get and update device properties. If the underlying protocol requires connection management, it will be performed as part of the API call. - name: NIPC event APIs description: |- APIs that allow apps to enable or disable event reporting on devices. If the underlying protocol requires connection management, it will be performed as part of the API call. - name: NIPC action APIs description: |- APIs that perform actions on devices. - name: NIPC management APIs description: |- APIs that manage device connections. - name: NIPC registration APIs description: |- APIs that register sdf models or data applications paths: ### NIPC Property APIs /devices/{id}/properties: put: tags: - NIPC property APIs summary: Update a value of one or more properties on a device description: |- Write a value to a property or multiple properties to a device. If underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: UpdateProperties parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: propertyName in: query description: |- The SDF property name that needs to be written to. required: false allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/thermos\ \tat/sdfProperty/temperature" requestBody: description: |- The value to be written to the property or properties. If multiple properties are specified, the request body should be application/nipc+json. content: application/nipc+json: schema: $ref: '#/components/schemas/PropertyValueArray' "*/*": schema: description: |- Any other content type, such as application/octet-stream, application/json that will be written to the device. required: true responses: '204': description: |- Success, no content, used for a single property write '200': description: Success, used for multiple property writes content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/PropertyValueRespons\ \eArray' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC property APIs summary: |- Read a value from one or multiple properties on a device description: |- Read a value to a property or multiple properties from a device. If underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: GetProperties parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: propertyName in: query description: Properties to be read required: true allowReserved: true schema: type: array items: type: string example: "https://example.com/heartrate#/sdfObject/therm\ \ostat/sdfProperty/temperature" responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/Id' - $ref: '#/components/schemas/PropertyValueReadRes\ \ponseArray' "*/*": schema: type: string description: |- Any other content type, such as application/octet-stream, application/json that will be read from the device. default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' ### NIPC Event APIs /devices/{id}/events: post: tags: - NIPC event APIs summary: Enable an event on a specific device description: |- Enable an event on a specific device or for a group of devices. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: EnableEvent parameters: - name: id in: path description: device id or group id required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: eventName in: query description: event that needs to be enabled required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/healths\ \ensor/sdfEvent/fallDetected" responses: '201': description: Success headers: Location: description: Location of the created event schema: type: string format: uri example: "/devices/{id}/events?instanceId={instanceI\ \d}" default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC event APIs summary: Disable an event on a specific device description: |- Disable an event on a specific device or a group of devices. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: DisableEvent parameters: - name: id in: path description: device id or group id required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: instanceId in: query description: instance id of the event that needs to be disab\ \led required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '204': description: Success, no content default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC event APIs summary: Get status of events on a device description: |- Get status of an event or multiple events on a specific devi\ \ce operationId: GetEvents parameters: - name: id in: path description: The ID of the device. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: instanceId in: query description: |- Instance ID of the events that need to be filtered required: false schema: type: array items: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success content: application/nipc+json: schema: $ref: '#/components/schemas/EventStatusResponseArray' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' /groups/{id}/events: post: tags: - NIPC event APIs summary: Enable an event on a group of devices description: |- Enable an event on a group of devices. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: EnableGroupEvent parameters: - name: id in: path description: |- group id for which the event needs to be enabled required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: eventName in: query description: event that needs to be enabled required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/healths\ \ensor/sdfEvent/fallDetected" responses: '201': description: Success, event enabled headers: Location: description: Location of the created event schema: type: string format: uri example: "/groups/{id}/events?instanceId={instanceId\ \}" default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC event APIs summary: Disable an event on a group of devices description: |- Disable an event on a group of devices. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: DisableGroupEvent parameters: - name: id in: path description: |- group id for which the event needs to be disabled required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: instanceId in: query description: instance id of the event that needs to be disab\ \led required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success, event disabled content: application/nipc+json: schema: $ref: '#/components/schemas/GroupEventStatusResponse\ \Array' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC event APIs summary: Get status of events on a group of devices description: |- Get status of an event or multiple events on a group of devi\ \ces. operationId: GetGroupEvents parameters: - name: id in: path description: group id of the SCIM group required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: instanceId in: query description: |- Instance IDs of the events that need to be filtered required: false schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success, events retrieved content: application/nipc+json: schema: $ref: '#/components/schemas/GroupEventStatusResponse\ \Array' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' ### NIPC action APIs /devices/{id}/actions: post: tags: - NIPC action APIs summary: Perform an action on a device description: |- Perform an action on a device. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. operationId: ActionProperty parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: actionName in: query description: action that needs to be performed required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/healths\ \ensor/sdfAction/start" requestBody: content: application/octet-stream: schema: type: string format: binary required: false responses: '202': description: Accepted, action is being performed headers: Location: description: Location of the action schema: type: string format: uri example: "/devices/{id}/actions?instanceId={instance\ \Id}" default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC action APIs summary: Get status of an action on a device description: |- Get status of an action on a specific device or a group of devices. Success is action is active, failure if action not active. operationId: GetAction parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: instanceId in: query description: |- instance id of the action that needs to be checked required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success, action is active content: application/nipc+json: schema: $ref: '#/components/schemas/ActionResponse' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' /devices/{id}/connections: post: tags: - NIPC management APIs summary: Connect a device description: |- Connect a device. 3 retries by default, optionally retry policy can be defined in the API body. If the protocol requires service discovery, full service discovery will be performed, unless specific services are described in the API body. operationId: ActionCreateConnection parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 requestBody: content: application/nipc+json: schema: anyOf: - $ref: '#/components/schemas/Connection' - $ref: './protocolmaps/ProtocolMap.yaml#/components\ \/schemas/ProtocolMap-ServiceList' required: false responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/Id' - $ref: './protocolmaps/ProtocolMap.yaml#/componen\ \ts/schemas/ProtocolMap-ServiceMap' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' put: tags: - NIPC management APIs summary: Update cached ServiceMap for a device. description: |- Update cached ServiceMap for a device. Full service discovery will be performed, unless specific services are described in the API body. operationId: ActionUpdateServiceMap parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 requestBody: content: application/nipc+json: schema: $ref: './protocolmaps/ProtocolMap.yaml#/components/sch\ \emas/ProtocolMap-ServiceList' required: false responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/Id' - $ref: './protocolmaps/ProtocolMap.yaml#/componen\ \ts/schemas/ProtocolMap-ServiceMap' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC management APIs summary: Disconnect a device description: |- Disconnect a device. operationId: ActionDeleteConnection parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/Id' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC management APIs summary: Get connection state for a device description: |- Get connection status for a device. Success when device(s) is/are connected, includes service map for the device if available. Failure when a device is not connected operationId: ActionGetConnection parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/Id' - $ref: './protocolmaps/ProtocolMap.yaml#/componen\ \ts/schemas/ProtocolMap-ServiceMap' default: description: Error response content: application/problem+json: schema: $ref: '#/components/schemas/FailureResponse' ### Registrations /registrations/models: post: tags: - NIPC registration APIs summary: Register an sdfObject description: |- Register an sdfObject, including Properties, Events and actions operationId: registerSdfObject requestBody: content: application/sdf+json: schema: $ref: '#/components/schemas/SdfModel' required: true responses: '200': description: Success content: application/nipc+json: schema: type: array items: allOf: - $ref: '#/components/schemas/SdfReference' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC registration APIs summary: Get all registered SDF model names description: |- Get all registered SDF model names. operationId: getSdfRefs parameters: - name: sdfName in: query description: |- sdfName can be a reference to an sdfThing or sdfObject required: false allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/healt\ \hsensor" responses: '200': description: Success content: application/sdf+json: schema: $ref: '#/components/schemas/SdfModel' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' put: tags: - NIPC registration APIs summary: Update an SDF model description: |- Update an SDF model, including Properties, Events and actions operationId: updateSdf parameters: - name: sdfName in: query description: |- sdfName can be a reference to an sdfThing or sdfObject required: true allowReserved: true schema: type: string example: "https://example.com/heartrate#/sdfObject/healt\ \hsensor" requestBody: content: application/sdf+json: schema: $ref: '#/components/schemas/SdfModel' required: true responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/SdfReference' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC registration APIs summary: Delete an sdfObject description: |- Delete an sdfObject, including Properties, Events and actions operationId: deleteSdfObject parameters: - name: sdfName in: query description: sdfObject name required: true schema: type: string example: "https://example.com/heartrate#/sdfObject/healt\ \hsensor" responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/SdfReference' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' /registrations/data-apps: post: tags: - NIPC registration APIs summary: Register a dataApp description: |- Register a dataApp that is able to receive device data. operationId: registerDataApp parameters: - name: dataAppId in: query description: id of the data app that will be registered required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 requestBody: content: application/nipc+json: schema: $ref: '#/components/schemas/DataApp' required: true responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/DataApp' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' put: tags: - NIPC registration APIs summary: Update registration of a dataApp description: |- Update registration of a dataApp that is able to receive dev\ \ice data. operationId: UpdateDataApp parameters: - name: dataAppId in: query description: id of the data app that will be updated required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 requestBody: content: application/nipc+json: schema: $ref: '#/components/schemas/DataApp' required: true responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/DataApp' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' delete: tags: - NIPC registration APIs summary: Delete registration of a dataApp description: |- Delete registration of a dataApp that is able to receive device data. operationId: DeleteDataApp parameters: - name: dataAppId in: query description: id of the data app that will be updated required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/DataApp' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' get: tags: - NIPC registration APIs summary: Get registration of a dataApp description: |- Get registrationdetails of a dataApp that is able to receive device data. operationId: GetDataApp parameters: - name: dataAppId in: query description: id of the data app that will be updated required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success content: application/nipc+json: schema: allOf: - $ref: '#/components/schemas/DataApp' default: description: Error response content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/FailureResponse' components: schemas: # Base objects ## A SCIM id, can be a device or a group Id: required: - id type: object properties: id: type: string format: uuid description: |- A SCIM-generated UUID, can be a device or group example: 12345678-1234-5678-1234-56789abcdef4 ## A property Property: required: - property type: object properties: property: type: string example: "https://example.com/heartrate#/sdfObject/thermos\ \tat/sdfProperty/temperature" ActionResponse: required: - action type: object properties: status: type: string example: COMPLETED description: |- Status of the action, can be IN_PROGRESS or COMPLETED ## A value Value: required: - value type: object properties: value: type: string format: byte example: dGVzdA== ## A value of an property of an Device PropertyValue: allOf: - $ref: '#/components/schemas/Property' - $ref: '#/components/schemas/Value' ## An array of Property values PropertyValueArray: type: array items: $ref: '#/components/schemas/PropertyValue' ## Event Event: required: - event type: object properties: event: type: string description: |- percent-encoded JSON pointer to the SDF event object example: https://example.com/heartrate#/sdfObject/healthse\ \nsor/sdfEvent/fallDetected InstanceId: type: object properties: instanceId: type: string format: uuid description: |- A SCIM-generated UUID for the event instance example: 12345678-1234-5678-1234-56789abcdef4 ## A Connection Connection: type: object properties: retries: type: integer format: int32 example: 3 retryMultipleAPs: type: boolean example: true ## DataApp DataApp: oneOf: - $ref: '#/components/schemas/DataAppMqttClient' - $ref: '#/components/schemas/DataAppMqttBroker' - $ref: '#/components/schemas/DataAppWebhook' - $ref: '#/components/schemas/DataAppWebsocket' type: object properties: events: type: array items: $ref: '#/components/schemas/Event' DataAppMqttClient: type: object properties: mqttClient: type: boolean DataAppMqttBroker: type: object properties: mqttBroker: type: object required: - URI - username - password properties: URI: type: string example: mqtt.broker.com:8883 username: type: string example: user1 password: type: string example: password1 brokerCACert: description: PEM encoded CA certificate type: string customTopic: type: string description: custom MQTT topic to publish to example: custom/topic DataAppWebhook: type: object properties: webhook: type: object properties: URI: type: string example: webhook.com:443 headers: type: object additionalProperties: type: string example: x-api-key: fjelk-3dl33f-2wdsd serverCACert: type: string DataAppWebsocket: type: object properties: websocket: type: object properties: URI: type: string example: websocket.com:443 headers: type: object additionalProperties: type: string example: x-api-key: fjelk-3dl33f-2wdsd serverCACert: type: string ## sdfObject registration definition SdfReference: type: object description: SDF URL referring to the sdfobject properties: sdfName: type: string example: "https://example.com/heartrate#/sdfObject/healths\ \ensor" SdfModel: allOf: - type: object description: Sample SDF model properties: namespace: type: object additionalProperties: type: string example: heartrate: https://example.com/heartrate defaultNamespace: type: string example: heartrate - oneOf: - $ref: '#/components/schemas/SdfThing' - $ref: '#/components/schemas/SdfObject' SdfThing: type: object description: Sample SDF thing properties: sdfThing: additionalProperties: anyOf: - $ref: '#/components/schemas/SdfProperty' - $ref: '#/components/schemas/SdfEvent' - $ref: '#/components/schemas/SdfAction' - $ref: '#/components/schemas/SdfObject' example: multipleSensor: sdfEvent: isPresent: sdfOutputData: sdfProtocolMap: ble: type: advertisement sdfObject: healthsensor: sdfProperty: heartrate: sdfProtocolMap: ble: serviceID: 12345678-1234-5678-1234-56789ab\ \cdef4 characteristicID: 12345678-1234-5678-1234-\ \56789abcdef4 sdfEvent: fallDetected: sdfOutputData: sdfProtocolMap: ble: serviceID: 12345678-1234-5678-1234-56789\ \abcdef4 characteristicID: 12345678-1234-5678-123\ \4-56789abcdef4 sdfAction: start: sdfProtocolMap: ble: serviceID: 12345678-1234-5678-1234-56789ab\ \cdef4 characteristicID: 12345678-1234-5678-1234-\ \56789abcdef4 SdfObject: type: object description: Sample SDF object properties: sdfObject: additionalProperties: anyOf: - $ref: '#/components/schemas/SdfProperty' - $ref: '#/components/schemas/SdfEvent' - $ref: '#/components/schemas/SdfAction' example: healthsensor: sdfProperty: heartrate: sdfProtocolMap: ble: serviceID: 12345678-1234-5678-1234-56789abcdef4 characteristicID: 12345678-1234-5678-1234-5678\ \9abcdef4 sdfEvent: fallDetected: sdfOutputData: sdfProtocolMap: ble: serviceID: 12345678-1234-5678-1234-56789abcd\ \ef4 characteristicID: 12345678-1234-5678-1234-56\ \789abcdef4 sdfAction: start: sdfProtocolMap: ble: serviceID: 12345678-1234-5678-1234-56789abcdef4 characteristicID: 12345678-1234-5678-1234-5678\ \9abcdef4 SdfProperty: type: object description: Sample SDF property properties: sdfProperty: additionalProperties: allOf: - $ref: './protocolmaps/ProtocolMap.yaml#/components/s\ \chemas/ProtocolMap-Property' example: heartrate: sdfProtocolMap: ble: serviceID: 12345678-1234-5678-1234-56789abcdef4 characteristicID: 12345678-1234-5678-1234-56789abc\ \def4 SdfEvent: type: object description: Sample SDF property properties: sdfEvent: additionalProperties: #example, this will be the registere\ \d event type: object properties: sdfOutputData: allOf: - $ref: './protocolmaps/ProtocolMap.yaml#/componen\ \ts/schemas/ProtocolMap-Event' example: fallDetected: sdfOutputData: sdfProtocolMap: ble: serviceID: 12345678-1234-5678-1234-56789abcdef4 characteristicID: 12345678-1234-5678-1234-56789a\ \bcdef4 SdfAction: type: object description: Sample SDF property properties: sdfAction: additionalProperties: allOf: - $ref: './protocolmaps/ProtocolMap.yaml#/components/s\ \chemas/ProtocolMap-Property' example: start: sdfProtocolMap: ble: serviceID: 12345678-1234-5678-1234-56789abcdef4 characteristicID: 12345678-1234-5678-1234-56789abc\ \def4 # responses SuccessResponse: type: object properties: status: type: integer format: int32 example: 200 description: HTTP status code ## Error 500 application Failure response FailureResponse: type: object properties: type: type: string description: URI to the error type enum: - https://www.iana.org/assignments/nipc-problem-types#in\ \valid-id - https://www.iana.org/assignments/nipc-problem-types#in\ \valid-sdf-url - https://www.iana.org/assignments/nipc-problem-types#ex\ \tension-operation-not-executed - https://www.iana.org/assignments/nipc-problem-types#sd\ \f-model-already-registered - https://www.iana.org/assignments/nipc-problem-types#sd\ \f-model-in-use - https://www.iana.org/assignments/nipc-problem-types#pr\ \operty-not-readable - https://www.iana.org/assignments/nipc-problem-types#pr\ \operty-read-failed - https://www.iana.org/assignments/nipc-problem-types#pr\ \operty-not-writable - https://www.iana.org/assignments/nipc-problem-types#pr\ \operty-write-failed - https://www.iana.org/assignments/nipc-problem-types#ev\ \ent-already-enabled - https://www.iana.org/assignments/nipc-problem-types#ev\ \ent-not-enabled - https://www.iana.org/assignments/nipc-problem-types#ev\ \ent-not-registered - https://www.iana.org/assignments/nipc-problem-types#pr\ \otocolmap-ble-already-connected - https://www.iana.org/assignments/nipc-problem-types#pr\ \otocolmap-ble-no-connection - https://www.iana.org/assignments/nipc-problem-types#pr\ \otocolmap-ble-connection-timeout - https://www.iana.org/assignments/nipc-problem-types#pr\ \otocolmap-ble-bonding-failed - https://www.iana.org/assignments/nipc-problem-types#pr\ \otocolmap-ble-connection-failed - https://www.iana.org/assignments/nipc-problem-types#pr\ \otocolmap-ble-service-discovery-failed - https://www.iana.org/assignments/nipc-problem-types#pr\ \otocolmap-ble-invalid-service-or-characteristic - https://www.iana.org/assignments/nipc-problem-types#pr\ \otocolmap-zigbee-connection-timeout - https://www.iana.org/assignments/nipc-problem-types#pr\ \otocolmap-zigbee-invalid-endpoint-or-cluster - https://www.iana.org/assignments/nipc-problem-types#ex\ \tension-broadcast-invalid-data - https://www.iana.org/assignments/nipc-problem-types#ex\ \tension-firmware-rollback - https://www.iana.org/assignments/nipc-problem-types#ex\ \tension-firmware-update-failed - about:blank status: type: integer format: int32 example: 400 description: HTTP status code title: type: string example: Invalid Device ID description: Human-readable error title detail: type: string example: |- Device ID 12345678-1234-5678-1234-56789abcdef4 does not exist or is not a device description: Human-readable error message ## Property operations responses PropertyValueResponseArrayItem: oneOf: - $ref: '#/components/schemas/SuccessResponse' - $ref: '#/components/schemas/FailureResponse' PropertyValueResponseArray: type: array items: $ref: '#/components/schemas/PropertyValueResponseArrayItem' PropertyValueReadResponseArrayItem: oneOf: - $ref: '#/components/schemas/PropertyValue' - $ref: '#/components/schemas/FailureResponse' PropertyValueReadResponseArray: type: array items: allOf: - $ref: '#/components/schemas/PropertyValueReadResponseArr\ \ayItem' ## Event operations responses EventStatusResponseArrayItem: oneOf: - allOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/InstanceId' - $ref: '#/components/schemas/FailureResponse' EventStatusResponseArray: type: array items: $ref: '#/components/schemas/EventStatusResponseArrayItem' GroupEventStatusResponse: type: object oneOf: - allOf: - $ref: '#/components/schemas/Event' - type: object properties: deviceId: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - $ref: '#/components/schemas/FailureResponse' GroupEventStatusResponseArray: type: array items: $ref: '#/components/schemas/GroupEventStatusResponse' ]]>

Protocol mapping NIPC requires that a protocol mapping be provided as part of the SDF model for a device or have one provided using the NIPC action APIs with embedded protocol mapping. The protocol mapping is a JSON object that describes the underlying technology used to communicate with the device along with any additional information needed to communicate with the device. The JSON format of the protocol mapping is provided as a non-normative OpenAPI model for the convenience of the implementor.

Protocol mapping OpenAPI model

file "ProtocolMap.yaml" =============== NOTE: '\' line wrapping per RFC 8792 ================ openapi: 3.0.3 info: title: Non IP Device Control (NIPC) Protocol Mapping description: |- Non IP Device Control (NIPC) Protocol Mapping. When adding a new protocol mapping pls add a reference to the protocol map for all the schemas in this file. termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.10.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ components: schemas: # Protocol Mapping ## Protocol Map for Service Discovery ProtocolMap-ServiceList: type: object properties: sdfProtocolMap: oneOf: - $ref: './ProtocolMap-BLE.yaml#/components/schemas/Prot\ ocolMap-BLE-ServiceList' ## Protocol Map for Service Discovery result ProtocolMap-ServiceMap: type: object properties: sdfProtocolMap: oneOf: - $ref: './ProtocolMap-BLE.yaml#/components/schemas/Prot\ ocolMap-BLE-ServiceMap' - $ref: './ProtocolMap-Zigbee.yaml#/components/schemas/P\ rotocolMap-Zigbee-ServiceMap' ## Protocol Map for Broadcasts ProtocolMap-Broadcast: type: object properties: sdfProtocolMap: oneOf: - $ref: './ProtocolMap-BLE.yaml#/components/schemas/Prot\ ocolMap-BLE-Broadcast' - $ref: './ProtocolMap-Zigbee.yaml#/components/schemas/P\ rotocolMap-Zigbee-Broadcast' ## Protocol Map for a property ProtocolMap-Property: type: object properties: sdfProtocolMap: oneOf: - $ref: './ProtocolMap-BLE.yaml#/components/schemas/Prot\ ocolMap-BLE-Propmap' - $ref: './ProtocolMap-Zigbee.yaml#/components/schemas/P\ rotocolMap-Zigbee-Propmap' ## Protocol Map for an event ProtocolMap-Event: type: object properties: sdfProtocolMap: oneOf: - $ref: './ProtocolMap-BLE.yaml#/components/schemas/Prot\ ocolMap-BLE-Event' - $ref: './ProtocolMap-Zigbee.yaml#/components/schemas/P\ rotocolMap-Zigbee-Event' ]]>

Protocol map for BLE

file "ProtocolMap-BLE.yaml" =============== NOTE: '\' line wrapping per RFC 8792 ================ openapi: 3.0.3 info: title: Non IP Device Control (NIPC) BLE Protocol Mapping description: |- Non IP Device Control (NIPC) BLE Protocol Mapping. termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.10.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ components: schemas: # BLE Protocol Mapping ## A Service is a device with optional service IDs ProtocolMap-BLE-ServiceList: type: object properties: ble: type: object properties: services: type: array items: type: object properties: serviceID: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 cached: description: |- If we can cache information, then device doesn't need to be rediscovered before every connected. type: boolean default: false cacheIdlePurge: description: cache expiry period, when device allows type: integer example: 3600 # default 1 hour autoUpdate: description: |- autoupdate services if device supports it (default) type: boolean example: true bonding: #optional, by default defined in SCIM object type: string example: default enum: - default - none - justworks - passkey - oob ## Protocol Mapping for BLE Service Map ProtocolMap-BLE-ServiceMap: required: - services type: object properties: ble: type: array items: $ref: '#/components/schemas/ProtocolMap-BLE-Service' ProtocolMap-BLE-Service: required: - serviceID - characteristics type: object properties: serviceID: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 characteristics: type: array items: $ref: '#/components/schemas/ProtocolMap-BLE-Characterist\ ic' ProtocolMap-BLE-Characteristic: required: - characteristicID - flags - descriptors type: object properties: characteristicID: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 flags: type: array example: - read - write items: type: string enum: - read - write - notify descriptors: type: array items: $ref: '#/components/schemas/ProtocolMap-BLE-Descriptor' ProtocolMap-BLE-Descriptor: required: - descriptorID type: object properties: descriptorID: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 ## Protocol Mapping for BLE Broadcast ProtocolMap-BLE-Broadcast: required: - ble type: object properties: ble: type: object properties: connectable: type: boolean ## Protocol Mapping for BLE Property ProtocolMap-BLE-Propmap: required: - ble type: object properties: ble: required: - serviceID - characteristicID type: object properties: serviceID: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 characteristicID: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 ## Defines different types of BLE events ProtocolMap-BLE-Event: required: - ble type: object properties: ble: required: - type type: object properties: type: type: string example: gatt enum: - gatt - connection_events - advertisements serviceID: type: string example: 12345678-1234-5678-1234-56789abcdef0 characteristicID: type: string example: 12345678-1234-5678-1234-56789abcdef1 ]]>

Protocol map for Zigbee

file "ProtocolMap-Zigbee.yaml" openapi: 3.0.3 info: title: Non IP Device Control (NIPC) Zigbee Protocol Mapping description: |- Non IP Device Control (NIPC) Zigbee Protocol Mapping. termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.10.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ components: schemas: # Zigbee Protocol Mapping ## Protocol Mapping for Zigbee Service Map ProtocolMap-Zigbee-ServiceMap: required: - zigbee type: object properties: zigbee: type: array items: $ref: '#/components/schemas/ProtocolMap-Zigbee-Endpoint' ProtocolMap-Zigbee-Endpoint: required: - endpointID - clusters type: object properties: endpointID: type: integer format: int32 example: 10 clusters: type: array items: $ref: '#/components/schemas/ProtocolMap-Zigbee-Cluster' ProtocolMap-Zigbee-Cluster: required: - clusterID - properties type: object properties: clusterID: type: integer format: int32 example: 0 properties: type: array items: $ref: '#/components/schemas/ProtocolMap-Zigbee-Property' ProtocolMap-Zigbee-Property: required: - attributeID - propertyType type: object properties: attributeID: type: integer format: int32 example: 1 propertyType: type: integer format: int32 example: 32 ## Protocol Mapping for Zigbee broadcast ProtocolMap-Zigbee-Broadcast: required: - zigbee type: object properties: zigbee: type: object ## Protocol mapping for Zigbee property ProtocolMap-Zigbee-Propmap: required: - zigbee type: object properties: zigbee: required: - endpointID - clusterID - attributeID type: object properties: endpointID: type: integer format: int32 example: 1 clusterID: type: integer format: int32 example: 6 attributeID: type: integer format: int32 example: 16 type: type: integer format: int32 example: 1 ProtocolMap-Zigbee-Event: allOf: - $ref: '#/components/schemas/ProtocolMap-Zigbee-Propmap' ]]>

NIPC API extensions The following OpenAPI models define a few example extensions to the NIPC API.

NIPC API write binary blob extension

file "Extension-Blob.yaml" =============== NOTE: '\' line wrapping per RFC 8792 ================ # yaml-language-server: $schema=https://json-schema.org/draft/2020-1\ 2/schema openapi: 3.0.3 info: title: Non IP Device Control (NIPC) API write binary blob extension description: |- Non IP Device Control (NIPC) API write binary blob extension termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.14.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ servers: - url: "{gw_host}/nipc/draft-14" variables: gw_host: default: localhost description: Gateway Host tags: - name: NIPC API extensions description: |- APIs that simplify application interaction by implementing one or more basic APIs into a single API call. paths: ### Extensions /extensions/{id}/properties/blob: put: tags: - NIPC API extensions summary: Write a binary blob to a property on a device description: |- Write a binary blob to a property on a device. Will chunk up the binary blob and perform multiple writes. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. ID cannot be a group-id. operationId: writeBlob parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: propertyName in: query description: |- The SDF property name that needs to be written to. required: true schema: type: string example: "https://example.com/heartrate#/sdfObject/thermos\ tat/sdfProperty/firmware" requestBody: content: application/json: schema: $ref: '#/components/schemas/Extension-Blob' required: true responses: '204': description: Success, no content 'default': description: Error response content: application/json: schema: $ref: '../NIPC.yaml#/components/schemas/FailureRespo\ nse' components: schemas: # Extensions ## A binary blob Extension Extension-Blob: required: - blob type: object properties: blob: type: string format: byte chunksize: type: integer ]]>

NIPC API bulk operations extension

file "Extension-Bulk.yaml" =============== NOTE: '\' line wrapping per RFC 8792 ================ # yaml-language-server: $schema=https://json-schema.org/draft/2020-1\ 2/schema openapi: 3.0.3 info: title: Non IP Device Control (NIPC) API bulk extension description: |- Non IP Device Control (NIPC) API bulk extension termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.14.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ servers: - url: "{gw_host}/nipc/draft-14" variables: gw_host: default: localhost description: Gateway Host tags: - name: NIPC API extensions description: |- APIs that simplify application interaction by implementing one or more basic APIs into a single API call. paths: ### Extensions /extensions/{id}/bulk: post: tags: - NIPC API extensions summary: Compound operations on a device description: Compound operations on a device operationId: Bulk parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 requestBody: content: application/json: schema: $ref: "#/components/schemas/Extension-Bulk" examples: bulkRequest: $ref: "#/components/examples/bulkRequest" firmwareUpgradeRequest: $ref: "#/components/examples/firmwareUpgradeRequest" required: true responses: "202": description: Accepted headers: Location: schema: type: string example: /extensions/12345678-1234-5678-1234-56789ab\ cdef4/bulk/status?instanceId=12345678-1234-5678-1234-56789abcdef4 description: URL to get the bulk status response "401": description: Unauthorized "405": description: Invalid request "500": description: Server-side failure content: application/json: schema: $ref: "../NIPC.yaml#/components/schemas/FailureRespo\ nse" callbacks: bulkEvent: "{$request.body#/callback.url}": post: description: Callback for bulk response operationId: bulkCallback requestBody: content: application/json: schema: allOf: - $ref: "../NIPC.yaml#/components/schemas/Id" - $ref: "#/components/schemas/Extension-Bulk\ Response" responses: "200": description: OK "400": description: Bad request "401": description: Unauthorized "405": description: Invalid request "500": description: Server-side failure get: tags: - NIPC API extensions summary: Get Bulk response description: Get Bulk response operationId: getBulkResponse parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: instanceId in: query description: Instance ID of the bulk operation required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: "200": description: OK headers: content: application/json: schema: allOf: - $ref: "../NIPC.yaml#/components/schemas/Id" - $ref: "#/components/schemas/Extension-BulkRespon\ se" examples: bulkResponse: $ref: "#/components/examples/bulkResponse" firmwareUpgradeResponse: $ref: "#/components/examples/firmwareUpgradeRespon\ se" errorBulkResponse: $ref: "#/components/examples/errorBulkResponse" /extensions/{id}/bulk/status: get: tags: - NIPC API extensions summary: Get Bulk status description: Get Bulk status operationId: getBulkStatus parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: instanceId in: query description: Instance ID of the bulk operation required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: "200": description: OK headers: content: application/json: schema: allOf: - $ref: "./Extension-Async.yaml#/components/schema\ s/Extension-StatusResponse" "303": description: See Other headers: Location: schema: type: string example: /extensions/12345678-1234-5678-1234-56789ab\ cdef4/bulk?instanceId=12345678-1234-5678-1234-56789abcdef4 description: URL to get the bulk response content: application/json: schema: allOf: - $ref: "./Extension-Async.yaml#/components/schema\ s/Extension-StatusResponse" examples: successExample: summary: Success value: status: COMPLETED components: schemas: # Extensions ## Bulk schema Extension Extension-Bulk: allOf: - $ref: "./Extension-Async.yaml#/components/schemas/Extensio\ n-Callback" - type: object properties: operations: type: array items: $ref: "#/components/schemas/Extension-BulkOperation" trigger: type: string description: |- When to trigger the operations. If not specified, th\ e operations are triggered immediately. default: immediate enum: - immediate - advertisement ## Extension that defines an operation in a bulk API Extension-BulkOperation: required: - method - path allOf: - type: object properties: method: type: string enum: - POST - PUT - GET path: type: string enum: - /devices/{id}/properties?propertyName={propertyNam\ e} - /devices/{id}/actions/?actionName={actionName} - /extensions/{id}/properties/read/conditional?prope\ rtyName={propertyName} - /extensions/{id}/events/conditional?eventName={eve\ ntName} - /extensions/{id}/properties/file?propertyName={pro\ pertyName} example: /devices/12345678-1234-5678-1234-56789abcdef4\ /properties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%\ 2FsdfThing%2Fthermometer%2FsdfProperty%2Ftemperature data: type: object oneOf: - $ref: "../NIPC.yaml#/components/schemas/Value" - $ref: "./Extension-ReadConditional.yaml#/component\ s/schemas/Extension-ConditionalRead" ## Multiple returns for a bulk operation Extension-BulkResponse: type: object properties: operations: type: array items: $ref: "#/components/schemas/Extension-OperationResponse" ## Return for an operation Extension-OperationResponse: allOf: - type: object properties: method: type: string enum: - POST - PUT - GET path: type: string enum: - /devices/{id}/properties?propertyName={propertyNam\ e} - /devices/{id}/actions/?actionName={actionName} - /extensions/{id}/properties/read/conditional?prope\ rtyName={propertyName} - /extensions/{id}/events/conditional?eventName={eve\ ntName} example: /devices/12345678-1234-5678-1234-56789abcdef4\ /properties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%\ 2FsdfThing%2Fthermometer%2FsdfProperty%2Ftemperature response: anyOf: - $ref: "../NIPC.yaml#/components/schemas/Value" - $ref: "../NIPC.yaml#/components/schemas/SuccessRes\ ponse" - $ref: "../NIPC.yaml#/components/schemas/FailureRes\ ponse" examples: bulkRequest: summary: Bulk request example value: operations: - method: GET path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2Ftemperature - method: PUT path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2Ftemperature data: value: dGVzdA== - method: POST path: /extensions/12345678-1234-5678-1234-56789abcdef4/p\ roperties/read/conditional?propertyName=https%3A%2F%2Fexample.com%2F\ thermometer%23%2FsdfThing%2Fthermometer%2FsdfProperty%2Ftemperature data: value: dGVzdA== maxRepeat: 5 retryTime: 1 bulkResponse: summary: Bulk response example value: operations: - method: GET path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2Ftemperature response: value: dGVzdA== - method: PUT path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2Ftemperature response: status: 200 - method: POST path: /extensions/12345678-1234-5678-1234-56789abcdef4/p\ roperties/read/conditional?propertyName=https%3A%2F%2Fexample.com%2F\ thermometer%23%2FsdfThing%2Fthermometer%2FsdfProperty%2Ftemperature response: value: dGVzdA== errorBulkResponse: summary: Error Bulk response example value: operations: - method: GET path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2Ftemperature response: type: https://www.iana.org/assignments/nipc-problem-ty\ pes#property-not-readable status: 400 title: Property not readable detail: Property https://example.com/thermometer#/sdfT\ hing/thermometer/sdfProperty/temperature is not readable - method: PUT path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2Ftemperature response: type: https://www.iana.org/assignments/nipc-problem-ty\ pes#extension-operation-not-executed status: 400 title: Operation not executed detail: Operation was not executed since the previous \ operation failed - method: POST path: /extensions/12345678-1234-5678-1234-56789abcdef4/p\ roperties/read/conditional?propertyName=https%3A%2F%2Fexample.com%2F\ thermometer%23%2FsdfThing%2Fthermometer%2FsdfProperty%2Ftemperature response: type: https://www.iana.org/assignments/nipc-problem-ty\ pes#extension-operation-not-executed status: 400 title: Operation not executed detail: Operation was not executed since the previous \ operation failed firmwareUpgradeRequest: summary: Firmware upgrade request example value: operations: - method: PUT path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2FstartOTA data: value: dGVzdA== - method: POST path: /extensions/12345678-1234-5678-1234-56789abcdef4/e\ vents/conditional?eventName=https%3A%2F%2Fexample.com%2Fthermometer%\ 23%2FsdfThing%2Fthermometer%2FsdfEvent%2FotaStarted data: value: MQ== timeout: 5 - method: PUT path: /extensions/12345678-1234-5678-1234-56789abcdef4/p\ roperties/file?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%\ 23%2FsdfThing%2Fthermometer%2FsdfProperty%2Ffirmware data: fileURL: https://example.com/firmware.bin chunkSize: 20 sha256Checksum: abcdef1234567890abcdef1234567890abcdef\ 1234567890abcdef1234567890 - method: PUT path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2FfinishOTA data: value: dGVzdA== - method: POST path: /extensions/12345678-1234-5678-1234-56789abcdef4/p\ roperties/read/conditional?propertyName=https%3A%2F%2Fexample.com%2F\ thermometer%23%2FsdfThing%2Fthermometer%2FsdfProperty%2FupdateStatus data: value: MQ== maxRepeat: 5 retryTime: 1 - method: PUT path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2FactivateOTA data: value: dGVzdA== firmwareUpgradeResponse: summary: Firmware upgrade response example value: operations: - method: PUT path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2FstartOTA response: status: 200 - method: POST path: /extensions/12345678-1234-5678-1234-56789abcdef4/e\ vents/conditional?eventName=https%3A%2F%2Fexample.com%2Fthermometer%\ 23%2FsdfThing%2Fthermometer%2FsdfEvent%2FotaStarted response: value: MQ== - method: PUT path: /extensions/12345678-1234-5678-1234-56789abcdef4/p\ roperties/file?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%\ 23%2FsdfThing%2Fthermometer%2FsdfProperty%2Ffirmware response: status: 204 - method: PUT path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2FfinishOTA response: status: 200 - method: POST path: /extensions/12345678-1234-5678-1234-56789abcdef4/p\ roperties/read/conditional?propertyName=https%3A%2F%2Fexample.com%2F\ thermometer%23%2FsdfThing%2Fthermometer%2FsdfProperty%2FupdateStatus response: value: MQ== - method: PUT path: /devices/12345678-1234-5678-1234-56789abcdef4/prop\ erties?propertyName=https%3A%2F%2Fexample.com%2Fthermometer%23%2Fsdf\ Thing%2Fthermometer%2FsdfProperty%2FactivateOTA data: status: 200 ]]>

NIPC API write file extension

file "Extension-File.yaml" =============== NOTE: '\\' line wrapping per RFC 8792 =============== # yaml-language-server: $schema=https://json-schema.org/draft/2020-1\ \2/schema openapi: 3.0.3 info: title: Non IP Device Control (NIPC) API write file extension description: |- Non IP Device Control (NIPC) API write file extension termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.14.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ servers: - url: "{gw_host}/nipc/draft-14" variables: gw_host: default: localhost description: Gateway Host tags: - name: NIPC API extensions description: |- APIs that simplify application interaction by implementing one or more basic APIs into a single API call. paths: ### Extensions /extensions/{id}/properties/file: put: tags: - NIPC API extensions summary: Write a file to a property on a device description: |- Write a file to a property on a device. Will chunk up the file and perform multiple writes. If the underlying protocol requires a connection to be set up, this API call will perform the necessary connection management. If a connection is already active for this device, the existing connection will be leveraged without modifying it. ID cannot be a group-id. operationId: writeFile parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: propertyName in: query description: |- The SDF property name that needs to be written to. required: true schema: type: string example: "https://example.com/heartrate#/sdfObject/thermos\ \tat/sdfProperty/firmware" requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Extension-File' - $ref: './Extension-Async.yaml#/components/schemas/\ \Extension-Callback' required: true responses: '202': description: Accepted headers: Location: schema: type: string example: /extensions/12345678-1234-5678-1234-56789ab\ \cdef4/properties/file/status?propertyName=https%3A%2F%2Fexample.com\ \%2Fheartrate%23%2FsdfObject%2Fthermostat%2FsdfProperty%2Ffirmware&i\ \nstanceId=12345678-1234-5678-1234-56789abcdef4 description: |- URL to get the file write status Retry-After: schema: type: integer description: |- Time in seconds to wait before retrying 'default': description: Error response content: application/json: schema: $ref: '../NIPC.yaml#/components/schemas/FailureRespo\ \nse' callbacks: callbackEvent: "{$request.body#/callback.url}": post: requestBody: content: application/json: schema: anyOf: - allOf: - $ref: '../NIPC.yaml#/components/schemas/\ \Id' - $ref: '../NIPC.yaml#/components/schemas/\ \PropertyValue' - $ref: '../NIPC.yaml#/components/schemas/Fa\ \ilureResponse' examples: successExample: summary: Success value: id: 12345678-1234-5678-1234-56789abcdef4 property: https://example.com/heartrate#/s\ \dfObject/thermostat/sdfProperty/firmware failedResponse: summary: Failed value: id: 12345678-1234-5678-1234-56789abcdef4 status: 400 type: https://www.iana.org/assignments/nip\ \c-problem-types#invalid-id title: Invalid ID detail: "Invalid request" property: https://example.com/heartrate#/s\ \dfObject/thermostat/sdfProperty/firmware responses: '200': description: Success get: tags: - NIPC API extensions summary: Get the status of a file write operation description: |- Get the status of a file write operation. This will return the status of the file write operation, including any errors that may have occurred. operationId: getFileWriteStatus parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: propertyName in: query description: |- The SDF property name that needs to be written to. required: true schema: type: string example: "https://example.com/heartrate#/sdfObject/thermos\ \tat/sdfProperty/firmware" - name: instanceId in: query description: |- The Instance ID for the file write operation. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '204': description: Success, no content default: description: Error response content: application/json: schema: $ref: '../NIPC.yaml#/components/schemas/FailureRespo\ \nse' /extensions/{id}/properties/file/status: get: tags: - NIPC API extensions summary: Get the status of a file write operation description: |- Get the status of a file write operation. This will return the status of the file write operation, including any errors that may have occurred. operationId: getFileWriteStatus parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: propertyName in: query description: |- The SDF property name that needs to be written to. required: true schema: type: string example: "https://example.com/heartrate#/sdfObject/thermos\ \tat/sdfProperty/firmware" - name: instanceId in: query description: |- The Instance ID for the file write operation. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success, returns the status of the file write\ \ operation. content: application/json: schema: $ref: './Extension-Async.yaml#/components/schemas/Ex\ \tension-StatusResponse' '303': description: See Other headers: Location: schema: type: string example: /extensions/12345678-1234-5678-1234-56789ab\ \cdef4/properties/file?propertyName=https%3A%2F%2Fexample.com%2Fhear\ \trate%23%2FsdfObject%2Fthermostat%2FsdfProperty%2Ffirmware&instance\ \Id=12345678-1234-5678-1234-56789abcdef4 description: URL to get the file write response content: application/json: schema: $ref: './Extension-Async.yaml#/components/schemas/Ex\ \tension-StatusResponse' examples: successExample: summary: Completed value: id: 12345678-1234-5678-1234-56789abcdef4 status: COMPLETED components: schemas: # Extensions ## A File Extension Extension-File: required: - fileURL type: object properties: fileURL: type: string example: "https://domain.com/firmware.dat" description: |- URL to the firmware file. The HTTP method is assumed to be a GET. chunkSize: type: integer sha256Checksum: type: string description: firmware checksum headers: type: object additionalProperties: type: string example: x-api-key: fjelk-3dl33f-2wdsd ]]>

NIPC API conditional read extension

file "Extension-ReadConditional.yaml" =============== NOTE: '\' line wrapping per RFC 8792 ================ # yaml-language-server: $schema=https://json-schema.org/draft/2020-1\ 2/schema openapi: 3.0.3 info: title: Non IP Device Control (NIPC) API read conditional extension description: |- Non IP Device Control (NIPC) API read conditional extension termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.14.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ servers: - url: "{gw_host}/nipc/draft-14" variables: gw_host: default: localhost description: Gateway Host tags: - name: NIPC API extensions description: |- APIs that simplify application interaction by implementing one or more basic APIs into a single API call. paths: ### Extensions /extensions/{id}/properties/read/conditional: post: tags: - NIPC API extensions summary: Conditional read of a property description: Conditional read of a property operationId: conditionalRead parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: propertyName in: query description: |- The SDF property name that needs to be read conditionally. required: true allowReserved: true schema: type: string example: "#/sdfObject/thermostat/sdfProperty/temperature" requestBody: content: application/json: schema: $ref: '#/components/schemas/Extension-ConditionalRead' required: true responses: '202': description: Accepted headers: Location: schema: type: string example: /extensions/12345678-1234-5678-1234-56789ab\ cdef4/properties/read/conditional/status?propertyName=https%3A%2F%2F\ example.com%2Fheartrate%23%2FsdfObject%2Fthermostat%2FsdfProperty%2F\ temperature&instanceId=12345678-1234-5678-1234-56789abcdef4 description: |- URL to get the conditional read status Retry-After: schema: type: integer description: |- Time in seconds to wait before retrying 'default': description: Error response content: application/json: schema: $ref: '../NIPC.yaml#/components/schemas/FailureRespo\ nse' callbacks: callbackEvent: "{$request.body#/callback.url}": post: requestBody: content: application/json: schema: anyOf: - allOf: - $ref: '../NIPC.yaml#/components/schemas/\ Id' - $ref: '../NIPC.yaml#/components/schemas/\ PropertyValue' - $ref: '../NIPC.yaml#/components/schemas/Fa\ ilureResponse' examples: successExample: summary: Success value: id: 12345678-1234-5678-1234-56789abcdef4 property: https://example.com/heartrate#/s\ dfObject/thermostat/sdfProperty/temperature value: dGVzdA== failedResponse: summary: Failed value: id: 12345678-1234-5678-1234-56789abcdef4 status: 400 type: https://www.iana.org/assignments/nip\ c-problem-types#invalid-id title: Invalid ID detail: "Invalid request" property: https://example.com/heartrate#/s\ dfObject/thermostat/sdfProperty/temperature value: dGVzdA== responses: '200': description: Success get: tags: - NIPC API extensions summary: Get Conditional read response of a property description: Conditional read response of a property operationId: getConditionalRead parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: propertyName in: query description: |- The SDF property name that needs to be read conditionally. required: true allowReserved: true schema: type: string example: "#/sdfObject/thermostat/sdfProperty/temperature" - name: instanceId in: query description: |- Instance ID of the conditional read operation required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success headers: content: application/json: schema: allOf: - $ref: '../NIPC.yaml#/components/schemas/Value' application/octet-stream: schema: type: string format: binary description: Binary data of the property value default: description: Error response content: application/problem+json: schema: allOf: - $ref: '../NIPC.yaml#/components/schemas/FailureR\ esponse' /extensions/{id}/properties/read/conditional/status: get: tags: - NIPC API extensions summary: Get Conditional read status of a property description: Conditional read status of a property operationId: getConditionalReadStatus parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: propertyName in: query description: |- The SDF property name that needs to be read conditionally. required: true allowReserved: true schema: type: string example: "#/sdfObject/thermostat/sdfProperty/temperature" - name: instanceId in: query description: Instance ID of the conditional read operation required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: OK headers: content: application/json: schema: $ref: './Extension-Async.yaml#/components/schemas/Ex\ tension-StatusResponse' '303': description: See Other headers: Location: schema: type: string example: /extensions/12345678-1234-5678-1234-56789ab\ cdef4/properties/read/conditional?propertyName=https%3A%2F%2Fexample\ .com%2Fheartrate%23%2FsdfObject%2Fthermostat%2FsdfProperty%2Ftempera\ ture&instanceId=12345678-1234-5678-1234-56789abcdef4 description: URL to get the conditional read response content: application/json: schema: $ref: './Extension-Async.yaml#/components/schemas/Ex\ tension-StatusResponse' examples: successExample: summary: Completed value: id: 12345678-1234-5678-1234-56789abcdef4 status: COMPLETED components: schemas: # Extensions Extension-ConditionalRead: allOf: - $ref: '../NIPC.yaml#/components/schemas/Value' - $ref: './Extension-Async.yaml#/components/schemas/Extensio\ n-Callback' - type: object properties: maxRepeat: description: |- maximum time the conditional read should repeat (default 5, max 10) type: integer example: 5 retryTime: description: |- time between reads in seconds (default 1, max 10) type: integer example: 1 ]]>

NIPC API conditional event extension

file "Extension-EventConditional.yaml" =============== NOTE: '\' line wrapping per RFC 8792 ================ # yaml-language-server: $schema=https://json-schema.org/draft/2020-1\ 2/schema openapi: 3.0.3 info: title: Non IP Device Control (NIPC) API event conditional extension description: |- Non IP Device Control (NIPC) API event conditional extension termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.14.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ servers: - url: "{gw_host}/nipc/draft-14" variables: gw_host: default: localhost description: Gateway Host tags: - name: NIPC API extensions description: |- APIs that simplify application interaction by implementing one or more basic APIs into a single API call. paths: ### Extensions /extensions/{id}/events/conditional: post: tags: - NIPC API extensions summary: Enable an event until a condition is met description: Enable an event until a condition is met operationId: conditionalEvent parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: eventName in: query description: |- The SDF event name that needs to be enabled. required: true allowReserved: true schema: type: string example: "#/sdfObject/thermostat/sdfEvent/temperature" requestBody: content: application/json: schema: $ref: '#/components/schemas/Extension-ConditionalEvent' required: true responses: '202': description: Accepted headers: Location: schema: type: string example: /extensions/12345678-1234-5678-1234-56789ab\ cdef4/events/conditional/status?eventName=https%3A%2F%2Fexample.com%\ 2Fheartrate%23%2FsdfObject%2Fthermostat%2FsdfEvent%2Ftemperature&ins\ tanceId=12345678-1234-5678-1234-56789abcdef4 description: |- URL to get the conditional event status Retry-After: schema: type: integer description: |- Time in seconds to wait before retrying 'default': description: Error response content: application/json: schema: $ref: '../NIPC.yaml#/components/schemas/FailureRespo\ nse' callbacks: callbackEvent: "{$request.body#/callback.url}": post: requestBody: content: application/json: schema: anyOf: - allOf: - $ref: '../NIPC.yaml#/components/schemas/\ Id' - $ref: '../NIPC.yaml#/components/schemas/\ PropertyValue' - $ref: '../NIPC.yaml#/components/schemas/Fa\ ilureResponse' examples: successExample: summary: Success value: id: 12345678-1234-5678-1234-56789abcdef4 event: https://example.com/heartrate#/sdfO\ bject/thermostat/sdfEvent/temperature value: dGVzdA== failedResponse: summary: Failed value: id: 12345678-1234-5678-1234-56789abcdef4 status: 400 type: https://www.iana.org/assignments/nip\ c-problem-types#invalid-id title: Invalid ID detail: "Invalid request" event: https://example.com/heartrate#/sdfO\ bject/thermostat/sdfEvent/temperature value: dGVzdA== responses: '200': description: Success get: tags: - NIPC API extensions summary: Get Conditional event response description: Conditional event response operationId: getConditionalEvent parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: eventName in: query description: |- The name of the SDF event that is enabled. required: true allowReserved: true schema: type: string example: "#/sdfObject/thermostat/sdfEvent/temperature" - name: instanceId in: query description: |- Instance ID of the conditional event operation required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: Success headers: content: application/json: schema: allOf: - $ref: '../NIPC.yaml#/components/schemas/Value' application/octet-stream: schema: type: string format: binary description: Binary data of the event value default: description: Error response content: application/problem+json: schema: allOf: - $ref: '../NIPC.yaml#/components/schemas/FailureR\ esponse' /extensions/{id}/events/conditional/status: get: tags: - NIPC API extensions summary: Get Conditional event status description: Conditional event status operationId: getConditionalEventStatus parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 - name: eventName in: query description: |- The name of the SDF event that is enabled. required: true allowReserved: true schema: type: string example: "#/sdfObject/thermostat/sdfEvent/temperature" - name: instanceId in: query description: Instance ID of the conditional event operation required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 responses: '200': description: OK headers: content: application/json: schema: $ref: './Extension-Async.yaml#/components/schemas/Ex\ tension-StatusResponse' '303': description: See Other headers: Location: schema: type: string example: /extensions/12345678-1234-5678-1234-56789ab\ cdef4/events/conditional?eventName=https%3A%2F%2Fexample.com%2Fheart\ rate%23%2FsdfObject%2Fthermostat%2FsdfEvent%2Ftemperature&instanceId\ =12345678-1234-5678-1234-56789abcdef4 description: URL to get the conditional event response content: application/json: schema: $ref: './Extension-Async.yaml#/components/schemas/Ex\ tension-StatusResponse' examples: successExample: summary: Completed value: id: 12345678-1234-5678-1234-56789abcdef4 status: COMPLETED components: schemas: # Extensions Extension-ConditionalEvent: allOf: - $ref: './Extension-Async.yaml#/components/schemas/Extensio\ n-Callback' - $ref: '../NIPC.yaml#/components/schemas/Value' - type: object properties: timeout: description: |- Time in seconds to keep the event enabled. If the event condition is not met within this time, the event will be disabled and marked as failed. type: integer example: 5 ]]>

NIPC API property extensions

file "Extension-Property.yaml" =============== NOTE: '\' line wrapping per RFC 8792 ================ # yaml-language-server: $schema=https://json-schema.org/draft/2020-1\ 2/schema openapi: 3.0.3 info: title: Non IP Device Control (NIPC) API read conditional extension description: |- Non IP Device Control (NIPC) API read conditional extension termsOfService: http://swagger.io/terms/ contact: email: bbrinckm@cisco.com license: name: TBD url: TBD version: 0.14.0 externalDocs: description: NIPC IETF draft url: https://datatracker.ietf.org/doc/draft-ietf-asdf-nipc/ servers: - url: "{gw_host}/nipc/draft-14" variables: gw_host: default: localhost description: Gateway Host tags: - name: NIPC API extensions description: |- APIs that simplify application interaction by implementing one or more basic APIs into a single API call. paths: ### Extensions /extensions/{id}/transmit: post: tags: - NIPC API extensions summary: Transmit to a device description: |- Transmit a payload to a device. The transmission is performe\ d on the AP where the device was last seen operationId: ActionTransmit parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 requestBody: content: application/json: schema: $ref: '#/components/schemas/Transmit' required: true responses: '200': description: Success default: description: Error response content: application/problem+json: schema: $ref: '../NIPC.yaml#/components/schemas/FailureRespo\ nse' /extensions/{id}/properties/write: post: tags: - NIPC API extensions summary: Write a value to an property using protocol mapping description: |- Write a value to an unregistered property, embedding property protocol mapping in the API, this does not require property registration. You cannot write to a group id. operationId: ActionPropWrite parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 requestBody: content: application/json: schema: allOf: - $ref: '../NIPC.yaml#/components/schemas/Value' - $ref: '../protocolmaps/ProtocolMap.yaml#/component\ s/schemas/ProtocolMap-Property' required: true responses: '204': description: Success, no content default: description: Error response content: application/problem+json: schema: $ref: '../NIPC.yaml#/components/schemas/FailureRespo\ nse' /extensions/{id}/properties/read: post: tags: - NIPC API extensions summary: Read a value to an property using protocol mapping description: |- Read a value from an unregistered property, embedding property protocol mapping in the API, this does not require property registration. You cannot read from a group id. operationId: ActionPropRead parameters: - name: id in: path description: The ID of the device. Group ID is not allowed. required: true schema: type: string format: uuid example: 12345678-1234-5678-1234-56789abcdef4 requestBody: content: application/json: schema: $ref: '../protocolmaps/ProtocolMap.yaml#/components/sc\ hemas/ProtocolMap-Property' required: true responses: '200': description: Success content: application/json: schema: allOf: - $ref: '../NIPC.yaml#/components/schemas/Value' default: description: Error response content: application/problem+json: schema: $ref: '../NIPC.yaml#/components/schemas/FailureRespo\ nse' components: schemas: Transmit: allOf: - $ref: '../protocolmaps/ProtocolMap.yaml#/components/schema\ s/ProtocolMap-Broadcast' required: - cycle type: object properties: cycle: type: string example: single enum: - single - repeat # transmit time in ms transmitTime: type: integer example: 3000 # interval between transmits in ms transmitInterval: type: integer example: 500 payload: type: string format: byte example: AgEaAgoMFv9MABAHch9BsDkgeA== ]]>

Example SDF model with protocol mappings for BLE

file "thermometer.sdf.json" { "namespace": { "thermometer": "https://example.com/thermometer" }, "defaultNamespace": "thermometer", "sdfThing": { "thermometer": { "sdfObject": { "health_thermometer": { "description": "Health Thermometer", "sdfProperty": { "temperature_type": { "description": "Temperature Type", "observable": false, "writable": false, "readable": true, "sdfProtocolMap": { "ble": { "serviceID": "1809", "characteristicID": "2A1D" } } }, "measurement_interval": { "description": "Measurement Interval", "observable": false, "writable": false, "readable": true, "sdfProtocolMap": { "ble": { "serviceID": "1809", "characteristicID": "2A21" } } } }, "sdfEvent": { "temperature_measurement": { "description": "Temperature Measurement", "sdfOutputData": { "sdfProtocolMap": { "ble": { "type": "gatt", "serviceID": "1809", "characteristicID": "2A1C" } } } }, "intermediate_temperature": { "description": "Intermediate Temperature", "sdfOutputData": { "sdfProtocolMap": { "ble": { "type": "gatt", "serviceID": "1809", "characteristicID": "2A1E" } } } } } } }, "description": "Generic Access, Device Information", "sdfProperty": { "device_name": { "description": "Device Name", "observable": false, "writable": true, "readable": true, "sdfProtocolMap": { "ble": { "serviceID": "1800", "characteristicID": "2A00" } } }, "appearance": { "description": "Appearance", "observable": false, "writable": false, "readable": true, "sdfProtocolMap": { "ble": { "serviceID": "1800", "characteristicID": "2A01" } } }, "manufacturer_name_string": { "description": "Manufacturer Name String", "observable": false, "writable": false, "readable": true, "sdfProtocolMap": { "ble": { "serviceID": "180A", "characteristicID": "2A29" } } }, "model_number_string": { "description": "Model Number String", "observable": false, "writable": false, "readable": true, "sdfProtocolMap": { "ble": { "serviceID": "180A", "characteristicID": "2A24" } } }, "hardware_revision_string": { "description": "Hardware Revision String", "observable": false, "writable": false, "readable": true, "sdfProtocolMap": { "ble": { "serviceID": "180A", "characteristicID": "2A27" } } }, "firmware_revision_string": { "description": "Firmware Revision String", "observable": false, "writable": false, "readable": true, "sdfProtocolMap": { "ble": { "serviceID": "180A", "characteristicID": "2A26" } } }, "system_id": { "description": "System ID", "observable": false, "writable": false, "readable": true, "sdfProtocolMap": { "ble": { "serviceID": "180A", "characteristicID": "2A23" } } } }, "sdfEvent": { "isPresent": { "description": "BLE advertisements", "sdfOutputData": { "sdfProtocolMap": { "ble": { "type": "advertisements" } } } }, "isConnected": { "description": "BLE connection events", "sdfOutputData": { "sdfProtocolMap": { "ble": { "type": "connection_events" } } } } } } } } ]]>