> 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/ble-business-command-reference.md).

# BLE Business Command Reference

BLE Business Command Reference (shared by plaintext and secured channels)

{% hint style="info" %}
**Status:** Active| **Applies to:** plaintext BLE (service `A002`, Basic / Basic+) and secured BLE (service `A003`, Lite / Pro)  | **Updated:** 2026-10-16&#x20;
{% endhint %}

**This page is the single source of truth for the business JSON**: provisioning and device commands, snapshot fields, and business error codes. After the transport layer is removed, the business JSON of both BLE channels is **identical**, so it is maintained only here. The transport layer (UUIDs, unlock / handshake, encrypted envelope, reconnect) lives in each channel document.

| Your device                     | Read first (transport) | Then (business layer) |
| ------------------------------- | ---------------------- | --------------------- |
| Basic / Basic+ (service `A002`) | Plaintext BLE API      | this page             |
| Lite / Pro (service `A003`)     | Secured BLE API        | this page             |

For system integrators, DIY developers and AI coding assistants. Command names, field names and device `msg` strings are kept in English exactly as the device returns them.

***

### 1. Conventions

#### 1.1 Requests and responses

A request is one JSON object. `cmd` is required on every request; other fields depend on the command. Response:

<table><thead><tr><th width="140.8887939453125">Field</th><th width="204.6666259765625">Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>ok</code></td><td>boolean</td><td>success or not</td></tr><tr><td><code>msg</code></td><td>string</td><td>English text, compare verbatim</td></tr><tr><td><code>event</code></td><td>string</td><td>normally equals the request <code>cmd</code></td></tr><tr><td><code>code</code></td><td>integer</td><td><strong>failures only</strong>, see Section 6</td></tr><tr><td><code>d</code></td><td>object</td><td>only on query commands</td></tr></tbody></table>

Match rule: a reply is yours and successful when `resp.event == cmd` and `resp.ok == true`. Each channel has one kind of "reply that is not for your command" you must recognise: `event == "pas"` on plaintext (not unlocked) and `event == "secure"` on secured (envelope-layer failure). See each channel document for handling.

**Commands are strictly serial**: write one, wait for its reply, then write the next. Suggested timeouts: 8–15 s for most commands; 20 s for `wifi`; 25 s for `checkota` / `startota`.

#### 1.2 Differences between the two channels (this is all of them)

<table data-header-hidden><thead><tr><th width="149.7777099609375"></th><th></th><th></th></tr></thead><tbody><tr><td>Item</td><td><strong>Plaintext BLE (<code>A002</code>)</strong></td><td><strong>Secured BLE (<code>A003</code>)</strong></td></tr><tr><td>Gate</td><td><code>cmd=pass</code> + BLE password</td><td><code>ble-crypto-*</code> handshake (PIN + SN)</td></tr><tr><td>Write</td><td>JSON written directly to <code>C303</code></td><td>same JSON encrypted into <code>{nonce,ct,tag}</code> and written to <code>C313</code></td></tr><tr><td>Reply</td><td><code>C305</code> notification, plaintext</td><td><code>C315</code> notification, envelope; <strong>after decryption</strong> identical to plaintext</td></tr><tr><td>Snapshot read</td><td><code>C304</code> GATT Read, plaintext</td><td><code>C314</code> GATT Read, may be an envelope; decrypt, then parse</td></tr><tr><td>Trigger snapshot</td><td><code>{"cmd":"read","continue":true}</code></td><td><code>{"cmd":"read"}</code></td></tr><tr><td>Channel-only commands</td><td><code>pass</code>, <code>blepassword</code>, <code>resetauth</code></td><td><code>ble-crypto-ver</code>, <code>ble-crypto-reset</code>, <code>ble-crypto-jpake-round1</code>, <code>ble-crypto-jpake-round2</code>, <code>ble-crypto-session-nonce</code></td></tr><tr><td>After reboot / disconnect</td><td><code>pass</code> again</td><td><code>step=2</code>: resume with LTK; otherwise J-PAKE again</td></tr></tbody></table>

