> For the complete documentation index, see [llms.txt](https://docs.bituo-technik.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/telemetry-payload.md).

# Telemetry Payload

{% hint style="info" %}
**Status:** Acitve | **Applies to:** all SPM / SDM Open Wi-Fi branches | **Updated:** 2026-10-17
{% endhint %}

\
The device periodically builds one telemetry JSON (a "packet"). The same JSON is sent unchanged over several channels, so its fields are maintained only on this page.

### 1. Which channels carry it

<table><thead><tr><th width="216.4444580078125">Channel</th><th>How to get it</th><th>Period</th></tr></thead><tbody><tr><td>MQTT</td><td>Subscribe to <code>{Model}/{SN}/data</code></td><td>Default 5 s, configurable (MQTT period, minimum 1 s)</td></tr><tr><td>HTTP / HTTPS</td><td><code>GET /data</code>; the <code>data</code> field of <code>GET /snapshot</code></td><td>On demand, latest packet on every call</td></tr><tr><td>WebSocket</td><td>Pushed automatically after you connect</td><td>Default 5000 ms, 100 ms to 86400000 ms</td></tr><tr><td>UDP</td><td>Sent to the configured target IP:port</td><td>Default 5000 ms, minimum 100 ms</td></tr><tr><td>Modbus TCP</td><td>Register reads, <strong>not JSON</strong>; see Modbus TCP</td><td>On demand</td></tr><tr><td>BLE</td><td><code>cmd=read</code>, then read the characteristic</td><td>On demand</td></tr></tbody></table>

The periods are independent; how to change them is in the Business Command Reference (`mqtt`, `udp`, `setInterval`). The value on the device wins over any factory default and can be read from the `model` response (MQTT period `MI`, UDP period `UI`; in HTTP `/model` they are `mqttInterval`, `udpInterval`, `wsInterval`).

### 2. Common fields

Present on every model:

<table><thead><tr><th width="169.77783203125">Field</th><th width="140.6666259765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>Post</code></td><td>number</td><td>Packet counter, +1 for each packet built, back to 0 after a reboot. Use it to spot loss and duplicates</td></tr><tr><td><code>Time</code></td><td>number</td><td>Unix timestamp (seconds). The device syncs by NTP; do not trust it before the first sync</td></tr><tr><td><code>IP</code></td><td>string</td><td>Device IPv4</td></tr><tr><td><code>Rssi</code></td><td>number</td><td>Wi-Fi signal strength in dBm, negative</td></tr><tr><td><code>FWVersion</code></td><td>string</td><td>Wi-Fi module firmware version, for example <code>"5.1.16"</code></td></tr><tr><td><code>MCUVersion</code></td><td>string</td><td>Metering MCU firmware version, for example <code>"003.00.13"</code></td></tr><tr><td><code>SerialNumber</code></td><td>string</td><td>Device serial number, 12 uppercase hex characters (Wi-Fi MAC)</td></tr><tr><td><code>ProductModel</code></td><td>string</td><td>Model, for example <code>SPM01</code>, <code>SPM02</code>, <code>SDM01_3PN</code></td></tr><tr><td><code>TP</code></td><td>number</td><td>Model code, see Section 3</td></tr></tbody></table>

### 3. TP model code

`TP` is a **model code**, not a phase count.

<table><thead><tr><th width="161.2222900390625">TP</th><th>Model</th><th>Phases</th><th>Seen on</th></tr></thead><tbody><tr><td>1</td><td><code>SPM01</code></td><td>single</td><td>Basic, Lite</td></tr><tr><td>2</td><td><code>SDM01_1PN</code></td><td>single</td><td>Basic, Lite</td></tr><tr><td>3</td><td><code>SPM02</code></td><td>three</td><td>Basic, Lite</td></tr><tr><td>4</td><td><code>SDM01_3PN</code></td><td>three</td><td>Basic, Lite</td></tr><tr><td>5</td><td><code>SDM02</code></td><td>split</td><td>Basic, Lite</td></tr><tr><td>8</td><td>all SDM01 Gen2 models</td><td>single or three</td><td>Basic+, Pro</td></tr><tr><td>9</td><td>other models</td><td>—</td><td>not covered here</td></tr></tbody></table>

Points to remember:

* On SDM01 Gen2 (Basic+ / Pro) `TP` is always `8`, so it **cannot** tell single phase from three phase.
* Decide by `ProductModel` or by which fields exist (`VoltageX` means three-phase, `VoltageL1` means split-phase, `Voltage` means single-phase). Do not hard-code `TP`.
* An earlier published page said "`TP` 1 = single phase, 3 = three phase"; that is only true for SPM01 / SPM02.

### 4. Fields per model

Values are **strings** with fixed decimals: voltage 1, current and power 3, power factor and frequency 2, energy 2, unbalance 0. Units: V, A, kW, kVA, kVAR, Hz, kWh, %.

#### 4.1 Single-phase (`SPM01`, `SDM01_1PN`)

| Field           | Unit | Description                    |
| --------------- | ---- | ------------------------------ |
| `Voltage`       | V    | Voltage                        |
| `Current`       | A    | Current                        |
| `ActivePower`   | kW   | Active power                   |
| `ApparentPower` | kVA  | Apparent power                 |
| `PowerFactor`   | —    | Power factor                   |
| `Frequency`     | Hz   | Frequency                      |
| `ForwardEnergy` | kWh  | Forward (import) active energy |
| `ReverseEnergy` | kWh  | Reverse (export) active energy |
| `TotalEnergy`   | kWh  | Forward + reverse              |

#### 4.2 Split-phase (`SDM02`)

<table><thead><tr><th width="575.666748046875">Field</th><th>Unit</th></tr></thead><tbody><tr><td><code>VoltageL1</code>, <code>VoltageL2</code></td><td>V</td></tr><tr><td><code>CurrentL1</code>, <code>CurrentL2</code>, <code>TotalCurrent</code></td><td>A</td></tr><tr><td><code>ActivePowerL1</code>, <code>ActivePowerL2</code>, <code>TotalActivePower</code></td><td>kW</td></tr><tr><td><code>ReactivePowerL1</code>, <code>ReactivePowerL2</code>, <code>TotalReactivePower</code></td><td>kVAR</td></tr><tr><td><code>ApparentPowerL1</code>, <code>ApparentPowerL2</code>, <code>TotalApparentPower</code></td><td>kVA</td></tr><tr><td><code>PowerFactorL1</code>, <code>PowerFactorL2</code>, <code>OverallPowerFactor</code></td><td>—</td></tr><tr><td><code>AverageVoltageL_N</code></td><td>V</td></tr><tr><td><code>AverageLineCurrent</code></td><td>A</td></tr><tr><td><code>Frequency</code></td><td>Hz</td></tr><tr><td><code>ForwardEnergyL1</code>, <code>ForwardEnergyL2</code>, <code>TotalForwardEnergy</code></td><td>kWh</td></tr><tr><td><code>ReverseEnergyL1</code>, <code>ReverseEnergyL2</code>, <code>TotalReverseEnergy</code></td><td>kWh</td></tr><tr><td><code>TotalEnergyL1</code>, <code>TotalEnergyL2</code>, <code>TotalEnergy</code></td><td>kWh</td></tr></tbody></table>

#### 4.3 Three-phase (`SPM02`, `SDM01_3PN`)

`X`, `Y`, `Z` are phases A, B, C.

<table><thead><tr><th width="579">Field</th><th>Unit</th></tr></thead><tbody><tr><td><code>VoltageX</code>, <code>VoltageY</code>, <code>VoltageZ</code></td><td>V</td></tr><tr><td><code>CurrentX</code>, <code>CurrentY</code>, <code>CurrentZ</code>, <code>TotalCurrent</code></td><td>A</td></tr><tr><td><code>ActivePowerX</code>, <code>ActivePowerY</code>, <code>ActivePowerZ</code>, <code>TotalActivePower</code></td><td>kW</td></tr><tr><td><code>ReactivePowerX</code>, <code>ReactivePowerY</code>, <code>ReactivePowerZ</code>, <code>TotalReactivePower</code></td><td>kVAR</td></tr><tr><td><code>ApparentPowerX</code>, <code>ApparentPowerY</code>, <code>ApparentPowerZ</code>, <code>TotalApparentPower</code></td><td>kVA</td></tr><tr><td><code>PowerFactorX</code>, <code>PowerFactorY</code>, <code>PowerFactorZ</code>, <code>OverallPowerFactor</code></td><td>—</td></tr><tr><td><code>AverageVoltageL_N</code></td><td>V</td></tr><tr><td><code>AverageLineCurrent</code></td><td>A</td></tr><tr><td><code>UnbalanceLineCurrents</code></td><td>%</td></tr><tr><td><code>Frequency</code></td><td>Hz</td></tr><tr><td><code>ForwardEnergyX</code>, <code>ForwardEnergyY</code>, <code>ForwardEnergyZ</code>, <code>TotalForwardEnergy</code></td><td>kWh</td></tr><tr><td><code>ReverseEnergyX</code>, <code>ReverseEnergyY</code>, <code>ReverseEnergyZ</code>, <code>TotalReverseEnergy</code></td><td>kWh</td></tr><tr><td><code>TotalEnergyX</code>, <code>TotalEnergyY</code>, <code>TotalEnergyZ</code>, <code>TotalEnergy</code></td><td>kWh</td></tr></tbody></table>

Field sets differ slightly between firmware versions (for example `TotalCurrent`, `TotalReactivePower`, `TotalApparentPower`, `AverageVoltageL_N`, `AverageLineCurrent` and `TotalEnergy*` exist on 5.1.16 and may be missing on older versions). Use a field if it is there and ignore it if it is not.

### 5. Examples

Single-phase:

```json
{
  "Post": 927,
  "Time": 1782313081,
  "IP": "192.168.1.20",
  "Rssi": -68,
  "FWVersion": "5.1.16",
  "SerialNumber": "AABBCCDDEEFF",
  "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"
}
```

Three-phase:

```json
{
  "Post": 1842,
  "Time": 1782312995,
  "IP": "192.168.1.21",
  "Rssi": -72,
  "FWVersion": "5.1.16",
  "SerialNumber": "AABBCCDDEE01",
  "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", "TotalCurrent": "0.000",
  "ActivePowerX": "0.000", "ActivePowerY": "0.000", "ActivePowerZ": "0.000", "TotalActivePower": "0.000",
  "ReactivePowerX": "0.000", "ReactivePowerY": "0.000", "ReactivePowerZ": "0.000", "TotalReactivePower": "0.000",
  "ApparentPowerX": "0.000", "ApparentPowerY": "0.000", "ApparentPowerZ": "0.000", "TotalApparentPower": "0.000",
  "PowerFactorX": "0.00", "PowerFactorY": "0.00", "PowerFactorZ": "1.00", "OverallPowerFactor": "0.00",
  "AverageVoltageL_N": "226.2", "AverageLineCurrent": "0.000", "UnbalanceLineCurrents": "0",
  "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",
  "TotalEnergyX": "0.85", "TotalEnergyY": "0.02", "TotalEnergyZ": "0.02", "TotalEnergy": "0.89"
}
```

### 6. Generic format (`commonmode`)

`{"cmd":"commonmode","value":1}` switches the report format from the default "BT format" (the sections above) to a "generic format" that follows the common smart-meter `NotifyStatus` message shape; `value=0` switches back. The setting is saved and survives reboots.

What changes in the generic format:

* Common fields use lowercase keys: `tp`, `src` (full device name), `dst` (always `"*"`), `method` (always `"NotifyStatus"`), `ip`, `rssi`, `fwversion`, `serialnumber`, `mcuversion`, `post`.
* Measurements sit under `params`: the timestamp is `params.ts`, the values are in `params["em:0"]`, and they are **numbers**, not strings.
* Power is in **W** and energy in **Wh** (the BT format uses kW and kWh; the device multiplies by 1000).
* Single-phase keys: `act_power`, `aprt_power`, `current`, `freq`, `pf`, `voltage`, `act_energy`, `act_ret_energy`.
* Three-phase keys: prefix `a_` / `b_` / `c_` with `act_power`, `aprt_power`, `current`, `freq`, `pf`, `voltage`; plus `total_act_power`, `total_aprt_power`, `total_current`, `a_total_act_energy`, `a_total_act_ret_energy` (same for B and C), `total_act`, `total_act_ret`. When a phase voltage is 50 V or lower, that phase's `*_freq` is 0.
* `params["emdata:0"]` is always an empty object; read energy from the keys in `em:0`.

```json
{
  "tp": 1,
  "src": "EnergySensor-SPM01-AABBCCDDEEFF",
  "dst": "*",
  "method": "NotifyStatus",
  "ip": "192.168.1.20",
  "rssi": -68,
  "fwversion": "5.1.16",
  "serialnumber": "AABBCCDDEEFF",
  "mcuversion": "003.00.13",
  "post": 12,
  "params": {
    "ts": 1782313081,
    "em:0": {
      "act_power": 123.0, "aprt_power": 125.0, "current": 0.54,
      "freq": 50.01, "pf": 0.98, "voltage": 227.6,
      "act_energy": 1234.0, "act_ret_energy": 0.0
    },
    "emdata:0": {}
  }
}
```

With the generic format on, the Modbus TCP register layout also changes to that style. This documentation does **not** cover that layout; keep `commonmode=0` if you need the standard register map.

### 7. Parsing advice

1. Look at `ProductModel` and the field names to choose single-phase, split-phase or three-phase parsing; do not rely on `TP`.
2. Parse numeric strings as decimal floats and do not assume the number of decimals stays fixed.
3. Use `Post` to detect duplicates and loss; after a reboot `Post` returns to a small value, so do not treat a decrease as an error.
4. Before using `Time`, check that it is not obviously small (not yet synced).
5. Ignore unknown fields and do not treat missing fields as errors.
