Z-Wave-ZME UZB1 USB Dongle

This is a short introduction to the communication protocol between host and UZB USB Dongle. All two digit values are hex values. Also see public specifications

Protocol

This section describes the communication protocol in an abstract view.

Request to Controller

Send a request to the controller, e.g. get list of all nodes in the network:

send REQUEST
receive RESPONSE

Request to Network

Send a request to send into the ZWave network, e.g. a command to a node to switch on a lamp:

send REQUEST (with funcId)
receive RESPONSE
receive REQUEST (contains funcId, used to filter double receive)

Request from Network

A node reports that e.g. the state of a lamp or switch has changed:

receive REQUEST

Messages

Messages are sent to and received from the USB Dongle via a serial port (e.g. on /dev/ttyUSB0 on Linux) with these settings: 115200 bps, 8 bits, no parity, 1 stop bit.

Frame

Structure of a standard frame (for list of FUNCTION values see OpenZWave):

FRAME = SOF length TYPE FUNCTION data checksum
	SOF = 01 (start of frame)
	length (length of following data)
	TYPE
		REQUEST = 00
		RESPONSE = 01
	FUNCTION
		SERIAL_API_GET_INIT_DATA = 02 (get list of nodes in the network)
		APPLICATION_COMMAND_HANDLER = 04 (a node reports its status)
		ZW_SEND_DATA = 13 (send data to a node)
		ZW_GET_NODE_PROTOCOL_INFO = 41 (get node device class)
		ZW_APPLICATION_UPDATE = 49 (a node reports its device class and command classes, "NIF")
		ZW_REQUEST_NODE_INFO = 60 (request node info, ZW_APPLICATION_UPDATE follows)
		...
	data (payload data of frame)
	checksum (xor of frame bytes without first byte, negated)

Request Frame to send data to a node containing funcId:

FRAME = SOF length REQUEST FUNCTION data funcId checksum
	funcId = 01-ff (used to associate requests that are sent in response to requests that transfer data over the network)

Request Frame received from the controller containing funcId:

FRAME = SOF length REQUEST FUNCTION funcId data checksum
	funcId (same id that was used when sending a request to the controller)

Acknowledgement

ACK = 06
NACK = 15
CAN = 18

Each FRAME is acknowledged with an ACK if the CHECKSUM is ok and with a NACK if there is a checksum error. CAN means CANCEL and is sent when a next FRAME is sent while the other end expects an ACK.

Send a Request

send REQUEST
receive ACK

Receive a Frame (Request or Response)

receive FRAME
send ACK

Send a Request with Checksum Error

send REQUEST
receive NACK

Double send before ACK

send REQUEST
send REQUEST
receive CAN

Node Info

Request node device class and supported command classes. See 5.3.1.8 ApplicationControllerUpdate in "Z-Wave ZW0201/ZW0301 Appl. Prg. Guide v4.50"

Request for getting node info:

send REQUEST REQUEST_NODE_INFO nodeId
	nodeId (id of target node)

Response to request:

receive RESPONSE REQUEST_NODE_INFO RESULT
	RESULT
		SENT = 01

Request for receiving a node info from a node:

receive REQUEST APPLICATION_UPDATE STATUS nodeId length [BASIC GENERIC SPECIFIC CLASSES [CONTROL]]
	STATUS
		SUC_ID = 10
		DELETE_DONE = 20
		NEW_ID_ASSIGNED = 40
		ROUTING_PENDING = 80
		NODE_INFO_REQ_FAILED = 81
		NODE_INFO_REQ_DONE = 82
		NODE_INFO_RECEIVED = 84
	nodeId (id of source node)
	length (length of following data, may be 0)
	BASIC (basic device class)
	GENERIC (generic device class)
		CONTROLLER = 01
		STATIC_CONTROLLER = 02
		THERMOSTAT = 08
		SWITCH_BINARY = 10
		SWITCH_MULTILEVEL = 11
		SWITCH_TOGGLE = 13
		SENSOR_BINARY = 20
		SENSOR_MULTILEVEL = 21
		SENSOR_ALARM = a1
		...
	SPECIFIC (specific device class)
	CLASSES (list of supported command classes)
	CONTROL (list of command classes this device can control in other devices)
		MARK = ef (marks start of CONTROL list)		

