XBee API Mode - Read Remote ADC Example

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

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 API mode with a host microcontroller. Additionally, the page describes how to setup a simple 3-node network and read ADC voltage of remote nodes.

XBee Module and AT/API Background

Digi International provides a large array of wireless modules. Each have their own 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 API mode. In general, AT (Transparent) mode is meant for applications that require user commands. In AT mode, any data sent to the local XBee module is immediately sent to the remote module identified by the Destination Address in memory. In AT mode, predefined AT commands can be sent serially to configure the device through Command Mode. API mode can be much faster than AT mode and therefore is useful in applications that involve machine-to-machine communication. 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 API mode operation.

Click here for an AT Mode example

XBee Module User Guide / API Operation Reference

API Operation and a list of supported frame types are described in detail in Chapter 9 of the following XBee 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 controls an XBee module configured as a Coordinator in API mode. The Coordinator sends IO Sample requests to 2 Routers, receives the ADC data from the Routers, and displays the results on a local PC terminal. 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. The remote nodes do not interface with an external microcontroller in this project.

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. This demo uses 3 to demonstrate a multi-point network. This demo would also work with 802.15.4 modules instead of ZigBee modules.
  • 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. 1 was used in this demo. USB cable and jumper wires are included with the kit.
  • A000065 - Wireless/XBee Arduino shield.
  • 32403PAR-ND - XBee/Breadboard Adapter board. 2 were used in this demo. Allows user to connect remote XBee modules to breadboard.
  • 438-1045-ND - Breadboard used to mount remote modules and connect ADC voltage sources.
  • 3352T-103LF-ND, 3352T-104LF-ND - This project used thumbwheel potentiometers for adjusting voltage to the ADC on the remote modules. The reader can use any analog voltage source for this application (like an analog sensor). Keep in mind, however, that XBee modules cannot read voltages outside the range 0~1.2V, so proper voltage scaling will be necessary.
  • 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 3.0 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.

image

Module Configuration without Parallax USB Adapter Board

Configuration Settings

Refer to this example for configuring XBee modules using the X-CTU software.

  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 API 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 was set to ‘000000000000FFFF’.
  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.

image

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

*The Advanced Settings for the PC / Micro UART were left at default values. RX and TX buffer sizes were left at 8 bytes. Interrupt was set as “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

image
image

The Advance Settings for the XBee / Micro UART were adjusted as shown in the figure to the right. PSoC Creator creates a built-in software buffer for the UART (SCB) component that will handle more than 8 bytes (hardware FIFO can only handle 8 max). This allows the user to have a much larger buffer at their disposal, and requires no additional code development to support >8 byte buffers. However, additional internal memory within the PSoC device is used to support the software buffer. In API operation, depending on the frame size, there is potential for a large number of bytes to be received/transmitted very quickly. Therefore, the built-in software buffer was used to ensure no data was thrown away before use.

When the buffer size exceeds 8 bytes, Internal Interrupt is enabled by default. This is required by the built-in software buffer to handle FIFO_NOT_EMPTY interrupts. No other interrupt sources were selected for this project.

image

Push-button (SW2)

The application code used a push-button as a “Start Button” and also to get ADC readings from the remote modules. 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:

image

  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.

image

Timeout Counter (Timer_1)

The application code implements a 16-bit counter that interrupts if too much time has passed before getting a proper response frame. The timer uses a 24MHz clock and the period was set to 24000 counts. Therefore, the counter reads ‘0x0000’ after 1ms. The “TC” output indicates when the counter reads 0x0000. This output was connected to an “Interrupt” Component (see below).

image

  1. In PSoC Creator, click and drag a Timer component into the design from the Component Catalog.
  2. Double-click the component to bring up the Component Configuration window.
  3. The default name “Timer_1” was used for this project.
  4. Resolution was set to 16-bit.
  5. Period was set to 24000 (Period = 1ms).
  6. Trigger mode was set to none.
  7. Capture mode was set to none.
  8. Enable mode was set to “Software Only”.
  9. Run Mode was set to “Continuous”.
  10. No Interrupt was selected.
  11. Click “Apply” and “OK” to close the Timer Configuration window.

image

Interrupt Sub-Routine (ms_ISR)

