5.2.10. Z/IP Command Class, version 2

The Z/IP Command Class is a special Command Class intended for encapsulation of Z-Wave commands in IP packets.

Z/IP Packets may be exchanged between IP hosts running over physical layers such as Ethernet or WiFi.

5.2.10.1. Security considerations

This Command Class is used to encapsulate Z-Wave Commands in an IP network. A Z/IP Gateway will forward some of the encapsulated Z-Wave commands into the Z-Wave Network.

The Z-Wave nodes may use encryption to protect the integrity of the Z-Wave network (refer to Security 0 and Security 2 Command Classes). IP nodes should always assume to be in a hostile network and support an encryption mechanism, such as DTLS.

If an IP node implements IP LAN security (DTLS or equivalent):

\requirement{CC:0023.02.00.41.001}{0}

  • Z/IP Packet received via secure IP channel MUST be accepted and a Z/IP Gateway MUST forward the optional Z-Wave Command in the Z-Wave network.

  • Z/IP Packet received via non-secure IP channel:

\requirement{CC:0023.02.00.41.002}{0} \requirement{CC:0023.02.00.41.003}{4} - Z/IP Discovery Command Class MUST be accepted. - All other encapsulated Command Classes MUST be discarded.

If an IP node does not implement IP LAN security (DTLS or equivalent):

\requirement{CC:0023.02.00.41.004}{0}

  • All Z/IP Packet received via non-secure IP channel MUST be accepted.

\requirement{CC:0023.02.00.43.001}{0}

If the Z/IP Command Class interface is used to communicate between applications within the same machine, the use of DTLS is OPTIONAL.

\requirement{CC:0023.02.00.41.005}{0}

If the Z/IP Command Class interface is used to communicate between applications across an IP network, the use of DTLS is REQUIRED.

5.2.10.2. Interoperability considerations

\requirement{CC:0023.02.00.32.001}{0}

Any Z-Wave Command Class SHOULD be sent encapsulated in a Z/IP Packet if a transmission takes place in an IP network.

\requirement{CC:0023.02.00.31.001}{0}

Commands part of this Command Class MUST NOT be encapsulated in a Z/IP Packet Command.

5.2.10.3. Z/IP Packet Command

IP->UDP:4123->Z/IP Packet Command->Optional Z-Wave command

IP->UDP:41230->DTLS->Z/IP Packet Command->Optional Z-Wave command

\requirement{CC:0023.02.02.11.001}{0}

A Z/IP Packet Command MUST be carried in a UDP packet, using destination port 4123 when no LAN security is used.

\requirement{CC:0023.02.02.11.002}{0}

A Z/IP Packet Command MUST be carried in a UDP packet, using destination port 41230 when DLTS is used.

\requirement{CC:0023.02.02.11.003}{0}

A node returning an answer to a Z/IP Packet (Ack/NAck Response) MUST swap the UDP source and destination ports.

The Z/IP Packet may carry a Z-Wave command or it may be used to communicate positive or negative acknowledgement for the delivery of another Z/IP Packet.

\requirement{CC:0023.02.02.11.004}{0}

The Z/IP Packet MUST NOT be used for transmission between native Z-Wave nodes. The Z/IP Packet is intended for transport of encapsulated Z-Wave commands inside IP packets in an IP environment.

For that reason, normal Z-Wave MAC layer frame size limitations do not apply to this command, however Z-Wave MAC Layer frame size and Z-Wave Transport Service Command Class size limitations apply to the Z-Wave Command field.

Table 5.149 Z/IP Packet Command

7

6

5

4

3

2

1

0

Command Class = COMMAND_CLASS_ZIP (0x23)

Command = COMMAND_ZIP_PACKET (0x02)

Ack

Request

Ack

Response

NAck

Response

(NAck flags)

Reserved

Waiting

Queue Full

Option Error

Header ext. included

Z-Wave Cmd included

More Information

Secure Origin

Reserved

Seq No

Res

Source End Point

Bit address

Destination End Point

Header extension 1 (Optional)

…

Header extension N (Optional)

Z-Wave Command 1 (Optional)

…

Z-Wave Command M (Optional)

