> 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/http-https-api.md).

# HTTP / HTTPS API

## HTTP / HTTPS API

{% hint style="info" %}
**Status:** Active | **Applies to:** all SPM / SDM Open Wi-Fi branches (HTTPS on Pro only) | **Updated:** 2026-10-16&#x20;
{% endhint %}

A gateway, script or Home Assistant on the LAN can read meter data and change settings over plain HTTP. The commands are the same set as on BLE, MQTT and WebSocket. This page covers what is specific to HTTP: sessions, the endpoint list, and how port 80 differs from port 443.

### 1. Introduction

<table><thead><tr><th width="200.1109619140625">Item</th><th>Description</th></tr></thead><tbody><tr><td>Address</td><td><code>http://&#x3C;device IP>/</code>; on Pro with HTTPS on, also <code>https://&#x3C;device IP>/</code> (port 443)</td></tr><tr><td>Switch</td><td>BLE commands <code>enablehttp</code> / <code>enablehttps</code>, see the Business Command Reference. Basic and Basic+ turn HTTP on at every boot; Lite and Pro leave it off</td></tr><tr><td>Finding the device</td><td>Resolve the hostname with mDNS, or read the IP from your router</td></tr><tr><td>Methods</td><td>Most endpoints are <code>GET</code> with parameters in the query string; endpoints that write settings are <code>POST</code> with a JSON body</td></tr><tr><td>Responses</td><td>Apart from a few endpoints that return plain text or raw JSON, responses use the unified <code>ok/msg/event/d</code> (failures add <code>code</code>). Conventions: Business Command Reference 1.1</td></tr><tr><td>Status code</td><td><strong>A failure usually still has HTTP status 200</strong>; read <code>ok</code> in the body. Exceptions: 403 when port 80 is refused by policy, 404 when the log file is missing or HTTPS has no such path</td></tr><tr><td>Concurrency</td><td>The port 80 web server handles one request at a time; do not poll in parallel. HTTPS connections are limited by the TLS slots, see Overview 3.1</td></tr><tr><td>Inbound size</td><td>The JSON body of a request must not exceed 1024 bytes</td></tr></tbody></table>

Responses come in three shapes. Tell them apart:

| Shape              | Examples                                                               | How to judge success                                                                                     |
| ------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Raw JSON (no `ok`) | `/data`, `/model`, `/status`, `/snapshot`, `/getSchedule`, `/checkota` | If it parses and the fields are there it succeeded; a token error returns a small object with `ok:false` |
| Unified structure  | `/restart`, `/location`, `/save-config` and others                     | Read `ok`                                                                                                |
| Plain text         | `/sn`, `/logfile`                                                      | HTTP status code                                                                                         |

### 2. Session and authentication

The meter has an optional **Web password**.

* **No Web password (factory default): no endpoint needs a sign-in.** Anyone who can reach the IP can read data, change settings, reboot and factory-reset.
* **With a Web password:** every endpoint except `/signin` needs a `token` query parameter, for example `/data?token=123456`. Without it, or with a wrong one, you get a failure response and nothing is executed.

#### 2.1 Sign in to get a token

```
GET /signin?password=<password>
```

On success the device issues a token:

```json
{"ok":true,"msg":"","token":1736912345}
```

Add `?token=1736912345` to every later request (use `&token=...` when other query parameters exist).

Optionally you can **bring your own token** when signing in: `/signin?password=<password>&token=<number you generated>`. If the password is right the device registers your token and the response has **no** `token` field. Several clients can each use their own token.

<table><thead><tr><th width="282.333251953125">Case</th><th>Response</th></tr></thead><tbody><tr><td>Right password</td><td><code>{"ok":true,"msg":"","token":N}</code> (no <code>token</code> field when you brought your own)</td></tr><tr><td>Wrong password</td><td><code>{"ok":false,"msg":"wrong password","code":2003}</code></td></tr><tr><td>Password over 16 characters</td><td><code>{"ok":false,"msg":"password too long","code":2004}</code></td></tr><tr><td>Device has no password</td><td><code>{"ok":true,"msg":"no password set"}</code></td></tr><tr><td>No <code>password</code>, device has one</td><td><code>{"ok":false,"msg":"need signin","code":2005}</code></td></tr><tr><td>No <code>password</code>, device has none</td><td><code>{"ok":true,"msg":"no password"}</code></td></tr></tbody></table>

`/signin` without `password` tells you whether the device needs a password at all.

#### 2.2 Token rules

