Skip to main content
Version: 1.0

Zigbee Through-RPC

The Zigbee Through-RPC Command Protocol exposes three RPC methods that allow external clients (HTTP, WebSocket, MQTT) to directly issue ZCL (Zigbee Cluster Library) commands to any Zigbee device on the network.

The following methods are available:

Common Parameters​

Addressing​

Zigbee.SendCommand supports three addressing modes. Zigbee.ReadAttr and Zigbee.WriteAttr only support unicast.

Unicast — send to a single device. Requires dst_addr and dst_ep. Waits for a ZCL response.

Group multicast — send to all devices that are members of a Zigbee group. Set dst_group to the group ID (0x0001–0xFFF7). Fire-and-forget, no ZCL response.

Bound devices (indirect) — send to all matching entries in the sending device's binding table. Set dst_group to 65535 (0xFFFF). Fire-and-forget, no ZCL response.

PropertyTypeDescription

dst_addr

uint16

16-bit short network address. Required for unicast. Mutually exclusive with dst_group.

dst_ep

uint8

Target endpoint number. Required for unicast, ignored for group/broadcast.

dst_group

uint16

Group ID (0x0001–0xFFF7) for group multicast, or 0xFFFF for indirect delivery via the binding table. Zigbee.SendCommand only. Mutually exclusive with dst_addr.

cluster

uint16

ZCL Cluster ID (e.g. 0x0006 for On/Off, 0x0008 for Level Control)

profile_id

uint16

Zigbee application profile ID. Optional, default 0x0104 (HA). Set to 0xC001 for the Shelly custom profile (endpoint 0xEF).

note

dst_addr is the 16-bit short address assigned to the device during Zigbee network joining. It is not the 64-bit IEEE/MAC address.

Payload Encoding​

All binary payloads and attribute values are passed as lowercase hex strings (e.g. "0100" = bytes 0x01 0x00). Multi-byte values follow little-endian byte order per the ZCL specification. Omit the field or pass "" for an empty payload.

Timeout​

All methods accept an optional timeout_ms parameter (default 10000 ms) that controls how long to wait for a response from the end device.

Methods​

Zigbee.SendCommand​

Send a raw ZCL cluster command to a Zigbee device.

Request​

PropertyTypeDescription

dst_addr

uint16

Short network address. Required for unicast, mutually exclusive with dst_group.

dst_ep

uint8

Target endpoint. Required for unicast, ignored for group/broadcast.

dst_group

uint16

Group ID or broadcast address. Optional, mutually exclusive with dst_addr.

cluster

uint16

ZCL Cluster ID

cmd

uint8

ZCL Command ID within the cluster

payload

string

Command payload as a hex string. Optional, default "". Maximum 255 bytes.

profile_id

uint16

Zigbee application profile ID. Optional, default 0x0104 (HA)

timeout_ms

uint32

Response timeout in milliseconds. Optional, default 10000. Only relevant for unicast.

Response​

PropertyTypeDescription

success

bool

true if the device acknowledged the command (unicast), or if the command was sent successfully (group/broadcast)

status

string

ZCL status code name (e.g. "ZB_ZCL_STATUS_SUCCESS")

Zigbee.ReadAttr​

Read a single ZCL attribute from a Zigbee device.

Request​

PropertyTypeDescription

dst_addr

uint16

Short Zigbee network address of the target device

dst_ep

uint8

Target endpoint number

cluster

uint16

ZCL Cluster ID

attr

uint16

Attribute ID to read

profile_id

uint16

Zigbee application profile ID. Optional, default 0x0104 (HA)

timeout_ms

uint32

Response timeout in milliseconds. Optional, default 10000

Response​

PropertyTypeDescription

success

bool

true if the attribute was read successfully; false on failure

type

uint8

ZCL attribute data type code (present on success)

value

string

Raw attribute value as a hex string (present on success)

len

uint8

Length of the value in bytes (present on success)

ZCL Data Types​

Common ZCL data type codes returned in the type field:

ValueDescription

0x10

Boolean — 1 byte

0x20

uint8 — 1 byte

0x21

uint16 — 2 bytes

0x23

uint32 — 4 bytes

0x29

int16 — 2 bytes

0x42

character string — variable length

Zigbee.WriteAttr​

Write a value to a single ZCL attribute on a Zigbee device.

Request​

PropertyTypeDescription

