free_frame_id_func Optional code references to functions used to allocate and free frame IDs. If both are specified they will be called in place of the internal frame ID tracking functions allowing the user more control over how frame IDs are generated. The alloc_frame_id_func will be called when a new frame ID is needed and will be passed as a parameter the reference to the Device:XBee::API object and must return an integer between 1 and 255 inclusive. The free_frame_id_func will be called when the reply frame is received and the frame ID is no longer needed and will be passed as parameters a reference to the Device::XBee::API obect and the frame ID to be freed.
See auto_reuse_frame_id for details on how this module uses frame IDs.
api_mode_escape
Optional. If set to a true value, the module will automatically escape
outgoing data and un-escape incoming data for use with XBee API mode 2.
Defaults to false.
See the XBee datasheet for details on API mode 2 and escaped characters.
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. This method does not wait for
a reply from the XBee, as the expected reply is dependent on the AT
command sent. To retrieve the reply (if any), call one of the rx
methods.
If no reply is expected, the caller should immediately free the returned
frame ID via free_frame_id to prevent frame ID leaks.
remote_at
Send an AT command to a remote module. Accepts three parameters: a
hashref with endpoint addresses, command options, frame_id; the AT
command name (as two-character string); and the third as the expected
data for that command (if any). See the XBee datasheet for a list of
supported AT commands and expected data for each.
Endpoint addresses should be specified as a hashref containing the
following keys:
sh The high 32-bits of the destination address.
sl The low 32-bits of the destination address.
na The destination network address.
disable_ack
If included ack is disabled
apply_changes
If included changes applied immediate, if missing an AC command must
be sent to apply changes
extended_xmit_timeout
If included the exteded transmission timeout is used
Returns the frame ID sent for this packet. To retrieve the reply (if
any), call one of the rx methods. If no reply is expected, the caller
should immediately free the returned frame ID via free_frame_id to
prevent frame ID leaks.
tx
Sends a transmit request to the XBee. Accepts three parameters, the
first is the endpoint address, the second is a scalar containing the
data to be sent, and the third is an optional flag (known as the async
flag) specifying whether or not the method should wait for an
acknowledgement from the XBee.
Endpoint addresses should be specified as a hashref containing the
following keys:
sh The high 32-bits of the destination address.
sl The low 32-bits of the destination address.
na The destination network address. If this is not specified, it will
default to XBEE_API_BROADCAST_NA_UNKNOWN_ADDR.
If both sh and sl are missing or the parameter is undefined,, they will
default to XBEE_API_BROADCAST_ADDR_H and XBEE_API_BROADCAST_ADDR_L.
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.
If the async flag is not set, the method will wait for an
acknowledgement packet from the XBee. 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.
If the async flag is set, the method will not wait for an
acknowledgement packet and the tx frame ID will be returned. The caller
will need to then receive the transmit status packet (via one of the rx
methods) and free the frame ID (via free_frame_id) manually.
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
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. When possible, packed
integers will be unpacked into the "data_as_int" key. If no packed
integer is found this key will not be present. If unpacking is not
possible (due to an unknown packet type, etc), the value will be undef.
Accepts a single parameter, a flag indicating the received frame ID
should NOT be freed automatically. See rx_frame_id for why you might
want to use this flag (generally, cases when you expect multiple packets
to arrive with the same frame ID).
rx_frame_id
Like rx but only returns the packet with the requested frame ID number
and then frees that frame ID. If no packet with the specified frame ID
is received within the object's configured packet_timeout time, undef
will be returned. Any other packets received will be enqueued for later
processing by another rx function call.
Accepts two parameters, the first being the desired frame ID and the
second a flag denoting that the frame ID should NOT be automatically
freed. In cases where multiple frames with the same ID are expected to
be returned (such as after an AT ND command), it is preferable to set
this flag to a true value and continue to call rx_frame_id until undef
is returned, and then free the ID via free_frame_id.
discover_network
Performs a network node discovery via the ND 'AT' command. Blocks until
no replies have been received in packet_timeout seconds.
node_info
known_nodes
Returns a hashref of all known nodes indexed by their full serial number
(i.e. $node->{sh} . '_' . $node->{sl}). Nodes that haven't been heard
from in the configured node_forget_time will be automatically removed
from this list if they've not been heard from in that time. Nodes are
added to that list when a message is received from them or a
discover_network call has been made.
Note, the age-out mechanism may be susceptable to stepping of the system
clock.EXAMPLES Miscellaneous code examples follow.
Fetch modem baud rage
use Device::SerialPort;
use Device::XBee::API;
# From XBee datasheet pg 73.
my @baud_rate_table = (
1200,
2400,
4800,
9600,
19200,
38400,
57600,
115200
);
# Configure the serial port
my $serial_port_device = Device::SerialPort->new( '/dev/ttyU0' )
|| die $!;
$serial_port_device->baudrate( 9600 );
$serial_port_device->databits( 8 );
$serial_port_device->stopbits( 1 );
$serial_port_device->parity( 'none' );
$serial_port_device->read_char_time( 0 );
$serial_port_device->read_const_time( 1000 );
# Create the API object
my $api = Device::XBee::API->new( { fh => $serial_port_device } )
|| die $!;
# Send the BD API command
my $at_frame_id = $api->at( 'BD' );
die "Transmit failed" unless $at_frame_id;
# Receive the reply
my $rx = $api->rx_frame_id( $at_frame_id );
die "No reply received" if !$rx;
if ( $rx->{status} != 0 ) {
die "API error" if $rx->{is_error};
die "Invalid command" if $rx->{is_invalid_command};
die "Invalid parameter" if $rx->{is_invalid_parameter};
die "Unknown error";
}
my $baud_rate = $baud_rate_table[ $rx->{data_as_int} ];
if ( !$baud_rate ) {
$baud_rate = $rx->{data_as_int};
}
print "Modem baud rate is $baud_rate bps.\n";CHANGES 0.7, 20130330 - jeagle Add ability to allow users to specify their own frame allocation routines.
Update API mode 2 with latest version from jdodgen
0.6, 20120624 - jeagle
Update documentation.
Add support for API mode 2 escapes. Needs testing.
Add constant for the "BD" baud rate table.
0.5, 20120401 - jeagle
Add support for Win32::SerialPort to enable Windows support. (Thanks
Jerry)
Fix issue with tx() in async mode. (Thanks Vicente)
Add support for "explicit rx indicator" packets. (Thanks Vicente)
0.4, 20110831 - jeagle
Fix packet timeout bug reported by Dave S.
Replace call to die() in __data_to_int with return undef, update docs to
reflect this.
0.3, 20110621 - jeagle, jdodgen
Change from internal Device::SerialPort wrapper to accepting an fh.
Add asynchronous support to tx and add some helpful methods to support
it.
Handle more command types (remote AT, ZigBee IO, node identification).
Add an option to re-use frame IDs under high tx load.
Many more changes!
0.2, 20101206 - jeagle
Initial release to CPAN.