Cisco Sensor Connect for IoT Services Programmability Guide

Use Case 2 - Remote Patient Health Monitoring (requiring BLE connection, reading, and writing)

In this use case, you can:

Onboard a device.
Connect to the device.
Perform service discovery.
Write a characteristic.
Read the characteristic.
Disconnect from the device.

The following workflow covers the sequence of operations:

Onboard a device using the SCIM API.
Connect to the device and discover GATT services using the NIPC Connect API.
Write a GATT characteristic to the device using the Data Write API.
Read a GATT characteristic to the device using the Data Read API.
Disconnect the device from the AP using the NIPC Disconnect API.

Onboarding a Device

API Definition


API	Description
`POST /scim/v2/Devices`	This is the API for onboarding a device.

Request Format for Onboarding the Device without Pairing


curl -k --location 'https://173.39.84.53:8081/scim/v2/Devices' \
--header 'Content-Type: application/json' \
--header 'x-api-key: 596f0eba1668e6afeb3b25669990b7d84b8bf70408f21465a05e227664763024' \
--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": "CA:2B:5C:EC:95:46",
        "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: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 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": "79ca0f72-4ae2-436a-8bd4-24a2770faa83",
  "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": {},
    "urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device": {
      "key": 0
    },
    "urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device": {
      "key": 0
    },
    "urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device": {
      "key": "",
      "randNumber": 0,
      "confirmationNumber": 0
    }
  },
  "urn:ietf:params:scim:schemas:extension:endpointAppsExt:2.0:Device": {
    "onboardingUrl": "onboardApplication",
    "deviceControlUrl": [
      "controlApplication"
    ],
    "dataReceiverUrl": []
  }
}

Request Format for Onboarding the Device with Pairing


curl -k --location 'https://173.39.84.53:8081/scim/v2/Devices' \
--header 'Content-Type: application/json' \
--header 'x-api-key: 596f0eba1668e6afeb3b25669990b7d84b8bf70408f21465a05e227664763024' \
--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": "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:pairingNull:2.0:Device": null,
        "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": "79ca0f72-4ae2-436a-8bd4-24a2770faa83",
  "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:pairingNull:2.0:Device": {},
    "urn:ietf:params:scim:schemas:extension:pairingJustWorks:2.0:Device": {
      "key": 0
    },
    "urn:ietf:params:scim:schemas:extension:pairingPassKey:2.0:Device": {
      "key": 0
    },
    "urn:ietf:params:scim:schemas:extension:pairingOOB:2.0:Device": {
      "key": "",
      "randNumber": 0,
      "confirmationNumber": 0
    }
  },
  "urn:ietf:params:scim:schemas:extension:endpointAppsExt:2.0:Device": {
    "onboardingUrl": "onboardApplication",
    "deviceControlUrl": [
      "controlApplication"
    ],
    "dataReceiverUrl": []
  }
}

Connecting to a Device

To connect to a BLE device and discover its services, perform the following:

Use the Device ID:

The device ID is "f837c89a-e1dd-4b90-a446-06016c0d2b75".
Connect the BLE device from the AP:

Use the device ID to establish a connection with the BLE device from the AP.
Discover Services:

Discover the services with the following service UUIDs:
- 1800
- 2002
- 1822
- 180F

API Definition


API	Description
`/control/connectivity/connect`	This API is used to connect to a device.

Request Format


{
    "technology": "ble",
    "id": "79ca0f72-4ae2-436a-8bd4-24a2770faa83",
    "ble": {
        "services": [
            {
                "serviceID": "1800"
            },
            {
                "serviceID": "2022"
            },
            {
                "serviceID": "1822"
            },
            {
                "serviceID": "180F"
            }
        ]
    },
    "controlApp": "controlApplication"
}

Response Format


