XBee AT Mode - Transmit and Command Mode Example

[ScottRaeker]

Created by Scott Schmit, last modified on Jan 06, 2014

note: This post for reference only. Xbee modules used in project are obsolete and no longer available. It is recommended customers look at the Xbee 3 family from Digi.

Purpose

XBee modules provide an easy way to add wireless capability to an embedded application. The purpose of this page is to demonstrate how to interface and control an XBee module in AT mode with a host microcontroller.

XBee Module and AT/API Background

Digi International provides a large array of wireless modules. Each have their individual benefits. Some are meant for WiFi, while some are meant for ZigBee applications. Some XBee modules are 802.15.4 compliant but do not necessarily comply with a wireless network protocol. Still other XBee modules from Digi International are completely proprietary and do not comply with well accepted standards. All of these modules can be used to accomplish wireless communication. It is up to the designer to determine what, if any, protocols the design must comply with and which XBee modules actually comply with the needed standard.

This example demonstrates XBee operation in AT mode. AT mode is synonymous with “Transparent” mode. In AT mode, any data sent to the XBee module is immediately sent to the remote module identified by the Destination Address in memory. When the module is in AT mode, it can be configured by the user or a host microcontroller by first placing the module in Command mode and then sending predefined AT commands through the UART port. This mode is useful when you don’t need to change destination addresses very often, or you have a very simple network, or simple point to point communication. For larger networks that involve nodes talking to multiple targets, API mode is more useful. In API mode, rather than sending AT commands serially, data packets are assembled that include the Destination Address. API mode allows you to change destination address much more quickly because Command Mode doesn’t need to be entered. API mode is also useful if the user needs to change the configuration of a remote module. This project focuses on AT mode operation.

Click here for an API Mode example

XBee Module User Guide / AT Command Reference

A list of supported AT commands can be found in Chapter 10 of the following XBee module user guide:

• XBee ZB Module User Guide

Project Brief

This project will demonstrate how to interface an XBee module with a host microcontroller. We will cover what hardware connections are needed and what communication settings are required. For this particular project, the microcontroller used was a PSoC4 device from Cypress (CY8C4245). The PSoC4 Pioneer Kit was used as the development platform for the microcontroller. For this particular project, the XBee module used was an XBee-PRO ZigBee module (XBP24BZ7WIT-004). A wireless Arduino shield (A000065) was used to interface the XBee module to the host microcontroller. The microcontroller was loaded with a user application that can place the module in Command Mode or Transmit mode. The application also accepts user input from a PC terminal. If the application is in Command Mode, it checks whether the user entered a valid AT command and either executes the command or displays an error message. If the application is in the Transmit state, any characters entered by the user are transmitted wirelessly to a remote node. The microcontroller uses two UART ports–one for communication between the PC and the microcontroller, and one for communication between the microcontroller and the XBee module. In this way, the microcontroller acts as a sort of “middle man” between the PC and the XBee device and monitors user input before sending it to the XBee module. The PSoC4 Pioneer Board includes an on-board UART / USB bridge, so we will be able to connect to a USB port of the PC with just a simple USB mini-B cable.

The X-CTU software provided for free by Digi International is still required to configure the XBee modules as Coordinators, Routers, or End Devices, and to switch between AT and API mode. For examples of how to configure XBee modules using X-CTU software, click here. Once the modules are configured, they can be used in an embedded application.

This project uses a Cypress microcontroller. If the reader is using a different host microcontroller, this project can still demonstrate, conceptually, what is required to interface with an XBee module. The reader can still view the example code and use it to re-create the application in the desired microcontroller software development environment. The reader should keep in mind, however, that two UART ports are required to re-create this demo.

Project Requirements

The following hardware/software is required if the reader wishes to re-create this demo:

