MQTT API Reference

MQTT API Reference

Status: Draft | Applies to: SPM/SDM Open WiFi (ESP32-8685) | Firmware: Basic 5.1.14+ (SPM/SDM) / Basic 6.1.4+(SDM01 UART Flashing PIN) | Updated: 2026-06-23

1. Overview

The Bituo SPM/SDM series smart meters can communicate over MQTT using a publish/subscribe model. The device pushes telemetry data periodically and responds to JSON commands sent from the server.

Important Notes for Firmware Basic 5.1.14+/6.1.4+:

• Command architecture is unified with the BLE API.

• The seq (sequence) field is deprecated and no longer used in requests or responses.

• Command responses follow a standardized ok/msg/event/d structure.

---

2. Topic Architecture

All MQTT topics follow this default pattern: {ProductModel}/{SerialNumber}/{TopicType}

Topic Suffix	Direction	Description	QoS	Retain
/data	Device → Server	Periodic telemetry data (e.g., Voltage, Current)	0	No
/cmd	Server → Device	Commands to device	0/1	No
/cdata	Device → Server	Command execution responses	0	No
/mdata	Device → Server	Device metadata (published on boot)	0	Yes

Example Topics (for SPM02, SN: 9D1024BD51F1):

• SPM02/9D1024BD51F1/data

• SPM02/9D1024BD51F1/cmd

---

3. Telemetry Data (/data)

The device publishes measurement data to the /data topic at a configurable interval (default: 30 seconds).

• Note: All measurement values are formatted as Strings (e.g., "227.7").

• The TP field indicates the phase type (1 for Single-Phase, 3 for Three-Phase). Developers should parse the payload structure based on the TP value.

3.1 System Information Fields (Common)

These fields are included in all /data payloads regardless of the model:

Field	Type	Description
Post	number	Packet sequence counter
Time	number	Unix timestamp (seconds)
IP	string	Device IP address
Rssi	number	Wi-Fi signal strength (dBm)
FWVersion	string	Firmware version (e.g., "5.1.12")
MCUVersion	string	MCU firmware version (e.g., "001.01.10")
SerialNumber	string	Device MAC/Serial Number
ProductModel	string	Product model (e.g., "SPM01", "SPM02")
TP	number	Phase Type (1 = Single-Phase, 3 = Three-Phase)

3.2 Single-Phase Payload (TP: 1)

For single-phase devices (e.g., SPM01), measurement fields have no suffix.

{
  "Post": 927,
  "Time": 1782313081,
  "IP": "192.168.50.188",
  "Rssi": -68,
  "FWVersion": "5.1.14",
  "SerialNumber": "9C0024BD51F1",
  "ProductModel": "SPM01",
  "MCUVersion": "003.00.13",
  "TP": 1,
  "Voltage": "227.6",
  "Current": "0.000",
  "ActivePower": "0.000",
  "ApparentPower": "0.000",
  "PowerFactor": "1.00",
  "Frequency": "50.09",
  "ForwardEnergy": "0.00",
  "ReverseEnergy": "0.00",
  "TotalEnergy": "0.00"
}

3.3 Three-Phase Payload (TP: 3)

For three-phase devices (or devices operating in 3-phase mode like SPM02), measurement fields use X/Y/Z suffixes.