\requirement{CC:0023.02.02.11.005}{0}

A receiving node MUST inspect the header flags in order to determine the offset to use for accessing the optional fields. If the packet contains invalid data, e.g. the ACK_RES and NACK_RES bits are both set to 1 or if the length of the extended header does not add up, a receiving node MUST ignore the packet.

Ack Request (1 bit)

\requirement{CC:0023.02.02.11.006}{0}

This flag signals that the receiving node MUST return an Ack or NAck message in response to the actual Z/IP Packet.

\requirement{CC:0023.02.02.11.007}{0}

This field MUST be encoded according to Table 5.150.

Table 5.150 Z/IP Packet::Ack Request Flag encoding

Value

Description

‘1’

Return Ack or NAck

‘0’

No confirmation needed

\requirement{CC:0023.02.02.11.008}{0}

If this flag is set to 1, the Z/IP Packet MUST contain a Z-Wave Command. A receiving node MUST discard the packet if this flag is set to 1 but no Z-Wave Command is included.

This field is intended for delivery acknowledgement for Z-Wave Commands encapsulated in Z/IP packets.

\requirement{CC:0023.02.02.12.001}{0}

Z-Wave link-level acknowledgement SHOULD always be used between Z-Wave nodes when Z-Wave is used as link layer.

\requirement{CC:0023.02.02.11.009}{0}

A Z/IP Gateway MUST return a ”NAck+Waiting” indication no later than 200ms after receiving an Ack Request if the Z-Wave Command is still being processed or pending delivery.

\requirement{CC:0023.02.02.13.001}{0}

A sending node that has requested an Ack and has waited for more than 300ms without receiving an Ack or NAck indication MAY conclude that the Z-Wave Command is lost and retransmit the Z/IP Packet.

\requirement{CC:0023.02.02.11.00A}{0}

In case of successful delivery to a Z-Wave node, a Z/IP Packet with Ack Response indication MUST be returned by the Z/IP Gateway upon reception of the Z-Wave Ack.

\requirement{CC:0023.02.02.11.00B}{0}

In case of successful delivery to a Z/IP node, the Z/IP node itself MUST return a Z/IP Packet with Ack Response indication.

Ack Response (1 bit)

\requirement{CC:0023.02.02.11.00C}{0}

This flag MUST be used to indicate that the destination has received the Z-Wave Command encapsulated in a preceding Z/IP packet.

\requirement{CC:0023.02.02.11.00D}{0}

This field MUST NOT be interpreted as a confirmation that the destination has accepted the application command carried in the Z-Wave Command field.

\requirement{CC:0023.02.02.11.00E}{0}

This field MUST be encoded according to Table 5.151.

\requirement{CC:0023.02.02.11.00F}{28}

Table 5.151 Z/IP Packet::Ack Response Flag encoding

value

Description

‘1’

This Z/IP Packet acknowledges a preceding packet that requested an Ack Response

‘0’

This Z/IP Packet does not acknowledge a preceding packet that requested an Ack Response.

A receiving node MUST inspect the NAck Response field

\requirement{CC:0023.02.02.11.010}{0}

If this field is set to 1, the Seq No field value MUST be the same as the Z/IP packet being acknowledged.

NAck Response (1 bit)

\requirement{CC:0023.02.02.11.011}{0}

This flag MUST be used to indicate that the destination has not (yet) received the Z-Wave Command encapsulated in a preceding Z/IP Packet.

\requirement{CC:0023.02.02.11.012}{0}

This field MAY be set to 1 by intermediate nodes such as a Z/IP Gateway. This field MUST be encoded according to Table 5.152.

\requirement{CC:0023.02.02.11.013}{20}

Table 5.152 Z/IP Packet::NAck Response Flag encoding

value

Description

‘1’

This Z/IP Packet negatively acknowledges a preceding packet that requested an Ack Response. (i.e. the Z-Wave Command was not delivered to the destination)

A receiving node MUST inspect the NAck flags fields.

‘0’

This field and the NAck flags fields may be ignored.

\requirement{CC:0023.02.02.11.014}{0}

If this field is set to 1, the Seq No field value MUST be the same as the Z/IP packet being negatively acknowledged.

