RESTful API - CassiaNetworks/CassiaSDKGuide GitHub Wiki

Most of the Bluetooth GAP/GATT operations are exposed in RESTful APIs. The signatures of those APIs are fully compliant with Bluetooth SIG’s Internet Working Group RESTful API specification.

NOTE: If you are accessing the RESTful API from the container, use the container static address: 10.10.10.254

NOTE: SSE streams are limited to about 20-30 per gateway. If too many SSE streams are opened at a given time, you may receive a 500 error due to not having enough resources on the gateway system. It's strongly recommended to close the SSE connection (by closing the stream explicitly). Sometimes, libraries have a close call like .close() to explicitly close a stream. Others may close the stream automatically after exiting the SSE handler.

NOTE: When using the /cassia/* APIs in Standalone Router mode, you may need to log in to the gateway first. To do so, send a POST request with the following instructions:

Make sure the request header contains:

Content-Type: application/x-www-form-urlencoded

The form data should contain the username and password of the gateway login. For example:

username=admin&password=admin2

Send the POST request to the login API. For example:

http://{gateway ip}/cassia/login

After the POST request returns a 200 OK response, you should be able to call the /cassia/* APIs without getting a Login page HTML response.

NOTE: Starting from version 2.1.1, logins have adopted a front-end encryption method. In case you need to call this login API, please consult Cassia technical support for more details.

Common Parameters

Here are common parameters for the RESTful API:

Parameter	Description
`mac`	The mac address of a Cassia gateway (e.g. CC:1B:E0:E0:24:B4).
`node`	The mac address of a BLE device (e.g. EF:F3:CF:F0:8B:81).
`handle`	After you find the device services, based on the device’s Bluetooth profile, you can identify its corresponding handle index in the UUID (e.g. 37).
`value`	the hex value written into the handle (e.g. FF000C00).
`chip`	(Optional) 0 or 1, indicates which chip of the Cassia gateway is used for scan and connect. By default, the gateway will pick up the chip automatically based on an internal algorithm. S Series gateways only support chip 0, X1000/E1000/C1000 supports 0 and 1.

NOTE: In this wiki, we will refer the gateway's MAC address as <gateway-mac>.

Management API

Obtain Cassia Router’s Configuration

You can use the API below to obtain the configuration of a gateway, including its IP address, model, version, etc.

NOTE: Since v2.0.2, the container status has been removed from the default cassia/info API output to avoid the problem of oversized UDP packets. The container status information is available through the fields=container parameter. The fields=container JSON output has the same JSON structure as the previous (v1.4.x and older) container status section of the cassia/info JSON output. To get the container status information, add the parameter fields=container to the API URL like (for AC API):

http://{your AC domain}/api/cassia/info?mac=<gateway-mac>&fields=container

AC Managed:

GET http://{your AC domain}/api/cassia/info?mac=<gateway-mac>

Local:

GET http://{gateway ip}/cassia/info

Container:

GET http://10.10.10.254/cassia/info

Parameter	Description
`fields`	(Optional): type of field to return from the gateway's configuration information. The field `container` returns the container status information. Currently, only the value `container` is accepted.

The return result is a JSON object.

Configuration Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

{
   "capwap-uplinkmac":"CC:1B:E0:E7:FD:84",
   "cpu":{
      "used":158,
      "total":2184
   },
   "mem":{
      "used":103508,
      "total":225716
   },
   "capwap-state":"7n",
   "timeconf":{
      "now":"2018-09-07 09:56:42",
      "ntp2":"stdtime.gov.hk",
      "auto":true,
      "ntp1":"time.nist.gov"
   },
   "timezone":"Asia/Shanghai",
   "chipinfo":{
      "1":{
         "adv_en":"0",
         "ant":"0",
         "max":11,
         "scan_type":"0",
         "ver":"7",
         "addr":"CC:EB:E0:19:88:1F",
         "scan_en":"0",
         "status":"Idle",
         "speed":{
            "rx":0,
            "tx":0
         },
         "id":"1"
      },
      "0":{
         "adv_en":"0",
         "ant":"0",
         "max":11,
         "scan_type":"0",
         "ver":"7",
         "addr":"CC:EB:E0:19:88:1E",
         "scan_en":"0",
         "status":"Idle",
         "speed":{
            "rx":0,
            "tx":0
         },
         "id":"0"
      }
   },
   "conn_params":{
      "type":0,
      "latency":0,
      "conn_max_intval":30,
      "supvtimeout":1000,
      "conn_min_intval":7.5,
      "scan_window":30,
      "scan_intval":60
   },
   "mqtt_stat":{
      "e":[
         0,
         0,
         0,
         0,
         0,
         0,
         0,
         0,
         0,
         0,
         0,
         0,
         0,
         0,
         0,
         0
      ],
      "d":0,
      "s":0,
      "f":0
   },
   "wireless":{
      "proto":"static",
      "dns":"",
      "dns2":"",
      "netmask":"255.255.255.0",
      "ip":"192.168.40.1",
      "password":"cassia-E7FD84",
      "speed":{
         "rx":0,
         "tx":0
      },
      "iface":{
         "mac":"CC:1B:E0:E7:FD:85",
         "mtu":"1500",
         "netmask":"255.255.255.0",
         "ip":"192.168.40.1",
         "tx":"428",
         "name":"wlan0",
         "metric":"0",
         "rx":"0",
         "bcast":"192.168.40.255"
      },
      "country":"US",
      "gateway":"",
      "mode":"ap",
      "ssid":"cassia-E7FD84",
      "dns1":""
   },
   "sshlogin":"1",
   "ble_power":20,
   "sqs_stat":{
      "e":[
         0,
         0,
         0,
         0,
         0,
         0
      ],
      "d":0,
      "s":0,
      "f":0
   },
   "fat":"0",
   "mac":"CC:1B:E0:E7:FD:84",
   "container":{
      "disk":{
         "used":"1.0G",
         "total":"2.3G"
      },
      "kernel":"Ubuntu 16.04.3 LTSn",
      "iface":{
         "mac":"FE:EB:E0:BE:E0:62",
         "mtu":"1500",
         "tx":"636",
         "name":"vethBU791K",
         "metric":"0",
         "rx":"568"
      },
      "cpu":{
         "used":205,
         "total":2204
      },
      "status_code":3,
      "process":"USER PID %CPU %MEM VSZ RSS TTY STATSTART TIME COMMANDnroot 1 0.0 0.4 2612 1056 pts/0 Ss+ 01:55 0:00 /bin/bash/root/start.shnroot 71 0.0 0.3 7980 848 ? Ss 01:55 0:00 /usr/sbin/sshdnroot 86 7.1 10.5118496 23852 ? Ssl 01:55 0:04 PM2 v2.10.1: God Daemon (/root/.pm2)nroot 99 0.0 0.6 27081360 pts/0 S+ 01:55 0:00 /bin/bashnroot 133 0.0 0.4 4740 1124 ? R 01:56 0:00 psauxn",
      "apps":{

      },
      "speed":{
         "rx":0,
         "tx":0
      },
      "mem":{
         "used":52350976,
         "total":134217728
      },
      "status":"running"
   },
   "capwapuplink":"wired",
   "ac":{
      "port":"5246,5247",
      "user":"",
      "control_port":"5246",
      "data_port":"5247",
      "force_network":"1",
      "address":""
   },
   "capwap-ip":"168.168.20.154n",
   "https":"0",
   "dongle":{
      "keepalive":"",
      "ifname":"ppp0",
      "dialnumber":"*99#",
      "service":"umts",
      "defaultroute":"",
      "username":"",
      "pincode":"",
      "apn":"3gnet",
      "metric":"5",
      "proto":"3g",
      "dns":"",
      "device":"/dev/ttyUSB0",
      "maxwait":"",
      "password":"",
      "ipv6":"",
      "type":"none",
      "demand":"",
      "peerdns":""
   },
   "scan":{
      "one_scan_time":"300",
      "scan_interval":"15",
      "scan_window":"10"
   },
   "wired":{
      "duplex":"full",
      "proto":"dhcp",
      "speed":{
         "rx":0.381,
         "tx":0.2376
      },
      "iface":{
         "mac":"CC:1B:E0:E7:FD:84",
         "mtu":"1500",
         "netmask":"255.255.255.0",
         "ip":"168.168.20.30",
         "tx":"27746",
         "name":"eth0",
         "metric":"1",
         "rx":"31793",
         "bcast":"168.168.20.255"
      },
      "trans_speed":"100"
   },
   "chip-params":"1",
   "version":"1.3.0.18070301"
}

Obtain Cassia Router’s Status (Through AC)

You might use the API below to obtain the status of a gateway, either online or offline.
NOTE: This API is only available through Cassia AC.

GET http://{your AC domain}/api/cassia/hubs/<gateway-mac>

The return result is a JSON object.

[Online] Status Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

{
    "_id": "5a9497eeadc22500524e27e5",
    "id": "CC:1B:E0:E0:DF:80",
    "mac": "CC:1B:E0:E0:DF:80",
    "name": "NewBootloader",
    "group": "SJCLab",
    "status": "online",
    "model": "E1000",
    "version": "1.2.1.1803121427",
    "position": "",
    "time": 1519687662258,
    "ip": "96.64.240.30",
    "localip": "192.168.0.106",
    "uptime": 807183,
    "offline_time": 1523468797,
    "online_time": 1523468804,
    "update_status": "update_ok",
    "update_reason": "",
    "update_version": "1.2.1.1803121427",
    "update_progress": 100,
    "groupcolor": "undefined"
}

[Offline] Status Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

{
    "_id": "5a9f5bb26d48ab005290b45f",
    "id": "CC:1B:E0:E0:61:9C",
    "mac": "CC:1B:E0:E0:61:9C",
    "name": "CassiaRouter",
    "group": "",
    "status": "offline",
    "model": "C1000",
    "version": "1.2.2.1801101456",
    "position": "",
    "time": 1520393138130,
    "ip": "73.202.248.99",
    "localip": "192.168.1.106",
    "uptime": 1708,
    "offline_time": 1520893570,
    "online_time": 1520891832,
    "update_status": "update_ok",
    "update_reason": "",
    "update_version": "",
    "update_progress": 0
}

Monitor Cassia Router’s Status (Through AC)

You can use this API to monitor the status of a gateway continuously.

NOTE: This API is a Server-Sent Events (SSE) API and is only available through Cassia AC.

GET http://{your AC domain}/api/cassia/hubStatus

The return result is a JSON object.

[Online] Monitor Status Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

{
    "model": "X1000",
    "ip": "96.64.240.30",
    "mac": "CC:1B:E0:E0:98:50",
    "version": "1.1.1.1710261111",
    "uptime": 0,
    "user": "tester",
    "localip": "192.168.0.105",
    "whitelist": true,
    "status": "online"
}

[Offline] Monitor Status Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

data:
{
    "mac": " CC:1B:E0:E0:98:50",
    "status": "offline"
}

Obtain All Online Routers’ Status (Through AC)

NOTE: This API is only available through Cassia AC.

GET http://{your AC domain}/api/cassia/hubs

The return result is an array of JSON objects.

Status Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

[{
        "_id": "5a9497eeadc22500524e27e5",
        "id": "CC:1B:E0:E0:DF:80",
        "mac": "CC:1B:E0:E0:DF:80",
        "name": "New Bootloader",
        "group": "ExampleLab",
        "status": "online",
        "model": "E1000",
        "version": "1.4.0.1901300130",
        "position": "",
        "time": "1519687662258",
        "ip": "96.64.240.30",
        "localip": "192.168.0.106",
        "uptime": 801523,
        "offline_time": 1523468797,
        "online_time": 1523468804,
        "update_status": "update_ok",
        "update_reason": "",
        "update_version": "1.4.0.1901300130",
        "update_progress": 100,
        "groupcolor": "undefined"
    },
    {
        "_id": "1a3447egadc24570524a27d1",
        "id": "CC:1B:E0:E0:FA:52",
        "mac": "CC:1B:E0:E0:FA:52",
        "name": "New Bootloader",
        "group": "AnotherLab",
        "status": "online",
        "model": "X1000",
        "version": "1.4.0.1901300130",
        "position": "",
        "time": "1519687662258",
        "ip": "62.134.231.112",
        "localip": "192.168.0.96",
        "uptime": 800215,
        "offline_time": 1523461324,
        "online_time": 1523467810,
        "update_status": "update_ok",
        "update_reason": "",
        "update_version": "1.4.0.1901300130",
        "update_progress": 100,
        "groupcolor": "undefined"
    }
]

Reboot a Router Remotely

AC Managed:

POST http://{your AC domain}/api/cassia/reboot?mac=<gateway-mac>

Local:

POST http://{gateway ip}/cassia/reboot

Container:

POST http://10.10.10.254/cassia/reboot

Traffic Related API

Scan Bluetooth Devices

To use the gateway to scan Bluetooth Low Energy (BLE) devices through your AC:

AC Managed:

GET http://{your AC domain}/api/gap/nodes?event=1&mac=<gateway-mac>

Local:

GET http://{gateway ip}/gap/nodes?event=1

Container:

GET http://10.10.10.254/gap/nodes?event=1

This API is a Server-Sent Events (SSE) which will be running continuously. Here are more optional parameters:

Parameter	Description
`active`	(Optional): 0 or 1, 0 indicates passive scanning and 1 active scanning. If you don't specify, by default the Cassia gateways will perform passive scanning.
`filter_duplicates`	(Optional): 0 or 1, 0 to turn off and 1 to turn on; filters duplicated records. Default is 0. >1000 (ms) timer to restart duplicate filter.
`connectable`	(Optional): filter connectable device, which the evtType of scan data is equal 0 or 4.
`report_interval`	(Optional): report scan data based on interval. the value of interval should equal or greater than 1000 (ms).
`timestamp`	(Optional): 0 or 1， default is 0， 1 adds a timestamp in the scan data, for example: data: {"name":"CASSIA-BEACON-335","timestamp":"2021-03-08 10:07:17.723 CST","evtType":0,"rssi":-69,"adData":"02010612094341535349412D424541434F4E2D333335","bdaddrs":[{"bdaddr":"CC:DD:EE:03:00:23","bdaddrType":"random"}]}
`beacon`	(Optional): 0 or 1, default is 0, 1 add beacon data in the scan data, for example: data: {"name":"(unknown)","beacon":{"type":"iBeacon","UUID":"B9407F30-F5F8-466E-AFF9-25556B57FE6D","minor":10,"major":73,"txPower":-58},"evtType":0,"rssi":-17,"adData":"0201061AFF4C000215B9407F30F5F8466EAFF925556B57FE6D0049000AC5","bdaddrs":[{"bdaddr":"CC:1B:EF:E2:31:C2","bdaddrType":"public"}]}. iBeacon, Eddystone-EID, Eddystone-UID, Eddystone-TLM, Eddystone-URL are supported.
`chip`	(Optional): 0, 1 or all(supported after version 2.1.1), indicates which chip of the Cassia gateway is used for scan

scan filter	notes	gateway scan support	AC combine SSE support	AC auto selection support
filter_uuid		1.3	1.4.3	2.0.3
filter_rssi		1.3	1.4.3	2.0.3
filter_mac	exact match	1.3	1.4.3	2.0.3
	prefix	2.0.3	2.0.3	2.0.3
filter_name	exact match	1.3	1.4.3	2.0.3
	prefix,suffix	2.0.3	2.0.3	2.0.3
filter_value	w/ offset	2.0.3	2.0.3	2.0.3
	w/o offset	2.1.1	2.1.1	2.1.1
	multiple values	2.1.1	2.1.1	2.1.1
filter_duplicates	=1	1.3	2.1.1	2.0.3
	>1000ms	2.0.3	2.1.1	2.0.3
timestamp		2.0.3	2.1.1
connectable		2.1.1	2.1.1	2.1.1
report_interval		2.1.0	2.1.1	2.1.0
beacon		2.1.1
ibeacon/eddystone		2.1.1

Filter Scanned Data based on Device MAC, RSSI, Name, and UUID

This API can significantly reduce the amount of packets sent from the gateway to the server.

NOTE: Multiple filters can be used at the same time. Scanned data is returned if all conditions are met. The wildcard is not supported.

NOTE: Multiple filter_name and filter_mac filters are allowed at the same time. The adData and scanData packets that meet one of the filters will be sent to the application.

NOTE: Different filter types are allowed at the same time (e.g. filter_value, filter_name and filter_mac). Only the adData and scanData packets that meet all the filters will be sent to the application.

Users can filter the devices based on its MAC address.

AC Managed:

GET http://{your AC domain}/api/gap/nodes?event=1&mac=<gateway-mac>&filter_mac=<mac1>,<mac2>, … , <macX>

Local:

GET http://{gateway ip}/gap/nodes?event=1&filter_mac=<mac1>,<mac2>, … , <macX>

Container:

GET http://10.10.10.254/gap/nodes?event=1&filter_mac=<mac1>,<mac2>, … , <macX>

Users can filter out devices based on its RSSI level, e.g. filter out devices who’s RSSI value is weaker than a certain value.

AC Managed:

GET http://{your AC domain}/api/gap/nodes?event=1&mac=<gateway-mac>&filter_rssi=<rssi>

Local:

GET http://{gateway ip}/gap/nodes?event=1&filter_rssi=<rssi>

Container:

GET http://10.10.10.254/gap/nodes?event=1&filter_rssi=<rssi>

In addition, users can filter out devices based on service UUID and name inside the scanned packets. The service UUID may be only part of the UUID in BLE profile. What is more, filter_uuid should not include “-”.

NOTE: filter_uuid can only filter the adData and scanData which includes BLE EIR type 0x02 to 0x07. Please search EIR_UUID16_SOME in this wiki for more information.

AC Managed:

GET http://{your AC domain}/api/gap/nodes?event=1&mac=<gateway-mac>&filter_uuid=<uuid1>,<uuid2>, … , <uuidX>

GET http://{your AC domain}/api/gap/nodes?event=1&mac=<gateway-mac>&filter_name=<name1>,<name2>, … , <nameX>

Local:

GET http://{gateway ip}/gap/nodes?event=1&filter_uuid=<uuid1>,<uuid2>, … , <uuidX>

GET http://{gateway ip}/gap/nodes?event=1&filter_name=<name1>,<name2>, … , <nameX>

Container:

GET http://10.10.10.254/gap/nodes?event=1&filter_uuid=<uuid1>,<uuid2>, … , <uuidX>

GET http://10.10.10.254/gap/nodes?event=1&filter_name=<name1>,<name2>, … , <nameX>

NOTE: The structure of BLE advertise packets and scan response packets is [1 Byte Length (type + data) + 1 Byte Type + Data] x n. In order to filter by UUID or name, the corresponding type should be included in advertise packets (adData) or scan response packets (scanData). Below are the types:

#define EIR_UUID16_SOME 0x02 /* 16-bit UUID, more available */
#define EIR_UUID16_ALL 0x03 /* 16-bit UUID, all listed */
#define EIR_UUID32_SOME 0x04 /* 32-bit UUID, more available */
#define EIR_UUID32_ALL 0x05 /* 32-bit UUID, all listed */
#define EIR_UUID128_SOME 0x06 /* 128-bit UUID, more available */
#define EIR_UUID128_ALL 0x07 /* 128-bit UUID, all listed */
#define EIR_NAME_SHORT 0x08 /* shortened local name */
#define EIR_NAME_COMPLETE 0x09 /* complete local name */