• XBP24BZ7WIT-004 - XBee ZigBee module. Only 2 are needed for wireless communication. This demo uses 3 to demonstrate a multi-point network.
• 32400 - Parallax USB Adapter board for XBee modules. Allows the user to connect XBee module to host PC for configuration using X-CTU software. This board isn’t required, but it makes configuration much easier. Without this board, the user must use jumper wires to configure the modules.
• PSoC4 Pioneer Kit - Evaluation board for PSoC 4 microcontroller. 2 are needed for this demo. USB cable is included with each kit.
• A000065 - Wireless/XBee Arduino shield. 2 are needed for this demo.
• X-CTU Software - This software is required to configure XBee modules. This software also provides an easy way to double check the configurations set by the example code. It is free to download.
• PSoC Creator - This software is required to develop firmware for PSoC 3, 4, 5, and 5LP devices. It is free to download. Version 2.2, Service Pack 1 was used for this demo.
• Tera Term - This is terminal software that supports serial port communication. It is free to download.

This project used a PC running x64 Windows 7 Pro with all of the required software.

XBee Module Configuration

XBee modules can be easily configured using the Parallax USB Adapter Board. If you have the Parallax adapter board, you can skip to the Configuration Settings section below.

The modules can be configured without the Parallax adapter board by using the Arduino Wireless Shield, the PSoC 4 Pioneer board, and jumper wires. The user must connect an XBee module to the Wireless Shield and make the following connections (it may be easier to connect the pins if the Arduino Shield is not mounted on the Pioneer Board) as shown in the Figure to the right:

Arduino Shield	Pioneer Board
Pin1 of J6	Pin9 of J8
Pin2 of J6	Pin10 of J8
*5V on Power Header	Pin4 of J1
*GND on Power Header	Pin2 of J1

*The Power/GND pins only need to be connected if the Arduino Shield is not mounted on the Pioneer Board.

Module Configuration without Parallax USB Adapter Board

Configuration Settings

Refer to this example for configuring XBee modules using the X-CTU software and the Parallax adapter board.

1. Use the Parallax USB Adapter board or the setup shown above to connect the XBee modules to the PC for configuration. If using the above setup, ensure the ‘Serial Select’ slide switch is set to ‘Micro’.
2. One XBee module needs to be configured as a Coordinator in AT mode. All other XBee modules (1 or more) were configured as Routers in AT mode for this example.
3. The PAN ID for all nodes was set to ‘1234’.
4. The Destination Address for each Router was set to the Coordinator’s Serial ID.
5. The Destination Address for the Coordinator can be set to ‘000000000000FFFF’ to broadcast to all nodes, or the reader can use the Serial ID of one of the Routers.
6. All other parameters were left at default values.

Microcontroller Firmware

PC UART / XBee UART

The application code for the host microcontroller sets up two UART ports. One UART port allows communication between the PC and microcontroller. The other allows communication between the microcontroller and the XBee module. For a simple PSoC UART example, click here. In PSoC Creator, two UART (SCB) components were added to the design.

The following settings were applied to each UART:

UART1 - PC / Micro
The UART between the PC and microcontroller used the following settings:

• • Baud Rate: 115200 kbs
  • Data: 8-bit
  • Parity: None
  • Stop Bits: 1 bit
  • Flow Control: None

UART2 - Micro / XBee
The UART between the microcontroller and XBee module used the following settings:

• • Baud Rate: 9600
  • Data: 8-bit
  • Parity: None
  • Stop Bits: 1 bit
  • Flow Control: None

Push-button (SW2)

The application code also used a push-button to switch between Command Mode and Transmit Mode. The PSoC4 Pioneer Kit comes with a tactile push-button (SW2) connected between Pin 0_7 and ground. When SW2 is pressed, P0_7 sees a logical ‘0’. In PSoC Creator, a digital input pin was created for P0_7. This is already done for you in the provided example code, but here are some step by step instructions:

1. In PSoC Creator, click and drag a Digital Input Pin into the design from the Component Catalog.
2. Double-click the component to bring up the Component Configuration window.
3. Name the pin “SW2”.
4. In the “Type” tab, deselect the “HW Connection” box, which makes the pin reading only accessible from software.
5. In the “General” tab, select “Resistive Pull Up” as the Drive Mode and select “High (1)” as the Initial State.
6. Click “Apply” and “OK” to close the Configuration window.

Application Code Outline

