> 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.md).

# SPM/SDM Open Wi-Fi API Overview

{% hint style="info" %}
**Status:** Active | **Applies to:** SPM/SDM Open Wi-Fi Series (ESP32-8685 / C6) | **Updated:** 2026-07-12
{% endhint %}

Read this page first, then open only the page for the job you have:

1. Section 2: confirm the meter is Basic, Basic+, Lite, or Pro.
2. Section 3: check that the branch actually has the channel you want.
3. Section 4: open that page. Provisioning and read/write over BLE go through GATT. To read electrical values with no connection, use encrypted business advertising (Lite / Pro only).

The pages in the left sidebar cover MQTT, mDNS, Modbus TCP, and BLE. HTTP, WebSocket, UDP, shared telemetry fields, error codes, and the business commands are in the [integration repository](https://github.com/bituo-technik/bt-open-wifi-apis/tree/docs/bilingual-entry-pages).

***

SPM / SDM Open Wi-Fi meters give system integrators and DIY builders local and cloud communication, so you can write an app or connect a meter to a system you already have.

* **Local network:** HTTP / HTTPS, WebSocket, UDP reports, Modbus TCP, mDNS discovery.
* **Cloud:** MQTT / MQTTS. MQTTS also works with a private broker.
* **Near-field from a phone:** BLE, plaintext or secured, for provisioning and local control.

All channels share one set of business commands (`cmd`) and one response shape, `ok / msg / event / d`. The command list is maintained in one place: [Business Command Reference](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/ble-common/ble-business-api.en.md). Each channel page only describes how to connect, how messages are wrapped, and the limits.

The product line has four firmware branches. **Channels differ between branches**, so check before integrating.

| Firmware Branch      | Basic (8685)                       | Basic+ (8685)                               | Lite (8685)                                 | Pro (C6)                           |
| -------------------- | ---------------------------------- | ------------------------------------------- | ------------------------------------------- | ---------------------------------- |
| **Target Hardware**  | SPM / SDM                          | SDM01                                       | SPM/SDM                                     | SDM01 Gen2                         |
| **Latest Version**   | B\_5.1.14 & B\_6.1.7 <sup>1)</sup> | BPlus\_1.2.8 & BPlus\_2.2.4 <sup>2)</sup>   | Lite\_5.1.11 & Lite\_6.1.4<sup>2)</sup>     | Pro\_V3.1.11                       |
| **Core Features**    | Cleartext BLE & Wi-Fi              | Cleartext BLE, Encrypted WiFi <sup>3)</sup> | Encrypted BLE & Cleartext WiFi<sup>3)</sup> | Encrypted BLE & WiFi <sup>3)</sup> |
| **WiFi Strength**    | 0 dB                               | 13 dB                                       | 0dB                                         | 13 dB                              |
| **Lifecycle Status** | NRND                               | NRND                                        | Active                                      | Active                             |

1. `B_6.1.7` is for the SDM01 Combo with the UART external flashing pins. `B_5.1.14` is for SPM01, SPM02, the SDM01 Combo with JTAG flashing pins, and SDM02.
2. Basic+ was the Gen1 EV / PV version and has been replaced by SDM01 Gen2. At most **1** TLS connection at a time.
3. Lite's BLE encryption covers provisioning and data advertising. On Wi-Fi, only MQTT supports TLS 1.2 / 1.3. HTTP, Modbus TCP, and WebSocket have no TLS.
4. Pro's BLE encryption covers provisioning and data advertising. On Wi-Fi, at most **2** TLS connections at a time.

The interface documents in the integration repository were checked against Basic / Lite 5.1.16, Basic+ 1.2.12, and Pro 3.1.19. The table above is the published product line.

#### 2.1 How to tell the branch