Apart from this table, every command, field, value and error code on this page is the same for both channels.

#### 1.3 Model differences

Models do not support exactly the same commands; an unsupported command fails — some reply `unsupported`, some `unknow cmd` (1015). For example, a model without WebSocket has no `setInterval`; a model without LAN TLS has no `enablehttps`. **Clients must act on `ok` / `msg` and must not assume every device has every command.** Product identity comes from the advertised name and `TP` / `SN` in the snapshot.

***

### 2. Wi-Fi provisioning (business commands)

A meter usually has no router credentials out of the box. First complete **unlock (plaintext) or the secure handshake (secured)** for your channel, then send the **2.4 GHz** SSID and router password. Once joined, HTTP / MQTT / Modbus TCP etc. become available.

The commands below are identical on both channels (on the secured channel, wrap the JSON in the encrypted envelope first).

#### 2.1 (Optional) scan for nearby Wi-Fi

```json
{"cmd":"wifiscan"}
```

Success: `msg=scan started`. If a scan is already running: `scan busy` / 1043, try again in a few seconds. Wait **3–8 seconds**, then:

```json
{"cmd":"getwifilist"}
```

```json
{"ok":true,"msg":"","event":"getwifilist","d":{"list":"OfficeWiFi|-45,Home|-72"}}
```

`d.list`: comma-separated, each item is `ssid|rssi` (integer dBm, closer to 0 is stronger), at most 10 items, sorted by strength, duplicate names keep only the strongest. If not ready: `scan not ready` / 1044, wait 2–3 s and retry.

#### 2.2 Send SSID and password

```json
{"cmd":"wifi","ssid":"OfficeWiFi","pass":"router-password"}
```

<table><thead><tr><th width="182.3333740234375">Field</th><th>Limit</th></tr></thead><tbody><tr><td><code>ssid</code></td><td>Required, ≤ 64</td></tr><tr><td><code>pass</code></td><td>≤ 64; an empty string for open networks</td></tr><tr><td><code>enableble</code></td><td>Optional boolean. Meaningful only on firmware with secured BLE (Lite / Pro): when on, the device <strong>keeps</strong> the application GATT service and the service UUID in advertising after Wi-Fi is connected; when off, the device withdraws the application GATT once Wi-Fi is up. Persisted across power cycles, cleared by factory reset; omit to keep the stored value</td></tr><tr><td><code>enablehttps</code></td><td>Optional boolean. <strong>Pro only</strong>: persistently enables LAN HTTPS (443) after provisioning, effective after a restart; omit to keep the stored value; ignored on non-Pro. On Pro, when this is on, periodic UDP reports use an AES-CCM wrapped JSON (<code>ct</code> / <code>tag</code> / <code>counter</code>); otherwise UDP stays plaintext JSON</td></tr></tbody></table>

Success: `{"ok":true,"msg":"WIFI successfully","event":"wifi"}`. This means the meter **accepted the credentials and started connecting to the router**; it does not mean an IP has been obtained yet. Missing fields: 1018; too long: 1019.

#### 2.3 Confirm it is online

```json
{"cmd":"read"}
```

On the plaintext channel send `{"cmd":"read","continue":true}`. After `ok=true`, GATT Read the snapshot characteristic (`C304` on plaintext; `C314` on secured, decrypt first) and look at `IP`:

<table data-header-hidden><thead><tr><th width="285.6666259765625"></th><th></th></tr></thead><tbody><tr><td><code>IP</code></td><td>Meaning</td></tr><tr><td>An IPv4 address such as <code>192.168.x.x</code></td><td><strong>Online, provisioning succeeded</strong></td></tr><tr><td><code>-1</code></td><td>Just sent, state unknown</td></tr><tr><td><code>0</code></td><td>Idle</td></tr><tr><td><code>1</code></td><td>SSID not found (wrong name, not 2.4 GHz, too far away)</td></tr><tr><td><code>3</code></td><td>Associated (normally becomes an IPv4 address very soon)</td></tr><tr><td><code>4</code> / <code>5</code> / <code>6</code></td><td>Failed / lost / disconnected (a wrong password is the most common cause)</td></tr></tbody></table>

