MQTT API ‐ BLE API - CassiaNetworks/CassiaSDKGuide GitHub Wiki

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
Loading

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

Copyright © 2021 Cassia Networks, Inc.

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