Below is an example which includes name in scan response:

Below is an example which includes UUID in advertise packet. The uuid in this advertise packets is F0FF. Please move the last byte (FF) forward and add the rest of the bytes(F0), here comes the filter_uuid= FFF0:

Enhanced Scan Filter (v2.0 and above)

In order to improve the flexibility of scan filter, Cassia enhanced name & MAC filter and added value filter from v2.0.

filter_name

Full name: same as legacy filter_name.
Filter out unknown name: format is *. Filter out the adv packets without name in both ad_data and scan_data.
Prefix: format is Cassia*. Filter prefix in either ad_data or scan_data.
Suffix: format is *Cassia. Filter suffix in either ad_data or scan_data.

Examples:

cURL (Local):

curl -v 'http://172.16.10.99/gap/nodes?event=1&filter_name=Cassia*,36NOTES,*aaa

AC Managed:

GET http://{your AC domain}/api/gap/nodes?mac=<gateway-mac>&access_token=<access-token>&active=1&event=1&chip=0&filter_name=Cassia*,36NOTES,*aaa

Local:

GET http://{gateway ip}/gap/nodes?event=1&filter_name=Cassia*,36NOTES,*aaa

Container:

GET http://10.10.10.254/gap/nodes?event=1&filter_name=Cassia*,36NOTES,*aaa