Example: Request node info from node 4 (Fibaro FGR-222)

send SOF length=05 REQUEST=00 REQUEST_NODE_INFO=60 nodeId=04
receive ACK
receive SOF length=04 RESPONSE=01 REQUEST_NODE_INFO=60 SENT=01
send ACK
receive SOF length=1c REQUEST=00 APPLICATION_UPDATE=49 STATUS.NODE_INFO_RECEIVED=84 nodeId=04 length=16 BASIC=04 GENERIC=11 SPECIFIC=06 CLASSES=(CONFIGURATION=70 SWITCH_BINARY=25 ...) CONTROL=(MARK=ef SWITCH_BINARY=25 ...)
send ACK

Example: Request node info from node 1 (the controller)

Fails because it has no associated NIF

send SOF length=05 REQUEST=00 REQUEST_NODE_INFO=60 nodeId=01
receive ACK
receive SOF length=04 RESPONSE=01 REQUEST_NODE_INFO=60 SENT=01
send ACK
receive SOF length=06 REQUEST=00 APPLICATION_UPDATE=49 STATUS.FAILED=81 nodeId=00 length=00
send ACK

Commands

Commands are used to tell nodes in the network to switch on the light, open the blinds or lock a door. Commands are also used to report the current state of the nodes, e.g. if a light or switch is on or the current temperature in a room. See section 5.3.3.1 ZW_SendData and 5.3.1.5 ApplicationCommandHandler in "Z-Wave ZW0201/ZW0301 Appl. Prg. Guide v4.50". See section 3.2.1 in "Z-Wave Application Command Class Specification".

Request for sending a command to a node:

send REQUEST ZW_SEND_DATA nodeId COMMAND TX_OPTIONS funcId
	nodeId (id of target node)
	TX_OPTIONS (transmit options, bit-wise combination of the following)
		ACK = 01 (request transfer acknowledge from receiving node to ensure proper transmission)
		LOW_POWER = 02 (low transmit power (if node is closer than 2 meters)			
		AUTO_ROUTE = 04 (try to transmit via repeater nodes if direct transmission is not possible)
		NO_ROUTE = 10 (disable routing)			
		EXPLORE = 20 (support explorer frames for automatic fixing of the routing table)		
	funcId = id to identify the request that follows the response (see Protocol)

Response to request:

receive RESPONSE ZW_SEND_DATA RESULT
	RESULT
		SENT = 01

Additional request that follows the response that informs about transmit status:

receive REQUEST ZW_SEND_DATA funcId TX_STATUS ? ?
	TX_STATUS
		OK = 00
		NO_ACK = 01
		FAIL = 02
		NOT_IDLE = 03
		NOROUTE = 04

Request for receiving a command (status report) from a node:

receive REQUEST APPLICATION_COMMAND_HANDLER RX_STATUS nodeId COMMAND
	nodeId (id of source node)
	RX_STATUS (combination of the following flags)
		ROUTED_BUSY = 01
		LOW_POWER = 02 (received at low power)
		BROADCAST = 04 (received broadcast frame)
		MULTICAST = 08 (received multicast frame)

Structure of a command:

COMMAND = length CLASS ID data
	length (length of command without length itself)
	CLASS (command class 1 or 2 bytes)
		BASIC = 20
		CONFIGURATION = 70
		...
	ID (class specific command identifiers)
		GET
		SET
		REPORT
		...
	data (data of command)

Example: Get BASIC value of node 4 (value is reported in an additional request)

send SOF length=09 REQUEST=00 ZW_SEND_DATA=13 node=04 COMMAND=(length=02 BASIC=20 GET=02) TX_OPTIONS=05 funcId=37
receive ACK
receive SOF length=04 RESPONSE=01 ZW_SEND_DATA=13 RESULT.SENT=01
send ACK
receive SOF length=07 REQUEST=00 ZW_SEND_DATA=13 funcId=37 TX_STATUS.OK=00 00? 02?
send ACK
receive SOF length=09 REQUEST=00 APPLICATION_COMMAND_HANDLER=04 RX_STATUS=00 nodeId=04 COMMAND=(length=03 BASIC=20 REPORT=03 value=01)
send ACK