Quelltext der Seite 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 [http://zwavepublic.com/specifications 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:
 <nowiki>
send REQUEST
receive RESPONSE
</nowiki>

=== Request to Network ===
Send a request to send into the ZWave network, e.g. a command to a node to switch on a lamp:
 <nowiki>
send REQUEST (with funcId)
receive RESPONSE
receive REQUEST (contains funcId, used to filter double receive)
</nowiki>

=== Request from Network ===
A node reports that e.g. the state of a lamp or switch has changed:
 <nowiki>
receive REQUEST
</nowiki>

== 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
[https://github.com/OpenZWave/open-zwave/blob/master/cpp/src/Defs.h OpenZWave]):
 <nowiki>
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)
</nowiki>
Request Frame to send data to a node containing funcId:
 <nowiki>
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)
</nowiki>
Request Frame received from the controller containing funcId:
 <nowiki>
FRAME = SOF length REQUEST FUNCTION funcId data checksum
	funcId (same id that was used when sending a request to the controller)
</nowiki>

=== Acknowledgement ===
 <nowiki>
ACK = 06
NACK = 15
CAN = 18
</nowiki>
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 ===
 <nowiki>
send REQUEST
receive ACK
</nowiki>

=== Receive a Frame (Request or Response) ===
 <nowiki>
receive FRAME
send ACK
</nowiki>

=== Send a Request with Checksum Error ===
 <nowiki>
send REQUEST
receive NACK
</nowiki>

=== Double send before ACK ===
 <nowiki>
send REQUEST
send REQUEST
receive CAN
</nowiki>

== 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:
 <nowiki>
send REQUEST REQUEST_NODE_INFO nodeId
	nodeId (id of target node)
</nowiki>
Response to request:
 <nowiki>
receive RESPONSE REQUEST_NODE_INFO RESULT
	RESULT
		SENT = 01
</nowiki>
Request for receiving a node info from a node:
 <nowiki>
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)		
</nowiki>

=== Example: Request node info from node 4 (Fibaro FGR-222) ===
 <nowiki>
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
</nowiki>

=== Example: Request node info from node 1 (the controller) ===
Fails because it has no associated NIF
 <nowiki>
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
</nowiki>

== 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:
 <nowiki>
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)
</nowiki>
Response to request:
 <nowiki>
receive RESPONSE ZW_SEND_DATA RESULT
	RESULT
		SENT = 01
</nowiki>
Additional request that follows the response that informs about transmit status:
 <nowiki>
receive REQUEST ZW_SEND_DATA funcId TX_STATUS ? ?
	TX_STATUS
		OK = 00
		NO_ACK = 01
		FAIL = 02
		NOT_IDLE = 03
		NOROUTE = 04
</nowiki>
Request for receiving a command (status report) from a node:
 <nowiki>
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)
</nowiki>
Structure of a command:
 <nowiki>
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)
</nowiki>

=== Example: Get BASIC value of node 4 (value is reported in an additional request) ===
 <nowiki>
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
</nowiki>


[[Kategorie:Z-Wave Components|CUL]]