After provisioning, read every 2 s for about 30 s at most.

```mermaid
sequenceDiagram
  participant App
  participant Meter as Meter BLE
  Note over App,Meter: channel ready (plaintext: pass done / secured: step=3)
  App->>Meter: cmd=wifiscan
  Meter-->>App: scan started
  Note over App: wait 3-8 s
  App->>Meter: cmd=getwifilist
  Meter-->>App: d.list = ssid|rssi,...
  App->>Meter: cmd=wifi ssid+pass
  Meter-->>App: WIFI successfully
  loop every 2 s, up to ~30 s
    App->>Meter: cmd=read, then GATT Read snapshot characteristic
    Meter-->>App: IP / RSSI / electrical
  end
```

#### 2.4 Suggested UI copy

Title "Connect meter to Wi-Fi"; SSID field "2.4 GHz network name"; password field "Router password (not the BLE password / PIN)"; primary button "Send to meter"; secondary button "Scan nearby Wi-Fi" (only after unlock / secure handshake).

***

### 3. Command reference

Send once the channel is ready (plaintext: `pass` done; secured: `step=3`). `event` equals `cmd` by default.

#### 3.1 Device control

<table data-header-hidden><thead><tr><th width="135.6666259765625"></th><th></th><th></th><th></th></tr></thead><tbody><tr><td>cmd</td><td>Request</td><td>Success <code>msg</code></td><td>Note</td></tr><tr><td><code>restart</code></td><td><code>{"cmd":"restart"}</code></td><td><code>restart received</code></td><td>GATT then drops; reconnect per plaintext 4.5 / secured 4.10</td></tr><tr><td><code>location</code></td><td><code>{"cmd":"location"}</code></td><td><code>location received</code></td><td>The LED blinks at about 4 Hz for 15 s so you can find the meter on site</td></tr><tr><td><code>zero</code></td><td><code>{"cmd":"zero"}</code></td><td><code>zero received</code></td><td><strong>Clears accumulated energy, cannot be undone</strong></td></tr><tr><td><code>reset</code></td><td><code>{"cmd":"reset"}</code></td><td><code>reset received</code></td><td>Clears the configuration and restarts</td></tr><tr><td><code>deviceName</code></td><td><code>{"cmd":"deviceName","name":"RoomMeter01"}</code></td><td><code>deviceName yes</code></td><td><code>name</code> ≤ 30; longer returns 1027</td></tr><tr><td><code>commonmode</code></td><td><code>{"cmd":"commonmode","value":0}</code></td><td><code>commonmode yes</code></td><td>Sets the message reporting format: <code>0</code> = BT format, <code>1</code> = generic format</td></tr></tbody></table>

#### 3.2 Queries

**`model`**, configuration snapshot:

```json
{"cmd":"model","type":1}
```

```json
{"ok":true,"msg":"","event":"model","d":{"WN":"OfficeWiFi","WPN":"EnergySensor-SDM01_3PN_01-10304B0D7760","MH":"","MF":false,"MP":0,"MC":"","MI":5000,"MS":false,"LSM":0,"UI":5000,"MAD":"5 / 9600 / N81"}}
```

See Appendix C for the short keys. The set of keys differs slightly between models: handle them by "does the key exist".

**`getFunctionMap`**, enabled communication features:

```json
{"cmd":"getFunctionMap"}
```

```json
{"ok":true,"msg":"","event":"getFunctionMap","d":{"functionMap":32896}}
```

`32896` = `32768 + 128`, meaning Modbus TCP (bit 15) and HTTP (bit 7) are enabled. See Appendix B for the bits.

**`mqttdata`**:

```json
{"ok":true,"msg":"","event":"mqttdata","d":{"TP":"SDM01_3PN/10304B0D7760/data","TC":"SDM01_3PN/10304B0D7760/cmd","TR":"SDM01_3PN/10304B0D7760/cdata","TM":"SDM01_3PN/10304B0D7760/mdata","MU":"","MPS":""}}
```