{
  "Post": 1842,
  "Time": 1782312995,
  "IP": "192.168.50.238",
  "Rssi": -72,
  "FWVersion": "5.1.14",
  "SerialNumber": "50701B597664",
  "ProductModel": "SPM02",
  "MCUVersion": "001.01.01",
  "TP": 3,
  "VoltageX": "226.3",
  "VoltageY": "226.2",
  "VoltageZ": "226.2",
  "CurrentX": "0.000",
  "CurrentY": "0.000",
  "CurrentZ": "0.000",
  "ActivePowerX": "0.000",
  "ActivePowerY": "0.000",
  "ActivePowerZ": "0.000",
  "TotalActivePower": "0.000",
  "ReactivePowerX": "0.000",
  "ReactivePowerY": "0.000",
  "ReactivePowerZ": "0.000",
  "ApparentPowerX": "0.000",
  "ApparentPowerY": "0.000",
  "ApparentPowerZ": "0.000",
  "PowerFactorX": "0.00",
  "PowerFactorY": "0.00",
  "PowerFactorZ": "1.00",
  "UnbalanceLineCurrents": "0",
  "OverallPowerFactor": "0.00",
  "Frequency": "50.01",
  "ForwardEnergyX": "0.85",
  "ForwardEnergyY": "0.02",
  "ForwardEnergyZ": "0.02",
  "TotalForwardEnergy": "0.89",
  "ReverseEnergyX": "0.00",
  "ReverseEnergyY": "0.00",
  "ReverseEnergyZ": "0.00",
  "TotalReverseEnergy": "0.00"
}

---

4. Metadata (/mdata)

Published once upon device boot with the Retain flag set. Useful for discovering device basic info without waiting for telemetry.

{
  "product": "EnergySensor-SPM01-9C0024BD51F1",
  "Serialnumber": "9C0024BD51F1",
  "fwVer": "5.1.12"
}

---

5. Command & Control (/cmd & /cdata)

5.1 Standard Message Format

Request (/cmd): A JSON object containing at least the cmd string.

{
  "cmd": "location"
}

Response (/cdata): A standardized JSON object returning the execution result.

{
  "ok": true,
  "msg": "location received",
  "event": "location",
  "d": {} 
}

• ok (boolean): Success or failure.

• msg (string): Result description or error message.

• event (string): Echoes the requested command.

• d (object): Optional. Contains requested data payload.

5.2 Supported Commands Reference

getFunctionMap - Read Device Capabilities

Reads the 16-bit function bitmap indicating enabled services (e.g., MQTT, HTTP).

• Request: {"cmd": "getFunctionMap"}

• Response:

  {
    "ok": true,
    "msg": "",
    "event": "getFunctionMap",
    "d": { "functionMap": 640 }
  }

model - Read Device Configuration

Returns a snapshot of the device's network and MQTT configuration.

• Request: {"cmd": "model"}

• Response:

  {
    "ok": true,
    "msg": "",
    "event": "model",
    "d": {
      "WN": "Bituo-ext",
      "MH": "broker.emqx.io",
      "MF": true,
      "MP": 8883,
      "MS": true
    }
  }

location - Identify Device

Triggers the device LED/Buzzer to flash/beep for 15 seconds.

• Request: {"cmd": "location"}

• Response: {"ok": true, "msg": "location received", "event": "location"}

zero - Reset Energy Counters

⚠️ Irreversible. Resets all accumulated energy counters to zero.

• Request: {"cmd": "zero"}

• Response: {"ok": true, "msg": "zero received", "event": "zero"}

restart - Reboot Device

Triggers a soft reboot.

• Request: {"cmd": "restart"}

• Response: {"ok": true, "msg": "restart received", "event": "restart"}

wifi - Configure Wi-Fi

Updates Wi-Fi credentials.

• Request:

  {
    "cmd": "wifi",
    "ssid": "YourSSID",
    "pass": "YourPassword"
  }

mqtt - Configure MQTT Broker

Updates MQTT broker settings.

• Request:

  {
    "cmd": "mqtt",
    "data": "broker.emqx.io|client_id|1|8883|30|user|pwd"
  }

  (Format: host|clientid|ssl(1/0)|port|interval|username|password)

---

6. How to Configure MQTTS (TLS/SSL)

The device supports secure MQTT connections over TLS 1.2 and TLS 1.3 to ensure data encryption and prevent man-in-the-middle attacks. Follow these steps to configure MQTTS via the embedded Web UI.

Step 1: Access the Embedded Web UI

