Author image Mike Schilli
and 1 contributors

NAME

ZWave::Protocol - Protocol helpers for Z-Wave communication

SYNOPSIS

    use ZWave::Protocol;
    my $zw = ZWave::Protocol->new( device => "/dev/ttyUSB0" );

    $zw->connect();

    my $node_id = 3;
    my $state   = 255; # "on"

    $zw->payload_transmit( 0x13, $node_id, 
                   0x03, 0x20, 0x01, $state, 0x05 );

DESCRIPTION

ZWave::Protocol helps with the low-level details of the Z-Wave protocol, and offers support for packing packets with length headers and checksums, as well as connecting, sending, and receiving to the Z-Wave controller plugged into the USB port.

METHODS

new( device = "/dev/ttyUSB0" )>

Constructor, takes the device path to the plugged in Z-Wave controller.

connect()

Initialize a connection with the Z-Wave controller plugged into the USB port.

payload_transmit( $payload_byte1, $payload_byte2, ... )

A combination of send() and recv_ack().

payload_send( $payload_byte1, $payload_byte2, ... )

Wrap the given payload bytes into a package and send the result over to the USB port.

payload_recv()

Wait for a payload packet to arrive and receive it.

ack_recv()

Wait for an ACK to arrive from the recipient of the previous send().

ack_send()

Send an ACK back to acknowledge receiving a packet.

request_packet( $payload_byte1, $payload_byte2, ... )

Packs a sequence of payload bytes into a request packet, by adding a request header, packet length, and a trailing checksum. For example,

                0x00, 0x13, 0x03, 0x03, 0x20, 0x01, 0x00, 0x05

becomes

    0x01, 0x09, 0x00, 0x13, 0x03, 0x03, 0x20, 0x01, 0x00, 0x05, 0xc1

with 0x01 being the packet header, 0x09 being the packet length, and 0xc1 being the checksum, which is calculated over all bytes except the first one (see the ZWave protocol spec for details).

checksum( $byte1, $byte2, ... )

Calculate the Z-Wave checksum required at the end of a package.

ERROR HANDLING

If one of the methods above returns a non-true value, the underlying error can be obtained by calling

    print $zwave->error();

Additional insight can be obtained by bumping up the Log4perl level to $DEBUG in the CWave::Protocol or root categories.

TODO List

Retries

LEGALESE

Copyright 2015 by Mike Schilli, all rights reserved. This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

2015, Mike Schilli <m@perlmeister.com>