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:

• Zigbee.SendCommand — send a raw ZCL cluster command
• Zigbee.ReadAttr — read a ZCL attribute value
• Zigbee.WriteAttr — write a ZCL attribute value

Common Concepts

Addressing

Every method requires identifying the target Zigbee device by its network address and endpoint:

Property	Type	Description
dst_addr	uint16	16-bit Zigbee short network address of the target device
dst_ep	uint8	Endpoint number on the target device
cluster	uint16	ZCL Cluster ID (e.g. 6 for On/Off, 8 for Level Control)

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

Property	Type	Description
dst_addr	uint16	Short Zigbee network address of the target device
dst_ep	uint8	Target endpoint number
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.
timeout_ms	uint32	Response timeout in milliseconds. Optional, default 10000

Response

Property	Type	Description
success	bool	true if the device acknowledged the command
status	string	ZCL status code name (e.g. "ZB_ZCL_STATUS_SUCCESS")

Zigbee.ReadAttr

Read a single ZCL attribute from a Zigbee device.

Request

Property	Type	Description
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
timeout_ms	uint32	Response timeout in milliseconds. Optional, default 10000

Response

Property	Type	Description
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:

Value	Description
16 (0x10)	Boolean — 1 byte
32 (0x20)	uint8 — 1 byte
33 (0x21)	uint16 — 2 bytes
35 (0x23)	uint32 — 4 bytes
41 (0x29)	int16 — 2 bytes
66 (0x42)	character string — variable length

Zigbee.WriteAttr

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

Request

Property	Type	Description
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
timeout_ms	uint32	Response timeout in milliseconds. Optional, default 10000

Response

Property	Type	Description
success	bool	true if the write was acknowledged by the device
status_str	string	ZCL status code name (e.g. "ZB_ZCL_STATUS_SUCCESS")

note

When a device times out or returns a ZCL-level error, the response body will be {"success": false, "status": "..."} with the relevant ZCL status code name.

Examples

Zigbee.SendCommand — On/Off/Toggle

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

Turn On (cmd: 1)

Zigbee.SendCommand HTTP GET Request

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

Zigbee.SendCommand Curl Request

curl -X POST -d '{"id":1,"method":"Zigbee.SendCommand","params":{"dst_addr":12345,"dst_ep":1,"cluster":6,"cmd":1}}' http://${SHELLY}/rpc

Zigbee.SendCommand Mos Request

mos --port ${PORT} call Zigbee.SendCommand '{"dst_addr":12345,"dst_ep":1,"cluster":6,"cmd":1}'

Response

Zigbee.SendCommand HTTP GET Response

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

Zigbee.SendCommand Curl Response

{
  "id": 1,
  "params": {
    "success": true,
    "status": "ZB_ZCL_STATUS_SUCCESS"
  }
}

Zigbee.SendCommand Mos Response

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

Turn Off (cmd: 0)

Zigbee.SendCommand HTTP GET Request

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

Zigbee.SendCommand Curl Request

curl -X POST -d '{"id":1,"method":"Zigbee.SendCommand","params":{"dst_addr":12345,"dst_ep":1,"cluster":6,"cmd":0}}' http://${SHELLY}/rpc

Zigbee.SendCommand Mos Request

mos --port ${PORT} call Zigbee.SendCommand '{"dst_addr":12345,"dst_ep":1,"cluster":6,"cmd":0}'

Response

Zigbee.SendCommand HTTP GET Response

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

Zigbee.SendCommand Curl Response

{
  "id": 1,
  "params": {
    "success": true,
    "status": "ZB_ZCL_STATUS_SUCCESS"
  }
}

Zigbee.SendCommand Mos Response

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

Toggle (cmd: 2)

Zigbee.SendCommand HTTP GET Request

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

Zigbee.SendCommand Curl Request