An ISR component was connected to the TC output of the counter to interrupt every millisecond.

image

  1. In PSoC Creator, click and drag an ISR component into the design from the Component Catalog.
  2. Connect the ISR to the TC output of Timer_1.
  3. Double-click on the ISR component and rename it “ms_isr”.
Example Code

Download the following PSoC Creator example project to demonstrate Coordinator API operation in a multi-node network.

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]

image

  1. Save and close the “.cydwr” file.
Coordinator

The Coordinator XBee module was connected to the host microcontroller through the PSoC4 Pioneer Board and the Arduino Wireless shield. 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 on the 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.
  1. Plug the Arduino Wireless shield to the PSoC4 Pioneer Board. Ensure the ‘Serial Select’ slide switch is set to ‘Micro’.

  2. Plug an XBee module into the Arduino Wireless shield.

  3. Connect the board to an open USB port of the PC using a USB mini-B cable

Routers

Two Routers were used in this project to achieve a multi-node ZigBee network. The Routers were connected to a breadboard using the Parallax XBee/Breadboard adapter boards. Thumbwheel potentiometers were used to create two separate 0~1.2V variable voltage dividers. The potentiometer outputs were then connected to ADC0 input of each respective Router. A bench supply was used to power the breadboard. Figures 1 and 2 below show a photo and schematic of the remote module connections.

image

Remote Node (Router) Setup

Remote Node (Router) Schematic

Resistors R1 and R3 were used to limit the max voltage seen at Pin20 of the XBee modules. Their value was set such that the max voltage across R2 and R4 was 1.2V. The following equation was used to calculate the value of R1 and R3:

image

The max value of R2 and R4 is approx 10kΩ. Therefore, for a voltage of 3.3V, R1 and R3 must be approximately 17.5kΩ. This ensures that the voltage at Pin20 does not exceed 1.2V. Some error will be introduced once the devices are connected in parallel with each other. Another source of error is caused by the max value of each potentiometer not being exactly 10kΩ. Resistors R1 and R3 shown in the schematic above, were actually potentiometers as shown in the photo. Using an ohmmeter, the value of R1 and R3 was set to 17.5kΩ. R2 and R4 were set to their max value of approx 10kΩ. A volt-meter was used to measure the voltage at Pin20 upon power up and the resistors R1 and R3 were adjusted slightly until the voltage at Pin20 was 1.2V. Once the values of R1 and R3 were trimmed properly, they were considered “fixed” resistors and remained untouched. R2 and R4 were then used to adjust the voltage at Pin20 to simulate an analog sensor.

Testing the Example Code

  1. Configure the modules using X-CTU software as shown above. Record the Serial ID of each remote node. The example code will need to be modified to transmit to these nodes.
  2. Connect the Routers as shown above. Provide 3.3V to the breadboard.
  3. Connect the Coordinator as shown above. Ensure the ‘Serial Select’ slide switch is set to ‘Micro’.
  4. Open the XBee_API_Example project provided above using PSoC Creator 3.0.
  5. Navigate to main.c and modify the Router addresses:
  • Towards the top of main.c you will find two arrays called const uint8 router_1_id [ ] and router_2_id[ ] .
  • Modify the content of these arrays to match the Serial ID of your Routers.
  1. Build the project and program the PSoC controller.
  2. Open a Tera Term window.
  3. Navigate to Setup → Serial Port, and verify the following settings:
  • Select the port corresponding to the Pioneer Board (may have to wait for driver to finish installing)
  • Baud Rate: 115200
  • Data: 8-bit
  • Parity: None
  • Stop: 1 bit
  • Flow Control: None
  • Transmit Delays: zero
  1. Press “OK”
  2. Press SW2 on the Pioneer Board to print the start-up header and instructions.
  • If nothing prints, try resetting the Pioneer Board and press SW2 again.
  1. Press SW2 to take ADC readings from the remote modules.
  2. Adjust R2 and R4. Press SW2 again to see how the ADC reading changes between 0 and 1200mV.

image

Comments from the Author

The provided example code can be used freely. However, it has not been tested comprehensively. Currently, no error handling exists, except to drop the frame and retransmit. 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 a simple 3-Node ZigBee network with a Coordinator in API 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. Add code to support additional frame types that are currently unsupported. 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!