Module Configuration

Now it’s time to set up your modules:

• 1.  Determine which module will be used as the coordinator and which will be used as the router, and mark them with a label to differentiate between them.
• 2.  Plug the XBee module to be used as the router into the USB adapter, making sure to line up the pins to the connector properly. The flat end usually points toward the USB connector.
• 3.  Start the X-CTU software and plug the USB adapter into the computer. On the PC Settings tab, select or enter the COM port that the adapter is connected to and click the Test/Query button. The test should come up with the module type, firmware number, and serial number. If there is an error, check the connections and the COM port number in the device manager and retry. If this is the first time that the XBee module is being configured, the standard serial configuration is 9600 8N1.
• 4.  After the test is complete, click the Modem Configuration tab and click the Read button in the Modem Parameter and Firmware box. If the module cannot be read at this point, click the “Download new versions…” button. If you’re using Windows, choose “Web source,” and for WINE setups, select file that was downloaded. Then retry reading the configuration.
• 5.  Once you have read the module, select ZIGBEE ROUTER AT from the Function Set drop-down menu, and set the version of the firmware to the highest hex number available.
• 6.  Check the “Always update firmware” box and click the Write button. This sets the firmware but not any of the networking options; once this operation completes, reread the module settings.
• 7.  In the following list, the firmware drop-down shows the options available for change. Options highlighted in green are at their default setting, and options highlighted in blue are set to a different setting. The options that need to be changed are

• The pan ID (ID)
• Destination address high (DH)
• Destination address low (DL)

  In transparent mode, the address is where the data will be sent. This can be changed by entering the command mode. The pan ID is like the ESSID for WiFi networks, and can be set from 0 to FFFF. The pan ID chosen for this example is 3300. click “pan ID” and set to the chosen ID. The next two options are the serial numbers written down earlier: the destination’s addresses. Both the high and low should be set to the serial number of the module chosen for the coordinator. These three settings prepare the module for communications in a network.

• 8.  One last setting needs to be set before writing the options to the module, and it’s specific to this example: the baud rate. There is a single number to identify the baud rate; the default is 3 for 9600 baud. Change this setting to 6 for a baud rate of 57600. When the options are highlighted in a yellow-green, they have been changed but not written to the module. Uncheck the “Always update firmware” box and click the Write button in the Modem Parameters and Firmware box, which will confirm and update the settings to the module.
• 9.  Once the router is configured, unplug the adapter from the computer and remove the module. Plug in the module to be used as the coordinator and repeat the steps used to configure the router, but select ZIGBEE COORDINATOR AT for the firmware options and set the destination address as the router’s serial number. Use the same baud and pan ID as for the router module.

Arduino Setup

The modules are now ready for communications, and it is time to set up the rest of the example.

1. Leave the coordinator plugged into the USB adapter and plug the router into the serial adapter.
2. Prepare an Arduino board by uploading the standard Firmata sketch as described in Chapter 3. Make sure that the Arduino can communicate to the Firmata test application before plunging the router into the Arduino, as shown in Figure 5-1.

Verifying the Code

The Firmata sketch is uploaded to the Arduino and the XBees are both plugged into the computer and Arduino. This configuration of the modules is in transparent mode, and the Firmata test app can now communicate with the Arduino. It is optional to add a few buttons, servos, or LEDs to explore the application’s potential, or use the examples created in Chapter 3. If the modules are not communicating, check the connections, settings, and selected COM port.

Module Configuration

Configuring the modules for API mode is similar to the setup for the AT command configuration:

1. A single coordinator is needed. Change the firmware settings to ZIGBEE COORDINATOR API and ZIGBEE ROUTER API for the router.
2. Set the PANID along with the baud rate; you can use the same settings as before for this setup.
3. The destination address is not necessary for this mode to communicate; packets determine where the information is going.
4. Choose a name for the node identification (NI) setting when configuring the module; ROUTER and COORDINATOR will suffice. The NI setting is helpful for identifying the node. This is independent of the addresses and equivalent to a computers host name.
5. Upload the software serial sketch to an Arduino with both baud rates set to the XBee modules’ rate of 57600, and connect the serial adapter to pins 2 and 3 of the Arduino, as shown in Figure 5-3.

   

   Figure 5-3 .  Setup for API examples. The XBee is connected to pins 2 and 3 for software serial

6. Once the Arduino is configured, connect via a serial terminal such as PuTTY, minicom, or HyperTerminal, with the setting 57600 8N1.

0x08 +0x01+0x4E+0x44  = 0x9B

0xFF – 0x9B = 0x64

0x7E 0x00 0x04 0x08 0x01 0x4E 0x44 0x64

0x7E 0x00 0x0F 0x17 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0xFF 0xFF 0xFF 0xFE 0x00 0x4E 0x44 0x5A

