MQTT API ‐ BLE API

BLE API

Interaction Flow

sequenceDiagram

participant Server as User Application Service
participant MQTT as User MQTT Server
participant Gateway as Cassia Bluetooth Gateway
participant Device as User BLE Device

rect rgba(136, 177, 234,0.4)
  note over Server,Device: [Data Reporting] BLE Advertising Data
  Device -) Device: BLE Advertising Mechanism
  Device --) Gateway: BLE Advertising Data
  Gateway --) Server: BLE Advertising Data
end

rect rgba(136, 177, 234,0.4)
  note over Server,Device: [API Call]-BLE Connection
  Server --) Gateway: BLE Connection Request
  Gateway --) Device: BLE Connect
  Device --) Gateway: BLE Connection Complete
  Gateway --) Server: BLE Connection Response
end

rect rgba(136, 177, 234,0.4)
  note over Server,Device: [Data Reporting] BLE Connection Event
  Device --) Gateway: BLE Connection Event
  Gateway --) Server: BLE Connection Event
  Server --) Server: Processing (Response and event sequence not fixed)
end

rect rgba(136, 177, 234, 0.4)
  note over Server,Device: [API Call] BLE Read Operation(Id)
  Server --) Gateway: BLE Read Operation Request
  Gateway --) Device: BLE Read Operation Request
  opt
    rect rgba(136, 177, 234, 0.4)
    Device --) Gateway: BLE Read Operation Response
    end
  end
  Gateway --) Server: BLE Read Operation Response
end

rect rgba(136, 177, 234, 0.4)
  note over Server,Device: [API Call] BLE Write Operation(Id)
  Server --) Gateway: BLE Write Operation Request
  Gateway --) Device: BLE Write Operation Request
  opt
    rect rgba(136, 177, 234, 0.4)
    Device --) Gateway: BLE Write Operation Response
    end
  end
  Gateway --) Server: BLE Write Operation Response
end

rect rgba(136, 177, 234,0.4)
  note over Server,Device: [Data Reporting] BLE Notification Data(Id)
  Device --) Gateway: BLE Notification Data
  Gateway --) Server: BLE Notification Data
  Server --) Server: Processing (Response and BLE Notification data sequence not in order)
end

rect rgba(136, 177, 234,0.4)
  note over Server,Device: [API Call]-BLE Disconnect
  Server --) Gateway: BLE Disconnect Request
  Gateway --) Device: BLE Disconnect
  Device --) Gateway: BLE Disconnect Complete
  Gateway --) Server: BLE Disconnect Response
end

rect rgba(136, 177, 234,0.4)
  note over Server,Device: [Data Reporting] BLE Disconnection Event
  Device --) Gateway: BLE Disconnection Event
  Gateway --) Server: BLE Disconnection Event
  Server --) Server: Processing (Response and event sequence not fixed)
end

Common APIs

Cassia RESTful API

BLE Operation	Mode	HTTP Method	HTTP URL
Connect Device		POST	/gap/nodes/{deviceMAC}/connection
Read	UUID	GET	/gatt/nodes/{deviceMAC}/services/{serviceUUID}/characteristics/{characteristicUUID}/value
	Handle	GET	/gatt/nodes/{deviceMAC}/handle/{handle}/value
Write	UUID	GET	/gatt/nodes/{deviceMAC}/services/{serviceUUID}/characteristics/{characteristicUUID}/value/{value}
	Handle	GET	/gatt/nodes/{deviceMAC}/handle/{handle}/value/{value}
Enable Notification	UUID	GET	/gatt/nodes/{deviceMAC}/services/{serviceUUID}/characteristics/{characteristicUUID}/value/0100
	Handle	GET	/gatt/nodes/{deviceMAC}/handle/{handle}/value/0100
Disable Notification	UUID	GET	/gatt/nodes/{deviceMAC}/services/{serviceUUID}/characteristics/{characteristicUUID}/value/0000
	Handle	GET	/gatt/nodes/{deviceMAC}/handle/{handle}/value/0000
Enable Indication	UUID	GET	/gatt/nodes/{deviceMAC}/services/{serviceUUID}/characteristics/{characteristicUUID}/value/0200
	Handle	GET	/gatt/nodes/{deviceMAC}/handle/{handle}/value/0200