The application code involves setting up and monitoring the UARTs and the push-button. The bulk of the application code involves checking user-entered data and string manipulation. The application code implements a 2-state machine. The two states are the Command Mode state and the Transmit Mode state. SW2 is used to toggle between the two states. On power-up the machine starts in Transmit Mode state. Any characters typed will be immediately transmitted to the node assigned by the “Destination Address”. If the machine is placed in the Command Mode state, the code checks for a valid command entered by the user. If the command is valid, the XBee module is placed in Command Mode and the entered AT command is executed. After the command is executed, the XBee module is placed back in Idle Mode. However, the state-machine remains in Command Mode until SW2 is pressed again. Therefore, the user doesn’t need to press SW2 every time an AT command is entered.

The following code block presents a code outline to assist the reader in generating application code for various platforms.

#include <device.h> // Include any device header files required for UART and GPIO operation
#include <string.h> // Include <string.h> file to allow for string manipulation
 
// Provide global definitions for things like special character ASCII codes, buffer sizes, etc.
#define CR 0x0D
#define MAX_NUM_CHAR 26
//...etc...
 
// Declare global variables like command buffers, display headers, etc.
const char startup_header[] = "XBee AT Mode Example\n\r";
char cmd_buf[MAX_NUM_CHAR];
//...etc...
 
// Include function prototypes if they occur after main() function
void XBee_Enter_Command_Mode (void);
//...etc...
 
void main() {
    // Initialize system variables
    // Initialize UARTs
    // Initialize SW2 Port[Pin], PSoC designs accomplish this through GUI instead of application code
     
    // Print startup headers on PC terminal
 
    for(;;) {
  
        //////////////////// Handle button press ////////////////////
        // Read SW2 and change application state if button is pressed
        // Must provide some sort of debounce functionality, such as a short (500ms) delay
        /////////////////////////////////////////////////////////////
 
 
        //////// Handle characters received from remote XBee ////////
        // Get characters from XBee UART
        // Print valid received characters on local terminal
        /////////////////////////////////////////////////////////////
 
 
        /////////////// Handle characters entered by user from local terminal ///////////////
        // Get characters from local terminal
        // If in command mode
            // If character is just an alphanumeric character, store in command buffer, increment command buffer index, print character to local terminal
            // If <backspace> was pressed:
                // if command buffer index > 0
                    // send BS character to local terminal
                    // send whitespace character to local terminal
                    // send BS character to local terminal
                    // decrement command buffer index
                // if command buffer index = 0, do nothing         
            // If <enter> was pressed:
                // Print newline to local terminal
                // Check command buffer for valid command
                    // If valid, put XBee in command mode, send command, wait for response, print some sort of response in local terminal, exit command mode
                    // If not valid, print error message
                // Erase command buffer
                // Reset command buffer index
        // If in Transmit mode
                //print character to local terminal, send character through XBee UART (to be displayed on remote terminal)
        //////////////////////////////////////////////////////////////////////////////////////
   }
}

Example Code

Download the following PSoC Creator example project to demonstrate running the XBee modules in AT mode through PC terminal software.

• XBee_AT_Example

Hardware Connections

The PC UART used P4[1:0] of the micro while the XBee UART used P0[5:4] of the micro. The Digital Input Pin was ported to P0_7. These connections are already done for you in the provided example code, but here are some step by step instructions:

1. In PSoC Creator, in the Workspace Explorer window, open the file with extension “.cydwr”.
2. You should see RX and TX signals corresponding to each UART, as well as the SW2 signal. The “Port” drop-down can be used to select the desired pins for each signal.
3. The following table shows which pins were used for each signal:

Signal Name	Port[Pin]
PC_UART: rx	P4[0]
PC_UART: tx	P4[1]
XBee_UART: rx	P0[4]
XBee_UART: tx	P0[5]
SW2	P0[7]

4. Save and close the “.cydwr” file.

Jumper wires (included in the Pioneer Kit) are needed to connect the PSoC4 device to the on-board UART / USB bridge. The following connections will need to be made for each Pioneer Board while powered down:

1. Using a jumper wire, connect Pin10 of J3 to Pin10 of J8 on the Pioneer board.
2. Using a jumper wire, connect Pin9 of J3 to Pin9 of J8 on the Pioneer board.
   
   

