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

#	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 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:

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

Response Example (Success):

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

4.2 Reboot

• Purpose: Trigger the device reboot process.

• Fields:

  • cmd: Fixed as restart.

Request Example:

{
  "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:

{
  "cmd": "location"
}

4.4 Unbind

• Purpose: Clear the bound authentication status.

• Fields:

  • cmd: Fixed as resetauth.

Request Example:

{
  "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:

{
  "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:

{
  "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:

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

4.8 Clear Energy Data

• Purpose: Clear all accumulated energy data (Irreversible).

• Fields:

  • cmd: Fixed as zero.

Request Example:

{
  "cmd": "zero"
}

4.11 Get Function Map

• Purpose: Read the functionMap (16-bit feature bitmap).

• Fields:

  • cmd: Fixed as getFunctionMap.

Request Example:

{
  "cmd": "getFunctionMap"
}

Response Example:

{
  "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:

{
  "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:

{
  "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:

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

4.25 Factory Reset

• Purpose: Clear configuration and trigger a reboot.

• Fields:

  • cmd: Fixed as reset.

Request Example:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

4.33 Start OTA

• Purpose: Start the OTA task.

• Fields:

  • cmd: Fixed as startota.

Request Example:

{
  "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:

{
  "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:

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

4.36 Enable HTTP

• Purpose: Enable the HTTP bit.

• Fields:

  • cmd: Fixed as enablehttp.

Request Example:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

Response Example:

{
  "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:

{
  "cmd": "mqttdata"
}

Response Example:

{
  "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)
Clears the bound authentication status. Request ```json
{
"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"
}

## 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)
Reads device configuration snapshots. Read Config (model) ```json
{
"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

Version	Date	Changes	Author	Checked	Remark
V1.0	2025-11-01	Initial release. Dedicated complete list for limited customers and users.	HX	LHL	N/A
V1.1 Preliminary	2026-04-14	Document maintained from Feishu/Larksuite to Gitbook	HX	LHL	N/A