`TP/TC/TR/TM` are the four topics (the defaults contain the model and serial number); `MU` / `MPS` are the MQTT credentials. The response above is from a real device with MQTT not enabled, and **it has no `MF` key**; only devices with MQTT enabled add `MF`, for example `"MF":0`. Handle it by "does the key exist".

`MF` (when MQTT is enabled): `-4` timeout, `-3` connection lost, `-2` TCP/TLS failure, `-1` disconnected, `0` connected, `1` protocol rejected, `2` ClientId rejected, `3` broker unavailable, `4` bad credentials, `5` not authorized. Some firmware returns `-1` when MQTT is not enabled, others omit `MF` entirely, so also check whether MQTT has been configured. **Note: `MF` in `model` is a boolean; do not mix it up with the numeric status code here.**

**`udpdata`**:

```json
{"ok":true,"msg":"","event":"udpdata","d":{"udp_data":[]}}
{"ok":true,"msg":"","event":"udpdata","d":{"udp_data":[{"ip":"192.168.1.20","port":"8888"}]}}
```

#### 3.3 LAN protocol switches

| cmd               | Purpose                                                             | Success `msg`             |
| ----------------- | ------------------------------------------------------------------- | ------------------------- |
| `enablehttp`      | Plain HTTP on `:80`. `enable` omitted or `true` = on, `false` = off | `http yes` / `http off`   |
| `enablewebsocket` | WebSocket; optional `enableTLS`                                     | `websocket yes`           |
| `enablemodbustcp` | Modbus TCP                                                          | `modbus tcp yes`          |
| `enabletls`       | TLS feature bit                                                     | `tls yes`                 |
| `enablehttps`     | LAN HTTPS (some models only)                                        | `https yes` / `https off` |

```json
{"cmd":"enablehttp","enable":true}
```

These commands **only save the configuration**. They do not drop BLE and do not restart the device by themselves. The device has limited memory, and toggling communication channels repeatedly fragments it, so:

* **After changing the switches, send a single `{"cmd":"restart"}`** and reconnect per plaintext 4.5 / secured 4.10;
* After `enablehttp` is turned on, `:80` only starts listening after a restart; turning it off stops it immediately;
* Do not toggle channels frequently at run time, and do not enable several memory-hungry channels at once (see `functionMap error` below).

Writing `{"cmd":"functionMap","value":<integer>}` directly **overwrites the whole bitmap**, and the number of LAN channels that can be on at the same time is limited; exceeding it returns `functionMap error` (1014). Normal apps should use the `enable*` commands above and not write `functionMap` directly.

#### 3.4 MQTT

```json
{"cmd":"mqtt","data":"broker.example.com|dev01|1|8883|5|user|pwd"}
```

`data` = `host|clientid|ssl|port|interval|username|password`. `ssl`: `1` TLS, `0` plaintext. `interval` is in **seconds**; after saving it appears in `model` as `MI` in **milliseconds**. Success: `MQTT successfully`.

* `mqtt`: saves only, **no restart**.
* `mqtr`: same parameters, saves and then **restarts**.
* Empty `data`: `Error mqtt data empty!` / 1021.

```json
{"cmd":"topic1","topic_post":"dev/up","topic_set":"dev/down"}
{"cmd":"topic2","topic_response":"dev/resp","topic_metadata":"dev/meta"}
```

To use your own CA certificate for MQTT: send `cafilestart` first, then `cafiledata` in several chunks. You can skip this if you only do Wi-Fi provisioning.

#### 3.5 Modbus 485, UDP, OTA

```json
{"cmd":"modbus","baud":9600,"parityStop":0,"address":1}
```

Success: `modbus yes`. `parityStop`: `0` = N81, `1` = E81, `2` = O81, `3` = N82 (no parity, 2 stop bits). The current 485 settings can be read from `model.d.MAD`, for example `"5 / 9600 / N81"` (address / baud rate / parity).

**UDP targets** (at most 5):

