497 lines
12 KiB
Markdown
Executable File
497 lines
12 KiB
Markdown
Executable File
# Soundbox Backend MQTT Specification
|
|
|
|
This document describes the backend contract used by the QF100 soundbox firmware in this project.
|
|
|
|
Source reference:
|
|
|
|
- MQTT payload parser: `app/source/MainApp/demo.c`
|
|
- Config endpoint constants: `app/source/MainApp/globalDefine.h`
|
|
|
|
## 1. Overview
|
|
|
|
The device communicates with the backend in two stages:
|
|
|
|
1. The device calls the config API to receive MQTT connection settings.
|
|
2. The device connects to MQTT and subscribes to the topic returned by the config API.
|
|
|
|
The backend then publishes JSON payloads to that topic.
|
|
|
|
Current firmware mode:
|
|
|
|
- `SAMPLE_MQTT_DEMO` is enabled by default.
|
|
- `MQTT_STRICT_TEST_DEMO` is disabled unless explicitly enabled in firmware.
|
|
|
|
## 2. Device Config API
|
|
|
|
The device sends a JSON request body to `CONFIG_ADDR`.
|
|
|
|
Current configured endpoint:
|
|
|
|
```text
|
|
http://sms.bizone.id/speaker/dev-config
|
|
```
|
|
|
|
Transport:
|
|
|
|
- HTTP is currently configured for the device config API.
|
|
- The firmware calls `sdk_http_get()` with the `http://` config URL.
|
|
- This avoids TLS/certificate validation issues during config fetch.
|
|
|
|
### Request Body
|
|
|
|
```json
|
|
{
|
|
"dev-model": "QF100",
|
|
"item-number": "00",
|
|
"dev-sn": "DEVICE_SN",
|
|
"hardware-config": "0x0F",
|
|
"fw-version": "1.0.0",
|
|
"fw-build": 1,
|
|
"app-config-version": 0,
|
|
"imei": "IMEI",
|
|
"imsi": "IMSI",
|
|
"iccid": "ICCID"
|
|
}
|
|
```
|
|
|
|
### Successful Response
|
|
|
|
```json
|
|
{
|
|
"error-code": 0,
|
|
"mqtt": {
|
|
"broker-ip": "broker.example.com",
|
|
"broker-port": 1883,
|
|
"client-id": "soundbox-DEVICE_SN",
|
|
"user-name": "mqtt_user",
|
|
"password": "mqtt_password",
|
|
"subscribe-topic": "soundbox/DEVICE_SN/down",
|
|
"keep-alive": 60
|
|
}
|
|
}
|
|
```
|
|
|
|
### Required Fields
|
|
|
|
| Field | Type | Required | Notes |
|
|
| --- | --- | --- | --- |
|
|
| `error-code` | number | yes | Must be `0` for success. |
|
|
| `mqtt` | object | yes | Required when `error-code` is `0`. |
|
|
| `mqtt.broker-ip` | string | yes | Hostname or IP. |
|
|
| `mqtt.broker-port` | number | yes | MQTT port. |
|
|
| `mqtt.client-id` | string | yes | MQTT client ID. |
|
|
| `mqtt.user-name` | string | yes | MQTT username. |
|
|
| `mqtt.password` | string | yes | MQTT password. |
|
|
| `mqtt.subscribe-topic` | string | yes | Topic the device will subscribe to. |
|
|
| `mqtt.keep-alive` | number | yes | Keep-alive interval in seconds. |
|
|
|
|
Important:
|
|
|
|
- Numeric fields must be JSON numbers, not strings.
|
|
- If any required MQTT field is missing, the device treats the config as invalid.
|
|
- `app-config-version` parsing is present but commented out in firmware, so it is not currently applied.
|
|
|
|
### Error Response
|
|
|
|
```json
|
|
{
|
|
"error-code": 1001
|
|
}
|
|
```
|
|
|
|
Any non-zero `error-code` is treated as config failure by the firmware.
|
|
|
|
## 3. MQTT Payment Payload
|
|
|
|
The backend publishes this payload to `mqtt.subscribe-topic`.
|
|
|
|
```json
|
|
{
|
|
"header": {
|
|
"category": 1
|
|
},
|
|
"data": {
|
|
"pay-amount": 15000
|
|
}
|
|
}
|
|
```
|
|
|
|
### Required Fields
|
|
|
|
| Field | Type | Required | Notes |
|
|
| --- | --- | --- | --- |
|
|
| `header` | object | yes | Container for message metadata. |
|
|
| `header.category` | number | yes | Use `1` for payment amount playback. |
|
|
| `data` | object | yes | Container for message body. |
|
|
| `data.pay-amount` | number | yes | Must be greater than `0`. |
|
|
|
|
Behavior:
|
|
|
|
- The device formats `pay-amount` into a 12-digit string.
|
|
- Example: `15000` becomes `000000015000`.
|
|
- The device displays the amount and plays the payment audio.
|
|
|
|
Do not send `pay-amount` as a string:
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"pay-amount": "15000"
|
|
}
|
|
}
|
|
```
|
|
|
|
Use a number instead:
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"pay-amount": 15000
|
|
}
|
|
}
|
|
```
|
|
|
|
## 3.1 MQTT Transport Security
|
|
|
|
Current firmware setting:
|
|
|
|
```c
|
|
#define MQTT_TLS_ENABLE (0)
|
|
```
|
|
|
|
This means MQTT currently connects without TLS.
|
|
|
|
The SDK and firmware code do support MQTT TLS:
|
|
|
|
- `sdk_MQTT_connect(..., tls, ...)` accepts a TLS flag.
|
|
- The firmware already passes `MQTT_TLS_ENABLE` into `sdk_MQTT_connect()`.
|
|
- Certificate setup hooks exist in firmware:
|
|
- `MQTT_SERVER_CA_CRT`
|
|
- `MQTT_CLIENT_CA_CRT`
|
|
- `MQTT_CLIENT_PRIKEY`
|
|
- `sdk_setx509cer(...)`
|
|
- `sdk_setx509_own_cer(...)`
|
|
- `sdk_setx509_prikey(...)`
|
|
|
|
To use MQTTS, firmware must be rebuilt with:
|
|
|
|
```c
|
|
#define MQTT_TLS_ENABLE (1)
|
|
```
|
|
|
|
Backend recommendation:
|
|
|
|
- For current firmware, expose plain MQTT, usually port `1883`.
|
|
- For TLS firmware, expose MQTTS, usually port `8883`, and provide the correct server CA chain expected by the firmware.
|
|
- Do not assume MQTTS is active unless the firmware was rebuilt with `MQTT_TLS_ENABLE (1)`.
|
|
|
|
## 4. MQTT OTA Trigger Payload
|
|
|
|
The backend can trigger an OTA check by publishing:
|
|
|
|
```json
|
|
{
|
|
"header": {
|
|
"category": 2
|
|
},
|
|
"data": {
|
|
"fw-version": "1.0.1",
|
|
"fw-build": 2
|
|
}
|
|
}
|
|
```
|
|
|
|
### Required Fields
|
|
|
|
| Field | Type | Required | Notes |
|
|
| --- | --- | --- | --- |
|
|
| `header.category` | number | yes | Use `2` for OTA trigger. |
|
|
| `data.fw-version` | string | yes | Target firmware version. |
|
|
| `data.fw-build` | number | yes | Target firmware build, must be greater than `0`. |
|
|
|
|
Behavior:
|
|
|
|
- If `fw-version` is greater than the current firmware version, the device starts OTA.
|
|
- If `fw-version` is equal but `fw-build` is greater, the device starts OTA.
|
|
- Otherwise, the device logs that no update is needed.
|
|
|
|
## 5. MQTT Device Heartbeat
|
|
|
|
The firmware publishes an application-level heartbeat over MQTT after it has connected and subscribed successfully.
|
|
|
|
Publish topic used by the device:
|
|
|
|
```text
|
|
{mqtt.subscribe-topic}/heartbeat
|
|
```
|
|
|
|
Example:
|
|
|
|
```text
|
|
soundbox/QF100123456/down/heartbeat
|
|
```
|
|
|
|
Payload:
|
|
|
|
```json
|
|
{
|
|
"header": {
|
|
"category": 3
|
|
},
|
|
"data": {
|
|
"dev-sn": "QF100123456",
|
|
"client-id": "soundbox-QF100123456",
|
|
"fw-version": "1.0.0",
|
|
"fw-build": 1,
|
|
"time": "20260607123045",
|
|
"battery-level": 80,
|
|
"wifi-ap": {
|
|
"ssid": "testap1",
|
|
"mac": "00:0f:e2:4e:aa:3e",
|
|
"rssi": -13
|
|
},
|
|
"main-cell-info": {
|
|
"mcc": 460,
|
|
"mnc": 0,
|
|
"rssi": 20
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Timing:
|
|
|
|
- The device publishes one heartbeat immediately after MQTT subscribe succeeds.
|
|
- The device then publishes periodically using `mqtt.keep-alive` seconds from the config response.
|
|
- If `mqtt.keep-alive` is `0`, firmware falls back to `60` seconds.
|
|
|
|
Backend handling:
|
|
|
|
- Subscribe to `{mqtt.subscribe-topic}/heartbeat`, or a wildcard such as `soundbox/+/down/heartbeat`.
|
|
- Treat each heartbeat message as the device's last-seen timestamp.
|
|
- This is separate from MQTT protocol `PINGREQ`/`PINGRESP`, which is handled by the broker and is not delivered as a subscribed message.
|
|
|
|
### Heartbeat Fields
|
|
|
|
| Field | Type | Required | Notes |
|
|
| --- | --- | --- | --- |
|
|
| `header.category` | number | yes | Always `3` for device heartbeat. |
|
|
| `data.dev-sn` | string | yes | Device serial number. |
|
|
| `data.client-id` | string | yes | MQTT client ID from config response. |
|
|
| `data.fw-version` | string | yes | Firmware version. |
|
|
| `data.fw-build` | number | yes | Firmware build number. |
|
|
| `data.time` | string | yes | Device local time in `YYYYMMDDHHMMSS` format. |
|
|
| `data.battery-level` | number | yes | Battery percentage calculated by firmware, `0` to `100`. |
|
|
| `data.wifi-ap` | object | optional | Present only when WiFi data is available. |
|
|
| `data.wifi-ap.ssid` | string | optional | Current configured WiFi SSID. |
|
|
| `data.wifi-ap.mac` | string | optional | AP MAC/BSSID, included only when the firmware can match it from WiFi scan result. |
|
|
| `data.wifi-ap.rssi` | number | optional | Connected WiFi RSSI from SDK. |
|
|
| `data.main-cell-info` | object | optional | Present only when GPRS/cellular data is available. |
|
|
| `data.main-cell-info.mcc` | number | optional | Parsed from IMSI when available. |
|
|
| `data.main-cell-info.mnc` | number | optional | Parsed from IMSI when available. |
|
|
| `data.main-cell-info.rssi` | number | optional | Cellular signal quality reported by the modem API. Current firmware does not expose LAC/cell-id through available SDK headers. |
|
|
|
|
Important:
|
|
|
|
- `wifi-ap` and `main-cell-info` are optional. Backend should not reject heartbeat if either object is absent.
|
|
- `wifi-ap.mac` is optional because the current SDK exposes AP MAC through scan results, not a direct "current BSSID" API.
|
|
- `main-cell-info.lac` and `main-cell-info.cell-id` are not sent by this firmware build because no SDK API for those values is available in this repo.
|
|
|
|
## 6. Unsupported Categories
|
|
|
|
For any category other than `1` or `2`, the firmware still requires:
|
|
|
|
```json
|
|
{
|
|
"header": {
|
|
"category": 99
|
|
},
|
|
"data": {}
|
|
}
|
|
```
|
|
|
|
The current firmware does not perform any action for unsupported categories.
|
|
|
|
## 7. OTA Check API Response
|
|
|
|
After an OTA trigger, the device calls the update check API configured by `UPDATE_ADDR`.
|
|
|
|
The response parsed by firmware is:
|
|
|
|
```json
|
|
{
|
|
"error-code": 0,
|
|
"version": "1.0.1",
|
|
"build": 2,
|
|
"file-length": 123456,
|
|
"download-url": "https://example.com/app_fota.bin"
|
|
}
|
|
```
|
|
|
|
### Required Fields
|
|
|
|
| Field | Type | Required | Notes |
|
|
| --- | --- | --- | --- |
|
|
| `error-code` | number | yes | Must be `0` for update available. |
|
|
| `version` | string | yes | New firmware version. |
|
|
| `build` | number | yes | New firmware build. |
|
|
| `file-length` | number | yes | Must be greater than `0`. |
|
|
| `download-url` | string | yes | Firmware download URL. |
|
|
|
|
Special error codes:
|
|
|
|
- `1002`: no update needed
|
|
- `1005`: download version not found
|
|
|
|
The firmware treats both as no-update conditions.
|
|
|
|
## 8. OTA Result Upload
|
|
|
|
The device uploads OTA result to `RESULT_ADDR`.
|
|
|
|
Request body:
|
|
|
|
```json
|
|
{
|
|
"dev-sn": "DEVICE_SN",
|
|
"result": 0
|
|
}
|
|
```
|
|
|
|
The current firmware sends the request but does not parse the response body.
|
|
|
|
## 9. Recommended Topic Design
|
|
|
|
Use one downlink topic per device:
|
|
|
|
```text
|
|
soundbox/{dev-sn}/down
|
|
```
|
|
|
|
Example:
|
|
|
|
```text
|
|
soundbox/QF100123456/down
|
|
```
|
|
|
|
Return the topic in config response:
|
|
|
|
```json
|
|
{
|
|
"error-code": 0,
|
|
"mqtt": {
|
|
"broker-ip": "broker.example.com",
|
|
"broker-port": 1883,
|
|
"client-id": "soundbox-QF100123456",
|
|
"user-name": "soundbox_user",
|
|
"password": "secret",
|
|
"subscribe-topic": "soundbox/QF100123456/down",
|
|
"keep-alive": 60
|
|
}
|
|
}
|
|
```
|
|
|
|
Backend can listen for heartbeat on:
|
|
|
|
```text
|
|
soundbox/{dev-sn}/down/heartbeat
|
|
```
|
|
|
|
## 10. End-to-End Example
|
|
|
|
### Config Response
|
|
|
|
```json
|
|
{
|
|
"error-code": 0,
|
|
"mqtt": {
|
|
"broker-ip": "broker.bizone.id",
|
|
"broker-port": 1883,
|
|
"client-id": "soundbox-QF100123456",
|
|
"user-name": "soundbox_user",
|
|
"password": "secret",
|
|
"subscribe-topic": "soundbox/QF100123456/down",
|
|
"keep-alive": 60
|
|
}
|
|
}
|
|
```
|
|
|
|
### Payment Publish
|
|
|
|
Publish to:
|
|
|
|
```text
|
|
soundbox/QF100123456/down
|
|
```
|
|
|
|
Payload:
|
|
|
|
```json
|
|
{
|
|
"header": {
|
|
"category": 1
|
|
},
|
|
"data": {
|
|
"pay-amount": 25000
|
|
}
|
|
}
|
|
```
|
|
|
|
### OTA Trigger Publish
|
|
|
|
Publish to:
|
|
|
|
```text
|
|
soundbox/QF100123456/down
|
|
```
|
|
|
|
Payload:
|
|
|
|
```json
|
|
{
|
|
"header": {
|
|
"category": 2
|
|
},
|
|
"data": {
|
|
"fw-version": "1.0.1",
|
|
"fw-build": 2
|
|
}
|
|
}
|
|
```
|
|
|
|
### Heartbeat From Device
|
|
|
|
Subscribe to:
|
|
|
|
```text
|
|
soundbox/QF100123456/down/heartbeat
|
|
```
|
|
|
|
Payload received:
|
|
|
|
```json
|
|
{
|
|
"header": {
|
|
"category": 3
|
|
},
|
|
"data": {
|
|
"dev-sn": "QF100123456",
|
|
"client-id": "soundbox-QF100123456",
|
|
"fw-version": "1.0.0",
|
|
"fw-build": 1,
|
|
"time": "20260607123045",
|
|
"battery-level": 80
|
|
}
|
|
}
|
|
```
|
|
|
|
## 11. Notes For Backend Implementation
|
|
|
|
- Always publish valid JSON.
|
|
- Always use JSON numbers for numeric fields.
|
|
- Do not use strings for `category`, `pay-amount`, `fw-build`, `broker-port`, or `keep-alive`.
|
|
- Keep `client-id` unique per device.
|
|
- Use the device serial number `dev-sn` as the main device identifier.
|
|
- The firmware logs MQTT payloads through CATStudio/DIAG, useful for debugging invalid payloads.
|
|
- Use MQTT broker ACLs carefully: the device must be allowed to publish to `{subscribe-topic}/heartbeat`.
|