Bluetooth-rest-api (REST-BLUE)

Prerequisite:container needs to be run with following 2 options to grant access:

--net=host
--privileged

Upon startup the container will start scanning if bluetooth is powered on and upon discovering devices it will store them locally and generate an internal ID. In most cases the container will work with this locally stored devices unless the scanning is restarted. If container received command to restart scanning it will delete all previously stored devices and start scanning anew (which results in generating new local IDs for devices). Container will return 'Timeout exception' in case if it didn't get any results of processing.

For example, if you try to hit http://localhost:10500/device/mac/{mac}/services?scan=true endpoint you may get 'Timeout exception' for the following reasons:

Container provides following REST endpoints:

Set Device Identifier (POST)

This endpoint provides the possibility to set config for bluetooth-rest-api system container, upon receiving config container will wipe out all previously stored devices and restart scanning. 'name' - will tell container differentiate devices' uniqueness by localname, 'mac' - will tell container differentiate devices' uniqueness by mac address

Endpoint 1
http://localhost:10500/config/scan
POST JSON raw body
{ "deviceIdentifier" : "name"/"mac" }
Response
"New config applied. Scanning restarted"

Turn ON/OFF level of logging (POST)

This endpoint provides the possibility to turn ON/OFF DEBUG level logging (empty level value will turn off/ "DEBUG" will show excessive logs)

Endpoint 2
http://localhost:10500/config/logging
POST JSON raw body
{ "LOG_LEVEL" : "DEBUG" }
Response
"LOG_LEVEL = ${LOG_LEVEL} is applied"

Restart scanning

This endpoint sends the command to restart scanning to a container. As a result all previously stored devices will be wiped out and then the scanning will be restarted.

Endpoint 3
http://localhost:10500/scan/restart
Response
"Scanning restarted"

Get list of devices (GET)

This endpoint returns a list of discovered devices till current moment.

Endpoint 4
http://localhost:10500/devices
Response
[
  {
    "id": "TzPxHVbBnn",
    "mac-address": "fe:10:4f:c6:b9:39",
    "local-name": "Kontakt",
    "mac-id": "fe104fc6b939",
    "rssi": -74
  },
  {
    "id": "MvSG3gCXU3",
    "mac-address": "5b:d7:13:2b:f9:42",
    "mac-id": "5bd7132bf942",
    "rssi": -81
  }
]			

Get list of services (GET)

This endpoint returns a list of services discovered for specified device ID/Mac Address.

Endpoint 5
http://localhost:10500/device/iid/{ID}/services
Endpoint 6
http://localhost:10500/device/mac/{mac}/services
Response
[
  {
    "uuid": "1800",
    "name": "Generic Access",
    "type": "org.bluetooth.service.generic_access"
  },
  {
    "uuid": "1801",
    "name": "Generic Attribute",
    "type": "org.bluetooth.service.generic_attribute"
  },
  {
    "uuid": "180a",
    "name": "Device Information",
    "type": "org.bluetooth.service.device_information"
  },
  {
    "uuid": "1804",
    "name": "Tx Power",
    "type": "org.bluetooth.service.tx_power"
  },
  {
    "uuid": "180f",
    "name": "Battery Service",
    "type": "org.bluetooth.service.battery_service"
  },
  {
    "uuid": "a1ea81100e1bd4a1b84063f88c8da1ea",
    "name": null,
    "type": null
  },
  {
    "uuid": "a1ea81200e1bd4a1b84063f88c8da1ea",
    "name": null,
    "type": null
  },
  {
    "uuid": "a1ea81300e1bd4a1b84063f88c8da1ea",
    "name": null,
    "type": null
  }
]			

Get list of characteristics (GET)

This endpoint returns the list of discovered characteristics for specified service sID and device dID/Mac Address.

Endpoint 7
http://localhost:10500/device/iid/{dID}/service/{sID}/characteristics
Endpoint 8
http://localhost:10500/device/mac/{mac}/service/{sID}/characteristics
Response
[
  {
    "uuid": "2a00",
    "name": "Device Name",
    "type": "org.bluetooth.characteristic.gap.device_name",
    "properties": [
      "read"
    ]
  },
  {
    "uuid": "2a01",
    "name": "Appearance",
    "type": "org.bluetooth.characteristic.gap.appearance",
    "properties": [
      "read"
    ]
  },
  {
    "uuid": "2a04",
    "name": "Peripheral Preferred Connection Parameters",
    "type": "org.bluetooth.characteristic.gap.peripheral_preferred_connection_parameters",
    "properties": [
      "read"
    ]
 }
]			