| You want to know         | How to read it                                                                                                                                                                                                                                      |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plaintext or secured BLE | Advertised service UUID: `A002` plaintext (Basic / Basic+), `A003` secured (Lite / Pro). A meter exposes only one of them.                                                                                                                          |
| Firmware version         | MQTT `mdata.fwVer`, `FWVersion` in telemetry, HTTP `/snapshot`, or Modbus register 997                                                                                                                                                              |
| Which channels are on    | `{"cmd":"getFunctionMap"}`. Bit definitions are in [Business Command Reference, Appendix B](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/ble-common/ble-business-api.en.md#appendix-b-functionmap-bits). |

| Channel                      |      Basic      |      Basic+     |       Lite       |        Pro       |
| ---------------------------- | :-------------: | :-------------: | :--------------: | :--------------: |
| **BLE plaintext** (`A002`)   |        ✅        |        ✅        |         ❌        |         ❌        |
| **BLE secured** (`A003`)     |        ❌        |        ❌        |         ✅        |         ✅        |
| **MQTT** (1883)              |        ✅        |        ✅        |         ✅        |         ✅        |
| **MQTTS** (TLS)              |        ✅        |        ✅        |         ✅        |         ✅        |
| **HTTP** (80, plaintext)     | ✅ on by default | ✅ on by default | ✅ off by default | ✅ off by default |
| **HTTPS** (443)              |        ❌        |        ❌        |         ❌        |         ✅        |
| **Modbus TCP** (502)         |        ✅        |        ✅        |         ✅        |         ✅        |
| **Modbus TCP over TLS**      |        ❌        |        ✅        |         ❌        |         ✅        |
| **WebSocket** (81)           |        ✅        |        ✅        |         ✅        |         ✅        |
| **WebSocket over TLS** (WSS) |        ❌        |        ✅        |         ❌        |         ✅        |
| **UDP report** (plaintext)   |        ✅        |        ✅        |         ✅        |         ✅        |
| **UDP report** (AES-CCM)     |        ❌        |        ❌        |         ✅        |         ✅        |
| **mDNS discovery**           |        ✅        |        ✅        |         ✅        |         ✅        |

Basic and Basic+ turn HTTP on at every boot. Lite and Pro leave it off until the BLE command `enablehttp` turns it on. On Pro, once HTTPS is on, business endpoints on port 80 return 403. See the [HTTP page](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/http/http-api.en.md).

{% hint style="warning" %}
**UDP AES-CCM:** trust the meter in front of you. This matrix lists both Lite and Pro. On Lite 5.1.16 the datagram is always plaintext. The encrypted datagram appears only on Pro 3.1.19, and only while HTTPS is on. Details are in the [UDP page](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/udp/udp-api.en.md).
{% endhint %}

#### 3.1 TLS connection limit

Device memory only allows a fixed number of TLS services at once: Basic+ **1**, Pro **2**. Services that can take a TLS slot are MQTTS, HTTPS (443), WSS (81), and Modbus TLS (502).

* When more TLS services are enabled than there are slots, they start in this order: **MQTTS > HTTPS > WSS > Modbus TLS**.
* A service that does not get a slot: MQTTS keeps its slot, HTTPS does not listen on 443, and WSS and Modbus fall back to plaintext.
* Before accepting a new TLS connection the meter checks the free slots and does not handshake if none is free.
* Reuse an existing connection. Do not open a new TLS session for every poll.

#### Cloud and backend

* [**MQTT API Reference**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/mqtt-api-reference.md): continuous telemetry and cloud commands. Command names match BLE. The `seq` field is deprecated in Basic 5.1.14 and later. Responses use `ok / msg / event / d`.

#### Local network

* [**mDNS Discovery**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/mdns-discovery.md): find a meter on the LAN without a static IP.
* [**HTTP / HTTPS**](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/http/http-api.en.md): sign-in, on-demand reads, and configuration. On Pro, prefer HTTPS.
* [**WebSocket**](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/websocket/websocket-api.en.md): a live stream for a local hub such as Home Assistant.
* [**UDP report**](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/udp/udp-api.en.md): one-way readings for export limiting and dynamic load balancing.

#### EMS and industrial gateways

* [**Modbus TCP Map**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/modbus-tcp-map.md): register map for PLC, energy gateways, and EMS. Connection limits for each branch are in the [Modbus TCP page](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/modbus-tcp/modbus-tcp-api.en.md) of the integration repository.

#### Phone app and near-field control

* [**BLE Basic API**](broken://pages/UlemP85jPIjB5RKMJlAl): plaintext BLE (`A002`) for Basic / Basic+.
* [**BLE Secured API**](broken://pages/PQLxFcSDJCH7A7xkndpT): secured BLE (`A003`) for Lite / Pro. Handshake, provisioning, and local read/write.
* [**Encrypted business advertising**](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/ble-secured/ble-advertising.en.md): voltage, current, power, and energy from the advertising packet, with no GATT connection. Lite / Pro only.

#### Shared by every channel

* [**Telemetry payload**](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/reference/telemetry-payload.en.md): the same JSON on MQTT `/data`, HTTP `/data`, WebSocket, UDP, and `/snapshot.data`.
* [**Error codes**](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/reference/error-codes.en.md): `code` ranges. BLE 1000s, HTTP 2000s, MQTT 3000s, WebSocket 4000s.
* [**Business Command Reference**](https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/ble-common/ble-business-api.en.md): every `cmd`, shared by BLE, HTTP, MQTT, and WebSocket.

Runnable examples are in the same repository, under `tools/`.

{% hint style="info" %}
**Status**: Active | **Applies to**:SPM/SDM Open Wi-Fi Series (ESP32-8685 / C6) | **Updated**: 2026-10-17
{% endhint %}

Read this page first, then open only the page for the job you have:

1. Section 2: confirm the meter is Basic, Basic+, Lite, or Pro.
2. Section 3: check that the branch actually has the channel you want.
3. Section 4: open that page. Provisioning and read/write over BLE go through GATT. To read electrical values with no connection, use encrypted business advertising (Lite / Pro only).

The pages in the left sidebar cover MQTT, mDNS, Modbus TCP, and BLE. HTTP, WebSocket, UDP, shared telemetry fields, error codes, and the business commands are in the [integration repository](https://github.com/bituo-technik/bt-open-wifi-apis/tree/docs/bilingual-entry-pages).

***

#### 1. Introduction

SPM / SDM Open Wi-Fi meters give system integrators and DIY builders local and cloud communication, so you can write an app or connect a meter to a system you already have.

* **Local network:** HTTP / HTTPS, WebSocket, UDP reports, Modbus TCP, mDNS discovery.
* **Cloud:** MQTT / MQTTS. MQTTS also works with a private broker.
* **Near-field from a phone:** BLE, plaintext or secured, for provisioning and local control.

All channels share one set of business commands (`cmd`) and one response shape, `ok / msg / event / d`. The command list is maintained in one place: [Business Command Reference](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/ble-business-command-reference.md). Each channel page only describes how to connect, how messages are wrapped, and the limits.

***

#### 2. Firmware Branches & Hardware Compatibility

The product line has four firmware branches. **Channels differ between branches**, so check before integrating.

| Firmware Branch      | Basic (8685)                       | Basic+ (8685)                                  | Lite (8685)                                | Pro (C6)                                     |
| -------------------- | ---------------------------------- | ---------------------------------------------- | ------------------------------------------ | -------------------------------------------- |
| **Target Hardware**  | SPM / SDM                          | SDM01                                          | SPM / SDM                                  | SDM01 Gen2                                   |
| **Latest Version**   | B\_5.1.14 & B\_6.1.7 <sup>1)</sup> | BPlus\_1.2.8 & BPlus\_2.2.4                    | Lite\_5.1.11 & Lite\_6.1.4                 | Pro\_V3.1.11                                 |
| **Core Features**    | Plaintext BLE, plaintext Wi-Fi     | Plaintext BLE, Wi-Fi can use TLS <sup>2)</sup> | Secured BLE, plaintext Wi-Fi <sup>3)</sup> | Secured BLE, Wi-Fi can use TLS <sup>4)</sup> |
| **Wi-Fi TX power**   | 0 dB                               | 13 dB                                          | 0 dB                                       | 13 dB                                        |
| **Lifecycle Status** | NRND                               | NRND                                           | Active                                     | Active                                       |