Disable Indication	UUID	GET	/gatt/nodes/{deviceMAC}/services/{serviceUUID}/characteristics/{characteristicUUID}/value/0000
	Handle	GET	/gatt/nodes/{deviceMAC}/handle/{handle}/value/0000
Disconnect		DELETE	/gap/nodes/{deviceMAC}/connection

BLE Advertising Data

Topic	action
up/{gateway}/scan	data.scan

Message Payload

{
  "id": "",
  "action": "data.scan",
  "timestamp": 1678698297028,
  "gateway": "CC:1B:E0:E2:8F:2C",
  "data": [
    {
      "bdaddrs": [
        {
          "bdaddr": "AA:AA:AA:88:88:0E",
          "bdaddrType": "public"
        }
      ],
      "chipId": 0,
      "evtType": 0,
      "rssi": -67,
      "adData": "020106020A000C0967776A5F4E6F646963446F",
      "name": "gwj_NodicDo"
    }
  ]
}

Field Descriptions

Field	Subfield	Type	Required	Default	Description
data		object array	Yes		Message payload
	bdaddrs	object array	Yes	-	Device MAC
	bdaddr	string	Yes	-	Device MAC Address
	bdaddrType	string	Yes	-	Device address type public random
	chipId	uint32	Yes	-	Gateway chip ID 0 1
	evtType	uint32	Yes	-	Broadcast data type
	rssi	int	Yes	-	RSSI
	name	string	Yes	-	BLE specification parsed name from advertising or scan response packet, if not present, it's `(unknown)`
	adData	string	No	-	Original advertising packet HEX string
	scanData	string	No	-	Original scan response packet HEX string

BLE Connection Request

Topic	action
down/{gateway}/api	api

Message Payload

{
  "id": "35656",
  "action": "api",
  "timestamp": 1678698297028,
  "gateway": "CC:1B:E0:E2:8F:2C",
  "data": {
    "url": "/gap/nodes/{deviceMac}/connection",
    "method": "POST",
    "body": {
      "type": "public"
    }
  }
}

Field Descriptions

Field	Subfield	Subfield	Type	Required	Default	Description
data			object	Yes		Connect Device
	method		string	Yes	-	GET
	url		string	Yes	-	/gap/nodes/{deviceMac}/connection deviceMac: Device MAC address
	body		object	Yes	-
		type	string	Yes	public	Device address type, set according to bdaddrType in data.scan

BLE Connection Event

Topic	action
up/{gateway}/connection_state	data.connection_state

Message Payload

{
  "id": "",
  "action": "data.connection_state",
  "timestamp": 1678698297028,
  "gateway": "CC:1B:E0:E2:8F:2C",
  "data": [
    {
      "handle": "D8:0B:CB:62:5C:2B",
      "connectionState": "connected",
      "chipId": 0
    }
  ]
}

Field Descriptions

Field	Subfield	Type	Required	Description
data		object array	Yes	Message payload
	handle	string	Yes	Device MAC
	connectionState	string	Yes	connected: BLE connection complete event disconnected: BLE disconnection event
	chipId	uint32	Yes	Gateway chip ID

BLE Read Operation Request (Id)

Topic	action
down/{gateway}/api	api

Message Payload

{
  "id": "35656",
  "action": "api",
  "timestamp": 1678698297028,
  "gateway": "CC:1B:E0:E2:8F:2C",
  "data": {
    "url": "/gatt/nodes/{deviceMac}/services/{serviceId}/characteristics/{characteristicId}/value",
    "method": "GET"
  }
}

Field Descriptions

Field	Subfield	Type	Required	Default	Description
data		object	Yes
	method	string	Yes	-	GET
	url	string	Yes	-	/gatt/nodes/{deviceMac}/services/{serviceId}/characteristics/{characteristicId}/value deviceMac: BLE device MAC address serviceId: Actual UUID characteristicId: Actual UUID

BLE Write Operation Request (Id)

Topic	action
down/{gateway}/api	api

Message Payload

{
  "id": "35656",
  "action": "api",
  "timestamp": 1678698297028,
  "gateway": "CC:1B:E0:E2:8F:2C",
  "data": {
    "url": "/gatt/nodes/{deviceMac}/services/{serviceId}/characteristics/{characteristicId}/value/{value}?noresponse=1",
    "method": "GET"
  }
}

