Control Operations on BLE Devices

Non-IP Control (NIPC) Open API Definition

API

Description

 
POST /control/connectivity/connect

This API is used to connect a BLE device to the network.

 
POST /control/data/read

This API is used to read a value from an attribute in the BLE device.

 
POST /control/data/write

This API is used to write a value to an attribute in the BLE device.

 
POST /control/data/discover

This API is used to discover services in a BLE device.

 
POST /control/connectivity/disconnect

This API is used to disconnect a connected BLE device from the network.

Other Supported API Types

API

Path

Summary

Register Data App

/registration/registerDataApp

Register a data application.

Unregister Data App

/registration/unregisterDataApp

Unregister a data application.

Register Topic

/registration/registerTopic

Register a publish or subscribe topic.

Unregister Topic

/registration/unregisterTopic

Unregister a publish or subscribe topic.

Subscribe Topic

/data/subscribe

Subscribe to the streaming data from an attribute in the device.

Unsubscribe Topic

/data/unsubscribe

Unsubscribe to the streaming data from an attribute in the device.

Connecting to a BLE Device

Connect Request - API Definition

Fields

Description

 
location 'https: //10.195.78.33:8081/control/connectivity/connect'

Connect a BLE device to the network.

 
header 'x-api-key: 2215dec3718288ad9028d39864f87d4c'

API key

 
header 'Content-Type: application/json'

Content type is JSON.

 
data
 
technology

BLE

 
id

Device ID

 
serviceID

Service ID of the BLE device.

 
"controlApp": "controlApplication"

Control application address

Connect Response - API Definition

Fields

Description

status

Status message

id

Device ID

requestID

Request ID

serviceID

Service ID

handle

Handle number

characteristicID

Characteristic ID

descriptorID

Descriptor ID

flags

Flags

API Example – Connect Request and Connect Response

Connect Request:


curl -k --location 'https: //10.195.78.33:8081/control/connectivity/connect' \
--header 'x-api-key: 2215dec3718288ad9028d39864f87d4c' \
--header 'Content-Type: application/json' \
--data '
{
"technology": "ble",
"id": "f837c89a-e1dd-4b90-a446-06016c0d2b75",
"ble": {
"services": [
{
"serviceID": "1800"
},
{
"serviceID": "2022"
},
{
"serviceID": "1822"
},
{
"serviceID": "180F"
}
]
},
"controlApp": "controlApplication"
}
'

Connect Response:


{
"status": "SUCCESS",
"id": "f837c89a-e1dd-4b90-a446-06016c0d2b75",
"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"
]
}
]
}
]
}

Reading from a BLE Device

Read Request - API Definition

Fields

Description

 
location 'https: //10.195.78.33:8081/control/data/read'

Read a value from an attribute in the BLE device.

 
header 'x-api-key: 2215dec3718288ad9028d39864f87d4c'

API key

 
header 'Content-Type: application/json'

Content type is JSON.

 
technology

BLE

 
id

Device ID

 
serviceID

Service ID of the BLE device.

 
characteristicID

Characteristic ID of the BLE device.

 
"controlApp": "controlApplication"

Control application address.

Read Response - API Definition

Fields

Description

status

Status message

id

Device ID

requestID

Request ID

value

Value

API Example – Read Request and Read Response

Read Request:


curl -k --location 'https: //10.195.78.33:8081/control/data/read' \
--header 'x-api-key: 2215dec3718288ad9028d39864f87d4c' \
--header 'Content-Type: application/json' \
--data '
{
"technology": "ble",
"id": "decf0dc6-9e9d-4d39-8c8b-00c541699b6a",
"ble": {
"serviceID": "1800",
"characteristicID": "2A00"
},
"controlApp": "controlApplication"
}
'

Read Response:


{
"status": "SUCCESS",
"id": " decf0dc6-9e9d-4d39-8c8b-00c541699b6a",
"requestID": "8ba846aa-6133-4392-b911-9850a90791f2",
"value": "2342432"
}

Writing to a BLE Device

Write Request - API Definition

Fields

Description

 
location 'https: //10.195.78.33:8081/control/data/write'

Write a value to an attribute in the BLE device.

 
header 'x-api-key: 2215dec3718288ad9028d39864f87d4c'