* A token is an **unsigned 32-bit integer** (decimal).
* The device remembers at most **5** tokens at once. When full, the least recently used one is dropped.
* A token **expires after 5 minutes idle**; every successful use renews it.
* Responses for a bad token: `{"ok":false,"msg":"need token","code":2001}` (missing) or `{"ok":false,"msg":"invalid token","code":2002}` (unknown or expired). Sign in again.
* After a successful password change (`/changepass`), **all tokens are revoked** at once.
* A reboot forgets all tokens.

#### 2.3 Change the Web password

```
GET /changepass?newpass=<new password>&oldpass=<old password>
```

The length is 1 to 16. When the device has no password yet, `oldpass` may be omitted. Failure `msg` values are `missing newpass`, `bad newpass length`, `old password wrong` and `nvs save failed`.

#### 2.4 Security reminders

* Password and token travel in the URL. On plain HTTP, anyone on the same network can capture them. Use HTTPS on Pro where protection matters.
* `/model` (and the `model` part of `/snapshot`) returns the **MQTT password in clear text** (`mqttUserPassword`), so do not expose a device without a Web password to an untrusted network.
* Use it only on a controlled LAN. Never forward port 80 / 443 to the Internet.

### 3. Endpoint list

"Needs a token" below means when a Web password is set. Unless noted, an endpoint exists on both 80 and 443. All `GET` parameters go in the query string.

#### 3.1 Reading data and state

<table><thead><tr><th width="188.666748046875">Endpoint</th><th width="156.2222900390625">Returns</th><th>Description</th></tr></thead><tbody><tr><td><code>GET /data</code></td><td>Raw JSON</td><td>The latest telemetry packet; fields are on the Telemetry Payload page. Each call increments an internal counter</td></tr><tr><td><code>GET /model</code></td><td>Raw JSON</td><td>Device configuration: model, Wi-Fi name, MQTT topics and connection, per-channel periods (<code>mqttInterval</code>, <code>udpInterval</code>, <code>wsInterval</code>), the <code>UDP</code> target list and more</td></tr><tr><td><code>GET /status</code></td><td>Raw JSON</td><td>Online state of each channel, valued <code>Online</code>, <code>Off</code> or <code>disconnected</code></td></tr><tr><td><code>GET /snapshot</code></td><td>Raw JSON</td><td>One call returns <code>{"data":telemetry,"model":configuration,"status":state}</code>; <strong>recommended for gateway polling</strong> instead of three requests</td></tr><tr><td><code>GET /getFunctionMap</code></td><td>Unified</td><td>The function bitmap in <code>d.functionMap</code>; bits are in Appendix B of the business command reference</td></tr><tr><td><code>GET /sn</code></td><td>Plain text</td><td><code>Model-SerialNumber</code>, such as <code>SPM02-AABBCCDDEEFF</code></td></tr><tr><td><code>GET /count</code></td><td>Unified</td><td><code>msg</code> is the cumulative number of <code>/data</code> and <code>/snapshot</code> calls</td></tr><tr><td><code>GET /checkota</code></td><td>Raw JSON</td><td><code>{"otastatus":number}</code>, whether new firmware exists</td></tr><tr><td><code>GET /low-signal-mode</code></td><td>Unified</td><td><code>d</code> is <code>{"mode":number}</code>; with a <code>mode</code> (or <code>value</code>, <code>state</code>) parameter it writes first and then returns. HTTPS also accepts the aliases <code>/lowSignalMode</code> and <code>/lowsignalmode</code></td></tr></tbody></table>

Fields of `/status`: `MQTTStatus`, `UDPStatus`, `WebSocketStatus`, `ModbusTCPStatus`, `wsInterval`; some models also have `LoRaWANStatus`.

#### 3.2 Control and maintenance

<table><thead><tr><th width="251.22216796875">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td><code>GET /location</code></td><td>Flash or beep to find the device</td></tr><tr><td><code>GET /zeroenergy</code></td><td>Reset energy counters; <strong>irreversible</strong></td></tr><tr><td><code>GET /restart</code></td><td>Reboot (the response is sent first, the reboot follows about 1 s later)</td></tr><tr><td><code>GET /ota</code> or <code>/ota?url=&#x3C;firmware URL></code></td><td>Upgrade the Wi-Fi module firmware online; without <code>url</code> the default is used. Reboots by itself on success when configured to</td></tr><tr><td><code>GET /mcuota</code></td><td>Upgrade the meter's metering chip firmware, <strong>reboots when done</strong></td></tr><tr><td><code>GET /erase</code></td><td><strong>Erase all stored settings and reboot</strong>; use with care</td></tr><tr><td><code>GET /deletewebpage</code></td><td>Delete the web page file stored on the device</td></tr><tr><td><code>GET /update</code></td><td>Make the device download the web page file again from the cloud (needs Internet access)</td></tr><tr><td><code>GET /clearlog</code></td><td>Clear the log (absent on some models)</td></tr><tr><td><code>GET /logfile</code></td><td>Plain-text log; 404 if there is none (absent on some models)</td></tr><tr><td><code>GET /hadata</code></td><td>Returns <code>{"zero":"zeroenergy"}</code>, used by the built-in page for Home Assistant; ignore it</td></tr><tr><td><code>GET /</code></td><td>The built-in web page, when the device has one</td></tr></tbody></table>

#### 3.3 Configuration commands

```
POST /save-config
Content-Type: application/json

{"cmd":"wifi","ssid":"MyRouter","pass":"secret"}
```

The body is a command JSON from the Business Command Reference; `cmd` may also be written as `configType`. The response is the unified structure with `event` echoing the command. Except for the BLE-only handshake commands, all business commands work.

A few commands are **written differently** on HTTP because the older handlers used by the built-in page catch them first. See Section 6.

#### 3.4 Certificate upload

<table><thead><tr><th width="246.7777099609375">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td><code>POST /upload</code></td><td>Port 80, <code>multipart/form-data</code> upload of one PEM file, saved as the MQTT CA (<code>/mqtt.pem</code>)</td></tr><tr><td><code>POST /uploadcefile</code></td><td>Used by the built-in page: the body is a quoted string with newlines written as <code>\n</code>; the device strips the quotes and <strong>drops one character at each end</strong> before saving it as the MQTT CA. The <code>filename=&#x3C;path></code> parameter sets the path, but on port 80 it must be the <strong>first</strong> query parameter, so with a Web password it sits after <code>token</code> and is ignored. These quirks are awkward; prefer <code>/upload</code> or BLE <code>cafilestart</code></td></tr><tr><td><code>POST /upload</code> (443)</td><td><strong>Not supported</strong>; returns <code>use HTTP :80 multipart POST /upload</code></td></tr></tbody></table>

For a large certificate, the safer way is writing it in pieces with `cafilestart` / `cafiledata` over BLE or MQTT.

#### 3.5 Endpoints of other models

Relay products (SRS series) also have `/switch1`, `/switch2`, `/schedule`, `/switch-config` and `/getSchedule`. SRS products are not covered by this repository, so they are not described here.

### 4. Access policy on port 80

When HTTPS (443) is on, the Pro secured build **turns off every business endpoint on port 80**:

```json
{"ok":false,"msg":"use_https","detail":"API only on HTTPS :443","code":2000}
```

The status is **403**. Only `GET /` (the built-in page) still opens on port 80. This prevents password and token leaks over the plaintext channel.

| Branch        | Port 80                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| Basic, Basic+ | Always available (no HTTPS)                                                                            |
| Lite          | Always available (Lite has no HTTPS and HTTP is off by default)                                        |
| Pro           | Available while HTTPS is off; once HTTPS is on only the page remains and business endpoints return 403 |

On a 403 `use_https`, switch to `https://`.

### 5. Port 80 versus port 443

Both ports offer the same endpoints. They differ in these ways:

<table><thead><tr><th width="179.7777099609375">Item</th><th width="195.6666259765625">80 (HTTP)</th><th>443 (HTTPS, Pro only)</th></tr></thead><tbody><tr><td>Certificate</td><td>none</td><td>Uses <code>/server_cert.pem</code> + <code>/server_key.pem</code> from the device when present; otherwise the <strong>certificate built into the firmware</strong>, which is shared by all devices and <strong>cannot protect against impersonation</strong>. If <code>/ca_cert.pem</code> is on the device, a client certificate is required</td></tr><tr><td>Methods</td><td>per route</td><td>Only <code>GET</code>, <code>POST</code>, <code>OPTIONS</code>; anything else gets 405</td></tr><tr><td><code>POST</code> body</td><td>Read by the web server</td><td><code>Content-Length</code> is required, otherwise 411; the request headers plus body must not exceed <strong>2048 bytes</strong> in total, otherwise 413. That is tighter than the 1024-byte JSON limit, so shorten long commands</td></tr><tr><td>JSON parse failure</td><td>Not checked; treated as a missing command and returns <code>No data received</code> (2040)</td><td>Explicit <code>bad json</code> (2070)</td></tr><tr><td>Connections</td><td>One request at a time</td><td>keep-alive supported, up to 32 requests in a row on one connection</td></tr><tr><td>CORS</td><td>none</td><td><code>Access-Control-Allow-Origin</code> is returned only when the request's <code>Origin</code> has the same host as the device</td></tr><tr><td>Unknown path</td><td>Web server default 404</td><td>404, <code>{"ok":false,"msg":"path not on HTTPS API","code":2090}</code></td></tr><tr><td><code>/upload</code></td><td>Works</td><td>Returns error 2080</td></tr></tbody></table>