If this field is set to 1 but none of the NAck flags field is set to 1, the Z-Wave Command was lost but no specific reason is provided.

(NAck flags) Waiting (1 bit)

\requirement{CC:0023.02.02.12.002}{0}

This flag is a companion flag to the NAck Response flag. It SHOULD be inspected only if the NAck Response flag field is set to 1 and SHOULD be ignored otherwise.

\requirement{CC:0023.02.02.11.015}{0}

This flag MUST be ignored if the Queue Full flag is set to 1.

\requirement{CC:0023.02.02.11.016}{0}

This flag MUST be used to indicate that the destination may have a long response time. i.e. the Z-Wave Command has not timed out yet and is pending delivery. This field MUST be encoded according to Table 5.153.

Table 5.153 Z/IP Packet::Waiting Flag encoding

value

Description

‘1’

Waiting: the preceding Z/IP Packet encapsulated Z-Wave Command is not yet delivered to the destination and delivery will be attempted later on

‘0’

Not waiting: the preceding Z/IP Packet encapsulated Z-Wave Command will not be delivered later on.

\requirement{CC:0023.02.02.13.002}{0} \requirement{CC:0023.02.02.12.003}{4} \requirement{CC:0023.02.02.11.017}{8}

An ”Expected Delay” Option MAY be returned by a Z/IP Gateway, indicating how long it should take before the final delivery acknowledgment status is known, refer to Section 5.2.13.2.1. A sending node SHOULD use this information to provide better user responsiveness. A default value of 90 seconds MUST be used by the sending node if no ”Expected delay” Option is provided.

A Z/IP ”NAck+Waiting” indication is returned for every packet that is queued up. If a sending node triggers to queue up three Z-Wave Commands, it will receive a ”NAck+Waiting” indication after each packet. It may be desirable to queue up three configuration commands if the intention is to perform a few configuration changes and allow a battery node to return to sleep.

\requirement{CC:0023.02.02.12.004}{4}

If a sending node wants to transfer larger amounts of data or commands, e.g. probing capabilities or downloading a new firmware image, it is RECOMMENDED to send a single Z/IP Packet using the More Information field to make the destination node stay awake. When a Z/IP Ack Response indication is returned to the sending node, it can start transferring packets at a higher rate.

\requirement{CC:0023.02.02.11.018}{0}

A Z/IP Gateway MUST return a ”NAck+Waiting” indication no later than 200ms after receiving an Ack Request indication if the Z-Wave Command is still pending delivery.

\requirement{CC:0023.02.02.11.019}{0}

If a message has been delayed for more than 60 seconds, an intermediate receiver, such as a Z/IP Gateway, MUST transmit a new ”NAck+Waiting” indication every 60 seconds to let the sending node know that it is still operational.

\requirement{CC:0023.02.02.13.003}{0}

A sending node waiting for more than 90 seconds after receiving a ”NAck+Waiting” indication MAY conclude that the Z-Wave Command is lost and retransmit a new Z/IP Packet.

\requirement{CC:0023.02.02.11.01A}{0}

A Z/IP Gateway issuing a ”NAck+Waiting” indication MUST subsequently issue an Ack Response indication when the Z-Wave Command has been delivered.

\requirement{CC:0023.02.02.11.01B}{0}

A Z/IP Gateway MUST return a Z/IP NAck Response indication if the Z-Wave Command delivery is aborted or not successful.

(NAck flag) Queue Full (1 bit)

\requirement{CC:0023.02.02.12.005}{0}

This flag is a companion flag to the NAck Response flag. It SHOULD be inspected only if the NAck Response flag is set to 1 and SHOULD be ignored otherwise.

\requirement{CC:0023.02.02.11.01C}{0}

This flag MUST be used by a Z/IP Gateway for packets targeting battery nodes, in a busy network, during bulk data transfers or route re-discovery.

\requirement{CC:0023.02.02.13.004}{0}

This flag MAY also be returned for always listening Z-Wave destinations.

\requirement{CC:0023.02.02.11.01D}{0}

A sending node MUST wait for at least 10 seconds before re-transmitting a new Z/IP Packet.