filter_mac

Full MAC: same as legacy filter_mac.
Prefix: format is CC:DD:EE*. Filter the adv packets by MAC prefix.

Examples:

cURL (Local):

curl -v 'http://172.16.10.99/gap/nodes?event=1&filter_mac=CC:DD:EE*,CC:1B:E0:E8:0B:4B'

AC Managed:

GET http://{your AC domain}/api/gap/nodes?mac=<gateway-mac>&access_token=<access-token>&active=1&event=1&chip=0&filter_mac=CC:DD:EE*,CC:1B:E0:E8:0B:4B

Local:

GET http://{gateway ip}/gap/nodes?event=1&filter_mac=CC:DD:EE*,CC:1B:E0:E8:0B:4B

Container:

GET http://10.10.10.254/gap/nodes?event=1&filter_mac=CC:DD:EE*,CC:1B:E0:E8:0B:4B

filter_value

filter value with data xx from offset yy

NOTE: multiple filter_value are supported from 2.1.1, i.e. [{"offset":"1","data":"1EFF06"},{"offset":"1","data":"020106"}]

Examples:

cURL (Local):

curl -v 'http://172.16.10.99/gap/nodes?event=1&filter_value=\{"offset":"7","data":"0302E9"\}'

AC Managed:

GET http://{your AC domain}/api/gap/nodes?mac=<gateway-mac>&access_token=<access-token>&active=1&event=1&chip=0&filter_value=\{"offset":"7","data":"0302E9"\}

Local:

GET http://{gateway ip}/gap/nodes?event=1&filter_value=\{"offset":"7","data":"0302E9"\}

Container:

GET http://10.10.10.254/gap/nodes?event=1&filter_value=\{"offset":"7","data":"0302E9"\}

Output example

data: {"name":"(unknown)","evtType":0,"rssi":-67,"adData":"0201060302E9FE08FFEC82 0418000363","bdaddrs":[{"bdaddr":"CC:1B:E0:E8:11:6A","bdaddrType":"public"}]}

Note: When using Chrome to call scan filter API, please encode "{" and "}", for example:

http://172.16.10.99/gap/nodes?event=1&filter_value=%7B"offset":"7","data":"0302E9"%7D

Connect/Disconnect to a Target Device

To use the gateway to connect to specific BLE devices using Cassia AC:

AC Managed:

POST http://{your AC domain}/api/gap/nodes/<node>/connection?mac=<gateway-mac>

Local:

POST http://{gateway ip}/gap/nodes/<node>/connection

Container:

POST http://10.10.10.254/gap/nodes/<node>/connection

NOTE: Multiple connecting requests cannot be handled simultaneously by one gateway. User needs to handle requests in serial, which is to wait for the response and then invoke the next connecting request. If connecting multiple devices is needed without setting a wait interval, please look at the Batch Connection API.

