Use Case 3 - BLE Notification-based Use Cases

Use Case 3 - BLE Notification-Based Use Cases

A BLE device can have multiple services and each service can have multiple characteristics. For BLE notification, you can register the topic and subscribe for a specific service or characteristic ID for which the notification needs to be received. In this case, the best example is to subscribe for BLE GATT notification.

In this use case, you will be able to onboard a device, register a topic, connect to a device, and subscribe for notification.

Here, the sample use case is that of a Pulse Oximeter. A Pulse Oximeter is a medical device that non-invasively measures the oxygen saturation level (SpO2) of a person’s blood and pulse rate. The Pulse Oximeter is a small portable device commonly used in hospitals, clinics, and home to monitor patients with respiratory or cardiovascular conditions.

The following are the GATT attributes associated with the Pulse Oximeter:

  1. Oxygen level

  2. Heart rate

The following workflow covers the sequence of operations:

  1. Onboard a BLE device using the SCIM API.

  2. Register a topic with the gateway.

  3. Connect to the device and discover GATT services using the NIPC Connect API.

  4. Start the GATT notifications or indications using the NIPC Data Subscribe API.

  5. Subscribe to the topic from the data receiver application.

Onboarding the BLE Device

API Definition

API

Description

 
POST /scim/v2/Devices

This API is used to onboard the BLE device.

Request Format for Onboarding the Device without Pairing


curl -k --location 'https: //10.195.78.33:8081/scim/v2/Devices' \
--header 'x-api-key: 5a9095d0457f24518bba93c50d69efe5' \
--header 'Content-Type: application/json' \
--data '
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Device",
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device",
"urn:ietf:params:scim:schemas:extension:endpointapps:2.0:Device"
],
"deviceDisplayName": "BLE Heart Monitor",
"adminState": true,
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device": {
"versionSupport": [
"5.3"
],
"deviceMacAddress": "EF:00:00:00:00:00",
"isRandom": false,
"mobility": false,
"pairingMethods": [
"urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device"
],
"urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device": null
},
"urn:ietf:params:scim:schemas:extension:endpointAppsExt:2.0:Device": {
"onboardingUrl": "onboardApplication",
"deviceControlUrl": [
"controlApplication"
],
"dataReceiverUrl": []
}
}
'

Response Format for Onboarding the Device without Pairing


{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Device",
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device",
"urn:ietf:params:scim:schemas:extension:endpointapps:2.0:Device"
],
"id": " df553860-975c-4d7f-8c1f-b2996f34e26f",
"deviceDisplayName": "BLE Heart Monitor",
"adminState": true,
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device": {
"versionSupport": [
"5.3"
],
"deviceMacAddress": "CA:2B:5C:EC:95:46",
"isRandom": false,
"pairingMethods": [
"urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device"
],
"mobility": false,
"urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device": null
},
"urn:ietf:params:scim:schemas:extension:endpointAppsExt:2.0:Device": {
"onboardingUrl": "onboardApplication",
"deviceControlUrl": [
"controlApplication"
],
"dataReceiverUrl": []
}
}

Request Format for Onboarding the Device with Pairing


{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Device",
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device",
"urn:ietf:params:scim:schemas:extension:endpointapps:2.0:Device"
],
"deviceDisplayName": "BLE Heart Monitor",
"adminState": true,
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device": {
"versionSupport": [
"5.3"
],
"deviceMacAddress": "CA:2B:5C:EC:95:46",
"isRandom": false,
"mobility": true,
"pairingMethods": [
"urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device"
],
"urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device": {
"key": null
}
},
"urn:ietf:params:scim:schemas:extension:endpointAppsExt:2.0:Device": {
"onboardingUrl": "onboardApplication",
"deviceControlUrl": [
"controlApplication"
],
"dataReceiverUrl": []
}
}

Response Format for Onboarding the Device with Pairing


{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Device",
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device",
"urn:ietf:params:scim:schemas:extension:endpointapps:2.0:Device"
],
"id": "df553860-975c-4d7f-8c1f-b2996f34e26f",
"deviceDisplayName": "BLE Heart Monitor",
"adminState": true,
"urn:ietf:params:scim:schemas:extension:ble:2.0:Device": {
"versionSupport": [
"5.3"
],
"deviceMacAddress": "CA:2B:5C:EC:95:46",
"isRandom": false,
"pairingMethods": [
"urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device"
],
"mobility": true,
"urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device": {
"key": null
}
},
"urn:ietf:params:scim:schemas:extension:endpointAppsExt:2.0:Device": {
"onboardingUrl": "onboardApplication",
"deviceControlUrl": [
"controlApplication"
],
"dataReceiverUrl": []
}
}