dst_addr

uint16

Short Zigbee network address of the target device

dst_ep

uint8

Target endpoint number

cluster

uint16

ZCL Cluster ID

attr

uint16

Attribute ID to write

type

uint8

ZCL attribute data type code — must match the ZCL-defined type of the target attribute

value

string

Value to write as a hex string

profile_id

uint16

Zigbee application profile ID. Optional, default 0x0104 (HA)

timeout_ms

uint32

Response timeout in milliseconds. Optional, default 10000

Response​

PropertyTypeDescription

success

bool

true if the write was acknowledged by the device

status

string

ZCL status code name (e.g. "ZB_ZCL_STATUS_SUCCESS")

Errors​

All methods return errors in the response body. Common failure scenarios:

ErrorCondition

503

"Zigbee task not running" — the Zigbee stack has not started or is not available on this device

400

"Missing required parameters" — one or more required fields are absent from the request

500

"Failed to queue command" / "Failed to queue read request" / "Failed to queue write request" — internal buffer allocation failure

When a command is sent successfully but the device responds with an error or does not respond in time, the HTTP status is 200 but the response body contains "success": false with the relevant ZCL status code:

{"success": false, "status": "ZB_ZCL_STATUS_FAIL"}

Examples​

Zigbee.SendCommand — On/Off/Toggle​

The On/Off cluster (cluster: 6) uses cmd to select the operation: 0 = off, 1 = on, 2 = toggle.

http://192.168.33.1/rpc/Zigbee.SendCommand?dst_addr=12345&dst_ep=1&cluster=6&cmd=1

Response

{
  "success": true,
  "status": "ZB_ZCL_STATUS_SUCCESS"
}

Zigbee.SendCommand — Move to Level (50%, 1s transition)​

The payload "800a00" encodes level 0x80 (128 = 50%) followed by transition time 0x000a (10 × 100ms = 1 second) in little-endian byte order.

http://192.168.33.1/rpc/Zigbee.SendCommand?dst_addr=12345&dst_ep=1&cluster=8&cmd=4&payload="800a00"

Response

{
  "success": true,
  "status": "ZB_ZCL_STATUS_SUCCESS"
}

Zigbee.SendCommand — Custom Profile (Shelly endpoint)​

When targeting the Shelly custom endpoint (dst_ep: 239 / 0xEF), set profile_id to 49153 (0xC001). Without this, the packet will be dropped by the target device because the APS profile does not match.

http://192.168.33.1/rpc/Zigbee.SendCommand?dst_addr=12345&dst_ep=239&cluster=64517&cmd=7&payload="ffff00"&profile_id=49153

Response

{
  "success": true,
  "status": "ZB_ZCL_STATUS_SUCCESS"
}

Zigbee.SendCommand — Group Multicast​

Turn off all devices in group 1. No ZCL response — fire-and-forget.

http://192.168.33.1/rpc/Zigbee.SendCommand?dst_group=1&cluster=6&cmd=0

Response

null

Zigbee.SendCommand — Bound Devices (Indirect)​

Turn off all bound devices via the binding table (dst_group: 65535). Fire-and-forget.

http://192.168.33.1/rpc/Zigbee.SendCommand?dst_group=65535&cluster=6&cmd=0

Response

null

Zigbee.SendCommand — Custom Timeout​

http://192.168.33.1/rpc/Zigbee.SendCommand?dst_addr=12345&dst_ep=1&cluster=6&cmd=1&timeout_ms=5000

Response

{
  "success": true,
  "status": "ZB_ZCL_STATUS_SUCCESS"
}

Zigbee.ReadAttr — On/Off State (cluster 6, attr 0)​

A response value of "01" means the light is currently on.

http://192.168.33.1/rpc/Zigbee.ReadAttr?dst_addr=12345&dst_ep=1&cluster=6&attr=0

Response

{
  "success": true,
  "type": 16,
  "value": "01",
  "len": 1
}

Zigbee.WriteAttr — Identify Time = 10s (cluster 3, attr 0)​

The value "0a00" encodes 10 seconds as a uint16 in little-endian byte order.

http://192.168.33.1/rpc/Zigbee.WriteAttr?dst_addr=12345&dst_ep=1&cluster=3&attr=0&type=33&value="0a00"

Response

{
  "success": true,
  "status": "ZB_ZCL_STATUS_SUCCESS"
}