\requirement{CC:0023.02.02.11.01E}{0}

This flag MUST be returned by a Z/IP Gateway if there is no more room in the queue system used for delivering Commands into the Z-Wave network. This field MUST be encoded according to Table 5.154.

Table 5.154 Z/IP Packet::Queue Full Flag encoding

value

Description

‘1’

Queue is full: the preceding Z/IP Packet Command is discarded and will not be delivered to the destination

‘0’

Queue OK

(NAck flag) Option Error (1 bit)

\requirement{CC:0023.02.02.12.006}{0}

This flag is a companion flag to the NAck Response flag. It should only be inspected if the NAck Response flag is set to 1 and SHOULD be ignored otherwise.

\requirement{CC:0023.02.02.11.01F}{0}

This flag MUST be set to 1 if a critical option is not recognized by the receiving node and the entire Z/IP Packet was discarded.

\requirement{CC:0023.02.02.11.020}{0}

This flag MUST NOT be set to 1 if an elective option is not recognized by the receiving node. Elective options MUST be silently ignored by a receiving node.

Table 5.155 Z/IP Packet::Option Error Flag encoding

value

Description

‘1’

Option Error: A critical extension was not understood and the entire Z/IP Packet was discarded

‘0’

(no error)

\requirement{CC:0023.02.02.12.007}{0}

A node setting this flag to 1 SHOULD include the offending Option in the ”NAck+OptionError” indication returned to the originating node.

\requirement{CC:0023.02.02.11.021}{0}

A node receiving a ”NAck+OptionError” indication MUST NOT process the Z/IP Packet Options in the Header Extension field as it is only included for debugging purposes.

Header extension Included (1 bit)

This flag is used to indicate that a Header Extension field is included in the Z/IP Packet. Refer to the Header Extension field description below.

\requirement{CC:0023.02.02.11.022}{0}

This flag MUST be encoded according to Table 5.156.

Table 5.156 Z/IP Packet::Header Extension Included Flag encoding

value

Description

‘1’

Header Extension field MUST be included in the Z/IP Packet

‘0’

Header Extension field MUST NOT be included in the Z/IP Packet

Reserved

\requirement{CC:0023.02.02.11.023}{0}

This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node.

Z-Wave Command Included (1 bit)

This flag is used to indicate that a Z-Wave Command field is included in the Z/IP packet. Refer to the Z-Wave Command field description below.

\requirement{CC:0023.02.02.11.024}{0}

This flag MUST be encoded according to Table 5.157.

Table 5.157 Z/IP Packet::Z-Wave Command Included Flag encoding

value

Description

‘1’

Z-Wave Command field MUST be included in the Z/IP Packet

‘0’

Z-Wave Command field MUST NOT be included in the Z/IP Packet

\requirement{CC:0023.02.02.11.025}{0}

If a Z/IP Packet is received with payload length = 0 and the ”Z-Wave command included” bit set to 1, a receiving node MUST treat the Z/IP Packet as if the ”Z-Wave command included” bit was set to 0.

\requirement{CC:0023.02.02.11.04A}{0}

If receiving a Z/IP Command with the Ack Request field set to 1 and no Z-Wave Command included, a Z/IP Gateway MUST issue a NOP frame to the destination and return a Z/IP Packet with Ack Response if the destination acknowledged the NOP frames.

More Information (1 bit)

This flag is used to indicate the Z/IP Gateway that it should prevent a sleeping node from returning to sleep during the next minute.

\requirement{CC:0023.02.02.11.026}{0} \requirement{CC:0023.02.02.13.005}{8}

This flag MUST indicate that more Z/IP Packets with Z-Wave Commands will be subsequently transmitted. A sending node knowing that it will be sending more commands to the destination node MAY set this flag to 1.

\requirement{CC:0023.02.02.11.027}{0}

This flag MUST be encoded according to Table 5.158.

Table 5.158 Z/IP Packet::More Information Flag encoding

value

Description

‘1’

The Z/IP Gateway should keep the sleeping node awake

‘0’

The Z/IP Gateway should put the sleeping node to sleep

Secure Origin (1 bit)

This field indicates if the Z-Wave Command is to be treated securely.