**Note:**

1. `B_6.1.7` is for the SDM01 Combo with the UART external flashing pins. `B_5.1.14` is for SPM01, SPM02, the SDM01 Combo with JTAG flashing pins, and SDM02.
2. Basic+ was the Gen1 EV / PV version and has been replaced by SDM01 Gen2. At most **1** TLS connection at a time.
3. Lite's BLE encryption covers provisioning and data advertising. On Wi-Fi, only MQTT supports TLS 1.2 / 1.3. HTTP, Modbus TCP, and WebSocket have no TLS.
4. Pro's BLE encryption covers provisioning and data advertising. On Wi-Fi, at most **2** TLS connections at a time.

The interface documents in the integration repository were checked against Basic / Lite 5.1.16, Basic+ 1.2.12, and Pro 3.1.19. The table above is the published product line.

**2.1 How to tell the branch**

| You want to know         | How to read it                                                                                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plaintext or secured BLE | Advertised service UUID: `A002` plaintext (Basic / Basic+), `A003` secured (Lite / Pro). A meter exposes only one of them.                                                                                                            |
| Firmware version         | MQTT `mdata.fwVer`, `FWVersion` in telemetry, HTTP `/snapshot`, or Modbus register 997                                                                                                                                                |
| Which channels are on    | `{"cmd":"getFunctionMap"}`. Bit definitions are in [Business Command Reference, Appendix B](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/ble-business-command-reference.md#appendix-c-model-short-keys). |

***

#### 3. API Capability Matrix

<table><thead><tr><th width="255.4444580078125">Channel</th><th>Basic</th><th>Basic+</th><th>Lite</th><th>Pro</th></tr></thead><tbody><tr><td><strong>BLE plaintext</strong> (<code>A002</code>)</td><td>✅</td><td>✅</td><td>❌</td><td>❌</td></tr><tr><td><strong>BLE secured</strong> (<code>A003</code>)</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td></tr><tr><td><strong>MQTT</strong> (1883)</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><strong>MQTTS</strong> (TLS)</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><strong>HTTP</strong> (80, plaintext)</td><td>✅ on by default</td><td>✅ on by default</td><td>✅ off by default</td><td>✅ off by default</td></tr><tr><td><strong>HTTPS</strong> (443)</td><td>❌</td><td>❌</td><td>❌</td><td>✅</td></tr><tr><td><strong>Modbus TCP</strong> (502)</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><strong>Modbus TCP over TLS</strong></td><td>❌</td><td>✅</td><td>❌</td><td>✅</td></tr><tr><td><strong>WebSocket</strong> (81)</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><strong>WebSocket over TLS</strong> (WSS)</td><td>❌</td><td>✅</td><td>❌</td><td>✅</td></tr><tr><td><strong>UDP report</strong> (plaintext)</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><strong>UDP report</strong> (AES-CCM)</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td></tr><tr><td><strong>mDNS discovery</strong></td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr></tbody></table>

Basic and Basic+ turn HTTP on at every boot. Lite and Pro leave it off until the BLE command `enablehttp` turns it on. On Pro, once HTTPS is on, business endpoints on port 80 return 403. See the [HTTP page](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/http-https-api.md).

{% hint style="warning" %}
**UDP AES-CCM**: trust the meter in front of you. This matrix lists both Lite and Pro. On Lite 5.1.16 the datagram is always plaintext. The encrypted datagram appears only on Pro 3.1.19, and only while HTTPS is on. Details are in the \[UDP page]\(<https://github.com/bituo-technik/bt-open-wifi-apis/blob/docs/bilingual-entry-pages/docs/udp/udp-api.en.md>).
{% endhint %}

**3.1 TLS connection limit**

Device memory only allows a fixed number of TLS services at once: Basic+ **1**, Pro **2**. Services that can take a TLS slot are MQTTS, HTTPS (443), WSS (81), and Modbus TLS (502).

* When more TLS services are enabled than there are slots, they start in this order: **MQTTS > HTTPS > WSS > Modbus TLS**.
* A service that does not get a slot: MQTTS keeps its slot, HTTPS does not listen on 443, and WSS and Modbus fall back to plaintext.
* Before accepting a new TLS connection the meter checks the free slots and does not handshake if none is free.
* Reuse an existing connection. Do not open a new TLS session for every poll.

***

#### 4. API Reference Directory

**Cloud and backend**

* [**MQTT API Reference**:](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/mqtt-api-reference.md) continuous telemetry and cloud commands. Command names match BLE. The `seq` field is deprecated in Basic 5.1.14 and later. Responses use `ok / msg / event / d`.

**Local network**

* [**mDNS Discovery**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/mdns-discovery.md): find a meter on the LAN without a static IP.
* [**HTTP / HTTPS**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/http-https-api.md): sign-in, on-demand reads, and configuration. On Pro, prefer HTTPS.
* [**WebSocket**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/websocket-api.md): a live stream for a local hub such as Home Assistant.
* [**UDP report**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/udp-report.md): one-way readings for export limiting and dynamic load balancing.

**EMS and industrial gateways**

* **Modbus TCP Map**: register map for PLC, energy gateways, and EMS. Connection limits for each branch are in the [Modbus TCP page](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/modbus-tcp-map.md) of the integration repository.

**Phone app and near-field control**

* [**BLE Basic API**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/ble-plaintext-api.md): plaintext BLE (`A002`) for Basic / Basic+.
* [**BLE Secured API**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/ble-secured-api.md): secured BLE (`A003`) for Lite / Pro. Handshake, provisioning, and local read/write.
* [**Encrypted business advertising**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/ble-advertising.md): voltage, current, power, and energy from the advertising packet, with no GATT connection. Lite / Pro only.

**Shared by every channel**

* [**Telemetry payload**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/telemetry-payload.md): the same JSON on MQTT `/data`, HTTP `/data`, WebSocket, UDP, and `/snapshot.data`.
* [**Error codes**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/error-code-reference.md): `code` ranges. BLE 1000s, HTTP 2000s, MQTT 3000s, WebSocket 4000s.
* [**Business Command Reference**](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/ble-business-command-reference.md): every `cmd`, shared by BLE, HTTP, MQTT, and WebSocket.

Runnable examples are in the same repository, under `tools/`.
