Onboarding BLE Devices using SCIM

SCIM API Definition

API for Onboarding Device

Description

 
POST /scim/v2/Devices

This is the API used for onboarding a BLE device using SCIM.

 
GET /scim/v2/Devices/{id}?onboardApp={onboardAppID}
 
DELETE /scim/v2/Devices/{id}?onboardApp={onboardAppID}

SCIM HTTP Methods

The SCIM protocol specifies end points and HTTP methods to manage resources.

The following are the supported HTTP methods:

HTTP Method

SCIM Usage

GET

Retrieve a resource.

POST

Create a new resource.

DELETE

Deletes a resource.

SCIM API Resource and Versions

The resource and endpoint supported in the SCIM APIs are Device and /Devices respectively.

The URL path covers the base URL and version identifier as a segment. The SCIM APIs support v2 as the version identifier.

/scim/v2/Devices are the SCIM API resource and version supported for HTTP POST, GET, or DELETE.

SCIM Schema

SCIM Core Device Schema

The SCIM core device schema supports the following attributes:

Attributes

Description

Sample

schemas

The schemas section of the SCIM APIs cover the list of schemas part of the API requests.

The following are the supported schemas:

  • Core device schema

  • BLE device extension schema

  • Endpoint application extension schema

 

"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

The attribute is of “string” type and provides a human-readable name for a device.

 
"deviceDisplayName": "BLE Heart Monitor",

adminState

The attribute is of “Boolean” type and is a mutable attribute.

If adminState is set to TRUE, connect, disconnect, and subscribe commands that control app sends to the controller for the devices will be processed by the application.

If adminState is set to FALSE, any command coming from the control app for the device will be rejected by the application. 

"adminState": true,

BLE Device Extension Schema

The SCIM device extension schema supports the following attributes:

Attributes

Description

Sample

DeviceMacAddress

  • Is a string value that represents a public MAC address assigned by the manufacturer.

  • It is a unique 48-bit value.

  • It is required, case-sensitive, mutable, and returned as default.

  • The following is the regex pattern: 

    ^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}$
 
"deviceMacAddress": "CA:2B:5C:EC:95:46",

isRandom

  • Is a Boolean flag.

  • If set to FALSE, the device uses a public MAC address.

  • If set to TRUE, the device uses a static random MAC address.

  • This attribute is not required, mutable, and returned by default.

  • The default value is FALSE. 

"isRandom": false,

versionSupport

  • Provides all the BLE versions supported by the device in the form of an array.

  • For example, [4.1, 4.2, 5.0, 5.1, 5.2,5.3].

  • This attribute is required, mutable, and returned as default.

 
"versionSupport": [
"5.3"
],

pairingMethods

  • Is an array of pairing methods associated with the BLE device.

  • May require sub-attributes, such as key or password for the device pairing process.

  • This attribute is required, case-sensitive, mutable, and returned by default.

 

"pairingMethods": [
"urn:ietf:params:scim:schemas:extension:pairingNull:2.0:Device",
"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
}

mobility

  • Is a Boolean flag.

  • When set to FALSE, this feature disables seamless movement between APs, requiring manual intervention for the IoT Orchestrator to handle connections and disconnections.

  • When set to TRUE, this feature allows devices to move between APs seamlessly, with the IoT Orchestrator automatically handling connections and disconnections without manual intervention.

  • This attribute is not required, mutable, and returned by default.

  • The default value is FALSE.

 
"mobility": true,

API Example

The following example lists the SCIM object for onboarding the BLE device:


{
  "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: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": []
  }
}