- All orders placed from 12/30/2014 at 9PM (CET) onwards will be billed dated 2015 -
libelium
  • rss
  • flickr
  • instagram
  • twitter
  • facebook
  • youtube

Documentation: XBee for Raspberry Pi Tutorial

Contents:

Introduction

Ingredients:

NOTE: If you don't have a Raspberry Pi you can get one buying a Raspberry Pi Starter Kit.

Difficulty: Medium -medium

Preparation Time: 45 minutes

xbee_shield
 

NOTE: All the code examples in this tutorial use the arduPi library. You can see the documentation and download the library here.

Steps Index

Steps Index:

  1. A simple example.
  2. Addressing.
  3. Configuring the XBee module.
  4. Using Series 2 ZB XBee's.
    • If a module's DH is 0 and its DL is less than 0xFFFF (i.e. 16 bits), data transmitted by that module will be received by any module whose 16-bit address MY parameter equals DL.
    • If DH is 0 and DL equals 0xFFFF, the module's transmissions will be received by all modules.
    • If DH is non-zero or DL is greater than 0xFFFF, the transmission will only be received by the module whose serial number equals the transmitting module's destination address (i.e. whose SH equals the transmitting module's DH and whose SL equals its DL).
    • Selects a channel and PAN ID (both 64-bit and 16-bit) to start the network
    • Can allow routers and end devices to join the network
    • Can assist in routing data
    • Cannot sleep--should be mains powered.
    • Must join a ZigBee PAN before it can transmit, receive, or route data
    • After joining, can allow routers and end devices to join the network
    • After joining, can assist in routing data
    • Cannot sleep--should be mains powered.
    • Must join a ZigBee PAN before it can transmit or receive data
    • Cannot allow devices to join the network
    • Must always transmit and receive RF data through its parent. Cannot route data.
    • Can enter low power modes to conserve power and can be battery-powered.
  5. Step 1: A simple example:

    You should be able to get two Raspberry Pi boards with Xbee shields talking to each other without any configuration, using just serial commands.
    In one of the Raspberry Pi boards we will run a code that turn on the LED attached to pin 7 whenever it receives an 'H' over its serial connection, and turn the LED off when it gets an 'L'. The other Raspberry Pi board will run a program that sends 'H' and 'L' sleeping 1 second in between.
    xbee_shield Code for listening:

    //Include ArduPi library
    #include "arduPi.h"
    
    char buffer;
    uint8_t led = 7;
    
    void setup(){
      Serial.begin(9600);
      pinMode(led, OUTPUT);
    }
    
    void loop(){
      while(Serial.available()){
        buffer = Serial.read();
        if (buffer == 'H'){
          digitalWrite(led,HIGH);
        }else if (buffer == 'L'){
          digitalWrite(led,LOW);
        }
      }
    }
    
    int main (){
      setup();
      while(1){
        loop();
      }
      return (0);
    }
    
    
    Code for sending:
    //Include ArduPi library
    #include "arduPi.h"
    
    
    void setup(){
      Serial.begin(9600);
    }
    
    void loop(){
      Serial.print('H');
      delay(1000);
      Serial.print('L');
      delay(1000);
    }
    
    int main (){
      setup();
      while(1){
        loop();
      }
      return (0);
    }
    
    
    When both programs are running (one on each board) you should see the LED on the first board turn on and off, once a second.

    Step 2: Addressing:

    There are multiple parameters that need to be configured correctly for two modules to talk to each other (although with the default settings, all modules should be able to talk to each other). They need to be on the same network, as set by the ID parameter (see "Configuration" below for more details on the parameters). The modules need to be on the same channel, as set by the CH parameter. Finally, a module's destination address (DH and DL parameters) determine which modules on its network and channel will receive the data it transmits. This can happen in a few ways:

    Again, this address matching will only happen between modules on the same network and channel. If two modules are on different networks or channels, they can't communicate regardless of their addresses.

    Step 3: Configuring the XBee module:

    You can configure the Xbee module from code running on the Arduino board or from software on the computer. To configure it from the Arduino board, you'll need to have the jumpers in the Xbee position. To configure it from the computer, you'll need to have the jumpers in the USB configuration and have removed the microncontroller from your Arduino board.

    To get the module into configuration mode, you need to send it three plus signs: +++ and there needs to be at least one second before and after during which you send no other character to the module. Note that this includes newlines or carriage return characters. Thus, if you're trying to configure the module from the computer, you need to make sure your terminal software is configured to send characters as you type them, without waiting for you to press enter. Otherwise, it will send the plus signs immediately followed by a newline (i.e. you won't get the needed one second delay after the +++). If you successfully enter configuration mode, the module will send back the two characters 'OK', followed by a carriage return.

    Send Command Expected Response
    +++ OK<CR>

    Once in configuration mode, you can send AT commands to the module. Command strings have the form ATxx (where xx is the name of a setting). To read the current value of the setting, send the command string followed by a carriage return. To write a new value to the setting, send the command string, immediately followed by the new setting (with no spaces or newlines in-between), followed by a carriage return. For example, to read the network ID of the module (which determines which other Xbee modules it will communicate with), use the 'ATID command:

    Send Command Expected Response
    ATID<enter> 3332<CR>

    To change the network ID of the module:

    Send Command Expected Response
    ATID3331<enter> OK<CR>

    Now, check that the setting has taken effect:

    Send Command Expected Response
    ATID<enter> 3331<CR>

    Unless you tell the module to write the changes to non-volatile (long-term) memory, they will only be in effect until the module loses power. To save the changes permanently (until you explicitly modify them again), use the ATWR command:

    Send Command Expected Response
    ATWR<enter> OK<CR>

    To reset the module to the factory settings, use the ATRE command:

    Send Command Expected Response
    ATRE<enter> OK<CR>

    Note that like the other commands, the reset will not be permanent unless you follow it with the ATWR command.

    Here are some of the more useful parameters for configuring your Xbee module.

    Command Description Valid Values Default Value
    ID The network ID of the Xbee module. 0 - 0xFFFF 3332
    CH The channel of the Xbee module. 0x0B - 0x1A 0X0C
    SH and SL The serial number of the Xbee module (SH gives the high 32 bits, SL the low 32 bits).
    Read-only.
    0 – 0xFFFFFFFF
    (for both SH and SL)
    different for each module
    MY The 16-bit address of the module. 0 - 0xFFFF 0
    DH and DL The destination address for wireless communication (DH is the high 32 bits, DL the low 32). 0 – 0xFFFFFFFF
    (for both DH and DL)
    0 (for both DH and DL)
    BD The baud rate used for serial communication with the Arduino board or computer. 0 (1200 bps)
    1 (2400 bps)
    2 (4800 bps)
    3 (9600 bps)
    4 (19200 bps)
    5 (38400 bps)
    6 (57600 bps)
    7 (115200 bps)
    3 (9600 baud)

    Note: although the valid and default values in the table above are written with a prefix of "0x" (to indicate that they are hexadecimal numbers), the module will not include the "0x" when reporting the value of a parameter, and you should omit it when setting values.

    Here are a couple more useful commands for configuring the Xbee module (you'll need to prepend AT to these too).

    Command Description
    RE Restore factory default settings (note that like parameter changes, this is not permanent unless followed by the WR command).
    WR Write newly configured parameter values to non-volatile (long-term) storage. Otherwise, they will only last until the module loses power.
    CN Exit command mode now. (If you don't send any commands to the module for a few seconds, command mode will timeout and exit even without a CN command.)

    You can see all the AT commands in the XBee manual.

    API mode

    As an alternative to Transparent Operation, API (Application Programming Interface) Operations are available. API operation requires that communication with the module be done through a structured interface (data is communicated in frames in a defined order). The API specifies how commands, command responses and module status messages are sent and received from the module using a UART Data Frame.

    Read the manual if you are going to use the API mode.

    Step 4: Using Series 2 ZB XBee's:

    Series 2 XBee's (ZigBee protocol) are quite different to 802.15.4 ones.

    ZigBee networks are called personal area networks or PANs. Each network is defined with a unique PAN identifier (PAN ID). XBee ZB supports both a 64-bit (extended) PAN ID and a 16-bit PAN ID.

    The 16-bit PAN ID is used in all data transmissions. The 64-bit PAN ID is used during joining, and to resolve 16-bit PAN ID conflicts that may occur.

    ZigBee defines three different device types: coordinator, router, and end devices.

    xbee_shield

    Coordinator

    Router

    End device

    In ZigBee networks, the coordinator must select a PAN ID (64-bit and 16-bit) and channel to start a network. After that, it behaves essentially like a router. The coordinator and routers can allow other devices to join the network and can route data.

    After an end device joins a router or coordinator, it must be able to transmit or receive RF data through that router or coordinator. The router or coordinator that allowed an end device to join becomes the "parent" of the end device. Since the end device can sleep, the parent must be able to buffer or retain incoming data packets destined for the end device until the end device is able to wake and receive the data.

    See this article for more information about 802.15.4 vs ZigBee: http://sensor-networks.org/index.php?page=0823123150

     

    Links and Documentation

    Links and Documentation: