# BLE Basic API

## BLE API Reference

**Document Version:** V0.1 Preliminary | **Last Updated:** 2026-04-21 | **Accessible Scope:** Public

This document is intended for third-party Apps, gateways, or debugging tools to interface with the device's BLE API. It describes only the externally visible protocols and does not cover internal implementations.

### Applied Product Models

<table><thead><tr><th width="76">#</th><th width="214">Ordering Number</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td><strong>SPM01-D2EW</strong></td><td>SPM01 1PN FLEX/63A Open BLE+Wi-Fi</td></tr><tr><td>2</td><td><strong>SPM01-D1EW</strong></td><td>SPM01 1PN MCBM-BM/63A Open BLE+Wi-Fi</td></tr><tr><td>3</td><td><strong>SPM01-U1EW</strong></td><td>SPM01 1PN MCBM-TM/63A Open BLE+Wi-Fi</td></tr><tr><td>4</td><td><strong>SPM02-D2EW</strong></td><td>SPM02 3PN FLEX/63A Open BLE+Wi-Fi</td></tr><tr><td>5</td><td><strong>SPM02-D1EW</strong></td><td>SPM02 3PN MCBM-BM/63A Open BLE+Wi-Fi</td></tr><tr><td>6</td><td><strong>SPM02-U1EW</strong></td><td>SPM02 3PN MCBM-TM/63A Open BLE+Wi-Fi</td></tr><tr><td>7</td><td><strong>SDM01-EWM-12</strong></td><td>SDM01 SCTA-3×120A/Φ16 Wi-Fi (ESP32) + RS485</td></tr><tr><td>8</td><td><strong>SDM01-EWM-20</strong></td><td>SDM01 SCTA-3×200A/Φ20 Wi-Fi (ESP32) + RS485</td></tr><tr><td>9</td><td><strong>SDM01-EWM-12-BKW</strong></td><td>SDM01 SCTA-3x120A/Φ16 Wi-Fi (ESP32) + RS485 BKW</td></tr></tbody></table>

***

### 1. Connection Information

#### 1.1 Device Broadcast Name

* **Naming Rule:** `<Product Model>-<Device Serial Number>`
* **Example:** `SPM01A-1234567890AB`

#### 1.2 GATT Services and Characteristics

* **Primary Service UUID:** `0000A002-0000-1000-8000-00805F9B34FB`
* **Read Characteristic UUID:** `0000C304-0000-1000-8000-00805F9B34FB`
* **Write Characteristic UUID:** `0000C303-0000-1000-8000-00805F9B34FB`
* **Notify Characteristic UUID:** `0000C305-0000-1000-8000-00805F9B34FB`

#### 1.3 Interaction Channel Description

* The client sends commands via the **Write Characteristic**.
* The device returns processing results via the **Notify Characteristic**.
* **Recommendation:** Subscribe to the Notify Characteristic immediately after connection.
* The maximum MTU can reach up to 512 (the actual effective value depends on the connection negotiation result).

***

### 2. Standard Interaction Flow

#### 2.1 Flow Overview

1. Scan and connect to the device.
2. Subscribe to the Notify Characteristic.
3. Send the unlock command (`cmd=pass`).
4. Send business commands after successful unlocking.
5. Receive the result for each command from the Notify Characteristic.

#### 2.2 Unlock Requirements

* In an un-unlocked state, most business commands will be rejected.
* The unlock command must include the password field `pas`.
* After a successful unlock, subsequent `cmd` requests within the current BLE connection session do not need to carry `pas` and `auth` by default.
* If unlocking fails, a "Password Error" or "Please unlock" prompt is returned.

#### 2.3 Phone Binding Authentication (Optional)

If the device has phone authentication enabled:

* It is recommended to include `auth` in the unlock command during the first authentication.
* An authentication error is returned if `auth` does not match.
* For the initial binding scenario, `auth` can be written in the unlock command.

***

### 3. Request & Response Specification

#### 3.1 Common Request Fields (Client -> Device)

* `cmd`: Command word (Required).
* `pas`: BLE password. Required only for the initial verification (`cmd=pass`).
* `auth`: Authentication identifier. Recommended during initial verification (if authentication is enabled).
* **Session Rule:** After successful initial verification, subsequent commands within the same connection session do not need to carry `pas` and `auth`.

#### 3.2 Common Response Fields (Device -> Client)

* `ok`: Boolean, indicates whether the request was processed successfully.
* `msg`: String, processing result description.
* `event`: String (Optional), usually echoes the command word.
* `d`: Object (Optional), appears only when query commands return data.

#### 3.3 Common Failure Semantics

* `Password Error`: Incorrect password.
* `Please unlock`: Device is not unlocked.
* `auth error`: Incorrect authentication field.
* `not authenticated`: Authentication failed.
* `illegal cmd`: Command not supported.

***

### 4. Command API Details

#### 4.1 Initial Handshake

* **Purpose:** Unlock session, change password, set session persistence, and bind initial authentication identifier.
* **Fields:**
  * `cmd`: Fixed as `pass`.
  * `pas`: Current BLE password (Required).
  * `newpas`: New password (Optional, max 16 characters).
  * `continue`: Keep session alive (Optional, Boolean). If omitted, every communication requires a handshake.
  * `auth`: Authentication identifier (Optional, max 40 characters).

**Request Example:**

```json
{
  "cmd": "pass",
  "pas": "123456",
  "continue": true
}
```

**Response Example (Success):**

```json
{
  "ok": true,
  "msg": "Password Correct",
  "event": "pass"
}
```

#### 4.2 Reboot

* **Purpose:** Trigger the device reboot process.
* **Fields:**
  * `cmd`: Fixed as `restart`.

**Request Example:**

```json
{
  "cmd": "restart"
}
```

#### 4.3 Device Location

* **Purpose:** Trigger location processing. The device indicator will flash at 4Hz for 15 seconds.
* **Fields:**
  * `cmd`: Fixed as `location`.

**Request Example:**

```json
{
  "cmd": "location"
}
```

#### 4.4 Unbind

* **Purpose:** Clear the bound authentication status.
* **Fields:**
  * `cmd`: Fixed as `resetauth`.

**Request Example:**

```json
{
  "cmd": "resetauth"
}
```

#### 4.5 Set MQTT Topic 1

* **Purpose:** Set the first group of MQTT topic parameters.
* **Fields:**
  * `cmd`: Fixed as `topic1`.
  * `topic_post`: Uplink topic.
  * `topic_set`: Downlink control topic.

**Request Example:**

```json
{
  "cmd": "topic1",
  "topic_post": "dev/up",
  "topic_set": "dev/down"
}
```

#### 4.6 Set MQTT Topic 2

* **Purpose:** Set the second group of MQTT topic parameters.
* **Fields:**
  * `cmd`: Fixed as `topic2`.
  * `topic_response`: Response topic.
  * `topic_metadata`: Metadata topic.

**Request Example:**

```json
{
  "cmd": "topic2",
  "topic_response": "dev/resp",
  "topic_metadata": "dev/meta"
}
```

#### 4.7 Unlock Read Characteristic

* **Purpose:** Enter readable state to prepare for subsequent status data reading.
* **Fields:**
  * `cmd`: Fixed as `read`.
  * `continue`: Default is read once. Add this field (`true`) for continuous reading (Optional).

**Request Example:**

```json
{
  "cmd": "read",
  "continue": true
}
```

#### 4.8 Clear Energy Data

* **Purpose:** Clear all accumulated energy data (Irreversible).
* **Fields:**
  * `cmd`: Fixed as `zero`.

**Request Example:**

```json
{
  "cmd": "zero"
}
```

#### 4.11 Get Function Map

* **Purpose:** Read the `functionMap` (16-bit feature bitmap).
* **Fields:**
  * `cmd`: Fixed as `getFunctionMap`.

**Request Example:**

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

**Response Example:**

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

**Bit Definition Table (Bit 15 is the highest bit):**

| Bit | Function   | Description             |
| --- | ---------- | ----------------------- |
| 15  | Modbus TCP | `1=Enable`, `0=Disable` |
| 14  | TLS Enable | `1=Enable`, `0=Disable` |
| 13  | UDP        | `1=Enable`, `0=Disable` |
| 11  | WebSocket  | `1=Enable`, `0=Disable` |
| 9   | MQTT       | `1=Enable`, `0=Disable` |
| 7   | HTTP       | `1=Enable`, `0=Disable` |
| 5   | LoRaWAN    | `1=Enable`, `0=Disable` |

#### 4.12 TLS Multiplexing Status

* **Purpose:** Read the Modbus TLS multiplexing status value.
* **Fields:**
  * `cmd`: Fixed as `getModbusTlsMuxSetupStatus`.

**Response Example:**

```json
{
  "ok": true,
  "msg": "",
  "event": "getModbusTlsMuxSetupStatus",
  "d": {
    "modbusTlsMuxSetupStatus": 1
  }
}
```

**Status Value Description:**

* `0`: `MODBUS_TLS_MUX_SETUP_IDLE` - Uninitialized (e.g., Wi-Fi disconnected, feature disabled).
* `1`: `MODBUS_TLS_MUX_SETUP_PLAIN_OK` - Started successfully in plaintext (due to incomplete certificates).
* `2`: `MODBUS_TLS_MUX_SETUP_TLS_OK` - TLS started successfully.
* `3`: `MODBUS_TLS_MUX_SETUP_TLS_CERT` - Certificate/Key file error.
* `4`: `MODBUS_TLS_MUX_SETUP_TLS_SOCK` - TLS socket/bind/listen failed.
* `5`: `MODBUS_TLS_MUX_SETUP_PLAIN_FAIL` - Plaintext startup failed.

#### 4.23 Set Function Map

* **Purpose:** Directly write the `functionMap` value.
* **Fields:**
  * `cmd`: Fixed as `functionMap`.
  * `value`: 16-bit integer.

**Request Example:**

```json
{
  "cmd": "functionMap",
  "value": 37376
}
```

#### 4.24 Data Format

* **Purpose:** Set the message reporting format. `0` represents BT format, `1` represents common format.
* **Fields:**
  * `cmd`: Fixed as `commonmode`.
  * `value`: Mode value.

**Request Example:**

```json
{
  "cmd": "commonmode",
  "value": 0
}
```

#### 4.25 Factory Reset

* **Purpose:** Clear configuration and trigger a reboot.
* **Fields:**
  * `cmd`: Fixed as `reset`.

**Request Example:**

```json
{
  "cmd": "reset"
}
```

#### 4.26 Wi-Fi Configuration

* **Purpose:** Set Wi-Fi connection parameters.
* **Fields:**
  * `cmd`: Fixed as `wifi`.
  * `ssid`: Wi-Fi Name (<=64 chars).
  * `pass`: Wi-Fi Password (<=64 chars).

**Request Example:**

```json
{
  "cmd": "wifi",
  "ssid": "OfficeWiFi",
  "pass": "12345678"
}
```

#### 4.27 MQTT Configuration

* **Purpose:** Configure MQTT. Using `mqtr` will additionally trigger a reboot.
* **Fields:**
  * `cmd`: `mqtt` or `mqtr`.
  * `data`: Formatted as `host|clientid|ssl|port|interval|username|password`.

**Request Example:**

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

#### 4.28 Start Certificate Writing

* **Purpose:** Create/clear the certificate file and prepare for fragmented writing.
* **Fields:**
  * `cmd`: Fixed as `cafilestart`.
  * `filename`: Target certificate file.

**Request Example:**

```json
{
  "cmd": "cafilestart",
  "filename": "/mqtt.pem"
}
```

#### 4.29 Write Certificate Fragment

* **Purpose:** Write a fragment of the certificate content.
* **Fields:**
  * `cmd`: Fixed as `cafiledata`.
  * `cadata`: Certificate fragment string. Fixed size of 128 bytes (no padding needed for the last packet).

**Request Example:**

```json
{
  "cmd": "cafiledata",
  "cadata": "-----BEGIN CERTIFICATE-----"
}
```

#### 4.30 Add UDP Target

* **Purpose:** Add a new UDP upload target.
* **Fields:**
  * `cmd`: Fixed as `udp`.
  * `IpAddress`: Target IP.
  * `localUdpPort`: Target port.

**Request Example:**

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

#### 4.31 OTA Status

* **Purpose:** Query the OTA status.
* **Fields:**
  * `cmd`: Fixed as `checkota`.

**Response Example:**

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

**`otastatus` Value Description:**

* `200`: Update package available.
* `404`: No update package available (already on the latest version).
* `-2`: OTA URL not configured.
* *Other values*: HTTP/Network error codes (e.g., connection failed, timeout).

#### 4.32 OTA Progress

* **Purpose:** Read the OTA progress percentage.
* **Fields:**
  * `cmd`: Fixed as `otaprogress`.

**Response Example:**

```json
{
  "ok": true,
  "msg": "",
  "event": "otaprogress",
  "d": {
    "otaprogress": 60
  }
}
```

#### 4.33 Start OTA

* **Purpose:** Start the OTA task.
* **Fields:**
  * `cmd`: Fixed as `startota`.

**Request Example:**

```json
{
  "cmd": "startota"
}
```

#### 4.34 Delete UDP Target

* **Purpose:** Delete an existing UDP target.
* **Fields:**
  * `cmd`: Fixed as `deleteudp`.
  * `IpAddress`: Target IP.
  * `localUdpPort`: Target port.

**Request Example:**

```json
{
  "cmd": "deleteudp",
  "IpAddress": "192.168.1.100",
  "localUdpPort": 9000
}
```

#### 4.35 UDP List

* **Purpose:** Read the list of UDP targets.
* **Fields:**
  * `cmd`: Fixed as `udpdata`.

**Response Example:**

```json
{
  "ok": true,
  "msg": "",
  "event": "udpdata",
  "d": {
    "items": []
  }
}
```

#### 4.36 Enable HTTP

* **Purpose:** Enable the HTTP bit.
* **Fields:**
  * `cmd`: Fixed as `enablehttp`.

**Request Example:**

```json
{
  "cmd": "enablehttp"
}
```

#### 4.37 Enable WebSocket

* **Purpose:** Enable/Disable the WebSocket bit.
* **Fields:**
  * `cmd`: Fixed as `enablewebsocket`.
  * `enable`: `true` to enable, `false` to disable.

**Request Example:**

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

#### 4.38 Enable Modbus TCP

* **Purpose:** Enable/Disable the Modbus TCP bit.
* **Fields:**
  * `cmd`: Fixed as `enablemodbustcp`.
  * `enable`: `true` to enable, `false` to disable.

**Request Example:**

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

#### 4.39 Enable TLS

* **Purpose:** Enable/Disable the TLS bit.
* **Fields:**
  * `cmd`: Fixed as `enabletls`.
  * `enable`: `true` to enable, `false` to disable.

**Request Example:**

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

#### 4.40 Modify BLE Password

* **Purpose:** Modify the BLE password.
* **Fields:**
  * `cmd`: Fixed as `blepassword`.
  * `old`: Old password.
  * `new`: New password (<=16 chars).

**Request Example:**

```json
{
  "cmd": "blepassword",
  "old": "123456",
  "new": "654321"
}
```

#### 4.41 Modbus Parameters

* **Purpose:** Set serial Modbus communication parameters.
* **Fields:**
  * `cmd`: Fixed as `modbus`.
  * `baud`: Baud rate.
  * `parityStop`: Parity/Stop bits.
  * `address`: Slave address.

**Request Example:**

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

#### 4.42 Device Name

* **Purpose:** Set the device name.
* **Fields:**
  * `cmd`: Fixed as `deviceName`.
  * `name`: Device name (<=30 chars).

**Request Example:**

```json
{
  "cmd": "deviceName",
  "name": "RoomMeter01"
}
```

#### 4.45 Read Configuration

* **Purpose:** Read the comprehensive configuration snapshot of the device.
* **Fields:**
  * `cmd`: Fixed as `model`.
  * `type`: Optional refresh type.

**Request Example:**

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

**Response Example:**

```json
{
  "ok": true,
  "msg": "",
  "event": "model",
  "d": {
    "WN": "OfficeWiFi",
    "MH": "broker.example.com"
  }
}
```

#### 4.46 Read MQTT Data

* **Purpose:** Read MQTT related topics and account information.
* **Fields:**
  * `cmd`: Fixed as `mqttdata`.

**Request Example:**

```json
{
  "cmd": "mqttdata"
}
```

**Response Example:**

```json
{
  "ok": true,
  "msg": "",
  "event": "mqttdata",
  "d": {
    "TP": "dev/up",
    "TC": "dev/down"
  }
}
```

***

### 5. Integration Notes

* It is recommended to uniformly use **UTF-8 encoded JSON text** for all requests.
* Always confirm that the Notify Characteristic is subscribed to before sending commands.
* After a successful initial `cmd=pass`, subsequent commands within the same connection session do not need to carry `pas` and `auth`.
* If the device returns `Please unlock` or `not authenticated`, you must re-execute the initial verification process.
* Supported commands may vary by model. It is recommended to perform capability probing using query commands.

***

### 6. Version & Compatibility

* **Backward Compatibility Recommendation:** The response structure is fixed as `ok / msg / event / d`.
* During external integration, it is recommended to implement failure retries and error prompts at the command level.

###

###

###

Here is the complete, restructured English documentation optimized for GitBook. I have categorized the APIs into logical modules, used parameter tables, and applied GitBook's native `{% tabs %}` syntax to make the code blocks compact and easy to read.

You can copy and paste this directly into your GitBook editor.

***

## BLE API Reference

**Document Version:** V0.1 Preliminary | **Last Updated:** 2026-04-21 | **Accessible Scope:** Public

This document is intended for third-party Apps, gateways, or debugging tools to interface with the device's BLE API. It describes only the externally visible protocols and does not cover internal implementations.

### Applied Product Models

| # | Ordering Number      | Description                                     |
| - | -------------------- | ----------------------------------------------- |
| 1 | **SPM01-D2EW**       | SPM01 1PN FLEX/63A Open BLE+Wi-Fi               |
| 2 | **SPM01-D1EW**       | SPM01 1PN MCBM-BM/63A Open BLE+Wi-Fi            |
| 3 | **SPM01-U1EW**       | SPM01 1PN MCBM-TM/63A Open BLE+Wi-Fi            |
| 4 | **SPM02-D2EW**       | SPM02 3PN FLEX/63A Open BLE+Wi-Fi               |
| 5 | **SPM02-D1EW**       | SPM02 3PN MCBM-BM/63A Open BLE+Wi-Fi            |
| 6 | **SPM02-U1EW**       | SPM02 3PN MCBM-TM/63A Open BLE+Wi-Fi            |
| 7 | **SDM01-EWM-12**     | SDM01 SCTA-3×120A/Φ16 Wi-Fi (ESP32) + RS485     |
| 8 | **SDM01-EWM-20**     | SDM01 SCTA-3×200A/Φ20 Wi-Fi (ESP32) + RS485     |
| 9 | **SDM01-EWM-12-BKW** | SDM01 SCTA-3x120A/Φ16 Wi-Fi (ESP32) + RS485 BKW |

***

### 1. Connection & Interaction Overview

#### 1.1 BLE Connection Info

* **Broadcast Name Rule:** `<Product Model>-<Device Serial Number>` (e.g., `SRS01A-1234567890AB`)
* **Primary Service UUID:** `0000A002-0000-1000-8000-00805F9B34FB`
* **Write Characteristic UUID:** `0000C303-0000-1000-8000-00805F9B34FB` (Client sends commands here)
* **Notify Characteristic UUID:** `0000C305-0000-1000-8000-00805F9B34FB` (Device returns results here)
* **Read Characteristic UUID:** `0000C304-0000-1000-8000-00805F9B34FB`

> 💡 **Best Practice:** Always subscribe to the **Notify Characteristic** immediately after connection. The maximum MTU can reach up to 512. We recommend using UTF-8 encoded JSON text for all requests.

#### 1.2 Standard Interaction Flow

1. **Connect & Subscribe:** Scan, connect, and subscribe to the Notify Characteristic.
2. **Unlock Session:** Send the unlock command (`cmd=pass`). Most business commands are rejected if the device is locked.
3. **Send Commands:** After a successful unlock, subsequent commands in the same session do not need to carry the password (`pas`) or auth token (`auth`).
4. **Receive Results:** Listen to the Notify Characteristic for the `ok`, `msg`, `event`, and `d` (data) fields.

***

### 2. Authentication & Session Management

#### Initial Handshake (`pass`)

Unlocks the session, changes the password, sets session persistence, and binds the initial authentication identifier.

**Parameters:**

| Field                                                                                 | Type    | Required | Description                                                               |
| ------------------------------------------------------------------------------------- | ------- | :------: | ------------------------------------------------------------------------- |
| `cmd`                                                                                 | String  |    Yes   | Fixed as `pass`.                                                          |
| `pas`                                                                                 | String  |    Yes   | Current BLE password.                                                     |
| `newpas`                                                                              | String  |    No    | New password (Max 16 chars).                                              |
| `continue`                                                                            | Boolean |    No    | Keep session alive. If omitted, every communication requires a handshake. |
| `auth`                                                                                | String  |    No    | Authentication identifier (Max 40 chars).                                 |
| {                                                                                     |         |          |                                                                           |
| "cmd": "pass",                                                                        |         |          |                                                                           |
| "pas": "123456",                                                                      |         |          |                                                                           |
| "continue": true                                                                      |         |          |                                                                           |
| }                                                                                     |         |          |                                                                           |
| `</div><div data-gb-custom-block data-tag="tab" data-title='Response (Success)'>`json |         |          |                                                                           |
| {                                                                                     |         |          |                                                                           |
| "ok": true,                                                                           |         |          |                                                                           |
| "msg": "Password Correct",                                                            |         |          |                                                                           |
| "event": "pass"                                                                       |         |          |                                                                           |
| }                                                                                     |         |          |                                                                           |
| `</div><div data-gb-custom-block data-tag="tab" data-title='Response (Fail)'>`json    |         |          |                                                                           |
| {                                                                                     |         |          |                                                                           |
| "ok": false,                                                                          |         |          |                                                                           |
| "msg": "Password Error",                                                              |         |          |                                                                           |
| "event": "pas"                                                                        |         |          |                                                                           |
| }                                                                                     |         |          |                                                                           |
| \`\`\`### Modify BLE Password (`blepassword`)                                         |         |          |                                                                           |
| Changes the BLE connection password.                                                  |         |          |                                                                           |

**Parameters:**

| Field                                                                                                                                                                               | Type   | Required | Description                  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | :------: | ---------------------------- |
| `cmd`                                                                                                                                                                               | String |    Yes   | Fixed as `blepassword`.      |
| `old`                                                                                                                                                                               | String |    Yes   | Old password.                |
| `new`                                                                                                                                                                               | String |    Yes   | New password (Max 16 chars). |
| {                                                                                                                                                                                   |        |          |                              |
| "cmd": "blepassword",                                                                                                                                                               |        |          |                              |
| "old": "123456",                                                                                                                                                                    |        |          |                              |
| "new": "654321"                                                                                                                                                                     |        |          |                              |
| }                                                                                                                                                                                   |        |          |                              |
| `</div><div data-gb-custom-block data-tag="tab" data-title='Response'>`json                                                                                                         |        |          |                              |
| {                                                                                                                                                                                   |        |          |                              |
| "ok": true,                                                                                                                                                                         |        |          |                              |
| "msg": "Password yes",                                                                                                                                                              |        |          |                              |
| "event": "blepassword"                                                                                                                                                              |        |          |                              |
| }                                                                                                                                                                                   |        |          |                              |
| \`\`\`### Unbind (`resetauth`)                                                                                                                                                      |        |          |                              |
| <p>Clears the bound authentication status.</p><div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title="Request"><p>\`\`\`json</p></div></div> |        |          |                              |
| {                                                                                                                                                                                   |        |          |                              |
| "cmd": "resetauth"                                                                                                                                                                  |        |          |                              |
| }                                                                                                                                                                                   |        |          |                              |
| `</div><div data-gb-custom-block data-tag="tab" data-title='Response'>`json                                                                                                         |        |          |                              |
| {                                                                                                                                                                                   |        |          |                              |
| "ok": true,                                                                                                                                                                         |        |          |                              |
| "msg": "resetauth received",                                                                                                                                                        |        |          |                              |
| "event": "resetauth"                                                                                                                                                                |        |          |                              |
| }                                                                                                                                                                                   |        |          |                              |
| \`\`\`### Unlock Read Characteristic (`read`)                                                                                                                                       |        |          |                              |
| Enables the readable state to prepare for subsequent status data reading.                                                                                                           |        |          |                              |

**Parameters:**

| Field                                                                       | Type    | Required | Description                                                 |
| --------------------------------------------------------------------------- | ------- | :------: | ----------------------------------------------------------- |
| `cmd`                                                                       | String  |    Yes   | Fixed as `read`.                                            |
| `continue`                                                                  | Boolean |    No    | Default is read once. Set to `true` for continuous reading. |
| {                                                                           |         |          |                                                             |
| "cmd": "read",                                                              |         |          |                                                             |
| "continue": true                                                            |         |          |                                                             |
| }                                                                           |         |          |                                                             |
| `</div><div data-gb-custom-block data-tag="tab" data-title='Response'>`json |         |          |                                                             |
| {                                                                           |         |          |                                                             |
| "ok": true,                                                                 |         |          |                                                             |
| "msg": "ready",                                                             |         |          |                                                             |
| "event": "read"                                                             |         |          |                                                             |
| }                                                                           |         |          |                                                             |

````</div></div>---

## 3. Network & Communication Configuration

### Wi-Fi Configuration (`wifi`)
Sets the Wi-Fi connection parameters.

**Parameters:**
| Field | Type | Required | Description |
| :--- | :--- | :---: | :--- |
| `cmd` | String | Yes | Fixed as `wifi`. |
| `ssid` | String | Yes | Wi-Fi Name (Max 64 chars). |
| `pass` | String | Yes | Wi-Fi Password (Max 64 chars). |<div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title='Request'>```json
{
  "cmd": "wifi",
  "ssid": "OfficeWiFi",
  "pass": "12345678"
}
```</div><div data-gb-custom-block data-tag="tab" data-title='Response'>```json
{
  "ok": true,
  "msg": "WIFI successfully",
  "event": "wifi"
}
```</div></div>### MQTT Configuration (`mqtt` / `mqtr`)
Configures the MQTT broker settings.

> ⚠️ **Warning:** Using the `mqtr` command will automatically trigger a device reboot after saving.

**Parameters:**
| Field | Type | Required | Description |
| :--- | :--- | :---: | :--- |
| `cmd` | String | Yes | `mqtt` (save) or `mqtr` (save & reboot). |
| `data` | String | Yes | Format: `host|clientid|ssl|port|interval|username|password` |<div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title='Request'>```json
{
  "cmd": "mqtt",
  "data": "broker.example.com|dev01|1|8883|5|user|pwd"
}
```</div><div data-gb-custom-block data-tag="tab" data-title='Response'>```json
{
  "ok": true,
  "msg": "MQTT successfully",
  "event": "mqtt"
}
```</div></div>### Set MQTT Topics (`topic1` & `topic2`)
Configures uplink/downlink and response/metadata topics.

**Parameters for `topic1`:**
| Field | Type | Required | Description |
| :--- | :--- | :---: | :--- |
| `cmd` | String | Yes | Fixed as `topic1`. |
| `topic_post` | String | Yes | Uplink topic. |
| `topic_set` | String | Yes | Downlink control topic. |

**Parameters for `topic2`:**
| Field | Type | Required | Description |
| :--- | :--- | :---: | :--- |
| `cmd` | String | Yes | Fixed as `topic2`. |
| `topic_response` | String | Yes | Response topic. |
| `topic_metadata` | String | Yes | Metadata topic. |<div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title='Request (Topic 1)'>```json
{
  "cmd": "topic1",
  "topic_post": "dev/up",
  "topic_set": "dev/down"
}
```</div><div data-gb-custom-block data-tag="tab" data-title='Request (Topic 2)'>```json
{
  "cmd": "topic2",
  "topic_response": "dev/resp",
  "topic_metadata": "dev/meta"
}
```</div></div>### UDP Management (`udp`, `deleteudp`, `udpdata`)
Manage UDP upload targets.

**Parameters for Add/Delete:**
| Field | Type | Required | Description |
| :--- | :--- | :---: | :--- |
| `cmd` | String | Yes | `udp` (Add) or `deleteudp` (Delete). |
| `IpAddress` | String | Yes | Target IP Address. |
| `localUdpPort` | Integer| Yes | Target Port. |<div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title='Add Target'>```json
{
  "cmd": "udp",
  "IpAddress": "192.168.1.100",
  "localUdpPort": 9000
}
```</div><div data-gb-custom-block data-tag="tab" data-title='Delete Target'>```json
{
  "cmd": "deleteudp",
  "IpAddress": "192.168.1.100",
  "localUdpPort": 9000
}
```</div><div data-gb-custom-block data-tag="tab" data-title='List Targets'>```json
{
  "cmd": "udpdata"
}
````

// Response: { "ok": true, "event": "udpdata", "d": { "items": \[] } }---

### 4. Device Control & Status

#### Device Operations (`restart`, `reset`, `location`, `zero`)

Basic device control commands requiring only the `cmd` field.

* `restart`: Triggers device reboot.
* `reset`: Clears configuration and triggers a factory reset.
* `location`: Device indicator flashes at 4Hz for 15 seconds.
* `zero`: Clears all accumulated energy data (Irreversible).

  \### Device Name (`deviceName`) Sets a custom name for the device.

**Parameters:**

| Field                                                                                                                                                                                         | Type   | Required | Description                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | :------: | --------------------------- |
| `cmd`                                                                                                                                                                                         | String |    Yes   | Fixed as `deviceName`.      |
| `name`                                                                                                                                                                                        | String |    Yes   | Device name (Max 30 chars). |
| {                                                                                                                                                                                             |        |          |                             |
| "cmd": "deviceName",                                                                                                                                                                          |        |          |                             |
| "name": "RoomMeter01"                                                                                                                                                                         |        |          |                             |
| }                                                                                                                                                                                             |        |          |                             |
| \`\`\`### Read Configuration (`model` & `mqttdata`)                                                                                                                                           |        |          |                             |
| <p>Reads device configuration snapshots.</p><div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title="Read Config (model)"><p>\`\`\`json</p></div></div> |        |          |                             |
| {                                                                                                                                                                                             |        |          |                             |
| "cmd": "model",                                                                                                                                                                               |        |          |                             |
| "type": 1                                                                                                                                                                                     |        |          |                             |
| }                                                                                                                                                                                             |        |          |                             |

````
// Response:
{
  "ok": true,
  "event": "model",
  "d": { "WN": "OfficeWiFi", "MH": "broker.example.com" }
}</div><div data-gb-custom-block data-tag="tab" data-title='Read MQTT Data'>```json
{
  "cmd": "mqttdata"
}
````

// Response: { "ok": true, "event": "mqttdata", "d": { "TP": "dev/up", "TC": "dev/down" } }---

### 5. Feature Flags & Protocols

#### Function Map (`getFunctionMap` / `functionMap`)

Reads or writes the 16-bit feature bitmap.

**Bit Definition Table (Bit 15 is MSB):**

| Bit                     | Function   | Description             |
| ----------------------- | ---------- | ----------------------- |
| 15                      | Modbus TCP | `1=Enable`, `0=Disable` |
| 14                      | TLS Enable | `1=Enable`, `0=Disable` |
| 13                      | UDP        | `1=Enable`, `0=Disable` |
| 11                      | WebSocket  | `1=Enable`, `0=Disable` |
| 9                       | MQTT       | `1=Enable`, `0=Disable` |
| 7                       | HTTP       | `1=Enable`, `0=Disable` |
| 5                       | LoRaWAN    | `1=Enable`, `0=Disable` |
| {                       |            |                         |
| "cmd": "getFunctionMap" |            |                         |
| }                       |            |                         |
|                         |            |                         |