Request Packets

Table 5-1 is a reference for the various packets that can be used to control the XBee modules. The frame name, the frame type, a general description, and the frame data are provided. Remember that the frame type is the last byte of the header, and following the frame data is the checksum.

Reply Packets

Table 5-2 shows the packets that are usually formed in a response to another packet. They are created outside of the program that creates the packet. These packets contain information that needs to be phrased so that the program can use the information. These packets still follow the same general structure as the request packets.

Arduino Data Echo

With a bit of understanding of the formation and reading of packets, this example will demonstrate in code the phrasing, retransmission, and construction of packets the code receives. The code will run on the Arduino and take incoming data packets (0x90) from any module in the network and pull the data out to reassemble the packet and retransmit back to the original source.

While the packet gets transmitted to the source, the code will print relative data to a serial monitor, such as a notification when an incoming packet has been received, the raw packet itself, addresses of the originating source, and the raw reply packet for sending. The code currently identifies and displays two different packets types (0x90) and (0x8B). This is accomplished through a switch statement after the whole packet has been captured.

The switch statement is pretty effective and can be expanded to recognize and handle current packet types plus any future additions. The packets are received and constructed in a byte array of 80 bytes, which is done to buffer the packets and to help ensure they’re complete before any phrasing is done or transmission starts. Although the XBee modules are capable of sending packets of greater sizes, this limit is to save on some space on the Arduino.

The setup is the same as in Figure 5-3, previously. The code uses software serial at 9600 baud and standard serial at 57600 baud; the XBee modules have to be reconfigured to 9600 baud. There are two ways to reconfigure the baud settings:

• Use the X-CTU software to set the baud back to setting 3.
• Construct and issue two AT command packets: one for the remote module and the other for the local module. The AT command is BD or 0x42 44, with the parameter being 3.

Both require you to change the X-CTU COM setting back to 9600 to accommodate the new setting. This example is one-sided, so packets sent to the Arduino will still have to be constructed in the terminal of the X-CTU; the HELLO packet will work for this example, although any properly formed transmit request will work with this code. To finish the setup for this example, step through the code and upload it to the Arduino.

Listing 5-1 is comprised of three parts. The first part sets up the variables and all the initialization of the Arduino’s serial connections before entering the loop function. The loop functions waits for the software serial to be available and checks for the packet start byte of 0x7E. A loop captures the packet and counts the incoming bytes while the software serial is available. When the packet is received, the user is informed of the incoming packet along with the contents of the raw packet by printing the details to the serial monitor before processing the packet. The first part of packet processing is to calculate the checksum by calling a function. If the checksum is correct, the program continues with parsing the packet and constructing and sending a reply packet that contains the same data that the received packet contained.

Listing 5-1.  Arduino Packet Echo Code, Part 1 of 3

#include <SoftwareSerial.h>
byte incomePacket[80];                               // buffer for incoming data
char incomeData [64];                                // phrased data holder
byte replyPacket[80];                                // packet construction buffer
byte sourceADR[10];                                  // source addresses
int datalen;                                         // length of data received
int count;                                           // total length of incoming packet
int length;                                          // misc. length holder
byte calcsum ;                                       // checksum
SoftwareSerial softSerial(2, 3);           // the main software serial

void setup()  {
   Serial.begin(57600);      // serial to monitor
   softSerial.begin(9600);   // serial to XBee
   Serial.println("Ready");
} // end setup

void loop(){
  if (softSerial.available() && 0x7E == softSerial.read() ){ // check for start byte
    incomePacket[0] = 0x7E;
    count = 1;
    while (softSerial.available()){
      incomePacket[count] =  softSerial.read();  // receive the incoming packet
      count ++;  // keep track of incoming bytes
    }  // end while (softSerial.available())
    Serial.println ("Recived a new packet");
    Serial.print ("Incoming packet is: ");
    for (int i = 0 ; i < count-1 ; i++){   // print raw packet
      Serial.print (incomePacket[i],HEX);
      Serial.print (' '),
    }
    Serial.println (incomePacket[count-1],HEX);   // last byte of the raw packet
    calcChecksum ();
    if (calcsum == incomePacket[count-1]){  // throw error if the checksum does not match
      processPacket();
    } // end if calcsum
    else {
      Serial.println ("Error packet is not proper");  // the error when packets are malformed
      while (softSerial.available()){
      softSerial.read();  // on error flush software serial buffer
      }
    }
  }// end looking for start byte
}// end loop