Parameter	Description
`type`	(Optional): the BLE device’s address type, either public or random. Default is public if not specified.
`timeout`	(Optional): in ms, the connection request will timeout if it can’t be finished within this time. The default timeout is 5,000ms. The range of value is 200 ms - 20000 ms.
`auto`	(Optional): 0 or 1, indicates whether or not the BLE device will be automatically reconnected after it is disconnected unexpectedly. Return value: 200 for success, 500 for error. The default value is 0 (don't reconnect). (After the BLE connection is reconnected, the user application needs to reconnect the up-layer connections. For example, resubscribe the BLE notifications.) This parameter is disabled for firmware v1.4.3 and above!
`discovergatt`	(Optional): 0 or 1 (default) ❖ Value 1 indicates the gateway should use the cached GATT database which was discovered during previous connection. It will save time for service discover API, but maybe the information is not updated. ❖ Value 0 indicates the gateway should not use the cached GATT database. When a user calls the service discover API, the gateway should read the GATT services & characteristics from the BLE device.
`mtu`	(Optional): 0 (default) or 23 ~ 498 ❖ Value 0 indicates the gateway will use an MTU length of 247 during the MTU exchange process with the device. ❖ Value greater than 0 indicates the gateway will use the specified value for the MTU exchange process. This parameter is supported in versions released after March 2025.

Here is an example for accessing the gateway from a local network (no "/api" and "mac="):

curl -X POST -H "content-type: application/json" -d '{"timeout":"10000","type":"public"}' 'http://172.16.10.6/gap/nodes/CC:1B:E0:E8:09:2B/connection'

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: text/plain
OK

To disconnect:

AC Managed:

DELETE http://{your AC domain}/api/gap/nodes/<node>/connection?mac=<gateway-mac>

Local:

DELETE http://{gateway ip}/gap/nodes/<node>/connection

Container:

DELETE http://10.10.10.254/gap/nodes/<node>/connection

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: text/plain
OK

Get the Device List Connected to a Router (AC Managed):

GET http://{your AC domain}/api/gap/nodes?connection_state=connected&mac=<gateway-mac>

Local:

GET http://{gateway ip}/gap/nodes?connection_state=connected

Container:

GET http://10.10.10.254/gap/nodes?connection_state=connected

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

{
    "nodes": [{
        "type": "random",
        "bdaddrs": {
            "bdaddr": "EF:A3:E6:94:CD:2D",
            "bdaddType": "random"
        },
        "chipId": 0,
        "handle": "",
        "name": "",
        "connectionState": "connected",
        "id": "EF:A3:E6:94:CD:2D",
        "pairStatus":"paired"
    }]
}

NOTE: The "pairStatus" value can either be "paired" (when the device has been paired with the Cassia gateway before) or "none" (when the device is not paired with the Cassia gateway).

Batch Connect to a Target Device (v2.0 and above)

To use the gateway to connect to specific BLE devices using Cassia AC:

AC Managed:

POST http://{your AC domain}/api/gap/batch-connect

Local:

POST http://{gateway ip}/gap/batch-connect

Container:

POST http://10.10.10.254/gap/batch-connect

NOTE: Parameters are provided via JSON (application/json) through the POST request.

Parameter	Description
`timeout`	(Optional): timeout value for each individual connection of one device. Range is 20 ms - 20000 ms. Default value: 5000 (ms).
`per_dev_timeout`	(Optional): timeout value for a single device, including retry duration. Default value: `timemout` * 2 (twice the `timeout` value in ms). `per_dev_timeout` should be greater than or equal to `timeout`.
`list`	(Optional): connection MAC list, format is JSON array. Example: [{"type":"public","addr":"C0:00:5B:D1:B7:25"},{"type":"public","addr":"C0:00:5B:D1:AF:F0"}]，could be one or multiple MACs, could add into existing batch-connect list. Sample ： `curl -v -X POST -H "content-type: application/json" -d '{"list":[{"type":"public","addr":"C0:00:5B:D1:B7:25"},{"type":"public","addr":"C0:00:5B:D1:AF:F0"}], "timeout":"5000"}' 'http://172.16.10.99/gap/batch-connect'`

Here is an example using the Local (Standalone Router Mode) API (no "/api" and "mac="):

              curl -v -X POST -H "content-type: application/json" -d '{"list":[{"type":"public","addr":"C0:00:5B:D1:B7:25"},{"type":"public","addr":"C0:00:5B:D1:AF:F0"}], "timeout":"5000"}' 'http://172.16.10.99/gap/batch-connect'

Connection-State SSE returns additional connection timeout status:

Get the connection timeout status through an SSE stream.

SSE cURL example:

curl –v 'http://172.16.10.99/management/nodes/connection-state'

Stream Output Data format：

data: {"handle":"C0:00:5B:D1:B7:26","chipId":0,"connectionState":"connect timeout"}

Remove batch-connect interface and empty connection queue:

This API removes the batch-connection activity and empties the queue of connections.

cURL:

curl -v -X DELETE 'http://172.16.10.99/gap/batch-connect'

AC Managed:

DELETE http://{your AC domain}/api/gap/batch-connect

Local:

DELETE http://{gateway ip}/gap/batch-connect

Container:

DELETE http://10.10.10.254/gap/batch-connect

NOTE: No parameters are accepted for this API.

Discover GATT Services and Characteristics

Discover all services:

AC Managed:

GET http://{your AC domain}/api/gatt/nodes/<node>/services?mac=<gateway-mac>

Local:

GET http://{gateway ip}/gatt/nodes/<node>/services

Container:

GET http://10.10.10.254/gatt/nodes/<node>/services

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

[{
    "uuid": "00001800-0000-1000-8000-00805f9b34fb",
    "primary": true,
    "handle": 1
}, {
    "uuid": "00001801-0000-1000-8000-00805f9b34fb",
    "primary": true,
    "handle": 8
}, {
    "uuid": "0000fd00-0000-1000-8000-00805f9b34fb",
    "primary": true,
    "handle": 9
}, {
    "uuid": "0000180d-0000-1000-8000-00805f9b34fb",
    "primary": true,
    "handle": 20
}, {
    "uuid": "0000180f-0000-1000-8000-00805f9b34fb",
    "primary": true,
    "handle": 26
}, {
    "uuid": "0000180a-0000-1000-8000-00805f9b34fb",
    "primary": true,
    "handle": 30
}, {
    "uuid": "00001802-0000-1000-8000-00805f9b34fb",
    "primary": true,
    "handle": 43
}, {
    "uuid": "00001803-0000-1000-8000-00805f9b34fb",
    "primary": true,
    "handle": 46
}]

Discover all characteristics:

AC Managed:

GET http://{your AC domain}/api/gatt/nodes/<node>/characteristics?mac=<gateway-mac>

Local:

GET http://{gateway ip}/gatt/nodes/<node>/characteristics

Container:

GET http://10.10.10.254/gatt/nodes/<node>/characteristics

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

[{
    "handle": 3,
    "properties": 10,
    "uuid": "00002a00-0000-1000-8000-00805f9b34fb"
}, {
    "handle": 5,
    "properties": 2,
    "uuid": "00002a01-0000-1000-8000-00805f9b34fb"
}, {
    "handle": 7,
    "properties": 2,
    "uuid": "00002a04-0000-1000-8000-00805f9b34fb"
}, {
    "handle": 11,
    "properties": 16,
    "uuid": "0000fd09-0000-1000-8000-00805f9b34fb"
}, {
    "handle": 14,
    "properties": 4,
    "uuid": "0000fd0a-0000-1000-8000-00805f9b34fb"
}]

Discover all characteristics in one service:

AC Managed:

GET http://{your AC domain}/api/gatt/nodes/<node>/services/<service_uuid>/characteristics?mac=<gateway-mac>

Local:

GET http://{your AC domain}/gatt/nodes/<node>/services/<service_uuid>/characteristics

Container:

GET http://10.10.10.254/gatt/nodes/<node>/services/<service_uuid>/characteristics

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

[{
    "handle": 48,
    "properties": 10,
    "uuid": "00002a06-0000-1000-8000-00805f9b34fb"
}]

Discover all descriptors in one characteristic:

AC Managed:

GET http://{your AC domain}/api/gatt/nodes/<node>/characteristics/<characteristic_uuid>/descriptors?mac=<gateway-mac>

Local:

GET http://{gateway ip}/gatt/nodes/<node>/characteristics/<characteristic_uuid>/descriptors

Container:

GET http://10.10.10.254/gatt/nodes/<node>/characteristics/<characteristic_uuid>/descriptors

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

[{
    "handle": 48,
    "properties": 10,
    "uuid": "00002a06-0000-1000-8000-00805f9b34fb"
}]

Discover a specific service by service UUID:

AC Managed:

GET http://{your AC domain}/api/gatt/nodes/<node>/services?mac=<gateway-mac>&uuid=<uuid>

Local:

GET http://{gateway ip}/gatt/nodes/<node>/services?uuid=<uuid>

Container:

GET http://10.10.10.254/gatt/nodes/<node>/services?uuid=<uuid>

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

{
    "uuid": "00001801-0000-1000-8000-00805f9b34fb",
    "primary": true,
    "handle": 8
}

Discover a specific characteristic by characteristics UUID:

AC Managed:

GET http://{your AC domain}/api/gatt/nodes/<node>/characteristics?mac=<gateway-mac>&uuid=<uuid>

Local:

GET http://{gateway ip}/gatt/nodes/<node>/characteristics?uuid=<uuid>

Container:

GET http://10.10.10.254/gatt/nodes/<node>/characteristics?uuid=<uuid>

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

{
    "handle": 45,
    "properties": 4,
    "uuid": "00002a06-0000-1000-8000-00805f9b34fb"
}

Discover all services, characteristics, and descriptors all at once:

AC Managed:

GET http://{your AC domain}/api/gatt/nodes/<node>/services/characteristics/descriptors?mac=<gateway-mac>

Local:

GET http://{gateway ip}/gatt/nodes/<node>/services/characteristics/descriptors

Container:

GET http://10.10.10.254/gatt/nodes/<node>/services/characteristics/descriptors

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

[{
    "uuid": "00001800-0000-1000-8000-00805f9b34fb",
    "primary": true,
    "characteristics": [{
        "descriptors": [{
            "handle": 3,
            "uuid": "00002a00-0000-1000-8000-00805f9b34fb"
        }],
        "handle": 3,
        "properties": 10,
        "uuid": "00002a00-0000-1000-8000-00805f9b34fb"
    }, {
        "descriptors": [{
            "handle": 5,
            "uuid": "00002a01-0000-1000-8000-00805f9b34fb"
        }],
        "handle": 5,
        "properties": 2,
        "uuid": "00002a01-0000-1000-8000-00805f9b34fb"
    }, {
        "descriptors": [{
            "handle": 7,
            "uuid": "00002a04-0000-1000-8000-00805f9b34fb"
        }],
        "handle": 7,
        "properties": 2,
        "uuid": "00002a04-0000-1000-8000-00805f9b34fb"
    }],
    "handle": 1
}]

Read/Write the Value of a Specific Characteristic

The read/write operations are based on the handle (found in the discover result) of a specific characteristic. To read by the handle:

AC Managed:

GET http://{your AC domain}/api/gatt/nodes/<node>/handle/<handle>/value?mac=<gateway-mac>

Local:

GET http://{gateway ip}/gatt/nodes/<node>/handle/<handle>/value

Container:

GET http://10.10.10.254/gatt/nodes/<node>/handle/<handle>/value

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json

{
    "handle": "36",
    "value": "56312e362e31"
}

To write by the handle:

AC Managed:

GET http://{your AC domain}/api/gatt/nodes/<node>/handle/<handle>/value/<value>?mac=<gateway-mac>

Local:

GET http://{gateway ip}/gatt/nodes/<node>/handle/<handle>/value/<value>

Container:

GET http://10.10.10.254/gatt/nodes/<node>/handle/<handle>/value/<value>

Parameter	Description
`noresponse`	(Optional): 0 or 1, 1 allows writing to the handle without a response. Default value is 0.

Example using Local API:
GET http://{gateway ip}/gatt/nodes/<node>/handle/<handle>/value/<value>?noresponse=1

Response Example (if `noresponse` is not set to 1)

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: text/plain

OK

Below is an example for opening and closing a specific characteristic’s notification and indication by Write API.

First, you need to call the Discover API to find the corresponding descriptors of the specified characteristic. Then, open the descriptors, find the UUID and its corresponding handle, e.g. “37”. Now, you can use this handle in the Write API. To open the notification, set the value to "0100"; to open the indication, set the value to "0200"; to close the notification/indication, set the value to "0000" (37, 0100, 0200 and 0000 are examples).

AC Managed:

GET http://{your AC domain}/api/gatt/nodes/<node>/handle/37/value/0100?mac=<gateway-mac>

Local:

GET http://{gateway ip}/gatt/nodes/<node>/handle/37/value/0100

Container:

GET http://10.10.10.254/gatt/nodes/<node>/handle/37/value/0100

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: text/plain

OK

Send Advertise Data

Begin advertising data:

AC Managed:

GET http://{your AC domain}/api/advertise/start?mac=<mac>&interval=<interval>&ad_data=<ad_data>&resp_data=<resp_data>

Local:

GET http://{gateway ip}/advertise/start?interval=<interval>&ad_data=<ad_data>&resp_data=<resp_data>

Container:

GET http://10.10.10.254/advertise/start?interval=<interval>&ad_data=<ad_data>&resp_data=<resp_data>

Here are the parameters:

Parameter	Description
`interval`	(Mandatory): advertising interval in ms. Range is 20 ms - 10000 ms. Default value 500 ms.
`ad_type`	(Optional): advertising type (see below table). Default value 3.
`ad_data`	(Mandatory): advertise package, the data type is string.
`resp_data`	(Mandatory): scan response package. The data type is string. When you want to send resp_data, please set ad_type=0.

Value	ad_type	Comments
0	ADV_IND	Connectable undirected advertising
1	ADV_DIRECT_IND	Connectable directed advertising
2	ADV_SCAN_IND	Scannable undirected advertising
3	ADV_NONCONN_IND	Non connectable undirected advertising
4	SCAN_RSP	Scan Response

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: text/plain
OK

Stop sending advertise data:

AC Managed:

GET http://{your AC domain}/api/advertise/stop?mac=<mac>

Local:

GET http://{gateway ip}/advertise/stop

Container:

GET http://10.10.10.254/advertise/stop

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: text/plain
OK

Get Device Connection Status

SSE API to get the connection status of all the devices that have connected to a gateway:

AC Managed:

GET http://{your AC domain}/api/management/nodes/connection-state?mac=<gateway-mac>

Local:

GET http://{gateway ip}/management/nodes/connection-state

Container:

GET http://10.10.10.254/management/nodes/connection-state

When a device status is changed from disconnected to connected, or from connected to disconnected, you will get a response. For example:

data: {"handle":"CC:1B:E0:E8:0D:F2","connectionState":"connected"}
data: {"handle":"88:C6:26:92:58:77","connectionState":"disconnected"}

Receive Notification and Indication

SSE API to receive continuous notification and indication:

AC Managed:

GET http://{your AC domain}/api/gatt/nodes?event=1&mac=<gateway-mac>

Local:

GET http://{gateway ip}/gatt/nodes?event=1

Container:

GET http://10.10.10.254/gatt/nodes?event=1

Parameter	Description
`sequence`	(Optional): 0 or 1 or 2, 1 adds global sequence number of this session into JSON data of SSE, 2 adds notification message sequence number for each device into JSON data of SSE. Default value is 0.
`timestamp`	(Optional): 0 or 1, 1 adds timestamp into JSON data of SSE. Default value is 0.

Response Example

{"value":"FFFFFFFF","id":"CC:1B:E0:E2:31:C2","handle":19,"dataType":"notification"}
{"value":"FFFFFFFF","id":"CC:1B:E0:E2:31:C2","timestamp":"2023-07-23 16:00:01.668 CST","handle":19,"dataType":"notification"}
{"seqNum":1,"value":"FFFFFFFF","id":"CC:1B:E0:E2:31:C2","timestamp":"2023-07-23 16:00:01.668 CST","handle":19,"dataType":"notification"}

Get RSSI for BLE Connection (v2.0 and above)

Users can get the current RSSI of a BLE connection with this API.

AC Managed:

GET http://{your AC domain}/api/gap/nodes/<node>/rssi?mac=<gateway-mac>

Local:

GET http://{gateway ip}/gap/nodes/<node>/rssi?mac=<gateway-mac>

Container:

GET http://10.10.10.254/gap/nodes/<node>/rssi?mac=<gateway-mac>

Response Example

{"id":"C0:00:5B:D1:A9:20","rssi":-33}

If users want to get a continuous RSSI report for all the BLE connections of a gateway, they can use below SSE API.

AC Managed:

GET http://{your AC domain}/api/gap/rssi?mac=<gateway-mac>

Local:

GET http://{gateway ip}/gap/rssi?mac=<gateway-mac>

Container:

GET http://10.10.10.254/gap/rssi?mac=<gateway-mac>

Here are the parameters:

Parameter	Description
`rssi`	(Optional): Only report RSSI if the RSSI is lower than this threshold. Default is 127.
`rssi_interval`	(Optional): RSSI report interval. The unit is ms. The default value is 1000.
`filter_mac`	(Optional): If users only want to get a RSSI report of a particular BLE devices, they can use this parameter. The format is same as the parameter filter_mac in Filter Scanned Data based on Device MAC, RSSI, Name, and UUID

Response Example

{"id":"C0:00:5B:D1:A9:20","rssi":-34}

Positioning API

Cassia supports room-based Bluetooth location tracking. Below are the related APIs.

NOTE: Before calling any positioning APIs, please call scan API for the related gateways. Positioning APIs are only available through Cassia AC.

To identify the closest gateway a BLE device is located:

GET http://{your AC domain}/api/middleware/position/by-device/<device_mac>

It will return {“hubMac”:”hubMac1”}, e.g. {“hubMac”:”CC:1B:E0:E0:01:47”}.

To obtain the closest gateway list for all the BLE devices that the AC can detect:

GET http://{your AC domain}/api/middleware/position/by-device/*

It will return a list:

{
    "device1": {
        "hubMac": "hubMac1"
    },
    "device2": {
        "hubMac": "hubMac2"
    },
    ...
}

Example

{
    "11: 22: 33: 44: 55: 66": {
        "hubMac": "CC: 1 B: E0: E0: 01: 47"
    },
    "11: 22: 33: 44: 55: 77": {
        "hubMac": "CC: 1 B: E0: E0: 01: 48"
    },
}

To get the list of BLE devices around a Cassia gateway:

GET http://{your AC domain}/api/middleware/position/by-ap/<hub_mac>

It will return:

["device1", "device2","device3", ...]

Example

["11:22:33:44:55:66","11:22:33:44:55:AA",...].

To get the list of BLE devices for all the gateways within the AC:

GET http://{your AC domain}/api/middleware/position/by-ap/*

It will return:

{
    "hubMac1": ["device1", "device2", "device3"…],
    "hubMac2": ["device1", "device2", "device3"…],
    ...
}

Example

{
    "CC:1B:E0:E0:11:22": ["11:22:33:44:55:66", "11:22:33:44:55:AA"…],
    …
}

Secure Pairing API

Since the v1.2 release, Cassia supports Bluetooth 4.1 Secure Simple Pairing, namely Just Works, Passkey Entry and Legacy OOB.

(v2.0 and above): Starting from the v2.0 release, Cassia supports Bluetooth 4.2 Pairing, namely Just Works, Passkey Entry, Security OOB and Numeric Comparison.

NOTE: Before the v2.0 release, users must call the connect API before calling the pair API. From the v2.0 release, the API Pair Request will set up the BLE connection automatically if the connection has not been set up.

Here is the mapping between pair modes, APIs, and typical responses.

NOTE: The 4.1 and 4.2 in the table refers to the Bluetooth versions. The "Y" and "N" means "Yes" and "No" to whether the Pair Mode is supported in a Bluetooth version.

Pair Mode	4.1	4.2	Step 1: API Pair Request	Step 2: API Pair-input Request
Just Works	Y	Y	Returns 0 for pairing failed or 1 for successful.	N/A
Passkey Entry	Y	Y	Returns 5 for using passkey entry (initiator inputs).	Returns 0 for pairing failed or 1 for successful.
Legacy OOB	Y	N	Returns 3 for using legacy OOB.	Returns 0 for pairing failed or 1 for successful.
Security OOB	N	Y	Returns 0 for pairing failed or 1 for successful	N/A
Numeric Comparison	N	Y	Returns 7 for using numeric comparison.	Returns 0 for pairing failed or 1 for successful.

Pair Request

AC Managed:

POST http://{your AC domain}/api/management/nodes/<node>/pair?mac=<gateway-mac>

Local:

POST http://{gateway ip}/management/nodes/<node>/pair

Container:

POST http://10.10.10.254/management/nodes/<node>/pair

Body parameters:

Parameter	Description
`oob`	(Optional): 0 means no OOB, 1 means Legacy OOB, 2 means Security OOB. Default is 0. Setting oob=0 or 1 has the same function as the old parameter `legacy-oob` (still valid for backward compatibility).
`legacy-oob`	(Deprecated): Default value is 0, which means not using Legacy OOB. If a user wants to use Legacy OOB, please set it to 1. This parameter is replaced by the `oob` parameter, but this parameter is still valid for backward compatibility.
`iocapability`	(Mandatory): See the table below. Same as the old parameter `io-capability` (still valid for backward compatibility).
`io-capability`	(Deprecated): See below table. Default value is KeyboardDisplay.
`rand`	(Mandatory for Security OOB): Random value for pair. Provided by the device.
`confirm`	(Mandatory for Security OOB): Confirm value for pair. Provided by the device.
`timeout`	(Optional): Pair connection attempt timeout in ms. The default value is 5 seconds (5000).
`type`	(Optional): ): The type of device (public or random). The default value is public.
`bond`	(Optional): Saves the pair key in the gateway and device, 0 or 1. The default value is 1 (save).