• The PSoC4 device is now connected to the PSoC5 device, which will convert the UART signal to a USB signal.

3. Plug the Arduino Wireless shield to the PSoC4 Pioneer Board. Ensure the ‘Serial Select’ slide switch is set to ‘Micro’.
   
   
4. Plug an XBee module into the Arduino Wireless shield (the reader will need to keep track of which XBee module is the Coord. and which are Routers).
   
   
5. Connect the board to an open USB port of the PC using a USB mini-B cable
   
   

Testing the Example Code

Setup

1. Connect the first board as shown above.
2. Open the XBee_AT_Example code provided above using PSoC Creator.
3. In PSoC Creator, build the project and program the first board.
4. Connect the second board and program it with the same example code.
5. Ensure both boards are connected to an open USB port of the PC.
6. Open a Tera Term window.
7. Navigate to Setup → Serial Port, and verify the following settings:

• Select the port corresponding to the first board.
• Baud Rate: 115200
• Data: 8-bit
• Parity: None
• Stop: 1 bit
• Flow Control: None
• Transmit Delays: zero

8. Press “OK”
9. Open a second Tera Term window.
10. Navigate to Setup → Serial Port.
11. Select the port corresponding to the second board, configure the same serial port settings, and click “OK”
12. Reset both boards using the “Reset” button on the Arduino Wireless shield.
13. The start-up headers should display in each terminal window.

Tutorials

Transmit Mode
On power up, the application is in the Transmit state. Since the XBee modules are configured in AT mode, any characters received on the local module’s UART will be transmitted wirelessly to the remote node. The address of the remote node is hard-coded into the module when configured (using X-CTU software).

1. When both boards are powered up using the USB mini-B cables and the start-up headers are displayed in Tera Term, begin typing characters into one of the terminals. You should see characters show up in both terminals.
2. Test both terminals and verify characters show up in both.

If characters don’t appear in both terminals:

• Ensure the boards are close enough to allow for wireless communication
• Try resetting the boards and verify the start-up headers print in each terminal
• Ensure the Destination Addresses of each module contains the Serial ID of the other module (use X-CTU software)

Below are some example screenshots of Transmit mode operation:

User Entered “HELLO”

Remote Module Received “HELLO”

Command Mode - Read Commands
When the XBee modules are configured in AT mode, predefined AT commands can be sent to the modules serially through the XBee UART port. First, the module must be placed in Command Mode by sending a predefined sequence of characters. Once the Command Mode Sequence is received, the XBee module is ready to receive any valid Read/Write commands received over UART. This tutorial demonstrates how to Read different configurations of the module. Specifically, this tutorial uses the “ATID”, “ATSx”, and “ATDx” commands to read the Network PAN ID, the module’s Serial ID, and the module’s Destination Address.

1. Once the boards are powered up using the USB mini-B cables and the start-up headers are displayed in Tera Term, press SW2 on the Pioneer Board to enter the Application Command Mode.
2. Using the PC terminal, enter “ATID” and press . The terminal will display the PAN ID configured in the local XBee module. The following actions will take place for this to occur:

• The microcontroller will check the characters the user entered to verify “ATID” is a valid command (which it is).
• The microcontroller will send the Command Mode Sequence over UART which will place the XBee module in Command Mode.
• The microcontroller will wait to receive the “OK” signal from the XBee module
• Once the “OK” signal is received, the microcontroller will send the command string “ATID” over XBee UART.
• The XBee module will send the Network PAN ID back to the microcontroller.
• The microcontroller will display the Network PAN ID in Tera Term by transmitting over the PC UART.

3. Using the PC terminal, type “ATSH” and press . The terminal will display the upper 32 bits of the module’s Serial ID.
4. Using the PC terminal, type “ATSL” and press . The terminal will display the lower 32 bits of the module’s Serial ID.
5. Send “ATDH” and “ATDL” to display the module’s Destination Address upper and lower 32 bits. This number should match the Serial ID of the remote module you are transmitting to.
6. Press SW2 to return to Application Transmit mode.
7. Type characters in the terminal and verify that characters are still received by the remote node.

“Read” Commands / Transmit “HELLO”

Refer to Chapter 10 of the XBee module user guide for a list of all supported commands. The example code currently does not support the “Node Discover” or “Destination Node” commands.

Command Mode - Write Commands

This tutorial demonstrates how to Write different configurations to the module. Specifically, this tutorial implements a 3-node network and uses the “ATDx” commands to change the Destination Address of the Coordinator from one Router to another Router. This demonstrates how the user would change the destination node using AT serial commands in a multi-node network.

Note: This tutorial requires that the user have Node 1 configured as an AT Coordinator and Nodes 2 and 3 configured as AT Routers. X-CTU software should be used to configure the modules. Also, the Destination Address of both Routers (Nodes 2 and 3) should be the Serial ID of the Coordinator and the Destination Address of the Coordinator (Node 1) should be the Serial ID of Node 2.

1. Connect Node 1 and Node 2 to the Pioneer Board through the Arduino Wireless shield.
2. Power the boards using the USB mini-B cables.
3. Setup two Tera Term windows as explained above.
4. Once the start-up headers are displayed in Tera Term, begin typing characters and verify communication has been established between the two boards.
   
   

Successful Transmission Between Node 1 (Coordinator) and Node 2 (Router 1)

5. Remove power from Node 2’s Pioneer Board. Remove the first Router module (Node 2) from the Arduino Wireless shield and insert the second Router module (Node 3).
6. Re-establish the Tera Term link with Node 3. You may need to close the Tera Term window, re-open, and re-configure the serial port to communicate with Node 3.
7. Begin typing characters in each Tera Term window. You should notice that wireless communication is only occurring from the Router (Node 3) to the Coordinator (Node 1). This is because Router 1’s (Node 2’s) Serial ID is still set as the Coordinator’s Destination address.

Unsuccessful 2-way Communication Between Node 1 (Coordinator) and Node 3 (Router 2)

8. Press SW2 on the Router’s Pioneer Board to enter the Application Command Mode.
9. Use AT commands to display the second Router’s Serial ID: “ATSH ” and “ATSL ”

Second Router’s (Node 3’s) Serial ID

10. Press SW2 on the Coordinator’s Pioneer Board to enter the Application Command Mode.
11. Use AT commands to display the Coordinator’s Destination Address: “ATDH ” and “ATDL ”. The Destination Address of the Coordinator is still the Serial ID of the first Router that we removed earlier. Router 2 is able to send data to the Coordinator because it already has the Coordinator’s Serial ID hard-coded as its Destination Address (from X-CTU software).

Coordinator’s (Node 1’s) Original Destination Address

12. Using AT commands, change the Coordinator’s Destination Address to the Serial ID of the second Router. You will need to include the new address with the command. For this example, the lower 32 bits of the second Router’s Serial ID were: “409E06DD”. Typing “ATDL 409E06DD ” would make the lower 32 bits of the Coordinator’s Destination Address equal to “409E06DD”. All 3 modules used in this example contained the same upper 32-bit Serial ID. Therefore, the “ATDH” command was not necessary.
13. Once you receive the “OK” signal, press SW2 on both boards to return to Application Transmit Mode.
14. Begin typing characters in either terminal and you should see them appear in the remote window as well.

Successful Destination Address Change through AT Commands

Comments from the Author

The provided example code can be used freely. However, it has not been tested with every AT command. Valid parametric entries are not extensively checked for within the application code and it is the user’s responsibility to either add parametric validity checks or be sure to only enter valid parameters with “Write” commands. I hope this example project was useful to you. The goal of this project was not to provide a perfect XBee command program. The goal was to demonstrate how to properly interface an XBee module with a host microcontroller and how to setup basic communication in AT mode. Hopefully this program will help familiarize you with the XBee modules enough to implement them in your own embedded design. I encourage you to play around with the code and add some of your own functionality. Try different AT commands not mentioned in this demo. If you have any questions or interesting breakthroughs, I would love to hear about them. I hope you enjoy experimenting with XBee modules from Digi International!