API key

 
header 'Content-Type: application/json'

Content type is JSON.

 
technology

BLE

 
id

Device ID

 
value

Value

 
serviceID

Service ID of the BLE device.

 
characteristicID

Characteristic ID of the BLE device.

 
"controlApp": "controlApplication"

Control application address.

Write Response – API Definition

Fields

Description

status

Status message

id

Device ID

requestID

Request ID

value

Value

Discovering Services from a BLE Device

Service Discovery Request - API Definition

Fields

Description

 
location 'https: //10.195.78.33:8081/control/data/discover'

Discover services in a BLE device.

 
header 'x-api-key: 2215dec3718288ad9028d39864f87d4c'

API key

 
header 'Content-Type: application/json'

Content type is JSON.

 
technology

BLE

 
id

Device ID

 
serviceID

Service ID of the BLE device.

 
"controlApp": "controlApplication"

Control application address

Service Discovery Response - API Definition

Fields

Description

status

Status message

id

Device ID

requestID

Request ID

serviceID

Service ID

handle

Handle

characteristicID

Characteristic ID

descriptorID

Descriptor ID

Flags

Flags: read, write, notify

API Example - Service Discovery Request and Service Discovery Response

Service Discovery Request:


curl -k --location 'https: //10.195.78.33:8081/control/data/discover' \
--header 'x-api-key: 2215dec3718288ad9028d39864f87d4c' \
--header 'Content-Type: application/json' \
--data '
{
"technology": "ble",
"id": "f837c89a-e1dd-4b90-a446-06016c0d2b75",
"ble": {
"services": [
{
"serviceID": "1800"
},
{
"serviceID": "2022"
},
{
"serviceID": "1822"
},
{
"serviceID": "180F"
}
]
},
"controlApp": "controlApplication"
}
'

Service Discovery Response:


{
"status": "SUCCESS",
"id": "f837c89a-e1dd-4b90-a446-06016c0d2b75",
"requestID": "d4a225b1-fc62-478e-ad54-928c8973351d",
"services": [
{
"serviceID": "1800",
"characteristics": [
{
"characteristicID": "1797",
"descriptors": [
{
"descriptorID": "7062"
}
],
"flags": [
"read",
"write",
"notify"
]
}
]
},
{
"serviceID": "2022",
"handle": 1,
"characteristics": [
{
"characteristicID": "4654",
"descriptors": [
{
"descriptorID": "8815"
}
],
"flags": [
"read",
"write",
"notify"
]
}
]
},
{
"serviceID": "1822",
"handle": 2,
"characteristics": [
{
"characteristicID": "7126",
"descriptors": [
{
"descriptorID": "4823"
}
],
"flags": [
"read",
"write",
"notify"
]
}
]
},
{
"serviceID": "180F",
"handle": 3,
"characteristics": [
{
"characteristicID": "4675",
"descriptors": [
{
"descriptorID": "9631"
}
],
"flags": [
"read",
"write",
"notify"
]
}
]
}
]
}

Disconnecting from a BLE Device

Disconnect Request - API Definition

Fields

Description

 
location 'https: //10.195.78.33:8081/control/connectivity/disconnect'

Disconnect a connected BLE device from the network.

 
header 'x-api-key: 2215dec3718288ad9028d39864f87d4c'

API key

 
header 'Content-Type: application/json'

Content type is JSON.

 
data
 
technology

BLE

 
id

Device ID

 
"controlApp": "controlApplication"

Control application address

Disconnect Response - API Definition

Fields

Description

status

Status message

id

Device ID

requestID

Request ID

API Example – Disconnect from a BLE Device

Disconnect Request:


curl -k --location 'https://10.195.78.33:8081/control/connectivity/disconnect'
\
--header 'x-api-key: 2215dec3718288ad9028d39864f87d4c' \
--header 'Content-Type: application/json' \
--data '
{
"technology": "ble",
"id" : "decf0dc6-9e9d-4d39-8c8b-00c541699b6a",
"controlApp" : "controlApplication"
}
'

Disconnect Response:


{
"status": "SUCCESS",
"id": "decf0dc6-9e9d-4d39-8c8b-00c541699b6a",
"requestID": "cb838a8d-775b-4e71-874d-1aa22e61f9af"
}