IO Capability:

Value	Comments
DisplayOnly	Check BLE specification version 4.2
DisplayYesNo	Check BLE specification version 4.2
KeyboardOnly	Check BLE specification version 4.2
NoInputNoOutput	Check BLE specification version 4.2
KeyboardDisplay	Default value

Response Parameters:

Name	Optional/Mandatory	Description
HTTP 500 error	Optional	Please check the Error Messages section.
`pairingStatusCode`	Optional	See below table
`pairingStatus`	Optional	Description of pairing status code
`display`	Optional	Display for pairing status code 6 and 7

Pairing Status Codes:

Status Code	Status Description
0	Pairing Failed
1	Pairing Successful
2	Pairing Aborted
3	LE Legacy Pairing OOB Expected
4	LE Secure Connections Pairing OOB Expected
5	Passkey Input Expected
6	Passkey Display Expected
7	Numeric Comparison Expected (LE Secure Connections Pairing only)

Pair-Input Request

NOTE: This API is only needed for Passkey Entry, Legacy OOB, and Numeric Comparison.

AC Managed:

POST http://{your AC domain}/api/management/nodes/<node>/pair-input?mac=<gateway-mac>

Local:

POST http://{gateway ip}/management/nodes/<node>/pair-input

Container:

POST http://10.10.10.254/management/nodes/<node>/pair-input