\requirement{CC:0023.02.02.11.028}{0}

The value 1 MUST indicate that the Z-Wave Command MUST be treated securely (i.e. it was or will be sent using encryption in the Z-Wave network).

\requirement{CC:0023.02.02.11.029}{0}

The value 0 MUST indicate that the Z-Wave Command MUST NOT be treated securely. (i.e. it was or will be sent non-securely in the Z-Wave network)

\requirement{CC:0023.02.02.11.02A}{0}

A Z/IP Gateway forwarding the contents of an encrypted Z-Wave frame MUST set the Secure Origin flag to ‘1’.

\requirement{CC:0023.02.02.11.02B}{0}

A Z/IP Gateway forwarding the contents of a non-encrypted Z-Wave frame MUST set the Secure Origin flag to ‘0’.

\requirement{CC:0023.02.02.11.02C}{0}

A Z/IP Gateway MUST inspect the Secure Origin flag when forwarding a Z-Wave Command contained in a Z/IP Packet from an IP network to a Z-Wave network.

\requirement{CC:0023.02.02.11.02D}{0}

A Z/IP Gateway MUST NOT use secure communication via Z-Wave if this flag is set to ‘0’ and MUST use secure communication via Z-Wave if this flag is set to ‘1’.

Seq No (8 bits)

This field is used to identify Z/IP Packet duplicates or retransmissions.

\requirement{CC:0023.02.02.11.02E}{0}

This field MUST carry a unique sequence number. Each sequence number MUST be generated from an 8-bit counter that is incremented by 1 whenever a new sequence number is generated. When a node powers up, the sequence counter MUST be initialized to a random value.

\requirement{CC:0023.02.02.13.006}{0}

The counter MAY be shared with other Command Classes.

\requirement{CC:0023.02.02.11.02F}{0}

Retransmitted Z/IP packets MUST carry the same value as the original Z/IP Packet. A Z/IP Ack or NAck packet MUST carry the same Seq No value as the Z/IP packet being acknowledged.

\requirement{CC:0023.02.02.11.030}{0}

Multiple Z/IP Packets may be received in case of link-layer retransmissions. Z/IP Packet duplicates MUST be ignored by a receiving node.

Source End Point (7 bits)

This field is used to indicate the originating end point from which the Z-Wave Command was sent.

\requirement{CC:0023.02.02.11.031}{0}

This field MUST be in the range 0..127.

The Source End Point value 0 represents the Root Device. Refer to the Multi Channel Command Class for more details.

Bit address (1 bit)

This field is used to advertise if the destination End Point field is specified as a bit mask.

\requirement{CC:0023.02.02.11.032}{0}

The value 0 MUST indicate that the Destination End Point field is specified as a single End Point.

\requirement{CC:0023.02.02.11.033}{0}

The value 1 MUST indicate that the Destination End Point field is specified as a bit mask. Only destination end points 1..7 are bit addressable.

\requirement{CC:0023.02.02.11.034}{0}

Bit addressing MUST NOT be used if the encapsulated command is a request (requiring a reply from the destination).

Destination End Point (7 bits)

This field is used to indicate the destination End Point of the actual Z-Wave Command.

\requirement{CC:0023.02.02.11.035}{0}

If the Bit address field is set to 0, this field MUST carry a single End Point identifier value in the range 0..127.

\requirement{CC:0023.02.02.11.036}{0}

The value 0 MUST represent the Root Device. Values in the range 1..127 MUST represent an actual End Point.

\requirement{CC:0023.02.02.11.037}{0}

If the Bit address field is set to 1, this field MUST use the following encoding:

  • Bit 0 in the Destination End Point indicates if End Point 1 is a destination

  • Bit 1 in the Destination End Point indicates if End Point 2 is a destination

  • …

\requirement{CC:0023.02.02.11.038}{0}

The bit value 0 MUST be used to advertise that the corresponding End Point is not a destination.

The bit value 1 MUST be used to advertise that the corresponding End Point is a destination.

Header Extension (variable)

\requirement{CC:0023.02.02.11.039}{0}