curl -X POST -d '{"id":1,"method":"Zigbee.SendCommand","params":{"dst_addr":12345,"dst_ep":1,"cluster":6,"cmd":2}}' http://${SHELLY}/rpc

Zigbee.SendCommand Mos Request

mos --port ${PORT} call Zigbee.SendCommand '{"dst_addr":12345,"dst_ep":1,"cluster":6,"cmd":2}'

Response

Zigbee.SendCommand HTTP GET Response

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

Zigbee.SendCommand Curl Response

{
  "id": 1,
  "params": {
    "success": true,
    "status": "ZB_ZCL_STATUS_SUCCESS"
  }
}

Zigbee.SendCommand Mos 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.

Zigbee.SendCommand HTTP GET Request

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

Zigbee.SendCommand Curl Request

curl -X POST -d '{"id":1,"method":"Zigbee.SendCommand","params":{"dst_addr":12345,"dst_ep":1,"cluster":8,"cmd":4,"payload":"800a00"}}' http://${SHELLY}/rpc

Zigbee.SendCommand Mos Request

mos --port ${PORT} call Zigbee.SendCommand '{"dst_addr":12345,"dst_ep":1,"cluster":8,"cmd":4,"payload":"800a00"}'

Response

Zigbee.SendCommand HTTP GET Response

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

Zigbee.SendCommand Curl Response

{
  "id": 1,
  "params": {
    "success": true,
    "status": "ZB_ZCL_STATUS_SUCCESS"
  }
}

Zigbee.SendCommand Mos Response

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

Zigbee.SendCommand — Custom Timeout

Zigbee.SendCommand HTTP GET Request

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

Zigbee.SendCommand Curl Request

curl -X POST -d '{"id":1,"method":"Zigbee.SendCommand","params":{"dst_addr":12345,"dst_ep":1,"cluster":6,"cmd":1,"timeout_ms":5000}}' http://${SHELLY}/rpc

Zigbee.SendCommand Mos Request

mos --port ${PORT} call Zigbee.SendCommand '{"dst_addr":12345,"dst_ep":1,"cluster":6,"cmd":1,"timeout_ms":5000}'

Response

Zigbee.SendCommand HTTP GET Response

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

Zigbee.SendCommand Curl Response

{
  "id": 1,
  "params": {
    "success": true,
    "status": "ZB_ZCL_STATUS_SUCCESS"
  }
}

Zigbee.SendCommand Mos 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.

Zigbee.ReadAttr HTTP GET Request

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

Zigbee.ReadAttr Curl Request

curl -X POST -d '{"id":1,"method":"Zigbee.ReadAttr","params":{"dst_addr":12345,"dst_ep":1,"cluster":6,"attr":0}}' http://${SHELLY}/rpc

Zigbee.ReadAttr Mos Request

mos --port ${PORT} call Zigbee.ReadAttr '{"dst_addr":12345,"dst_ep":1,"cluster":6,"attr":0}'

Response

Zigbee.ReadAttr HTTP GET Response

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

Zigbee.ReadAttr Curl Response

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

Zigbee.ReadAttr Mos 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.

Zigbee.WriteAttr HTTP GET Request

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

Zigbee.WriteAttr Curl Request

curl -X POST -d '{"id":1,"method":"Zigbee.WriteAttr","params":{"dst_addr":12345,"dst_ep":1,"cluster":3,"attr":0,"type":33,"value":"0a00"}}' http://${SHELLY}/rpc

Zigbee.WriteAttr Mos Request

mos --port ${PORT} call Zigbee.WriteAttr '{"dst_addr":12345,"dst_ep":1,"cluster":3,"attr":0,"type":33,"value":"0a00"}'

Response

Zigbee.WriteAttr HTTP GET Response

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

Zigbee.WriteAttr Curl Response

{
  "id": 1,
  "params": {
    "success": true,
    "status_str": "ZB_ZCL_STATUS_SUCCESS"
  }
}

Zigbee.WriteAttr Mos Response

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