```json
{"cmd":"udp","IpAddress":"192.168.1.100","localUdpPort":9000,"Frequency":5}
```

* `IpAddress`: target IP; `localUdpPort`: target port (that is the field name, but it means the **remote** port).
* `Frequency`: optional, report period in **seconds**; the device converts it to milliseconds (`UI` in `model`) with a lower limit of 100 ms; if omitted the current period is kept. The period is global and shared by all UDP targets.
* Success: `UDP successfully`. Sending the same IP + port again only updates the period. **Adding a target automatically turns on the UDP feature bit** (functionMap bit 13).
* If the IP is empty or the port is invalid, the device also returns `UDP full` / 1024, so do not read it literally as "full".
* Delete: `{"cmd":"deleteudp","IpAddress":"192.168.1.100","localUdpPort":9000}`, success `UDP deleted`; if it does not exist `UDP not found` / 1025. Deleting a target does **not** turn off the UDP feature bit.
* List: `udpdata`, see 3.2. Targets are in `d.udp_data` as `{"ip":"…","port":"…"}`; with no targets it is an empty array.

**OTA upgrade**:

<table><thead><tr><th width="165.3333740234375">cmd</th><th>Request</th><th>Description</th></tr></thead><tbody><tr><td><code>checkota</code></td><td><code>{"cmd":"checkota"}</code></td><td>Asks the server whether new firmware exists, without downloading. The device has to contact the server, so <strong>it took about 8 seconds to answer in testing</strong>; allow 25 s</td></tr><tr><td><code>otaprogress</code></td><td><code>{"cmd":"otaprogress"}</code></td><td>Query progress, read-only</td></tr><tr><td><code>startota</code></td><td><code>{"cmd":"startota"}</code> or with <code>url</code> / <code>reboot</code></td><td>Starts the upgrade and returns immediately; poll progress with <code>otaprogress</code></td></tr></tbody></table>

`checkota` response (`otastatus`: `200` update available, `404` already up to date or version info invalid, `199` not enough device memory, anything else is a network / server error code):

```json
{"ok":true,"msg":"","event":"checkota","d":{"otastatus":404}}
```

`otaprogress` response (real device, no upgrade running):

```json
{"ok":true,"msg":"","event":"otaprogress","d":{"otaprogress":0,"otastatus":-1,"otastatusText":"idle","reboot":1,"version":"5.1.15"}}
```

<table data-header-hidden><thead><tr><th width="147.5556640625"></th><th></th><th></th></tr></thead><tbody><tr><td><code>otastatus</code></td><td><code>otastatusText</code></td><td>Meaning</td></tr><tr><td>-1</td><td>idle</td><td>No upgrade task (default after power-up)</td></tr><tr><td>0</td><td>success</td><td>Upgrade finished; it only counts as success when <code>otaprogress</code> is 100</td></tr><tr><td>1</td><td>write length insufficient</td><td>Firmware data incomplete</td></tr><tr><td>2</td><td>verify failed</td><td>Firmware verification failed</td></tr><tr><td>3</td><td>set boot partition failed</td><td>Switching boot partition failed</td></tr><tr><td>4</td><td>ota begin failed</td><td>Upgrade initialization failed</td></tr><tr><td>5</td><td>no ota partition available</td><td>No usable upgrade partition</td></tr><tr><td>6</td><td>ota running</td><td>Upgrade in progress</td></tr><tr><td>other</td><td>—</td><td>Network / HTTP error code during download</td></tr></tbody></table>

`startota`: `url` is optional and defaults to the address determined by `checkota`; `reboot` is optional (`true` / `false` / `1` / `0`, default `1`); with `0` the device does not restart after the upgrade and the client has to send `restart` itself. Success response: `{"ok":true,"msg":"startota yes","event":"startota"}`. The upgrade runs in the background on the device; do not cut the power while it runs.

**WebSocket push interval**:

<table><thead><tr><th width="275.6666259765625">cmd</th><th>Description</th></tr></thead><tbody><tr><td><code>setInterval</code> / <code>getInterval</code></td><td>Control <strong>only</strong> the WebSocket push interval (milliseconds, 100–86400000, usually 5000 by default); they do <strong>not</strong> change MQTT <code>MI</code> or UDP <code>UI</code>. Unsupported models fail: some answer <code>unsupported</code>, others (such as SDM01_3PN) answer <code>unknow cmd</code> / 1015. Treat both as a failure</td></tr></tbody></table>

***

### 4. Command index (for AI to scan)

Business commands (both channels):

`read`, `wifi`, `wifiscan`, `getwifilist`, `restart`, `location`, `zero`, `reset`, `deviceName`, `commonmode`, `model`, `getFunctionMap`, `functionMap`, `enablehttp`, `enablehttps`, `enablewebsocket`, `enablemodbustcp`, `enabletls`, `setInterval`, `getInterval`, `mqtt`, `mqtr`, `topic1`, `topic2`, `mqttdata`, `cafilestart`, `cafiledata`, `modbus`, `getModbusTlsMuxSetupStatus`, `udp`, `deleteudp`, `udpdata`, `checkota`, `otaprogress`, `startota`

Channel-only commands: plaintext `pass`, `blepassword`, `resetauth` (see the plaintext doc); secured `ble-crypto-ver`, `ble-crypto-reset`, `ble-crypto-jpake-round1`, `ble-crypto-jpake-round2`, `ble-crypto-session-nonce` (see the secured doc).

Do not use command or field names that are not listed here.

***

### 5. Snapshot read: IP and electrical readings

The electrical / IP snapshot is obtained with a **GATT Read** (`C304` on plaintext, `C314` on secured); do not mix it with notifications. Send the `read` command first (see 1.2), then Read after the `ready` reply.

On the secured channel the bytes read back may be an envelope `{nonce,ct,tag}`; the JSON below appears **after decryption**. On the plaintext channel, reading before unlock returns `Please unlock` (1002).

Most numeric readings are **decimal strings**, not JSON numbers; convert them yourself.

#### 5.1 Common fields

<table><thead><tr><th width="179.7777099609375">Key</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>IP</code></td><td>string</td><td>Online = IPv4; not online = a status code, see 2.3</td></tr><tr><td><code>RSSI</code></td><td>int</td><td>Downlink signal strength from router to meter (dBm)</td></tr><tr><td><code>FW</code></td><td>string</td><td>Firmware version</td></tr><tr><td><code>SN</code></td><td>string</td><td>Serial number</td></tr><tr><td><code>TP</code></td><td>int</td><td>Product type code</td></tr></tbody></table>

#### 5.2 Electrical keys: parse by "does the key exist"

**Do not hard-code single-phase / three-phase from `TP`.** If `VX` / `VY` / `VZ` exist, parse as multi-phase; if `V` exists, parse as single-phase. A missing key means the model does not have that item.

<table><thead><tr><th width="145.666748046875">Form</th><th>Keys</th></tr></thead><tbody><tr><td>Single-phase</td><td><code>V</code> <code>I</code> <code>P</code> <code>PF</code> <code>F</code> <code>FE</code> <code>RE</code></td></tr><tr><td>Three-phase</td><td><code>VX VY VZ</code>, <code>IX IY IZ</code>, <code>PX PY PZ</code>, <code>PFX PFY PFZ</code>, <code>F</code>, <code>FEX FEY FEZ</code>, <code>REX REY REZ</code></td></tr><tr><td>Two-channel</td><td>Same as three-phase but only with suffixes <code>X</code> / <code>Y</code> (no <code>Z</code>)</td></tr></tbody></table>

`TP` reference: `1` / `2` single-phase, `3` / `4` three-phase, `5` two-channel, `8` / `9` new platform (still use the single-phase or three-phase key names above).

Meaning: `V` voltage, `I` current, `P` power, `PF` power factor, `F` frequency, `FE` forward energy, `RE` reverse energy. A trailing `X/Y/Z` denotes the phase or channel.

Units: voltage **V**, current **A**, power **kW** (not W), energy **kWh**, frequency **Hz**. The strings contain digits only, no unit. Approximate decimals: voltage 1, current / power 3, power factor / frequency / energy 2.