This field is used for advertising additional Z/IP Packet Options that are necessary in certain cases. A Z/IP node MUST support and parse this field.

\requirement{CC:0023.02.02.11.03A}{0}

This field MUST be omitted if the Header extension Included field is set to 0.

\requirement{CC:0023.02.02.11.03B}{0}

If the Header Extension Included field is set to 1, this field MUST be formatted as follows:

Table 5.159 Header Extension Field

7

6

5

4

3

2

1

0

Header Extension Length

Z/IP Packet Option 1, 1

…

Z/IP Packet Option P, 1

…

Z/IP Packet Option 1, N

…

Z/IP Packet Option P, N

Header Extension Length (1 byte)

\requirement{CC:0023.02.02.11.03C}{0}

This field MUST indicate the combined length in bytes of the Z/IP Header Extension Length and all the Z/IP Packet Options included in the Z/IP Header Extension.

\requirement{CC:0023.02.02.11.03D}{0}

This field MUST be in the range 1..255. The length of the Header Extension field cannot exceed 255 bytes.

Z/IP Packet Option (variable)

\requirement{CC:0023.02.02.11.03E}{0}

Each Z/IP Packet Option MUST be treated parsed as a block using the following format:

Table 5.160 Z/IP Packet Option (variable) Field

7

6

5

4

3

2

1

0

Critical

Option Type

Option Length

Option Data 1 (Optional)

…

Option Data L (Optional)

\requirement{CC:0023.02.02.11.03F}{0}

A receiving node MUST accept receiving supported options in any order.

(Z/IP Packet Option) Critical (1 bit)

This field is used to indicate if the whole Z/IP Packet Command must be ignored if the option is not recognized by the receiving node.

\requirement{CC:0023.02.02.11.040}{0}

The value 0 MUST indicate that the option is elective and a receiving node MUST ignore this option only and continue processing the frame if the option is not recognized.

\requirement{CC:0023.02.02.11.041}{0}

The value 1 MUST indicate that the option is critical and a receiving node MUST discard the entire Z/IP Packet Command and return a Z/IP Packet Command with the Option Error flag set to 1 if the option is not recognized.

\requirement{CC:0023.02.02.11.042}{0}

An option MUST be considered as recognized even if:

  • The Option Length field is set to a greater value than expected

  • Reserved fields in the Option Data field are not set to 0.

\requirement{CC:0023.02.02.11.043}{0}

An option MUST NOT be considered as recognized when:

  • The Option Type field is set to an unknown value.

  • A field value in the Option Data field value which is out of expected range or seems to be using reserved values.

(Z/IP Packet Option) Option Type (7 bits)

This field is used to indicate which format to use for parsing the corresponding Option Data field. The list of defined Option Type is specified in Section 5.2.13.2.

\requirement{CC:0023.02.02.11.044}{0}

A receiving node MUST accept supported Z/IP Packet Options in any order.

(Z/IP Packet Option) Option Length (8 bits)

\requirement{CC:0023.02.02.11.045}{0}

This field MUST indicate the length of the corresponding Option Data field in bytes.

(Z/IP Packet Option) Option Data (L bytes)

\requirement{CC:0023.02.02.11.046}{0}

This field is used to carry the actual Option data. It MUST be parsed and interpreted using the corresponding Option Type field value.

\requirement{CC:0023.02.02.11.047}{0}

The size of this field in bytes MUST be according the corresponding Option Length field. This field MUST be omitted if the corresponding Option Length field is set to 0.

Z-Wave Command (M bytes)

\requirement{CC:0023.02.02.11.048}{0}

This field carries a complete Z-Wave command. This field MUST be formatted according to the corresponding command class as defined in Section 4, Section 3, Section 2 and in this specification.

\requirement{CC:0023.02.02.12.008}{0}

A sending Z/IP client SHOULD be aware that this command will be transmitted over a Z-Wave network and therefore respect the Z-Wave Command length limitations. A Z/IP Client SHOULD limit the length of this field to 45 bytes for non-S2 destination nodes and 117 bytes for S2 supporting nodes.

\requirement{CC:0023.02.02.11.049}{0}

This field MUST be omitted if the Z-Wave Cmd Included field is set to 0.