Read characteristic's value (GET)

This endpoint reads the value from specified characteristic cID for specified service sID and device dID/Mac Address.

Endpoint 9
http://localhost:10500/device/iid/{dID}/service/{sID}/characteristic/{cID}
Endpoint 10
http://localhost:10500/device/mac/{mac}/service/{sID}/characteristic/{cID}
Response
{
  "data": "base64 encoded data"
}				

Write value to characteristic (POST)

This endpoint writes value to specified characteristic cID for specified service sID and device dID/Mac Address.

Endpoint 11
http://localhost:10500/device/iid/{dID}/service/{sID}/characteristic/{cID}
Endpoint 12
http://localhost:10500/device/mac/{mac}/service/{sID}/characteristic/{cID}
POST JSON raw body

"withresponse" isn't required (in case it's omitted the default value will be false)

{ "data" : "base64 encoded data" , "withresponse" : true }
Response
"Success writing data to characteristic id = cID"

Get list of descriptors (GET)

This endpoint returns a list of discovered descriptors for specified characteristic cID, service sID and device dID/Mac Address.

Endpoint 13
http://localhost:10500/device/id/{dID}/service/{sID}/characteristic/{cID}/descriptors
Endpoint 14
http://localhost:10500/device/mac/{mac}/service/{sID}/characteristic/{cID}/descriptors
Response
[
  {
    "uuid": "2901",
    "name": "Characteristic User Description",
    "type": "org.bluetooth.descriptor.gatt.characteristic_user_description"
  },
  {
    "uuid": "2900",
    "name": "Characteristic Extended Properties",
    "type": "org.bluetooth.descriptor.gatt.characteristic_extended_properties"
  }
]			

Read the value from descriptor (GET)

This endpoint reads the value from specified descriptor dsID for specified characteristic cID, service sID and device dID/Mac Address.

Endpoint 15
http://localhost:10500/device/iid/{dID}/service/{sID}/characteristic/{cID}/descriptor/{dsID}
Endpoint 16
http://localhost:10500/device/mac/{mac}/service/{sID}/characteristic/{cID}/descriptor/{dsID}
Response
{
  "data": "base64 encoded data"
}			

Subscribe to characteristic's notify event (GET)

This endpoint sets notify property to true for specified characteristic's cID for specified service sID and device dID/Mac Address and returns url where buffered values can be picked up. If timeout parameter is specified (in millisecond) it'll be applied, otherwise REST-Blue will use the default value 1 min (60000 milliseconds). This timeout is specified to handle usecase when device is still connected and advertising, but REST-Blue stopped receiving any data on notify subscription. When picking up buffered notify data:

Endpoint 17
http://localhost:10500/device/iid/{dID}/service/{sID}/characteristic/{cID}/notify??timeout=TIME_MILLISEC
Endpoint 18
http://localhost:10500/device/mac/{mac}/service/{sID}/characteristic/{cID}/notify
Response
{
  "message": "Notification is turned ON for characteristic uuid = CH_ID ",
  "url": "notify_buffer/BUFFER_GENERATEDID"
}			

Check status of Bluetooth Adapter (GET)

This endpoint return the status of Bluetooth Adapter: if it's powered on/off (true/false).

Endpoint 19
http://localhost:10500/status
Response
{
  "bluetooth_adapter_powered_on": true/false
}			
NOTES:

For endpoints 5-18 all the operations will be performed with previously scanned devices (the scanning starts upon container's start).

Parameters for endpoints 5-18:

scan=true : This parameter will tell REST Blue to stop scanning, clean up previously stored devices and start scan again and look for specified in the URL device.

drct=1000 : Device reconnect timeout. Default value = 1000 milliseconds. This parameter is specified in milliseconds, it's a timeout that REST Blue will wait to reconnect to device after receiving disconnect event for this device. REST Blue will try to reconnect only if it was subscribed on device's notifications and is storing data for 'NOTIFY Buffer' functionality.

drca=5 : Device reconnect attempts. Default value = 5 attempts. This parameter specifies how many attempts REST Blue should make to reconnect to device in case it lost connection while being subscribed to data notifications.