Part 2 of the program contains the functions to calculate the checksum and parse the packets’ data. The calcChecksum function pulls the length of the packet from the first two bytes after the packet start, and then the checksum is calculated before retuning back to the loop function. When the processPacket function is called, the user is informed that the packet has the correct checksum; the code then determines the packet type using the fourth position of the packet. The switch statement responds to a transmission-reply packet (0x8B) and a data-receive packet (0x90). The transmission-reply packet is handled by informing the user by printing to the serial monitor. The data packet is handled by parsing out the address of the sending XBee and pulling out the data to be used to construct a reply packet. During the whole process, the information is printed to the serial monitor.

Listing 5-1.  Arduino Packet Echo Code, Part 2 of 3

void calcChecksum () {
  calcsum =0;     // begin calculating errorsum of incoming packet
  length = incomePacket[1] +incomePacket[2];
  for (int i = 3 ; i <= length+2 ; i++){
    calcsum = calcsum + incomePacket[i];
  }
  calcsum = 0xFF - calcsum;  // finish calculating errorsum
}     // end void calcChecksum ()

void processPacket(){
  Serial.println ("Packet has correct checksum ");
  switch (incomePacket[3]){  // check packet type and perform any responses
    case 0x90:
      Serial.println ("The packet is a data packet"); // announce packet type
      for (int i = 4 ; i <= 13 ; i++){  // get both addresses of the source device
        sourceADR[i-4]= incomePacket[i];
      }
      datalen = count - 16 ;  // reduce to just the data length to get the data
      for (int i = 15 ; i < datalen+15 ; i++){
        incomeData [i-15] = incomePacket[i]; // phrase out the data
      }
      Serial.print ("source addess is: ");  // begin printing 64 bit address
      for (int i =0 ; i < 7 ; i++){
        Serial.print (sourceADR[i],HEX);
        Serial.print (' '),
      }
      Serial.println (sourceADR[7],HEX); // finish 64-bit address
      Serial.print ("network addess is: "); // begin printing 16-bit address
      Serial.print(sourceADR[8] ,HEX);
      Serial.print (' '),
      Serial.println(sourceADR[9] ,HEX); // finish 64-bit address
      Serial.print ("the packet contains: ");  // start printing the data from packet
      for (int i =0 ; i < datalen ; i++){
        Serial.print (incomeData [i]);
      }
      Serial.println (" : For data");   // finish the data print
      constructReply();
      break; // done with the received packet
    case 0x8B: //start response to the return packet from sending data
      Serial.println ("Received reply ");
      break;
    default: // anouce unknown packet type
      Serial.println ("error: packet type not known");
  }// end switch
}    // end processPacket()
  

Part 3 of the code echoes the data received from another XBee. The reply packet is built one byte at a time in an array starting with the packet start frame, the type, and the frame ID. Portions of the packet that are a single-byte setting are set one at a time. The parts of the packet that are from the received packet are added to the outgoing packet via for loops (the parts added include the address to send the new packet to and a copy of the received data). When the packet is almost complete, the packet size is calculated and added. The final calculation to be added to the packet is for the checksum before the packet is sent, and the program continues waiting for new packets.

Listing 5-1.  Arduino Packet Echo Code, Part 3 of 3

void constructReply(){
  Serial.println ("Constructing a reply packet"); // announce packet construction
  // start adding data to the reply packet buffer
  replyPacket[0] = 0x7E;    // start byte
  replyPacket[1] = 0; // 1st address byte will be zero with current limitations
  replyPacket[3] = 0x10;        // frame type
  replyPacket[4] =  1;         // frame ID
  for (int i =5 ; i <= 14 ; i++){     // add addresses
    replyPacket[i] = sourceADR[i-5] ;
  }
  replyPacket[15] = 0 ;          // set both options
  replyPacket[16] = 0 ;
  for (int i =17 ; i < datalen+17 ; i++){
    replyPacket[i] =  incomeData [i-17];  // add data to packet
  }
  replyPacket[2] = 14 + datalen ;      // set the lower length byte
  calcsum = 0; // start calculating errorsum
  replyPacket[17 + datalen] = 0;
  for (int i = 3 ; i <= replyPacket[2]+3 ; i++){
    calcsum = calcsum + replyPacket[i];
  }
  replyPacket[17 + datalen]= 0xFF - calcsum; // finish packet by adding checksum
  Serial.print ("The packet is: ");  // start printing raw packet before sending
  for (int i = 0 ; i < replyPacket[2]+3 ; i++){
    Serial.print (replyPacket[i],HEX);
    Serial.print (' '),
  }
  Serial.println (replyPacket[17 + datalen],HEX); // finish printing packet
  Serial.println ("Sending Packet");   // start sending packet to original source
  for (int i =0 ; i <= 17 + datalen ; i++){
    softSerial.write ( replyPacket[i]);
  }
} // end void constructReply()

With everything compiled and hooked up, a prepared packet can be sent from the X-CTU’s packet-assembly window. Watch the code’s actions in a serial monitor that is connected to the Arduino. The serial monitor should start printing information when a packet is received and proceed through the programmed responses. This code is a demonstration of packet handling and sometimes messes up on receive and transmit packets, because of the lack of more robust error correction.