Body example for Passkey Entry (application/json):

{ "passkey": "123456" }

Body example for Numeric Comparison (application/json):

Success:

{ "passkey": "1" }

Fail:

{ "passkey": "0" }

Body example for Legacy OOB (application/json):

{ "tk": "0x0123456789ABCDEF0123456789ABCDEF" }

The response format is same as the pair request API.

Unpair Request

AC Managed:

DELETE http://{your AC domain}/api/management/nodes/<node>/bond?mac=<gateway-mac>

Local:

DELETE http://{gateway ip}/management/nodes/<node>/bond

Container:

DELETE http://10.10.10.254/management/nodes/<node>/bond

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: text/plain
OK

Just Works Example

AC Managed:

POST http://{your AC domain}/api/management/nodes/<node>/pair?mac=<gateway-mac>

Local:

POST http://{gateway ip}/management/nodes/<node>/pair

Container:

POST http://10.10.10.254/management/nodes/<node>/pair

Body example (application/json):

{"iocapability": "NoInputNoOutput"}

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json
{"pairingStatusCode": 1, "pairingStatus": "Pairing Successful"}

Passkey Entry Example: Initiator Inputs

Step #1

AC Managed:

POST http://{your AC domain}/api/management/nodes/<node>/pair?mac=<gateway-mac>

Local:

POST http://{gateway ip}/management/nodes/<node>/pair

Container:

POST http://10.10.10.254/management/nodes/<node>/pair

Body example (application/json):

{"iocapability": "KeyboardDisplay"}

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json
{"pairingStatusCode": 5, "pairingStatus": "Passkey Input Expected"}

Step #2

AC Managed:

POST http://{your AC domain}/api/management/nodes/<node>/pair-input?mac=<gateway-mac>

Local:

POST http://{gateway ip}/management/nodes/<node>/pair-input

Container:

POST http://10.10.10.254/management/nodes/<node>/pair-input

Body example (application/json):

{"passkey": "123456"}

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json
{"pairingStatusCode": 1, "pairingStatus": "Pairing Successful"}

Legacy Pairing OOB Example

Step #1

AC Managed:

POST http://<your AC domain>/api/management/nodes/<node>/pair?mac=<gateway-mac>

Local:

POST http://{gateway ip}/management/nodes/<node>/pair

Container:

POST http://10.10.10.254/management/nodes/<node>/pair

Body example (application/json):

