.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Device::XBee::API 3"
.TH Device::XBee::API 3 "2010-12-08" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Device::XBee::API \- Object\-oriented Perl interface to Digi XBee module API
mode.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
A basic example:
.PP
.Vb 9
\& use Device::XBee::API;
\& use Data::Dumper;
\& my $api = Device::XBee::API\->new( { device => \*(Aq/dev/ttyU0\*(Aq } ) || die $!;
\& die "Failed to transmit" unless $api\->tx(
\&    { dest_h => 0, dest_l => 0 },
\&    \*(Aqhello world!\*(Aq
\& );
\& my $rx = $api\->rx();
\& die Dumper($rx);
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Device::XBee::API is a module designed to encapsulate the Digi XBee \s-1API\s0 in
object-oriented Perl. This module expects to communicate with an XBee module
using the \s-1API\s0 firmware via a serial (or serial over \s-1USB\s0) device.
.PP
This module is currently a work in progress and thus the \s-1API\s0 may change in the
future.
.SH "LICENSE"
.IX Header "LICENSE"
This module is licensed under the same terms as Perl itself.
.SH "CONSTANTS"
.IX Header "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:
.PP
.Vb 10
\& 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
.Ve
.PP
The above should be self explanatory (with the help of the datasheet). The
constant \*(L"\s-1XBEE_API_TYPE_TO_STRING\s0\*(R" is a hashref keyed by the numeric id of the
packet type with the value being the constant name, to aid in debugging.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Object constructor. Accepts a single parameter, a hashref of options. The
following options are recognized:
.PP
\fIdevice\fR
.IX Subsection "device"
.PP
Required. The device entry to open (to be passed to Device::SerialPort).
Example:: /dev/ttyU0
.PP
\fIpacket_timeout\fR
.IX Subsection "packet_timeout"
.PP
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 \*(L"slow\*(R".
.SS "at"
.IX Subsection "at"
Send an \s-1AT\s0 command to the module. Accepts two parameters, the first is the \s-1AT\s0
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 \s-1AT\s0
commands and expected data for each.
.PP
Returns the frame \s-1ID\s0 sent for this packet. To retrieve the reply (if any), call
\&\fIrx()\fR.
.SS "tx"
.IX Subsection "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.
.PP
Endpoint addresses should be specified as a hashref containing the following
keys:
.IP "dest_h" 4
.IX Item "dest_h"
The high 32\-bits of the destination address.
.IP "dest_l" 4
.IX Item "dest_l"
The low 32\-bits of the destination address.
.IP "dest_na" 4
.IX Item "dest_na"
The destination network address.
.PP
The meaning of these addresses can be found in the XBee datasheet. Note: In
the future, a Device::XBee::API::Node object will be an acceptable parameter.
.PP
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.
.PP
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 \*(L"broadcast\*(R").
.SS "rx"
.IX Subsection "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.
.PP
If no packet is received before the timeout period expires, undef is returned.
.PP
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 \*(L"api_type\*(R" key to determine the
type of the received packet.
.SH "CHANGES"
.IX Header "CHANGES"
.SS "0.2, 20101206 \- jeagle"
.IX Subsection "0.2, 20101206 - jeagle"
Initial release to \s-1CPAN\s0.