# XBee
[Libraries]

Communicate with XBee (Zigbee) wireless modules via the Make Controller's serial port. More...

## Data Structures
struct | XBeePacket
| Representation of an XBee packet. More...
## Modules
| XBee Packet Types
| The different types of packet that can be used with the XBee subsystem.

## Functions
int | XBee_SetActive (int state)
| Controls the active state of the XBee subsystem.
int | XBee_GetActive ()
| Read the active state of the XBee subsystem.
int | XBee_Write (uchar *buffer, int count, int timeout)
| Write the specified number of bytes into the XBee unit.
int | XBee_Read (uchar *buffer, int count, int timeout)
| Read data from the Xbee unit waiting for the specified time.
int | XBee_GetReadable (void)
| Returns the number of bytes in the queue waiting to be read.
int | XBee_GetPacket (XBeePacket *packet, int timeout)
| Receive an incoming XBee packet.
int | XBee_SendPacket (XBeePacket *packet, int datalength)
| Send an XBee packet.
void | XBee_ResetPacket (XBeePacket *packet)
| Initialize a packet before reading into it.
int | XBee_IsBusyPacket (XBeePacket *packet)
| Checks to see if a packet is receiving a message.
void | XBeeConfig_SetPacketApiMode (int value)
| Set a module into packet API mode.
int | XBeeConfig_RequestPacketApiMode ()
| Query whether the module is in API mode.
void | XBee_CreateATCommandPacket (XBeePacket *packet, uint8 frameID, char *cmd, uint8 *params, uint8 datalength)
| A convenience function for creating an AT command packet.
int | XBeeConfig_RequestATResponse (char *cmd)
| Query the address of the module.
void | XBeeConfig_SetIO (int pin, int value)
| Configure the IO settings on an XBee module.
int | XBeeConfig_RequestIO (int pin)
| Query the configuration of an IO pin.
bool | XBee_CreateTX16Packet (XBeePacket *xbp, uint8 frameID, uint16 destination, uint8 options, uint8 *data, uint8 datalength)
| Create a packet to be transmitted with a 16-bit address.
bool | XBee_CreateTX64Packet (XBeePacket *xbp, uint8 frameID, uint64 destination, uint8 options, uint8 *data, uint8 datalength)
| Create a packet to be transmitted with a 64-bit address.
bool | XBee_ReadRX16Packet (XBeePacket *xbp, uint16 *srcAddress, uint8 *sigstrength, uint8 *options, uint8 **data, uint8 *datalength)
| Unpack the info from an incoming packet with a 16-bit address.
bool | XBee_ReadRX64Packet (XBeePacket *xbp, uint64 *srcAddress, uint8 *sigstrength, uint8 *options, uint8 **data, uint8 *datalength)
| Unpack the info from an incoming packet with a 64-bit address.
bool | XBee_ReadIO16Packet (XBeePacket *xbp, uint16 *srcAddress, uint8 *sigstrength, uint8 *options, int *samples)
| Unpack the info from an incoming IO packet with a 16-bit address.
bool | XBee_ReadIO64Packet (XBeePacket *xbp, uint64 *srcAddress, uint8 *sigstrength, uint8 *options, int *samples)
| Unpack the info from an incoming IO packet with a 64-bit address.
bool | XBee_ReadAtResponsePacket (XBeePacket *xbp, uint8 *frameID, char **command, uint8 *status, int *datavalue)
| Unpack the info from an incoming AT Command Response packet.
bool | XBee_ReadTXStatusPacket (XBeePacket *xbp, uint8 *frameID, uint8 *status)
| Unpack the info from TX Status packet.
void | XBeeConfig_WriteStateToMemory (void)
| Save the configuration changes you've made on the module to memory.
void | XBeeConfig_SetAddress (uint16 address)
| Set this module's address.
int | XBeeConfig_RequestAddress ()
| Query the address of the module.
void | XBeeConfig_SetPanID (uint16 id)
| Set this PAN (Personal Area Network) ID.
int | XBeeConfig_RequestPanID ()
| Query the PAN ID of the module.
void | XBeeConfig_SetChannel (uint8 channel)
| Set the module's channel.
int | XBeeConfig_RequestChannel ()
| Query the channel of the module.
void | XBeeConfig_SetSampleRate (uint16 rate)
| Set the rate at which the module will sample its IO pins.
int | XBeeConfig_RequestSampleRate ()
| Query the sample rate of the module.
void | XBee_IntToBigEndianArray (int value, uint8 *array)
| Convert a 32-bit integer into a big endian array of 4 unsigned 8-bit integers.