To make the error checking a bit more robust, you can the check the reply packet against the created checksum for the new packet and re-create it before the packet is sent. Other error checking can be performed with flow control, timeouts, resends, and packet-acknowledgement communication. The transmit status frame type (0x8B) that is returned when a packet is sent does not indicate that the packet was successfully received by anything other than XBee modules. A microcontroller should form a reply packet to the state of a received packet if the incoming packets are from serial out from an XBee module. This method of packet handling is demonstrated in greater depth in Chapter 8.

If the code in Listing 5-1 does not respond, resend the packet a few times before checking the configurations. You can also issue an ND command to check the XBee radio connection. If the radios can see one another, double-check the serial connections on the Arduino and, if necessary, revert to the software serial, and then double-check the code.

Endpoint Firmware

The last firmware option is that of endpoint for both AT and API modes. They act similarly to any other module firmware by issuing and receiving data. However, unlike the router and coordinator, end devices do not route packets to other devices. End devices also have the capability to enter sleep mode because they do not store routing information. Sleep mode makes end devices the preferred choice when making remote sensors or controllers that need low power consumption.

There are three types of sleep configuration that are set via the sleep mode (SM) register:

• Setting a value of 1 in the SM register will put the module in hibernate mode. When XBee pin 9 is high, the module will not respond to any transmissions or requests, but will return from sleep.
• Setting the SM register to 4 is for cyclic sleep. In this mode, the endpoint module will still respond to incoming transmissions. When using API mode, the extended timeout option (0x40) needs to be set in the packet’s transmit options, giving the end device time to wake up and respond. The controlling program in this mode must wait till the Clear to Send (CTS) flow-control line is low.
• Setting the value to 5 works the same as 4, but allows a transition from low to high on XBee pin 9 to wake the module for transmission.

Endpoint modules have the capability to connect to either routers or coordinators. The code and setup for the last example will work for the end device.

1. For this setup, reconfigure the router module with ZIGBEE END DEVICE API.
2. Use the same settings to create a network, change the node identifier to ENDDEVICE, set the SM register to 4, and connect back to the Arduino.
3. Reconstruct the HELLO packet with 0x40 in the options byte, and send this packet to watch the code work. In this configuration, when the end device receives a packet, it will be awake for a period of time to allow the module to transmit the outgoing packet.

The next example (see Listing 5-2) Arduino sketch uses sleep mode 5, demonstrating a method of allowing other modules in the network to wake and send data to the end device, while allowing the code to wake up the module to send data. The code examples use the setup in Figure 5-4; the only change to the Arduino connections is that an extra connection is added between the serial adapter and the Arduino, connecting XBee pin 9 to Arduino pin 9. Both modules need to be set with AT command mode firmware—ZIGBEE COODINATOR AT for one and ZIGBEE END DEVICE AT for the other. The modules need the destination addressed set to be able to communicate. When configuring the end device, set the SM register to 5, allowing the code and other external events wake up the module.

Listing 5-2.  Arduino Dual-Direction Communication with Sleep Mode Communications

#include <SoftwareSerial.h>
SoftwareSerial mySerial(2, 3); //rx,tx
void setup()  {
  pinMode (9 , OUTPUT);
  Serial.begin(9600);
  Serial.println("Ready");
  mySerial.begin(9600);
} // end setup

void loop() {
  digitalWrite (9 , LOW);
  if (mySerial.available())
    Serial.write(mySerial.read());
  if (Serial.available()){
    digitalWrite (9 , HIGH);  // transition from LOW to HIGH to wake up module
    delay (2);
    digitalWrite (9 , LOW);
    delay (2);                      // delay to give the chip time to recognize the transition
    mySerial.write(Serial.read());
  } // end if (Serial.available())
}   // end loop                 

The code is a simple chat-style program that can receive data from another XBee and transmit data itself. With everything configured and plugged in, start a serial program to monitor and send data from the Arduino; use the terminal in the X-CTU’s terminal for the coordinator. Any data typed into either terminal will show up on the other terminal. When typing in the terminal for the Arduino, the code does not echo the typed data back to the terminal; the local echo in the terminal would need to be set for you to see the typed characters. This setup is good when devices need to access or poll from the end device when power consumption is a concern.

Summary

This chapter demonstrated working with XBee modules in both AT command mode and API packet mode. There are a lot more configuration and communication options available, such as implementing encryption, working with other ZigBee-compatible devices, and using the other available pins for analog-to-digital sensors or controlling PWM. The XBee data sheet for the modules provides a wealth of information. This chapter did not discuss setting up a large network of XBees, but the concepts described are scalable.