gitpan / xbee-api Goto Github PK

NAME
    XBee::API - Object-oriented Perl interface to Digi XBee module API mode.

EXAMPLE
    A basic example:

     use XBee::API;
     use Data::Dumper;
     my $api = XBee::API->new( { device => '/dev/ttyU0' } ) || die $!;
     die "Failed to transmit" unless $api->tx(
        { dest_h => 0, dest_l => 0 },
        'hello world!'
     );
     my $rx = $api->rx();
     die Dumper($rx);

SYNOPSIS
    XBee::API is a module designed to encapsulate the Digi XBee API in
    object- oriented Perl. This module expects to communicate with an XBee
    module using the API firmware via a serial (or serial over USB) device.

    This module is currently a work in progress and thus the API may change
    in the future.

LICENSE
    This module is licensed under the same terms as Perl itself.

CONSTANTS
    A single set of constants, ':xbee_flags', can be imported. These
    constants all represent various XBee flags, such as packet types and
    broadcast addresses. See the XBee datasheet for details. The following
    constants are available:

     XBEE_API_TYPE__MODEM_STATUS
     XBEE_API_TYPE__AT_COMMAND
     XBEE_API_TYPE__AT_COMMAND_QUEUE_PARAMETER_VALUE
     XBEE_API_TYPE__AT_COMMAND_RESPONSE
     XBEE_API_TYPE__REMOTE_COMMAND_REQUEST
     XBEE_API_TYPE__REMOTE_COMMAND_RESPONSE
     XBEE_API_TYPE__ZIGBEE_TRANSMIT_REQUEST
     XBEE_API_TYPE__EXPLICIT_ADDRESSING_ZIGBEE_COMMAND_FRAME
     XBEE_API_TYPE__ZIGBEE_TRANSMIT_STATUS
     XBEE_API_TYPE__ZIGBEE_RECEIVE_PACKET
     XBEE_API_TYPE__ZIGBEE_EXPLICIT_RX_INDICATOR
     XBEE_API_TYPE__ZIGBEE_IO_DATA_SAMPLE_RX_INDICATOR
     XBEE_API_TYPE__XBEE_SENSOR_READ_INDICATOR_
     XBEE_API_TYPE__NODE_IDENTIFICATION_INDICATOR
 
     XBEE_API_BROADCAST_ADDR_H
     XBEE_API_BROADCAST_ADDR_L
     XBEE_API_BROADCAST_NA_UNKNOWN_ADDR
 
     XBEE_API_TYPE_TO_STRING

    The above should be self explanatory (with the help of the datasheet).
    The constant "XBEE_API_TYPE_TO_STRING" is a hashref keyed by the numeric
    id of the packet type with the value being the constant name, to aid in
    debugging.

METHODS
  new
    Object constructor. Accepts a single parameter, a hashref of options.
    The following options are recognized:

   device
    Required. The device entry to open (to be passed to Device::SerialPort).
    Example:: /dev/ttyU0

   packet_timeout
    Optional, defaults to 20. Amount of time (in seconds) to wait for a read
    to complete. Smaller values cause the module to wait less time for a
    packet to be received by the XBee module. Setting this value too low
    will cause timeouts to be reported in situations where the network is
    "slow".

  at
    Send an AT command to the module. Accepts two parameters, the first is
    the AT command name (as two-character string), and the second is the
    expected data for that command (if any). See the XBee datasheet for a
    list of supported AT commands and expected data for each.

    Returns the frame ID sent for this packet. To retrieve the reply (if
    any), call rx().

  tx
    Sends a transmit request to the XBee. Accepts two parameters, the first
    is the endpoint address and the second the data to be sent.

    Endpoint addresses should be specified as a hashref containing the
    following keys:

    dest_h
        The high 32-bits of the destination address.

    dest_l
        The low 32-bits of the destination address.

    dest_na
        The destination network address.

    The meaning of these addresses can be found in the XBee datasheet. Note:
    In the future, a XBee::API::Node object will be an acceptable parameter.

    Return values depend on calling context. In scalar context, true or
    false will be returned representing transmission acknowledgement by the
    remote XBee device. In array context, the first return value is the
    delivery status (as set in the transmit status packet and documented in
    the datasheet), and the second is the actual transmit status packet (as
    a hashref) itself.

    No retransmissions will be attempted by this module, but the XBee device
    itself will likely attempt retransmissions as per its configuration (and
    subject to whether or not the packet was a "broadcast").

  rx
    Accepts no parameters. Receives a packet from the XBee module. This
    packet may be a transmission from a remote XBee node or a control packet
    from the local XBee module.

    If no packet is received before the timeout period expires, undef is
    returned.

    Returned packets will be as a hashref of the packet data, broken out by
    key for easy access. Note, as this module is a work in progress, not
    every XBee packet type is supported. Callers should check the "api_type"
    key to determine the type of the received packet.

CHANGES
  0.2, 20101206 - jeagle
    Initial release to CPAN.