Single-phase read-back shape (values are illustrative):

```json
{"IP":"192.168.3.60","RSSI":-58,"FW":"5.1.15","SN":"10304B0D0001","TP":2,"V":"230.1","I":"1.234","P":"0.280","PF":"0.98","F":"50.00","FE":"12.34","RE":"0.01"}
```

Three-phase read-back (real SDM01\_3PN, `TP` is 4):

```json
{"IP":"192.168.3.75","RSSI":-56,"FW":"5.1.15","SN":"10304B0D7760","TP":4,"VX":"225.8","VY":"225.9","VZ":"226.0","IX":"7.207","IY":"7.191","IZ":"7.212","PX":"1.627","PY":"1.625","PZ":"1.630","PFX":"1.00","PFY":"1.00","PFZ":"0.99","F":"50.00","FEX":"0.21","REX":"0.00","FEY":"0.22","REY":"0.00","FEZ":"0.17","REZ":"0.00"}
```

The values are consistent with each other: about 226 V, about 7.2 A per phase and about 1.63 kW per phase (226 × 7.2 ≈ 1.63 kW), which you can use as a unit sanity check.

***

### 6. Business error codes

On failure the notification or the read characteristic is JSON: `ok=false`, an integer `code` and an English `msg`. **Success packets have no `code`.**

For configuration failures the BLE `code` = **1000 + sub-code**, so some numbers overlap with fixed codes (especially 1002–1005). **Rely on `msg`; use `code` only as a hint.**

<table data-header-hidden><thead><tr><th width="117.5555419921875"></th><th width="283.3333740234375"></th><th></th></tr></thead><tbody><tr><td>code</td><td><code>msg</code></td><td>Meaning / action</td></tr><tr><td>1014</td><td>functionMap error</td><td>Illegal or over-limit combination of communication features</td></tr><tr><td>1015</td><td>unknow cmd</td><td>Unknown command, or this model does not have it (the <code>msg</code> is spelled this way, compare it verbatim)</td></tr><tr><td>1018</td><td>Error wifi ssid/pass required!</td><td>SSID or password missing</td></tr><tr><td>1019</td><td>Error wifi length!</td><td>Wi-Fi parameter too long</td></tr><tr><td>1021</td><td>Error mqtt data empty!</td><td>MQTT <code>data</code> is empty</td></tr><tr><td>1024</td><td>UDP full</td><td>UDP target list full, or the IP / port is invalid</td></tr><tr><td>1025</td><td>UDP not found</td><td>The UDP target to delete does not exist</td></tr><tr><td>1027</td><td>Error name length!</td><td>Display name too long</td></tr><tr><td>1043</td><td>scan busy</td><td>A scan is in progress, try later</td></tr><tr><td>1044</td><td>scan not ready</td><td>Result not ready, wait 2–3 s and fetch again</td></tr></tbody></table>

Channel gate / handshake / envelope errors are in plaintext doc Section 8 and secured doc Section 8. Less common codes: Appendix A.

#### 6.1 Cases without a `code`

| Symptom                                | Action                                                |
| -------------------------------------- | ----------------------------------------------------- |
| `msg` is `illegal cmd` / `unsupported` | this model does not have the command                  |
| a notification is not valid JSON       | log and ignore, do not crash; suspect a too-small MTU |

***

### Appendix A Less common error codes

The BLE `code` = 1000 + sub-code. Most integrators will not need these.

