MQTT API ‐ Convention

API Convention

MAC Addresses

• MACs should be uppercase with colons.
• Include in both message body and topic.
• Applies to both gateway and device MACs.

Data Direction

Data Direction	Description
Upstream	Cassia Bluetooth Gateway -> User MQTT Server -> User Application Service
Downstream	User Application Service -> User MQTT Server -> Cassia Bluetooth Gateway

Topic List

Topic	Data Direction	Category	Description
up/{gateway}/gateway_status	Upstream	GATEWAY_STATUS	Gateway status
up/{gateway}/heartbeat	Upstream	HEARTBEAT	Heartbeat request
down/{gateway}/heartbeat_reply	Downstream	HEARTBEAT	Heartbeat response
down/{gateway}/api	Downstream	API	RESTful API request
up/{gateway}/api_reply	Upstream	API	RESTful API response
up/{gateway}/scan	Upstream	BLE Data	BLE scan data
up/{gateway}/notification	Upstream	BLE Data	BLE notification data
up/{gateway}/connection_state	Upstream	BLE Data	BLE connection state event

Message Format

Message Payload

{
  "id": "35656",
  "action": "api",
  "timestamp": 1678698297028,
  "gateway": "CC:1B:E0:E2:8F:2C",
  "data": {}
}

Field Descriptions

Field	Type	Required	Default	Description
id	string	Yes	-	Message ID, unique identifier, consistent with request in responses
action	string	Yes	-	Distinguishes message type
timestamp	uint32	Yes	-	Timestamp in milliseconds
gateway	string	Yes	-	Gateway MAC address
data	object	Yes	-	Message payload

Action Field

• Use the action field for message processing, not the topic.
• Request/response pairs use {action}/{action}_reply.
• For hierarchical messages, use a period (.) to separate levels.

Action Type	Description
gateway_status	Gateway status
heartbeat	Heartbeat request
heartbeat_reply	Heartbeat response
api	RESTful API request
api_reply	RESTful API response
data.scan	BLE scan data
data.notification	BLE notification data
data.connection_state	BLE connection state event