### 6. `/save-config` special cases on HTTP

These `configType` / `cmd` values are **matched first** on HTTP, and behave differently from the same-named commands on BLE and MQTT.

| Command   | How to write it on HTTP                                                                                                                             | Description                                                                                                                                                                  |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mqtt`    | `{"configType":"mqtt","host":"broker.example.com","port":8883,"clientid":"dev01","username":"u","password":"p","ssltls":true,"ReportFrequency":30}` | Uses **separate fields**, not the pipe-separated `data`. `enable:false` turns MQTT off. The connection is rebuilt immediately, no reboot. Response `MQTT sent successfully!` |
| `mqtr`    | `{"cmd":"mqtr","data":"host\|clientid\|ssl\|port\|interval\|user\|pwd"}`                                                                            | To use the **pipe string** on HTTP, use this command (the device reboots after saving). Write a plain \`                                                                     |
| `model`   | `{"configType":"model"}`                                                                                                                            | Returns **raw JSON without `ok`**, similar to `GET /model`                                                                                                                   |
| `getmqtt` | `{"configType":"getmqtt"}`                                                                                                                          | `msg` is the connected broker address, or `OFF`                                                                                                                              |
| `name`    | `{"configType":"name","name":"..."}`                                                                                                                | Device name up to 30 characters                                                                                                                                              |
| `ble`     | `{"configType":"ble","opass":"old","npass":"new"}`                                                                                                  | Change the BLE password, up to 16                                                                                                                                            |
| `topic`   | `{"configType":"topic","topic_post":"..","topic_set":"..","topic_response":"..","topic_metadata":".."}`                                             | Changes all four topics                                                                                                                                                      |
| `ota`     | `{"configType":"ota","EspOTA":"true"}`                                                                                                              | Starts an upgrade                                                                                                                                                            |
| `erase`   | `{"configType":"erase"}`                                                                                                                            | Erase settings and reboot                                                                                                                                                    |

Other legacy types (`getconfig`, `baudrate`, `ParityStop`, `Modbusaddress`, `clear`, `report`, `alarm`) belong to the built-in page; new development does not need them, use the unified commands.

The point: **do not send `{"cmd":"mqtt","data":"..."}` on HTTP**. It takes the separate-field path above, the port is read as 0 and the configuration is corrupted. Use `mqtr`, or the separate-field `mqtt`.

### 7. Examples

With `curl` (replace the IP and password with yours):

```bash
# No Web password: read one telemetry packet directly
curl http://192.168.1.50/data

# With a Web password: sign in for a token, then use it
curl "http://192.168.1.50/signin?password=mypass"
curl "http://192.168.1.50/snapshot?token=1736912345"

# Make the device flash
curl "http://192.168.1.50/location?token=1736912345"

# Change the report target
curl -X POST "http://192.168.1.50/save-config?token=1736912345" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"udp","IpAddress":"192.168.1.20","localUdpPort":8888,"Frequency":5}'

# Pro HTTPS (the built-in certificate is shared; -k skips verification, debugging only)
curl -k "https://192.168.1.50/snapshot?token=1736912345"
```

The parameter names of the `udp` command follow the Business Command Reference.

The HTTP polling tool in this repository handles sign-in and token renewal for you.

### 8. Troubleshooting

<table><thead><tr><th width="355.6666259765625">Symptom</th><th>Cause</th></tr></thead><tbody><tr><td>Connection refused or timeout</td><td>HTTP is off (Lite and Pro default to off), use BLE <code>enablehttp</code>; or the device is on another subnet</td></tr><tr><td>403 <code>use_https</code></td><td>Pro has HTTPS on; use <code>https://</code></td></tr><tr><td><code>need token</code> / <code>invalid token</code></td><td>The device has a Web password, sign in with <code>/signin</code>; a token expires after 5 idle minutes, is pushed out of the 5 slots, or was revoked by a password change</td></tr><tr><td>HTTPS handshake fails</td><td>The TLS slots are taken by MQTTS and HTTPS is not listening; see Overview 3.1</td></tr><tr><td>HTTPS 413</td><td>Request headers plus body exceed 2048 bytes</td></tr><tr><td><code>/save-config</code> returns <code>No data received</code></td><td>The body is empty, the JSON is invalid, or <code>cmd</code> / <code>configType</code> is missing</td></tr></tbody></table>