Field Descriptions

Field	Subfield	Type	Required	Default	Description
data		object	No
	method	string	Yes	-	GET
	url	string	Yes	-	/gatt/nodes/{deviceMac}/services/{serviceId}/characteristics/{characteristicId}/value/{value}?noresponse=1 deviceMac: BLE device MAC address serviceId: Actual UUID characteristicId: Actual UUID value: Data to write HEX string noresponse: 1: BLE Write Cmd 0: BLE Write Request and wait for Response

BLE Notification Data (Id)

Topic	action
up/{gateway}/notification	data.notification

Message Payload

{
  "id": "",
  "action": "data.notification",
  "timestamp": 1678698297028,
  "gateway": "CC:1B:E0:E2:8F:2C",
  "data": [
    {
      "value": "C1:04:92:DC:09:00",
      "handle": 23,
      "service": "FFAB",
      "characteristic": "FFAB",
      "id": "D8:0B:CB:62:5C:2B",
      "dataType": "notification"
    }
  ]
}

Field Descriptions

Field	Subfield	Type	Required	Default	Description
data		object array	Yes		Message payload
	value	string	Yes	-	Notification/Indication data HEX string
	handle	int	Yes	-	Notification/Indication data handle
	service	string	Yes	-	Service UUID
	characteristic	string	Yes	-	Characteristic UUID
	id	string	Yes	-	Device MAC
	dataType	string	Yes	-	notification indication

BLE Disconnect Request

Topic	action
down/{gateway}/api	api

Message Payload

{
  "id": "35656",
  "action": "api",
  "timestamp": 1678698297028,
  "gateway": "CC:1B:E0:E2:8F:2C",
  "data": {
    "url": "/gap/nodes/{deviceMac}/connection",
    "method": "DELETE"
  }
}

Field Descriptions

Field	Subfield	Type	Required	Default	Description
data		object	Yes		Message payload
	method	string	Yes	-	DELETE
	url	string	Yes	-	/gap/nodes/{deviceMac}/connection deviceMac: Device MAC address

BLE Disconnection Event

Topic	action
up/{gateway}/connection_state	data.connection_state

Message Payload

{
  "id": "",
  "action": "data.connection_state",
  "timestamp": 1678698297028,
  "gateway": "CC:1B:E0:E2:8F:2C",
  "data": [
    {
      "handle": "D8:0B:CB:62:5C:2B",
      "connectionState": "disconnected",
      "chipId": 0,
      "reason": "host disconnect"
    }
  ]
}

Field Descriptions

Field	Subfield	Type	Required	Description
data		object array	Yes	Message payload
	handle	string	Yes	Device MAC
	connectionState	string	Yes	connected: BLE connection complete event disconnected: BLE disconnection event
	chipId	uint32	Yes	Gateway chip ID
	reason	string	Yes	Disconnection reason

More API

Cassia RESTful API

Home

Overview

Getting Started

RESTful API

Overview of RESTful API
Common Parameters
Management API
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
- Batch Connect to a Target Device (v2.0 and above)
- Discover GATT Services and Characteristics
- 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
- Overview of Secure Pairing API
- Pair Request
- Pair-Input Request
- Unpair Request
- Just Works Example
- Passkey Entry Example: Initiator Inputs
- LE Legacy Pairing OOB Example
- Numeric Comparison Example (v2.0 and above)
- Security OOB Example (v2.0 and above)
Router Auto-Selection API
SSE Combination API

Advanced RESTful API

MQTT API (Beta Version)

Error Messages

Device Integrating

Sample Code

Misc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MQTT API ‐ BLE API

BLE API

Interaction Flow

Common APIs

BLE Advertising Data

Message Payload

Field Descriptions

BLE Connection Request

Message Payload

Field Descriptions

BLE Connection Event

Message Payload

Field Descriptions

BLE Read Operation Request (Id)

Message Payload

Field Descriptions

BLE Write Operation Request (Id)

Message Payload

Field Descriptions

BLE Notification Data (Id)

Message Payload

Field Descriptions

BLE Disconnect Request

Message Payload

Field Descriptions

BLE Disconnection Event

Message Payload

Field Descriptions

More API

Clone this wiki locally