{
  "status": "SUCCESS",
  "id": "79ca0f72-4ae2-436a-8bd4-24a2770faa83",
  "services": [
    {
      "serviceID": "1800",
      "characteristics": [
        {
          "characteristicID": "6367",
          "descriptors": [
            {
              "descriptorID": "7751"
            }
          ],
          "flags": [
            "read",
            "write",
            "notify"
          ]
        }
      ]
    },
    {
      "serviceID": "2022",
      "handle": 1,
      "characteristics": [
        {
          "characteristicID": "3670",
          "descriptors": [
            {
              "descriptorID": "7929"
            }
          ],
          "flags": [
            "read",
            "write",
            "notify"
          ]
        }
      ]
    },
    {
      "serviceID": "1822",
      "handle": 2,
      "characteristics": [
        {
          "characteristicID": "2198",
          "descriptors": [
            {
              "descriptorID": "5622"
            }
          ],
          "flags": [
            "read",
            "write",
            "notify"
          ]
        }
      ]
    },
    {
      "serviceID": "180F",
      "handle": 2,
      "characteristics": [
        {
          "characteristicID": "2198",
          "descriptors": [
            {
              "descriptorID": "5622"
            }
          ],
          "flags": [
            "read",
            "write",
            "notify"
          ]
        }
      ]
    }
  ],
  "requestID": "251ea636-8708-43b0-b8f8-438332098c9d",
  "reason": "NO_INFO"
}

Writing a Characteristic to the Device

API Definition


API	Description
`/control/data/write`	This API is used to write a characteristic to the device.

Request Format


{
    "technology": "ble",
    "id": "79ca0f72-4ae2-436a-8bd4-24a2770faa83",
    "value": "0001",
    "ble": {
        "serviceID": "1800",
        "characteristicID": "2A00"
    },
    "controlApp": "controlApplication"
}

Response Format


{
  "status" : "SUCCESS",
  "id" : "79ca0f72-4ae2-436a-8bd4-24a2770faa83",
  "requestID" : "621f4b8c-c1eb-461f-ac2d-818a9193f10e"
}

Reading a Characteristic to the Device

API Definition


API	Description
`/control/data/read`	This API is used to read a characteristic to the device.

Request Format


{
    "technology": "ble",
    "id": "79ca0f72-4ae2-436a-8bd4-24a2770faa83",
    "ble": {
        "serviceID": "1800",
        "characteristicID": "2A00"
    },
    "controlApp": "controlApplication"
}

Response Format


{
  "status" : "SUCCESS",
  "id" : "79ca0f72-4ae2-436a-8bd4-24a2770faa83",
  "value" : "2342432",
  "requestID" : "7245ed08-11ff-4a3d-a023-9fe8c8fec89f"
}

Disconnecting the Device

API Definition


API	Description
`/control/connectivity/disconnect`	This API is used to disconnect the device.

Request Format


{
    "technology": "ble",
    "id" : "79ca0f72-4ae2-436a-8bd4-24a2770faa83",
    "controlApp" : "controlApplication"
}

Response Format


{
  "status" : "SUCCESS",
  "id" : "79ca0f72-4ae2-436a-8bd4-24a2770faa83",
  "requestID" : "d1ef1fdf-d70b-4674-bb09-ff85870ad18d"
}

Bias-Free Language

Book Title

Cisco Sensor Connect for IoT Services Programmability Guide

Chapter Title

Use Case 2 - Remote Patient Health Monitoring

Results

Chapter: Use Case 2 - Remote Patient Health Monitoring

Use Case 2 - Remote Patient Health Monitoring

Use Case 2 - Remote Patient Health Monitoring (requiring BLE connection, reading, and writing)

Onboarding a Device

API Definition

Request Format for Onboarding the Device without Pairing

Response Format for Onboarding the Device without Pairing

Request Format for Onboarding the Device with Pairing

Response Format for Onboarding the Device with Pairing

Connecting to a Device

API Definition

Request Format

Response Format

Writing a Characteristic to the Device

API Definition

Request Format

Response Format

Reading a Characteristic to the Device

API Definition

Request Format

Response Format

Disconnecting the Device

API Definition

Request Format

Response Format

Was this Document Helpful?

Contact Cisco