{"oob": 1, "iocapability": "KeyboardDisplay"}

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json
{"pairingStatusCode": 3, "pairingStatus": "LE Legacy Pairing OOB Expected"}

Step #2

AC Managed:

POST http://<your AC domain>/api/management/nodes/<node>/pair-input?mac=<gateway-mac>

Local:

POST http://{gateway ip}/management/nodes/<node>/pair-input

Container:

POST http://10.10.10.254/management/nodes/<node>/pair-input

Body example (application/json):

{"tk": "0x0123456789ABCDEF0123456789ABCDEF"}

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json
{"pairingStatusCode": 1, "pairingStatus": "Pairing Successful"}

Numeric Comparison Example

Step #1

AC Managed:

POST http://<your AC domain>/api/management/nodes/<node>/pair?mac=<gateway-mac>

Local:

POST http://{gateway ip}/management/nodes/<node>/pair

Container:

POST http://10.10.10.254/management/nodes/<node>/pair

Body example (application/json):

{"iocapability":"KeyboardDisplay"}

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json
{"display":"425472","pairingStatus":"Numeric Comparison Expected","pairingStatusCode":7}

Step #2

AC Managed:

POST http://<your AC domain>/api/management/nodes/<node>/pair- input?mac=<gateway-mac>

Local:

POST http://{gateway ip}/management/nodes/<node>/pair-input

Container:

POST http://10.10.10.254/management/nodes/<node>/pair-input

Body example (application/json):

{"passkey":"1"}

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json
{ "pairingStatusCode": 1, "pairingStatus": "Pairing Successful" }

Security OOB Example

Step #1

AC Managed:

POST http://<your AC domain>/api/management/nodes/<node>/pair?mac=<gateway-mac>

Local:

POST http://{gateway ip}/management/nodes/<node>/pair

Container:

POST http://10.10.10.254/management/nodes/<node>/pair

Body example (application/json):

{
  "oob":2,
  "timeout":20000,
  "type":"random",
  "rand":"e18df48c5ad68f0ee3d541e4d60f9ae5",
  "confirm":"dbc116a241c8894a67bcbd6841a79473",
  "bond":0,
  "iocapability":"KeyboardDisplay"
}

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json
{"pairingStatusCode":1,"pairingStatus":"Pairing Successful"}

Router Auto-Selection API

From firmware 1.3, Cassia AC can select one gateway automatically from a list of candidates, and then connect the BLE device by using this gateway. The selection is based on RSSI, gateway load, and gateway capabilities.
If users want to connect a BLE device with a specific gateway, or they want to use a customized gateway selection algorithm, they should use the APIs in Connect/Disconnect to a Target Device.

NOTE: these APIs are only available through Cassia AC.

Router Auto-Selection

This API will enable/disable the gateway auto-selection function.

If the flag is 1, the gateway auto-selection function will be enabled. If the flag is 0, the gateway auto-selection function will be disabled.

For the gateway auto-selection function, scanning will be turned on in the AC automatically. By specifying scan_params when calling this API, you can filter scanned data based on device MAC, RSSI, name, and UUID. This is passive scanning, so it can only filter advertisement data packets from devices.

The scan_params include the following options:

Parameter	Description
`filter_mac`	(Optional): Device MAC address list. Advertisement data from only these devices will be sent to the AC.
`filter_rssi`	(Optional): RSSI value. Filters out devices with an RSSI value weaker than the defined value.

For a more comprehensive and detailed description of scan filter parameters, please refer to this section: Filter Scanned Data based on Device MAC, RSSI, Name, and UUID

NOTE: This API should be called before using any other gateway auto-selection APIs. You can also switch on/off the gateway auto-selection function in Cassia AC settings (as shown in the screenshot below).

Figure 6: Gateway auto-selection configuration in AC

POST http://{your AC domain}/api/aps/ap-select-switch

Body example #1 (application/json):

{"flag": 1}

Body example #2 (application/json):

{
   "flag":1,
   "scan_params":{
      "filter_mac":[
         "C7:ED:44:24:3E:55",
         "C7:ED:44:24:3E:56",
         "C7:ED:44:24:3E:57"
      ],
      "filter_rssi":"-70"
   }
}

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: application/json
{ "status": "success", "flag": 1 }

Connect a Device

This API will automatically select one gateway from a list of candidates and use it to connect the device. POST http://{your AC domain}/api/aps/connections/connect

Parameters for JSON body:

Parameter	Description
`aps`	The list of gateways which will be used for this auto-select connect request. The user can use one or multiple gateway’s MAC or * for “aps”. If the user uses *, it means all the online gateways that controlled by the AC should be included.
`devices`	Only one device MAC address can be added in "devices".
`timeout (Optional)`	in ms, the connection request will timeout if it can’t be finished within this time. The default timeout is 10,000ms. The range of value is 1000ms - 20000ms.
`random (Optional)`	0 (default) or 1, set it to 1 to use the roaming function.
`rssi (Optional)`	If this threshold is set, when this device is connected, the router checks the device's RSSI every 1000ms(default, this interval can be set using the "rssi_interval" parameter ), if device’s RSSI is lower than the value set by this parameter for 5 consecutive times, the device will be disconnected.
`rssi_interval(Optional)`	set the interval to check whether the device's RSSI is lower than the threshold( set by “rssi” parameter) when it is connected, default is 1000ms.
`discovergatt(Optional)`	0 or 1 (default) ? Value 1 indicates the router should use the cached GATT database which was discovered during previous connection. It will save time for service discover API, but maybe the information is not updated. Value 0 indicates the router should not use the cached GATT database. When a user calls the service discover API, the router should read the GATT services & characteristics from the BLE device.

Body example (application/json):