Registering a Topic

You can register the topic "enterprise/hospital/pulse_oximeter" with the gateway to subscribe to GATT notifications from the device ID "df553860-975c-4d7f-8c1f-b2996f34e26f", service UUID "1800", and characteristic UUID "2A5E".

API Definition

API

Description

 
/control/registration/registerTopic

This API is used to register a topic with the gateway to subscribe to GATT notifications from the device.

Request Format


{
"technology": "ble",
"ids": [
"df553860-975c-4d7f-8c1f-b2996f34e26f",
],
"controlApp": "controlApplication",
"topic": "enterprise/hospital/pulse_oximeter",
"dataFormat": "default",
"ble": {
"type": "gatt",
"serviceID": "1800",
"characteristicID": "2A5E"
}
}

Response Format


{
"status": "SUCCESS",
"topic": "enterprise/hospital/pulse_oximeter",
"isOnboarded": true
}

Connecting to a BLE Device from an AP

API Definition

API

Description

 
/control/connectivity/connect

This API is used to connect to the BLE device from the AP and discover the services with service UUIDs 1800, 2022, 1822, and 180F.

Request Format


{
"technology": "ble",
"id": "df553860-975c-4d7f-8c1f-b2996f34e26f",
"ble": {
"services": [
{
"serviceID": "1800"
},
{
"serviceID": "2022"
},
{
"serviceID": "1822"
},
{
"serviceID": "180F"
}
]
},
"controlApp": "controlApplication"
}

Response Format


{
"status": "SUCCESS",
"id": "df553860-975c-4d7f-8c1f-b2996f34e26f",
"requestID": "75310f89-79c6-4e7b-93cb-f58a8f18fc57",
"services": [
{
"serviceID": "1800",
"characteristics": [
{
"characteristicID": "3443",
"descriptors": [
{
"descriptorID": "9059"
}
],
"flags": [
"read",
"write",
"notify"
]
}
]
},
{
"serviceID": "2022",
"handle": 1,
"characteristics": [
{
"characteristicID": "8065",
"descriptors": [
{
"descriptorID": "9620"
}
],
"flags": [
"read",
"write",
"notify"
]
}
]
},
{
"serviceID": "1822",
"handle": 2,
"characteristics": [
{
"characteristicID": "8912",
"descriptors": [
{
"descriptorID": "1554"
}
],
"flags": [
"read",
"write",
"notify"
]
}
]
},
{
"serviceID": "180F",
"handle": 3,
"characteristics": [
{
"characteristicID": "2810",
"descriptors": [
{
"descriptorID": "1517"
}
],
"flags": [
"read",
"write",
"notify"
]
}
]
}
]
}

Starting Notifications

API Definition

API

Description

 
/control/data/subscribe

This API enables the GATT notifications in the device using the device ID, GATT service UUID, and characteristic UUID.

Request Format


{
"technology": "ble",
"id": "df553860-975c-4d7f-8c1f-b2996f34e26f",
"ble": {
"serviceID": "1800",
"characteristicID": "2A5E"
},
"controlApp": "controlApplication"
}

Response Format


{
"status": "SUCCESS",
"id": "df553860-975c-4d7f-8c1f-b2996f34e26f",
"requestID": "12345678-5678-1234-5578-abcdef1234"
}

MQTT Subscription Messages

Once the notification is enabled using the subscribe API, the data receiver application starts receiving the GATT notifications once it subscribes to the registered topic. 


mosquitto_sub -h localhost -p 41883 -t enterprise/hospital/pulse_oximeter -u
https://dataApplication --pw c4e80e0483af0a4394dfb6e3ec5e820b
$26efb024-a052-4279-9b06-5f17e00d84401028f90
18002A5E
$26efb024-a052-4279-9b06-5f17e00d84401028f90
18002A5E
$26efb024-a052-4279-9b06-5f17e00d84401028f90
18002A5E
$26efb024-a052-4279-9b06-5f17e00d84401028f90
18002A5E
$26efb024-a052-4279-9b06-5f17e00d84401028f90
18002A5E