## Detailed Description

Communicate with XBee (Zigbee) wireless modules via the Make Controller's serial port.

XBee modules from MaxStream are small, cheap ($19 each), wireless RF (radio frequency) modules that can easily be used with the Make Controller Kit to create projects that require wireless communication. Check http://www.maxstream.net/products/xbee/xbee-oem-rf-module-zigbee.php for more info.

## Overview

XBee modules are ZigBee/IEEE 802.15.4 compliant and can operate in several modes:

- Transparent serial port. Messages in one side magically end up at the other endpoint. Great for enabling wireless communication between 2 Make Controllers.
- AT command mode. Send traditional AT commands to configure the module itself (as opposed to having the data go straight through via serial mode.
- Packet (API) mode. Lower level communication that doesn't have to wait for the module to be in AT command mode. Check the XBee Packet Types for a description of how these packets are laid out. Be sure to call XBeeConfig_SetPacketApiMode before trying to do anything in this mode.

The general idea is that you have one XBee module connected directly to your Make Controller Kit, and then any number of other XBee modules that can communicate with it in order to get information to and from the Make Controller. Or, several Make Controllers can each have an XBee module connected in order to communicate wirelessly among themselves.

XBee modules also have some digital and analog I/O right on them, which means you can directly connect sensors to the XBee modules which will both read the values and send them wirelessly. Check the XBee doc for the appropriate commands to send in order to set this up.

## API

The Make Controller API for working with the XBee modules makes use of the XBee Packet API. If you simply want to make use of the transparent serial port functionality, you can use the following functions: XBee_SetActive( ) XBee_Write( ); XBee_Read( ); XBee_GetReadable( );

Or if you want to handle setup etc. yourself, you don't need to deal with these - just hook up the module to your Make Controller and start reading and writing over the serial port.

Bytes sent in this way are broadcast to all XBee modules on the same chanel and with the same PAN ID. All similarly configured modules will receive all bytes sent. However, because these bytes are broadcast, there is no message reliability, so there's no guarantee that the messages will actually get there.

The XBee Packet API allows for much more flexible and powerful communication with the modules. With the Packet API you can send messages to a specific module, detect where messages came from, check signal strength, and most importantly packets are sent with a send / acknowledges / retry scheme which greatly increases message reliability.

Packet API uses commands to configure the XBee module itself, and then a handful of Zigbee specified packet types can be sent and received. See XBee Packet Types for details on these packet types.

The XBeeConfig_ functions are convenient wrappers around some of the most common AT commands you might want to send. For any of the other AT commands, check the XBee documentation and create them using XBee_CreateATCommandPacket( ). These will always be sent to the XBee module attached to the Make Controller. The XBee_ functions deal with sending and receiving messages to other XBee modules not connected to the Make Controller.

## Function Documentation

void XBee_CreateATCommandPacket | ( | XBeePacket * | packet,
|  | uint8 | frameID,
|  | char * | cmd,
|  | uint8 * | params,
|  | uint8 | datalength |
| ) |  |  |

A convenience function for creating an AT command packet.

As per the XBee spec, AT Command packets that want to set/write a value must have 4 bytes of data. Packets that query the value of an AT parameter send 0 bytes of data. Note that multi-byte data must be sent big-endian (most significant byte first) - see XBee_IntToBigEndianArray( ).

Make sure you're in API mode before creating & sending packets - see XBeeConfig_SetPacketApiMode( ). See the XBee documentation for the official list of AT commands that the XBee modules understand.

Parameters:

  | packet | The XBeePacket to create.
  | frameID | The frame ID for this packet that subsequent response/status messages can refer to.
  | cmd | The 2-character AT command.
  | params | A pointer to the buffer containing the data to be sent.
  | datalength | The number of bytes to send from the params buffer.

Example - Writing

        XBeePacket txPacket;
        uint8 params[4];
        XBee_IntToBigEndianArray( 1000, params ); // set our sampling rate to 1000
        XBee_CreateATCommandPacket( &txPacket, 0, "IR", &params, 4 ); // set the sampling rate of the IO pins
        XBee_SendPacket( &txPacket, 4 );

Example - Reading

        XBeePacket txPacket;
        XBee_CreateATCommandPacket( &txPacket, 0, "IR", NULL, 0 ); // query the sampling rate of the IO pins
        XBee_SendPacket( &txPacket, 0 );
        // then we'll receive a response packet

Definition at line 461 of file xbee.c.

bool XBee_CreateTX16Packet | ( | XBeePacket * | xbp,
|  | uint8 | frameID,
|  | uint16 | destination,
|  | uint8 | options,
|  | uint8 * | data,
|  | uint8 | datalength |
| ) |  |  |

Create a packet to be transmitted with a 16-bit address.

If the frameID is 0, you won't receive a TX Status message in response.

Parameters:

  | xbp | The XBeePacket to create.
  | frameID | The frame ID for this packet that subsequent response/status messages can refer to. Set to 0 for no response.
  | destination | The destination address for this packet. Broadcast Address: 0xFFFF.
  | options | The XBee options for this packet (0 if none).
  | data | A pointer to the data to be sent in this packet. Up to 100 bytes.
  | datalength | The number of bytes of data to be sent. Maximum 100 bytes.

Returns:
  True on success, false on failure.

Example

        XBeePacket txPacket;
        uint8 data[] = "ABC";
        XBee_CreateTX16Packet( &txPacket, 0x52, 0, 0, data, 3 );
        XBee_SendPacket( &txPacket, 3 );

Definition at line 569 of file xbee.c.

bool XBee_CreateTX64Packet | ( | XBeePacket * | xbp,
|  | uint8 | frameID,
|  | uint64 | destination,
|  | uint8 | options,
|  | uint8 * | data,
|  | uint8 | datalength |
| ) |  |  |

Create a packet to be transmitted with a 64-bit address.

Parameters:

  | xbp | The XBeePacket to create.
  | frameID | The frame ID for this packet that subsequent response/status messages can refer to. Set to 0 for no response.
  | destination | The destination address for this packet. Broadcast Address: 0xFFFF (same as 16b broadcast address)
  | options | The XBee options for this packet (0 if none).
  | data | A pointer to the data to be sent in this packet. Up to 100 bytes.
  | datalength | The number of bytes of data to be sent. Maximum 100 bytes.

Returns:
  True on success, false on failure.

Example

        XBeePacket txPacket;
        uint8 data[] = "ABCDE";
        XBee_CreateTX16Packet( &txPacket, 0, 0, 0, data, 5 );
        XBee_SendPacket( &txPacket, 5 );

Definition at line 602 of file xbee.c.

int XBee_GetActive | ( | void |  | ) |

Read the active state of the XBee subsystem.

Returns:
  An integer specifying the active state - 1 (active) or 0 (inactive).

Definition at line 146 of file xbee.c.

int XBee_GetPacket | ( | XBeePacket * | packet,
|  | int | timeout |
| ) |  |  |

Receive an incoming XBee packet.

A single call to this will continue to read from the serial port as long as there are characters to read or until it times out. If a packet has not been completely received, call it repeatedly with the same packet.

Clear out a packet before reading into it with a call to XBee_ResetPacket( )

Parameters:

  | packet | The XBeePacket to receive into.
  | timeout | The number of milliseconds to wait for a packet to arrive. Set this to 0 to return as soon as there are no characters left to process.

Returns:
  1 if a complete packet has been received, 0 if not.

See also:
  XBeeConfig_SetPacketApiMode( )

Todo:
  Probably need some way to reset the parser if there are no bytes for a while

Example

        // we're inside a task here...
        XBeePacket myPacket;
        XBee_ResetPacket( &myPacket );
        while( 1 )
        {
          if( XBee_GetPacket( &myPacket, 100 ) )
          {
            // process the new packet
            XBee_ResetPacket( &myPacket ); // then clear it out before reading again
          }
          Sleep( 10 );
        }

Definition at line 219 of file xbee.c.

int XBee_GetReadable | ( | void |  | ) |

Returns the number of bytes in the queue waiting to be read.

Returns:
  bytes in the receive queue.

void XBee_IntToBigEndianArray | ( | int | value,
|  | uint8 * | array |
| ) |  |  |

Convert a 32-bit integer into a big endian array of 4 unsigned 8-bit integers.

This is mostly useful for sending AT Command packets.

Parameters:

  | value | The value to convert.
  | array | An array of 4 unsigned 8-bit integers (uint8). Be sure you have 4.

Example
  see XBee_CreateATCommandPacket( ) for an example.

Definition at line 1145 of file xbee.c.

int XBee_IsBusyPacket | ( | XBeePacket * | packet | ) |

Checks to see if a packet is receiving a message.

Parameters:

  | packet | The XBeePacket to check

Returns:
  true if the packet is busy, false if it's free

Definition at line 355 of file xbee.c.

int XBee_Read | ( | uchar * | buffer,
|  | int | count,
|  | int | timeout |
| ) |  |  |

Read data from the Xbee unit waiting for the specified time.

Use XBee_GetReadable() to determine how many bytes are waiting to avoid waiting. It is assumed that the unit is in TRANSPARENT, not in PACKET API mode. To write to the unit using packets first set packet mode (using XBeeConfig_SetPacketApiMode) then use XBee_CreateXXXPacket() followed by XBee_SendPacket().

Parameters:

  | buffer | A pointer to the buffer to read into.
  | count | An integer specifying the maximum number of bytes to read.
  | timeout | Time in milliseconds to block waiting for the specified number of bytes. 0 means don't wait.

Returns:
  number of bytes read (>=0) or error <0 .

Definition at line 178 of file xbee.c.

bool XBee_ReadAtResponsePacket | ( | XBeePacket * | xbp,
|  | uint8 * | frameID,
|  | char ** | command,
|  | uint8 * | status,
|  | int * | datavalue |
| ) |  |  |

Unpack the info from an incoming AT Command Response packet.

In response to a previous AT Command message, the module will send an AT Command Response message.

Pass NULL into any of the parameters you don't care about.

Parameters:

  | xbp | The XBeePacket to read from.
  | frameID | A pointer to a uint64 that will be filled up with the 16-bit address of this packet.
  | command | A pointer to a uint8 that will be filled up with the signal strength of this packet.
  | status | A pointer to a uint8 that will be filled up with the XBee options for this packet.
  | datavalue | The value of the requested command.

Returns:
  True on success, false on failure.

Example

        XBeePacket rxPacket;
        if( XBee_GetPacket( &rxPacket, 0 ) )
        {
          uint8 frameID;
          char* command;
          uint8 status;
          int value = -1;
          if( XBee_ReadAtResponsePacket( &rxPacket, &frameID, command, &status, &value ) )
          {
            // then process the new packet here
            XBee_ResetPacket( &rxPacket ); // and clear it out before reading again
          }
        }

Definition at line 859 of file xbee.c.

bool XBee_ReadIO16Packet | ( | XBeePacket * | xbp,
|  | uint16 * | srcAddress,
|  | uint8 * | sigstrength,
|  | uint8 * | options,
|  | int * | samples |
| ) |  |  |

Unpack the info from an incoming IO packet with a 16-bit address.

When an XBee module has been given a sample rate, it will sample its IO pins according to their current configuration and send an IO packet with the sample data. This function will extract the sample info into an array of ints for you. There are 9 IO pins on the XBee modules, so be sure that the array you pass in has room for 9 ints.

Pass NULL into any of the parameters you don't care about.

Parameters:

  | xbp | The XBeePacket to read from.
  | srcAddress | A pointer to a uint16 that will be filled up with the 16-bit address of this packet.
  | sigstrength | A pointer to a uint8 that will be filled up with the signal strength of this packet.
  | options | A pointer to a uint8 that will be filled up with the XBee options for this packet.
  | samples | A pointer to an array of ints that will be filled up with the sample values from this packet.

Returns:
  True on success, false on failure.

See also:
  XBeeConfig_SetSampleRate( ), XBeeConfig_SetIOs( )

Example

        XBeePacket rxPacket;
        if( XBee_GetPacket( &rxPacket, 0 ) )
        {
          uint16 src;
          uint8 sigstrength;
          int samples[9];
          if( XBee_ReadIO16Packet( &rxPacket, &src, &sigstrength, NULL, samples ) )
          {
            // then process the new packet here
            XBee_ResetPacket( &rxPacket ); // and clear it out before reading again
          }
        }

Definition at line 752 of file xbee.c.

bool XBee_ReadIO64Packet | ( | XBeePacket * | xbp,
|  | uint64 * | srcAddress,
|  | uint8 * | sigstrength,
|  | uint8 * | options,
|  | int * | samples |
| ) |  |  |

Unpack the info from an incoming IO packet with a 64-bit address.

When an XBee module has been given a sample rate, it will sample its IO pins according to their current configuration and send an IO packet with the sample data. This function will extract the sample info into an array of ints for you. There are 9 IO pins on the XBee modules, so be sure that the array you pass in has room for 9 ints.

Pass NULL into any of the parameters you don't care about.

Parameters:

  | xbp | The XBeePacket to read from.
  | srcAddress | A pointer to a uint64 that will be filled up with the 16-bit address of this packet.
  | sigstrength | A pointer to a uint8 that will be filled up with the signal strength of this packet.
  | options | A pointer to a uint8 that will be filled up with the XBee options for this packet.
  | samples | A pointer to an array of ints that will be filled up with the sample values from this packet.

Returns:
  True on success, false on failure.

See also:
  XBeeConfig_SetSampleRate( ), XBeeConfig_SetIOs( )

Example

        XBeePacket rxPacket;
        if( XBee_GetPacket( &rxPacket, 0 ) )
        {
          uint64 src;
          uint8 sigstrength;
          int samples[9];
          if( XBee_ReadIO16Packet( &rxPacket, &src, &sigstrength, NULL, samples ) )
          {
            // then process the new packet here
            XBee_ResetPacket( &rxPacket ); // and clear it out before reading again
          }
        }

Definition at line 805 of file xbee.c.

bool XBee_ReadRX16Packet | ( | XBeePacket * | xbp,
|  | uint16 * | srcAddress,
|  | uint8 * | sigstrength,
|  | uint8 * | options,
|  | uint8 ** | data,
|  | uint8 * | datalength |
| ) |  |  |

Unpack the info from an incoming packet with a 16-bit address.

Pass NULL into any of the parameters you don't care about.

Parameters:

  | xbp | The XBeePacket to read from.
  | srcAddress | The 16-bit address of this packet.
  | sigstrength | The signal strength of this packet.
  | options | The XBee options for this packet.
  | data | A pointer that will be set to the data of this packet.
  | datalength | The length of data in this packet.

Returns:
  True on success, false on failure.

Example

        XBeePacket rxPacket;
        if( XBee_GetPacket( &rxPacket, 0 ) )
        {
          uint16 src;
          uint8 sigstrength;
          uint8* data;
          uint8 datalength;
          if( XBee_ReadRX16Packet( &rxPacket, &src, &sigstrength, NULL, &data, &datalength ) )
          {
            // then process the new packet here
            XBee_ResetPacket( &rxPacket ); // and clear it out before reading again
          }
        }

Definition at line 646 of file xbee.c.

bool XBee_ReadRX64Packet | ( | XBeePacket * | xbp,
|  | uint64 * | srcAddress,
|  | uint8 * | sigstrength,
|  | uint8 * | options,
|  | uint8 ** | data,
|  | uint8 * | datalength |
| ) |  |  |

Unpack the info from an incoming packet with a 64-bit address.

Pass NULL into any of the parameters you don't care about.

Parameters:

  | xbp | The XBeePacket to read from.
  | srcAddress | The 64-bit address of this packet.
  | sigstrength | The signal strength of this packet.
  | options | The XBee options for this packet.
  | data | A pointer that will be set to the data of this packet.
  | datalength | The length of data in this packet.

Returns:
  True on success, false on failure.

Example

        XBeePacket rxPacket;
        if( XBee_GetPacket( &rxPacket, 0 ) )
        {
          uint64 src;
          uint8 sigstrength;
          uint8* data;
          uint8 datalength;
          if( XBee_ReadRX64Packet( &rxPacket, &src, &sigstrength, NULL, &data, &datalength ) )
          {
            // then process the new packet here
            XBee_ResetPacket( &rxPacket ); // and clear it out before reading again
          }
        }

Definition at line 696 of file xbee.c.

bool XBee_ReadTXStatusPacket | ( | XBeePacket * | xbp,
|  | uint8 * | frameID,
|  | uint8 * | status |
| ) |  |  |

Unpack the info from TX Status packet.

When a TX is completed, the modules esnds a TX Status message. This indicates whether the packet was transmitted successfully or not. If the message you sent had a frameID of 0, a TX status message will not be generated.

Pass NULL into any of the parameters you don't care about.

Parameters:

  | xbp | The XBeePacket to read from.
  | frameID | A pointer to a uint8 that will be filled up with the frame ID of this packet.
  | status | A pointer to a uint8 that will be filled up with the status of this packet.

Returns:
  True on success, false on failure.

Example

        XBeePacket rxPacket;
        if( XBee_GetPacket( &rxPacket, 0 ) )
        {
          uint8 frameID;
          uint8 status;
          if( XBee_ReadTXStatusPacket( &rxPacket, &frameID, &status ) )
          {
            // then process the new packet here
            XBee_ResetPacket( &rxPacket ); // and clear it out before reading again
          }
        }

Definition at line 910 of file xbee.c.

void XBee_ResetPacket | ( | XBeePacket * | packet | ) |

Initialize a packet before reading into it.

Parameters:

  | packet | The XBeePacket to initialize.

See also:
  XBee_GetPacket( )

Definition at line 339 of file xbee.c.

int XBee_SendPacket | ( | XBeePacket * | packet,
|  | int | datalength |
| ) |  |  |

Send an XBee packet.

Use the following functions to create packets to be sent:

- XBee_CreateTX16Packet( ) - create a data packet to be sent out wirelessly with a 16-bit address
- XBee_CreateTX64Packet( ) - create a data packet to be sent out wirelessly with a 64-bit address
- XBee_CreateATCommandPacket( ) - create an AT command to configure an attached XBee module
  Parameters:

    | packet | The XBeePacket to send.
    | datalength | The length of the actual data being sent (not including headers, options, etc.)

  Returns:
    Zero on success.
  See also:
    XBeeConfig_SetPacketApiMode( )
  Example

          XBeePacket txPacket;
          uint8 data[] = "ABC"; // 3 bytes of data
          XBee_CreateTX16Packet( &txPacket, 0, 0, 0, data, 3 );
          XBee_SendPacket( &txPacket, 3 );

Definition at line 297 of file xbee.c.

int XBee_SetActive | ( | int | state | ) |

Controls the active state of the XBee subsystem.

Parameters:

  | state | Whether this subsystem is active or not

Returns:
  Zero on success.

Definition at line 103 of file xbee.c.

int XBee_Write | ( | uchar * | buffer,
|  | int | count,
|  | int | timeout |
| ) |  |  |

Write the specified number of bytes into the XBee unit.

It is assumed that the unit is in TRANSPARENT, not in PACKET API mode. To write to the unit using packets first set packet mode (using XBeeConfig_SetPacketApiMode) then use XBee_CreateXXXPacket() followed by XBee_SendPacket().

Parameters:

  | buffer | The block of bytes to write
  | count | The number of bytes to write
  | timeout | The time in ms to linger waiting to succeed (0 for no wait)

Returns:
  status

Definition at line 162 of file xbee.c.

int XBeeConfig_RequestAddress | ( | void |  | ) |

Query the address of the module.

This will block for up to a 1/2 second waiting for a response from the XBee module.

Returns:
  An integer corresponding to the address of the module, or negative number on failure.

Example

        int address = XBeeConfig_RequestAddress( );
        if( address >= 0 )
        {
          // then we have our address
        }

Definition at line 984 of file xbee.c.

int XBeeConfig_RequestATResponse | ( | char * | cmd | ) |

Query the address of the module.

This will block for up to a 1/2 second waiting for a response from the XBee module.

Returns:
  An integer corresponding to the address of the module, or negative number on failure.

Example

        int address = XBeeConfig_RequestAddress( );
        if( address >= 0 )
        {
          // then we have our address
        }

Definition at line 487 of file xbee.c.

int XBeeConfig_RequestChannel | ( | void |  | ) |

Query the channel of the module.

This will block for up to a 1/2 second waiting for a response from the XBee module.

Returns:
  An integer corresponding to the channel of the module, or negative number on failure.

Example

        int chan = XBeeConfig_RequestChannel( );
        if( chan >= 0 )
        {
          // then we have our channel
        }

Definition at line 1081 of file xbee.c.

int XBeeConfig_RequestIO | ( | int | pin | ) |

Query the configuration of an IO pin.

See XBeeConfig_SetIO( ) for the possible return values. This will block for up to a 1/2 second waiting for a response from the XBee module.

Returns:
  An integer corresponding to the config of the requested pin, or negative number on failure.

Example

        int pin = XBeeConfig_RequestIO( 0 ); // request the configuration of pin 0
        if( pin >= 0 )
        {
          // then we have our pin config
        }

Definition at line 539 of file xbee.c.

int XBeeConfig_RequestPacketApiMode | ( | void |  | ) |

Query whether the module is in API mode.

This will block for up to a 1/2 second waiting for a response from the XBee module.

Returns:
  0 if off, 1 if enabled, 2 if enabled with escape characters.

Example

        int mode = XBeeConfig_RequestPacketApiMode( );
        if( mode >= 0 )
        {
          // then we have our mode
        }

Definition at line 422 of file xbee.c.

int XBeeConfig_RequestPanID | ( | void |  | ) |

Query the PAN ID of the module.

This will block for up to a 1/2 second waiting for a response from the XBee module.

Returns:
  An integer corresponding to the PAN ID of the module, or negative number on failure.

Example

        int panid = XBeeConfig_RequestPanID( );
        if( panid >= 0 )
        {
          // then we have our pan id
        }

Definition at line 1031 of file xbee.c.

int XBeeConfig_RequestSampleRate | ( | void |  | ) |

Query the sample rate of the module.

This will block for up to a 1/2 second waiting for a response from the XBee module.

Returns:
  An integer corresponding to the sample rate of the module, or negative number on failure.

Example

        int rate = XBeeConfig_RequestSampleRate( );
        if( rate >= 0 )
        {
          // then we have our rate
        }

Definition at line 1129 of file xbee.c.

void XBeeConfig_SetAddress | ( | uint16 | address | ) |

Set this module's address.

As with the other XBeeConfig functions, make sure you're in API mode before trying to use this function.

Parameters:

  | address | An integer specifying the module's address.

Returns:
  True on success, false on failure.

See also:
  XBeeConfig_SetPacketApiMode( )

Example

        XBeeConfig_SetPacketApiMode( );
        XBeeConfig_SetAddress( 100 );
        XBeeConfig_WriteStateToMemory( );

Definition at line 961 of file xbee.c.

void XBeeConfig_SetChannel | ( | uint8 | channel | ) |

Set the module's channel.

The channel is one of 3 addressing options available to the module - the others are the PAN ID and the destination address. In order for modules to communicate with each other, the modules must share the same channel number. Default is 0x0C.

This value can have the range 0x0B - 0x1A for XBee modules, and 0x0C - 0x17 for XBee-Pro modules.

As with the other XBeeConfig functions, make sure you're in API mode before trying to use this function.

Parameters:

  | channel | A uint8 specifying the channel.

Returns:
  True on success, false on failure.

See also:
  XBeeConfig_SetPacketApiMode( )

Example

        XBeeConfig_SetPacketApiMode( );
        XBeeConfig_SetChannel( 0x0D );

Definition at line 1058 of file xbee.c.

void XBeeConfig_SetIO | ( | int | pin,
|  | int | value |
| ) |  |  |

Configure the IO settings on an XBee module.

IO pins can have one of 5 values:

- XBEE_IO_DISABLED
- XBEE_IO_ANALOGIN - Analog input (10-bit)
- XBEE_IO_DIGITALIN - Digital input
- XBEE_IO_DIGOUT_HIGH - Digital out high
- XBEE_IO_DIGOUT_LOW - Digital out low
  Parameters:

    | pin | An integer specifying which pin to configure. There are 9 IO pins (numbered 0-8) on the XBee modules. Only channels 0-7 can be analog inputs - channel 8 can only operate as a digital in or out.
    | value | An int specifying the behavior of this pin (options shown above).

  Example

          // set channel 0 to analog in
          XBeeConfig_SetIO( 0, XBEE_IO_ANALOGIN );

Definition at line 512 of file xbee.c.

void XBeeConfig_SetPacketApiMode | ( | int | value | ) |

Set a module into packet API mode.

XBee modules are in transparent serial port mode by default. This allows you to work with them via the packet API.

When setting this on, the XBee module needs to wait 1 second after sending the command sequence before it's ready to receive any AT commands - this function will block for that amount of time. Once you turn it off, you won't get any responses to packets you send the module until you turn packet mode on again.

Parameters:

  | value | 1 to turn packet mode on, 0 to turn it off.

Example

        MyTask( void * p )
        {
          XBeeConfig_SetPacketApiMode( 1 ); // initialize the module to be in API mode
          while( 1 )
          {
            // your task here.
          }
        }

Definition at line 382 of file xbee.c.

void XBeeConfig_SetPanID | ( | uint16 | id | ) |

Set this PAN (Personal Area Network) ID.

Only modules with matching PAN IDs can communicate with each other. Unique PAN IDs enable control of which RF packets are received by a module. Default is 0x3332.

As with the other XBeeConfig functions, make sure you're in API mode before trying to use this function.

Parameters:

  | id | A uint16 specifying the PAN ID.

Returns:
  True on success, false on failure.

See also:
  XBeeConfig_SetPacketApiMode( )

Example

        XBeeConfig_SetPacketApiMode( );
        XBeeConfig_SetPanID( 0x1234 );

Definition at line 1008 of file xbee.c.

void XBeeConfig_SetSampleRate | ( | uint16 | rate | ) |

Set the rate at which the module will sample its IO pins.

When the sample rate is set, the module will sample all its IO pins according to its current IO configuration and send a packet with the sample data. If this is set too low and the IO configuration is sampling too many channels, the RF module won't be able to keep up. You can also adjust how many samples are gathered before a packet is sent.

As with the other XBeeConfig functions, make sure you're in API mode before trying to use this function.

Parameters:

  | rate | A uint16 specifying the sample rate in milliseconds.

Returns:
  True on success, false on failure.

See also:
  XBeeConfig_SetIOs( ), XBeeConfig_SetPacketApiMode( )

Example

        XBeeConfig_SetPacketApiMode( );
        XBeeConfig_SetSampleRate( 0x14 );

Definition at line 1106 of file xbee.c.

void XBeeConfig_WriteStateToMemory | ( | void |  | ) |

Save the configuration changes you've made on the module to memory.

When you make configuration changes - setting the module to API mode, or configuring the sample rate, for example - those changes will be lost when the module restarts. Call this function to save the current state to non-volatile memory.

As with the other XBeeConfig functions, make sure you're in API mode before trying to use this function.

Returns:
  True on success, false on failure.

See also:
  XBeeConfig_SetPacketApiMode( )

Example

        XBeeConfig_SetPacketApiMode( );
        XBeeConfig_SetSampleRate( 100 );
        XBeeConfig_WriteStateToMemory( );

Definition at line 937 of file xbee.c.