Wireless Firmata using XBees

There seems to be a fair amount of interest lately in using XBee to create wireless Firmata client applications. In such a setup you’d have a single XBee radio connected to a computer running the Firmata client application (we’ll refer to this XBee node as the “coordinator”). You’d have a second XBee connected to your Arduino board (we’ll refer to this node as the “end point”). There are obvious advantages here if you making anything that moves, flies or would otherwise be constrained by a physical serial link. I’ve been using XBees with a couple of different Firmata client libraries (funnel.cc and BreakoutJS) for few years so I figured I’d share my knowledge of configuring XBees and the issues presented by using XBees in Firmata-based applications. But first it helps to have an understanding of the Firmata startup sequence.

Firmata Startup Sequence

Before we get into XBee configuration, it’s important to understand the Firmata startup sequence and whether or not your Firmata client relies on certain messages sent during the startup sequence.

If you load StandardFirmata onto an Arduino board and look at the on-board blink LED (connected to pin 13 on many boards) when you reset the board, you’ll see this LED blink rapidly, then after a brief pause you’ll see it blink 3 times followed by a short pause and then it will blink 2 or 3 more times (depending on which version of StandardFirmata you have loaded). You will then see the TX led blink rapidly. So what is happening here?

The initial set of blinks is the Arduino starting up. This happens before StandardFirmata even runs. You’ll see this with any Arduino sketch you run.