````
// Response:
{
  "ok": true,
  "event": "getFunctionMap",
  "d": { "functionMap": 37376 }
}</div><div data-gb-custom-block data-tag="tab" data-title='Write (functionMap)'>```json
{
  "cmd": "functionMap",
  "value": 37376
}
```</div></div>### Enable Services (`enable...`)
Quick toggle commands for specific services. All require `cmd` and a boolean `enable` field (except HTTP).

* `enablehttp`: Enables HTTP (No `enable` field required).
* `enablewebsocket`: Enables/Disables WebSocket.
* `enablemodbustcp`: Enables/Disables Modbus TCP.
* `enabletls`: Enables/Disables TLS.<div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title='Request Example'>```json
{
  "cmd": "enablewebsocket",
  "enable": true
}
```</div></div>### Modbus Parameters (`modbus`)
Sets serial Modbus communication parameters.

**Parameters:**
| Field | Type | Required | Description |
| :--- | :--- | :---: | :--- |
| `cmd` | String | Yes | Fixed as `modbus`. |
| `baud` | Integer| Yes | Baud rate (e.g., 9600). |
| `parityStop` | Integer| Yes | Parity/Stop bits configuration. |
| `address` | Integer| Yes | Slave address. |<div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title='Request'>```json
{
  "cmd": "modbus",
  "baud": 9600,
  "parityStop": 0,
  "address": 1
}
```</div></div>### TLS Multiplexing Status (`getModbusTlsMuxSetupStatus`)
Reads the Modbus TLS multiplexing status value.<div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title='Request'>```json
{
  "cmd": "getModbusTlsMuxSetupStatus"
}
```</div><div data-gb-custom-block data-tag="tab" data-title='Response'>```json
{
  "ok": true,
  "event": "getModbusTlsMuxSetupStatus",
  "d": { "modbusTlsMuxSetupStatus": 1 }
}
```</div></div>**Status Values:**
* `0`: Uninitialized.
* `1`: Started successfully in plaintext (incomplete certificates).
* `2`: TLS started successfully.
* `3`: Certificate/Key file error.
* `4`: TLS socket/bind/listen failed.
* `5`: Plaintext startup failed.

---

## 6. Certificate Management

### Write Certificate (`cafilestart` / `cafiledata`)
Creates a certificate file and writes it in fragments.

**Parameters for Start:**
| Field | Type | Required | Description |
| :--- | :--- | :---: | :--- |
| `cmd` | String | Yes | Fixed as `cafilestart`. |
| `filename` | String | Yes | Target certificate file (e.g., `/mqtt.pem`). |

**Parameters for Data Fragment:**
| Field | Type | Required | Description |
| :--- | :--- | :---: | :--- |
| `cmd` | String | Yes | Fixed as `cafiledata`. |
| `cadata` | String | Yes | Fragment string (Fixed 128 bytes, no padding for the last packet). |<div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title='1. Start Writing'>```json
{
  "cmd": "cafilestart",
  "filename": "/mqtt.pem"
}
```</div><div data-gb-custom-block data-tag="tab" data-title='2. Send Fragment'>```json
{
  "cmd": "cafiledata",
  "cadata": "-----BEGIN CERTIFICATE-----"
}
```</div></div>---

## 7. OTA (Over-The-Air) Updates

### OTA Management (`checkota`, `otaprogress`, `startota`)
Commands to manage firmware updates.

* `checkota`: Queries OTA status.
* `otaprogress`: Reads progress percentage.
* `startota`: Initiates the OTA task.<div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title='Check Status'>```json
{
  "cmd": "checkota"
}
````

// Response: { "ok": true, "event": "checkota", "d": { "otastatus": 200 } }

\`\`\`json { "cmd": "otaprogress" }

````
// Response:
{
  "ok": true,
  "event": "otaprogress",
  "d": { "otaprogress": 60 }
}</div><div data-gb-custom-block data-tag="tab" data-title='Start OTA'>```json
{
  "cmd": "startota"
}
```</div></div>

**`otastatus` Values:**
* `200`: Update package available.
* `404`: No update package available (already on the latest version).
* `-2`: OTA URL not configured.
* *Other*: HTTP/Network error codes.
````

***

### 5. Revision History

<table><thead><tr><th width="151">Version</th><th>Date</th><th>Changes</th><th>Author</th><th>Checked</th><th>Remark</th></tr></thead><tbody><tr><td>V1.0</td><td>2025-11-01</td><td>Initial release. Dedicated complete list for limited customers and users.</td><td>HX</td><td>LHL</td><td>N/A</td></tr><tr><td>V1.1 Preliminary</td><td>2026-04-14</td><td>Document maintained from Feishu/Larksuite to Gitbook</td><td>HX</td><td>LHL</td><td>N/A</td></tr></tbody></table>

\ <br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bituo-technik.com/device-api/ble-basic-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.