{ "aps": ["CC:1B:E0:E7:FE:F8","CC:1B:E0:E7:FE:F9","CC:1B:E0:E7:FE:FA"], "devices": ["F7:1
8:BC:18:F0:3A"] }

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: text/plain
OK

Disconnect a Device

This API will disconnect a device. In json Body, only one device’ MAC address can be added in “devices”.

POST http://{your AC domain}/api/aps/connections/disconnect

Body example (application/json):

{ "devices": ["F7:18:BC:18:F0:3A"] }

Response Example

Status-Line : HTTP/1.1 200 OK/r/n
Header : (general-header)
Message-body: text/plain
OK

SSE Combination API

These APIs simplify the handling of multiple gateways. They also improve the scalability of AC in terms of the number of gateways supported in given hardware resources.

NOTE: these APIs are only available through Cassia AC.

Before firmware 1.3, if an application wants to control gateways with RESTful APIs through AC, the application has to create three SSE tunnels for each gateway: one for scan data, one for notification/indication data, and one for connected device status.

From firmware 1.3, the application only needs to create one SSE tunnel with AC. This SSE tunnel can receive scan data, notification/indication data, and connected device status for all gateways controlled by this AC.

Create Combined SSE

This API will create one combined SSE connection with AC. This SSE connection can receive scan data, notification/indication data, and connected device status for all the gateways controlled by this AC.

GET http://{your AC domain}/api/aps/events

When invoke this API, AC will return a message immediately which include all gateway’s information, for example:

Response Example

data: {
    "dataType": "state",
    "aps": {
        "CC:1B:E0:E7:FE:F8": {
            "_id": "5a93755b028e6c00519ce1dc",
            "id": "CC:1B:E0:E7:FE:F8",
            "mac": "CC:1B:E0:E7:FE:F8",
            "name": "Cassia Router",
            "group": "",
            "status": "online",
            "model": "X1000",
            "version": "1.2.0.1803131043",
            "position": "",
            "time": 1519613275655,
            "ip": "192.168.1.202",
            "localip": "192.168.1.202",
            "uptime": 14873,
            "offline_time": 0,
            "online_time": 1522052125,
            "update_status": "update_ok",
            "update_reason": "",
            "update_version": "",
            "update_progress": 0,
            "notify": true,
            "connectionstate": true
        },
        "CA:79:F5:B6:1F:04": {
            "devices": {
                "CA:79:F5:B6:1F:04": {
                    "type": "random",
                    "bdaddrs": {
                        "bdaddr": "CA:79:F5:B6:1F:04",
                        "bdaddrType": "random"
                    },
                    "chipId": 0,
                    "handle": "",
                    "name": "",
                    "connectionState": "connected",
                    "id": "CA:79:F5:B6:1F:04"
                }
            }
        }
    }
}

One keep-alive message will be returned every 30 seconds to make sure the SSE link is up and running.

If scanning is open, this SSE tunnel will send scanning data to user application through AC. For example:

Scanning Data Example

data:
{
  "dataType": "scan",
  "ap": "CC:1B:E0:E7:FE:F8",
  "bdaddrs": [
    {
      "bdad": "CC:1B:E0:E0:98:16",
      "bdaddrType": "public"
    }
  ],
  "adData": "0201060D084361737369615F5331303030",
  "name": "Cassia_S1000",
  "rssi": -34,
  "evt_type": 3
}

If notification is open (default configuration), this SSE tunnel will return the notification messages to user application when any gateway has notification messages to AC.

Notification Message Example

data:
{
    "dataType": "notification",
    "ap": "CC:1B:E0:E7:FE:F8",
    "value": "FF000C000205100101010126",
    "device": "CA:79:F5:B6:1F:04",
    "handle": 16
}

If connection-state is open (default configuration), this SSE tunnel will return the device’s connection status to user application when any device’s status changes. For example:

Connection Status Example

data: {"handle":"CA:79:F5:B6:1F:04","connectionState":"disconnected","dataType":"connection_state","ap":"CC:1B:E0:E7:FE:F8"}
data: {"handle":"CA:79:F5:B6:1F:04","connectionState":"connected","dataType":"connection_state","ap":"CC:1B:E0:E7:FE:F8"}

If ap-state is open (default configuration), this SSE tunnel will return the ap-state information when gateway’s status is changed between online and offline. For example:

AP-State Information Example

data:
{
    "dataType": "ap_state",
    "ap": "CC:1B:E0:E7:FE:F8",
    "mac": "CC:1B:E0:E7:FE:F8",
    "status": "offline",
    "offline_time": 1522067273296
}

Open Scan

This API will open gateway scanning for all the gateways in the gateway list. The SSE tunnel will receive scan data.

POST http://{your AC domain}/api/aps/scan/open

Body example (application/json):

{
  "aps": [
    "CC:1B:E0:E7:FE:F8",
    "CC:1B:E0:E7:FE:F8",
    "CC:1B:E0:E7:FE:F8",
    "CC:1B:E0:E7:FE:F8"
  ],
  "chip": 0,
  "active": 0,
  "filter_name": "cassia"
}

Parameters for JSON Body:

Parameter	Description
`aps`	(Mandatory): one or multiple gateway’s MAC address
`chip`	(Optional): 0 or 1. It means which chip to scan
`active`	(Optional): 0 or 1. 0 means enable passive scanning; 1 means enable active scanning
`filter_name`	(Optional): filter for device name
`filter_mac`	(Optional): filter for device MAC
`filter_uuid`	(Optional): filter for device UUID
`filter_rssi`	(Optional): filter for device RSSI
`filter_duplicates`	(Optional): filter for duplicates devices
`filter_value`	(Optional): filter value with data xx from offset yy

Response example:

Status-Line  : HTTP/1.1 200 OK/r/n
Header       : (general-header)
Message-body : text/plain
OK

Close Scan

This API will close the gateway scanning for all the gateways in the gateway list. The user application will not receive scan data anymore.

POST http://{your AC domain}/api/aps/scan/close

Parameters for JSON Body:

Parameter	Description
`aps`	One or multiple gateway’s MAC address

Body example (application/json):

{
    "aps": [
        "CC:1B:E0:E7:FE:F8",
        "CC:1B:E0:E7:FE:F8"
    ]
}

Response example:

Status-Line  : HTTP/1.1 200 OK/r/n
Header       : (general-header)
Message-body : text/plain

Open Notify

This API will open the notification messages on SSE tunnel. The notification data will be sent to the user application on this SSE tunnel.

POST http://{your AC domain}/api/aps/notify/open

Parameters for JSON Body:

Parameter	Description
`aps`	One or multiple gateway’s MAC address

Body example (application/json):

{
  "aps": [
    "CC:1B:E0:E7:FE:F8",
    "CC:1B:E0:E7:FE:F8"
  ]
}

Response example:

Status-Line  : HTTP/1.1 200 OK/r/n
Header       : (general-header)
Message-body : text/plain
OK

Close Notify

This API will close the notification messages on SSE tunnel. The notification data will not be sent to the user application on this SSE tunnel anymore.

POST http://{your AC domain}/api/aps/notify/close

Parameters for JSON Body:

Parameter	Description
`aps`	One or multiple gateway’s MAC address

Body example (application/json):

{
    "aps": [
        "CC:1B:E0:E7:FE:F8",
        "CC:1B:E0:E7:FE:F8"
    ]
}

Response example:

Status-Line  : HTTP/1.1 200 OK/r/n
Header       : (general-header)
Message-body : text/plain
OK

Open Connection-State Report

This API will open the connection-state monitoring on SSE tunnel. The connection-state data will be sent to the user application on this SSE tunnel when the state of the connected device changed.

POST http://{your AC domain}/api/aps/connection-state/open

Parameters for JSON Body:

Parameter	Description
`aps`	One or multiple gateway’s MAC address

Body example (application/json):

{
    "aps": [
        "CC:1B:E0:E7:FE:F8",
        "CC:1B:E0:E7:FE:F8"
    ]
}

Response example:

Status-Line  : HTTP/1.1 200 OK/r/n
Header       : (general-header)
Message-body : text/plain
OK

Close Connection-State Report

This API will close the connection-state monitoring on SSE tunnel. The connection-state data will not be sent to the user application on this SSE tunnel anymore.

POST http://{your AC domain}/api/aps/connection-state/close

Parameters for JSON Body:

Parameter	Description
aps	One or multiple gateway’s MAC address

Body example (application/json):

{
    "aps": [
        "CC:1B:E0:E7:FE:F8",
        "CC:1B:E0:E7:FE:F8"
    ]
}

Response example:

Status-Line  : HTTP/1.1 200 OK/r/n
Header       : (general-header)
Message-body : text/plain
OK

Open AP-State Report

This API will open the ap-state monitoring for all gateways on SSE tunnel. The data of ap-state will be sent to the user application on this SSE tunnel when the gateway state changed between online and offline.

GET http://{your AC domain}/api/aps/ap-state/open

Response example:

Status-Line  : HTTP/1.1 200 OK/r/n
Header       : (general-header)
Message-body : text/plain
OK

Close AP-State Report

This API will close the ap-state monitoring for all gateways on SSE tunnel. The data of ap-state will not be sent to the user application on this SSE tunnel anymore.

GET http://{your AC domain}/api/aps/ap-state/close

Response example:

Status-Line  : HTTP/1.1 200 OK/r/n
Header       : (general-header)
Message-body : text/plain
OK

RESTful API - CassiaNetworks/CassiaSDKGuide GitHub Wiki

Common Parameters

Management API

Obtain Cassia Router’s Configuration

Obtain Cassia Router’s Status (Through AC)

Monitor Cassia Router’s Status (Through AC)

Obtain All Online Routers’ Status (Through AC)

Reboot a Router Remotely

Traffic Related API

Scan Bluetooth Devices

Filter Scanned Data based on Device MAC, RSSI, Name, and UUID

Enhanced Scan Filter (v2.0 and above)

Connect/Disconnect to a Target Device

Get the Device List Connected to a Router (AC Managed):

Batch Connect to a Target Device (v2.0 and above)

Discover GATT Services and Characteristics

Discover all services:

Discover all characteristics:

Discover all characteristics in one service:

Discover all descriptors in one characteristic:

Discover a specific service by service UUID:

Discover a specific characteristic by characteristics UUID:

Discover all services, characteristics, and descriptors all at once:

Read/Write the Value of a Specific Characteristic

Send Advertise Data

Get Device Connection Status

Receive Notification and Indication

Get RSSI for BLE Connection (v2.0 and above)

Positioning API

Secure Pairing API

Pair Request

Pair-Input Request

Unpair Request

Just Works Example

Passkey Entry Example: Initiator Inputs

Legacy Pairing OOB Example

Numeric Comparison Example

Security OOB Example

Router Auto-Selection API

Router Auto-Selection

Connect a Device

Disconnect a Device

SSE Combination API

Create Combined SSE

Open Scan

Close Scan

Open Notify

Close Notify

Open Connection-State Report

Close Connection-State Report

Open AP-State Report

Close AP-State Report

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️