# 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`.