<table data-header-hidden><thead><tr><th width="143.111083984375"></th><th></th><th></th></tr></thead><tbody><tr><td>code</td><td><code>msg</code></td><td>Meaning</td></tr><tr><td>1006</td><td>null</td><td>Not the matching model, no such data</td></tr><tr><td>1016</td><td>Timer not found</td><td>Timer does not exist</td></tr><tr><td>1017</td><td>Invalid timer</td><td>Invalid timer parameters</td></tr><tr><td>1020</td><td>Error wifi reset in progress</td><td>Wi-Fi reset conflict</td></tr><tr><td>1022</td><td>Error length!</td><td>MQTT or other field too long</td></tr><tr><td>1023</td><td>cafile error</td><td>Certificate flow error</td></tr><tr><td>1028</td><td>mda format error</td><td>Register extension format error</td></tr><tr><td>1029</td><td>mda failed</td><td>Register extension failed</td></tr><tr><td>1030</td><td>minvert data format error</td><td>Invert configuration format error</td></tr><tr><td>1031</td><td>minvert save failed</td><td>Saving invert configuration failed</td></tr><tr><td>1032</td><td>minvert data length error</td><td>Invert configuration length error</td></tr><tr><td>1033</td><td>minvert data error</td><td>Invert configuration data error</td></tr><tr><td>1034</td><td>minvert missing data</td><td>Invert configuration data missing</td></tr><tr><td>1035</td><td>bleota no data</td><td>BLE OTA: no data</td></tr><tr><td>1036</td><td>bleota err param</td><td>BLE OTA: invalid parameter</td></tr><tr><td>1037</td><td>bleota err state</td><td>BLE OTA: wrong state</td></tr><tr><td>1038</td><td>bleota err seq</td><td>Packet sequence not continuous</td></tr><tr><td>1039</td><td>bleota err crc</td><td>CRC failure</td></tr><tr><td>1040</td><td>bleota err write</td><td>Partition write failed</td></tr><tr><td>1041</td><td>bleota err size</td><td>Firmware too large</td></tr><tr><td>1042</td><td>bleota err unknown</td><td>BLE OTA: unknown error</td></tr></tbody></table>

### Appendix B functionMap bits

`d.functionMap` is a 16-bit integer. Bit `n` is on when `functionMap & (1<<n)` is non-zero.

<table><thead><tr><th width="230.111083984375">Bit</th><th>Feature</th></tr></thead><tbody><tr><td>15</td><td>Modbus TCP</td></tr><tr><td>14</td><td>TLS (usually together with Modbus)</td></tr><tr><td>13</td><td>UDP</td></tr><tr><td>11</td><td>WebSocket</td></tr><tr><td>10</td><td>WebSocket TLS</td></tr><tr><td>9</td><td>MQTT</td></tr><tr><td>7</td><td>HTTP <code>:80</code></td></tr><tr><td>5</td><td>LoRaWAN</td></tr><tr><td>others</td><td>Reserved, ignore them</td></tr></tbody></table>

Examples: `128` = HTTP only; HTTP + MQTT = `128 + 512 = 640`; `32896` = Modbus TCP + HTTP.

### Appendix C model short keys

<table><thead><tr><th width="225.6666259765625">Key</th><th>Meaning</th></tr></thead><tbody><tr><td><code>WN</code></td><td>Wi-Fi SSID</td></tr><tr><td><code>WPN</code></td><td>Device display name</td></tr><tr><td><code>MH</code></td><td>MQTT host (empty = not configured)</td></tr><tr><td><code>MF</code></td><td>Whether MQTT is connected (<strong>boolean</strong>)</td></tr><tr><td><code>MP</code></td><td>MQTT port (0 = not configured)</td></tr><tr><td><code>MC</code></td><td>MQTT ClientId</td></tr><tr><td><code>MI</code></td><td>MQTT report interval, in <strong>milliseconds</strong></td></tr><tr><td><code>MS</code></td><td>Whether MQTT uses TLS</td></tr><tr><td><code>LSM</code></td><td>Weak-signal mode, 0 / 1</td></tr><tr><td><code>UI</code></td><td>UDP report interval, in milliseconds</td></tr><tr><td><code>WI</code></td><td>WebSocket push interval, in milliseconds (models without WebSocket do not have this key)</td></tr><tr><td><code>TS</code></td><td>Modbus TLS multiplexing state 0–5 (some models only)</td></tr><tr><td><code>MAD</code></td><td>485: <code>address / baud rate / parity</code>, e.g. <code>5 / 9600 / N81</code></td></tr></tbody></table>