The following set of 3 blinks begins when Firmata.begin(57600) is called within StandardFirmata (or any other Firmata sketch for that matter). The first blink of this sequence occurs because the Arduino starts up with all digital pins initialized to INPUT (this causes the blink LED to illuminate, then StandardFrimata starts and initializes all digital pins to OUTPUT which turns the blink LED off. So that first blink doesn’t mean anything. The following 2 blinks indicate the Firmata major version (2 in this case).

The final sequence blinks indicate the Firmata minor version (either 2 or 3 depending on the version of StandardFirmata you have loaded). The entire Firmata blink version sequence takes a little over 1.6 seconds to execute and this does not include the time of the general Arduino startup blink sequence.

After the startup blink sequence completes, 2 Firmata messages are sent (this is the blink sequence you see on the TX line immediately following the pin 13 blink sequence). First a REPORT_VERSION message is sent [0xF9, 0x02, 0x03] (assuming Frimata v 2.3) then immediately after a REPORT_FIRMWARE message is sent [0xF0, 0x79, 0x02, 0x03, a 7 bit pair for each char in the filename, …0xF7].

What does this have to do with using XBees?

There are several things to be aware of here. The most important of them is to understand that when you make a new serial connection from a Firmata client application your Arduino board is reset. This is because the DTR (Data Terminal Ready) pin is wired to reset the Arduino and the DTR pin is toggled when a serial connection is made (hence the data terminal is now ready). This is standard among all newer Arduino boards that support automatic reset when loading a sketch (in the earlier days of Arduino you had to physically press the reset button on the board prior to uploading a new sketch… the DTR hack automates this). See this link to determine whether or not your Arduino board is using auto-reset (it most likely is). You can also just create a serial connection from your Firmata client and look at the onboard (pin 13) LED. If it executes the entire blink version sequence, then the serial connection is automatically resetting your board.

So you make a serial connection, the Arduino board is automatically reset and the startup blink sequence occurs. What is important to note here is that during this startup sequence you cannot reliably send any Firmata commands to the Arduino board. During the blink version sequence the UART is capable of receiving serial data in the background, but the processor will not be able to send a response until after the sequence has ended so consider this unreliable. What many Firmata client implementation do to ensure the board is “ready” is to listen for the initial Firmata version and firmware messages. Once you receive the final END_SYSEX (0xF7) byte you know that Firmata is in the “ready” state.

Now the issue with using an XBee wireless link is that your Arduino board is no longer connected to your computer (and well, that’s the whole point of using XBees in this way). This means you’re now making a serial connection with the XBee explorer board connected to your computer rather than directly to your Arduino so when the connection is made, the Arduino board will not be reset automatically and the startup sequence will not run. At this point if the Firmata client you are using is waiting for the Firmata version and firmware message as a ready indicator, it will not get them because the Arduino will not be reset automatically. Now we see where the issue is…

This is not an issue with all Firmata client libraries. It is only an issue with those libraries that rely on the Firmata version messages (which is likely most Firmata client libraries that connect directly via serial vs using a serial proxy). What this means is if you are using one of those libraries you will either have to physically reset your Arduino board after making a new serial connection (not ideal) or you can configure the XBee connected to the computer to send a signal to the XBee connected to the Arduino to cause the Arduino to reset. This however can introduce additional timing issues depending on how quickly your Firmata client application attempts to communicate with the Arduino. For example if the client application sends a message this is missed due to the Arduino hard reset and the response is never sent (because the Arduino is resetting) then you client application may hang. So some Firmata client implementations may require tweaks if timing becomes an issue. So now you can see the challenge before us.

Configuring XBees to support automatic reset

What you will need:

XBee USB breakout board.

I’m using an older rev of the Sparkfun Xbee Explorer USB board, but any of the following should work:

• XBee Explorer USB or XBee Explorer Dongle
• USB XBee Adapater
• XBee Adapter kit – v1.1

Arduino Fio (recommended) or Arduino with XBee shield

If you would like to use a standard Arduino rather than an Arduino Fio and don’t currently have the XBee shield, XBee radios and explorer board, you can save a couple of bucks buy purchasing the XBee Wireless Kit from Sparkfun. However I highly recommend an Arduino Fio since it has been proven to work with the configuration described in this article while the XBee shield auto reset has not yet proven to be successful.

2 Series 1 XBee radios

You have a few options:

• Series 1 with Trace Antenna (if you have the older chip antenna version, that works as well)
  
• Series 1 with Wire Antenna (sparkfun)
• Series 1 with Wire Antenna (adafruit)

This tutorial is written specifically for Series 1 radios, if you already have Series 2 XBees you may not be able to get auto reset to work (but please ask Google… someone may have figured out a way).

XBee Configuration

Step 1: Verify XBee firmware version for each radio.

The first step is make sure your XBee firmware is up to date (it should only be out of date if it is several years old). If you’re using an older XBee radio, you’ll need to be sure the firmware version is at least 10A5. In order to check the firmware, we’ll need a terminal emulator  (or use a GUI such as X-CTU which is not covered in this tutorial or you could even write a script to execute the appropriate commands). I’m only going to cover the use of CoolTerm (which is also applicable to other terminal applications).

Note OS X users that the standard Terminal application will not work. You’ll need CoolTerm or similar instead.

Note Windows users, you have to make a slight change to the driver preferences. In the Device Manager, select the USB COM port. Then right click and select Properties. Click on the Port Settings tab, and click on Advanced…, then make Set RTS On Close is selected and click OK to apply settings. (these instructions copied from http://arduino.cc/en/Main/ArduinoBoardFioProgramming)

You can download CoolTerm here: http://freeware.the-meiers.org/

Once you have CoolTerm installed, attach your XBee explorer board to your computer and launch CoolTerm. You’ll first want to change a couple of settings. Open the Connection menu and select Options. Under the Serial Port option, select the Port that your XBee explorer is connected to. The tricky part is the Baudrate. If you have a brand new XBee, select 9600. If you have a used XBee and are unsure what the baud rate is, you’ll need to experiment, trying each baud (although 9600, 19200, 57600 and 115200 are the most likely suspects) until you can connect. If you are unable to connect at any of the baud rates it’s possible you may have a bricked Bbee (you can unbrick it however, see this instructable). While you’re still in the Options menu, select Terminal and check Local Echo and from the Enter Key Emulation radio group, select CR. That will enable you to see the characters you type to send commands to the XBee.

Close the Options menu and click on the Connect button in the CoolTerm home menu. You should see the name of the port your XBee is connected to and the Connected time in the footer.

Open CoolTerm, connect to the XBee and follow these instructions:

1. Type +++ to enter command mode. You should see a response of OK
2. Type ATVR and press Enter. This will print the version. If the version is less than 10A5 (hex) you will need to update your firmware. This is a more complicated process and the only way I’ve done it is using the X-CTU application in Windows. See these instructions. If you do not get an OK message after typing +++ or you do not get a version after typing ATVR, double check that you have selected the correct serial port, and baud rate for you XBee.

Step 2: Set baud rate for each radio to 57600

If the baud rate for your XBee radios is already set to 57600 you can skip this step.

The next step is to set the baud rate for each XBee radio. Out of the box they are configured at 9600 baud. Firmata uses 57600 baud so you’ll need to determine the current baud rate configuration of your radios (I’ve you’ve been using the for a while) and change the baud rate if you have brand-new radios.

1. Type +++ to enter command mode. You should see a response of OK
2. Type ATBD and press Enter. The response will be a number that corresponds to the baud rate. The default baud rate of 9600 will be reported as 3. We want 6, which is 57600 baud.
3. If the ATBD command does not return 6, set it as follows:
4. Type ATBD 6 and press Enter to set the baud rate to 57600.
5. Type ATBD and press Enter to confirm that you get a response of 6
6. Type ATWR and press Enter to save the configuration.
7. Return to the CoolTerm Connection menu -> Options and set the baud rate to 57600.

You CoolTerm window should look something like this:

Now that the correct baud rate is set, it’s time to move on to configuring the coordinator and end point radios.

Step 3:  Set up coordinator node

You need different settings for the coordinator and end point nodes. The coordinator is the XBee radio that is connected to your computer. The easiest way to configure it is to use the XBeeConfigTool. I’ve also included instructions for configuring from CoolTerm so skip down to that section if you prefer to keep working in CoolTerm.

Download XBeeConfigTool and uncompress it. XBeeConfigTool was built with Processing so you can either open one of the compiled versions (for OS X, Win32 or Win 64) or open the Processing sketch (XBeeConfigTool.pde). Linux users will need to use the sketch (.pde) version.

Connect an XBee explorer (with XBee attached obviously) to your computer then open the XBeeConfigTool application (or sketch) and complete the following steps:

1. Select the serial port your XBee explorer board is connected to.
2. For Mode, select “Programming radio”
3. Select 57600 for the baud rate.
4. Pan ID: The Pan ID should be unique for each XBee network. You should set this to the same value for both the coordinator and end point nodes. Leave as default if there are not other XBee users within range or enter any numeric value from 0000 to FFFF.
5. MY ID: Enter a unique ID for this node (the coordinator and end point nodes should each have a unique MY ID)
6. DL ID: leave this at FFFF (recommended) or set it to the end point’s MY ID.
7. Click the Configure button. If all goes well, after a couple of seconds (note there is no feedback during this time period) you should see the message “Configured successfully.” printed below the buttons. If not, make sure you selected the correct Serial port and that you had successfully set your XBee radio’s baud rate to 57600.
8. Click the Exit button.

Example coordinator node configuration (your specific values may be different):

Alternative: Coordinator configuration using CoolTerm

1. Type +++ to enter command mode. You should see a response of OK
2. Type ATRE, BD6, ID1234, MY0, DLFFFF, D33, IC8, RR3, RO10, WR and press Enter. You should see OK printed each time you enter a comma character. If you see the message ERROR instead, double check your entry (you may also need to disconnect then reconnect). You can also change the values for ID (must be same as end point), MY (unique) and DL (FFFF or end point MY value) rather than using the specific values in the string above.

 

Step 4: Set up end point node

Disconnect the XBee explorer board from your computer. Swap the XBee coordinator radio on the XBee explorer board with the XBee end point radio and reconnect the XBee explorer board to your computer (always disconnect before swapping radios). Launch the XBeeConfigTool and complete the following steps:

1. Select the serial port your XBee explorer board is connected to.
2. For Mode, select “Arduino Fio radio”
3. Select 57600 for the baud rate.
4. Pan ID: Enter the same Pan ID you set for the coordinator node.
5. MY ID: Enter a unique ID for this node (the coordinator and end point nodes should each have a unique MY ID)
6. DL ID: leave this at 0000 (recommended) or set it to the coordinator node’s MY ID.
7. Click the Configure button. If all goes well, after a couple of seconds (note there is no feedback during this time period) you should see the message “Configured successfully.” printed below the buttons. If not, make sure you selected the correct Serial port and that you had successfully set your XBee radio’s baud rate to 57600.
8. Click the Exit button.

Example end point node configuration (your specific values may be different):

Alternative: End point configuration using CoolTerm

1. Type +++ to enter command mode. You should see a response of OK
2. Type ATRE, BD6, ID1234, MY1, DL0, D35, IU0, IAFFFF, RO10, WR and press Enter. You should see OK printed each time you enter a comma character. If you see the message ERROR instead, double check your entry (you may also need to disconnect then reconnect). You can change the values for ID (must be same as coordinator), MY (unique) and DL (0 or coordinator MY value) as necessary.

 

In case your curious what some of these settings do, I’ll provide a brief explanation:

• D33 (coordinator): Sets digital pin 3 to a digital input.
• D35 (end point): Sets digital pin 3 to a digital output, defaulting to HIGH.
• RO10 (both): Sets packetization timeout to 10 to allow time to buffer data into packets.
• IC8 (coordinator): Sets mask to listen to change on pin D3. We’ll modify the XBee explorer board to tie RTS to pin D3 so the pin will change when the serial connection is made. This will relay the status of input pin D3 to the end point D3 output pin which will in turn reset the Arduino (because pin D3 of the XBee will be wired to the Arduino Reset pin) .
• IU0 (end point): Disables I/O output to toggle the D3 pin instead of sending the status serially.
• IAFFFF (end point): Configures I/O line passing to match all addresses.

NodeJS users: @reconbot is working on an XBee configuration script that should be able to perform all of the config steps automatically.

At this point your XBee radios should be set, but you’ll still have to make some modifications to your hardware to complete the process.

Hardware Configuration

Step 1: Solder jumper across pins RTS and D3 of your XBee explorer board.

This image if of a Sparkfun XBee explorer, but the Adafruit XBee boards also have these pins (Image from Arduino Fio Programming page on arduino.cc).

 

Step 2: Solder jumper between DI03 and Reset on XBee shield.

Note this step only applies if you are using an XBee shield. If you’re using an Arduino Fio, you’re all set and can jump down to the “Putting it all together” section.

These instructions are specifically for the Sparkfun XBee shield, but if pin DI03 of the XBee is broken out on other XBee shields you should (theoretically) be able to jumper that pin to the Arduino Reset pin as well. At this point however I have not yet seen auto reset work properly on this XBee shield with the configuration described in this article. However, the Arduino Fio works without issue when running the same Firmata client. This doesn’t mean that you can’t use this XBee shield, but that until the issue is resolved you’ll need to perform a manual reset after the firmata client application creates the serial connection. If you are finding that the manual reset is not working, then you may want to look into the Firmata client’s startup implementation (keeping in mind the Firmata startup sequence described at the top of this post).

One possible solution to the XBee shield auto reset issue could be in changing the D3 pin configuration for the end point radio from D35 to D34 (in case the reset pin is wired differently on the Arduino Fio than on the XBee shield). I don’t have an XBee shield to test with but if someone gives that a try and it works, please let me know. I’ll update this section once a working solution has been identified.

If you have a Sparkfun XBee shield, solder the jumper highlighted in the image below (image copied from Sparkfun XBee shield product description). Note however that auto reset has not yet been proven to work with this particular shield even when the jumper is soldered.

 

Putting it all together

Attach the coordinator XBee to your XBee explorer board and attach the end point XBee to your Arduino Fio board or your Arduino XBee shield (depending on your setup). You should now be able to use Firmata wirelessly (but may only be able to auto reset properly with the Arduino Fio until the XBee shield issue is resolved). If after creating a serial connection in the client application you see that the Arduino is not resetting automatically, try to manually reset the board. If a manual reset works you may need to investigate the firmata client startup sequence to be sure that no commands are being sent while the Arduino would be resetting. In this case a delay may be needed after the serial port connection is made before sending any commands to the Arduino.

My setup

XBee configuration can be a frustrating experience (I’ve learned this the hard way). I’ve only tested a very specific setup (Arduino Fio with Sparkfun XBee Explorer USB board and Series 1 XBee radios) so there is a chance that this guide may not help you since I cannot test every possible setup. I’ve included links to some additional resources below that may be useful if you run into any issues or just want to further explore XBee configuration options.

Additional Resources:

Miscellaneous XBee guides and tutorials:

Sparkfun XBee guide: https://www.sparkfun.com/pages/xbee_guide

Bildr XBee tutorial: http://bildr.org/2011/04/arduino-xbee-wireless/

XBee series 1 documentation: http://www.digi.com/support/productdetail?pid=3257&osvid=0&type=documentation

Arduino Wireless Programming:

Adafruit tutorial: http://www.ladyada.net/make/xbee/arduino.html

Arduino.cc tutorial: http://arduino.cc/en/Main/ArduinoBoardFioProgramming

Funnel.cc tutorial: http://funnel.cc/Hardware/FIO

Additional XBee configuration tools:

There are a couple of other popular tools for XBee configuration. You can find tutorials by googling either of them. I use X-CTU (via windows running in a VM) for more complex tasks such as unbricking an XBee.

X-CTU (windows only)

If you have a windows box or windows running on a virtual PC you can download the X-CTU software (expand Diagnostics, Utilities and MIBs and click on the XCTU var. 5.2.8.6 installer link). This is software provided by Digi to configure XBee radios. If you already have an older version installed, make sure you download the latest version. A quick Google search on “X-CTU configure XBee” will turn up several helpful tutorials.

X-CTU User’s Guide: http://ftp1.digi.com/support/documentation/90001003_A.pdf

moltosenso Network Manager: Iron 1.0 (OS X, Linux and Windows)

Has similar functionality to X-CTU but it’s cross platform. You can download the application here: http://www.moltosenso.com/client/fe/browser.php?pc=/client/fe/download.php. See moltosenso’s youtube channel for tutorials: https://www.youtube.com/moltosenso.