1. Open a web browser and enter the device's IP address (e.g., http://192.168.50.208).

2. Troubleshooting: If the web page is inaccessible, the HTTP service might be disabled on the device. You can enable it using the BT Powerlink APP or the WeChat Mini APP:

   • Open the App and connect to the device via Bluetooth.

   • Navigate to Settings -> Forwarding.

   • Turn on the HTTP toggle.

Step 2: Upload the CA Certificate

To establish a trusted TLS connection, the device needs the Root CA certificate of your MQTT broker.

1. In the Web UI, navigate to Edit -> Forwarding -> Upload MQTT CA certificate.

2. Click Choose File and select your CA certificate file (must be in PEM format, usually .pem or .crt).

3. Click Upload.

Step 3: Configure MQTT Broker Settings

1. Navigate to Edit -> Forwarding -> MQTT broker.

2. Check the SSL / TLS box at the top.

3. Fill in your broker details.

Example using EMQX Public Broker:

• Host: broker.emqx.io

• Port: 8883 (Standard secure MQTT port)

• Client ID / Username / Password: Fill according to your needs.

• ReportFrequency: Set your desired interval (e.g., 30 seconds).

• Click Save MQTT.

💡 Tip: How to get the EMQX CA Certificate? If you are using broker.emqx.io, you can download their Root CA certificate directly from the EMQX official website (search for "EMQX Public Broker CA download"). Alternatively, you can visit https://broker.emqx.io in your browser, click the "Lock" icon in the address bar, view the certificate details, and export the Root CA as a Base64 encoded .cer or .crt file.

Step 4: Reboot to Apply Changes

After saving the configuration, the device must be rebooted for the new TLS settings and certificates to take effect.

1. Look at the top right corner of the Web UI dashboard.

2. You will see a notification: "Configuration was sent. Enable restart when you are ready to reboot the device."

3. Check the "Send restart command" box. The device will reboot immediately and attempt to connect to your broker using MQTTS.

4. Once rebooted, you can verify the connection status at the top right of the dashboard (it should display MQTT: Online).

---

7. Appendix: Major Changes from Legacy API (v5.1.14-)

For developers migrating from the older firmware (e.g., v1.1.8) to the new Basic Firmware (5.1.12+), please note the following breaking changes. The architecture has been unified with the BLE standard to improve efficiency and reduce payload sizes.

7.1 Quick Comparison Table

Feature / Concept	Legacy API (v5.1.13-)	Basic Firmware (v5.1.14+)
Topic Prefix	bituotechnik/{Model}/...	{Model}/... (Prefix removed)
Command Format	Uppercase (e.g., RDATA, WINT)	Lowercase / BLE semantics (e.g., location)
Request Tracking	Uses seq (Sequence Number)	Deprecated. Uses event field in response
Response Format	{"result": "SUCCESS", "seq": ...}	{"ok": true, "msg": "...", "event": "...", "d": {...}}
Phase Indicator	Implicit (relies on DeviceType)	Explicit TP field (1 = Single, 3 = Three-Phase)
New Telemetry Fields	N/A	Time, IP, MCUVersion
Metadata (/mdata)	macAddr, fwVer	product, Serialnumber, fwVer

7.2 Detailed Change Notes

• Command Architecture (BLE Unification): The seq field is completely removed. Request/response matching is now handled via the event field in the response payload. Commands now strictly follow the BLE API semantics.

• Telemetry Payload (/data): Added the TP field to explicitly indicate phase type, replacing the old DeviceType logic. Payloads now include Time (Unix timestamp), IP, and MCUVersion. (Note: Starting from v5.1.14, calculated totals like TotalActivePower, TotalForwardEnergy, and TotalReverseEnergy have been re-introduced to the 3-phase payload).

• Metadata (/mdata): The JSON schema has been updated. The legacy macAddr field is replaced by Serialnumber, and a new product string is included.