How to use an xBee Series 1 in API mode

Gathering Parts

The first thing I did was dig through my boxes of carefully collected (but not so carefully stored) junk to see if I could borrow parts from anything. As it turns out, I had 3 original Xbox controllers that have fairly common, and fairly inexpensive analog joysticks in them. The way the controllers are designed, removing them was dead simple.

I took my trusty multi-meter and went about seeing their resistances. After determining this, I attached them to an Arduino’s analog input pins and wrote some code to read the value from the pin, map it to the servo’s preferred range and output it to the serial console. Success!

My background in R/C electronics isn’t that strong so it took a while to find a local hobby shop that would have spare parts. As it turns out, hobby shops seem to be something of a dying breed. After about 45 minutes of driving I found a shop that sold HiTek hobby servos with metal gears inside rated for quite a bit of torque. These will be excellent for interfacing with the hydraulic controls on the lift itself.

Interfacing with an Arduino

I included the SoftwareServo library for the Arduino to my sketch and hooked up the two servos to 2 digital pins on the Arduino. Everything worked as I’d hoped; each joystick’s vertical movement perfectly corresponded to the movement of the horn on the servo. There was just one problem; the controls were tethered to the circuit controlling the servos.

I did a little digging and found the xBee, a small radio that’s capable of transmitting up to 8 lines of input across a RF serial modem. For around $20 from sparkfun you get a lot of ability. The xBee runs on 3.3v and I wanted it to be portable so I also ordered a 3.3v Li-Po battery pack.

Understanding the xBee

By default, the xBee operates in a mode that I could see being useful in some applications, just not mine. Basically, the input pins of one radio can be mapped virtually to be output pins on a receiving radio. For example: you have a switch hooked up to DIO0 on one xbee and a LED hooked up to DIO0 on another. In this pin-mapping mode, if the radios are programmed correctly, you’d press the button on the sending radio and the LED on the receiving radio would light up. Spiffy. It’s also got built-in analog to digital converters on a few of the inputs that convert the voltage range into values of 0-1024. The bad part about this is that these values map only to the PWM outputs of the xBee.

Enter API mode. In this mode, the values received via the radio are sent out the UART, serial port, of the xBee. The data follows this format:

For whatever reason, the documentation is wrong here. It says the API Identifier will be 0×81 but it’s actually 0×83. Also, the “Length” portion is actually of the “Sample Data” format above. This means for every sample “packet” the xBee receives, you’ll start reading at 0x7E and continue reading until you see it again. Despite how the first graphic looks, you won’t actually receive the header. I configured my xBee to send the status of all of the analog signals all at once so I didn’t really care about the length or the checksum bytes. If, like me,  you don’t have any of the digital I/O enabled, the analog data will be the only thing sent over. The ADC data is “represented as an unsigned 10-bit value right-justified on a 16-bit boundary.” I didn’t understand this at first so someone had to explain it to me. Basically you’ll get 000000XX XXXXXXXX where X is the actual data. In order to get this data, you’ll have to grab both bytes, shift the first one 8 bytes left and add the two values together. I got most of my understanding in code from this guy. His code is really flexible and allows for variable input. This is great if you’re not sure what’s going to come out of the other side, but in this case you will be.

Configuring the xBee

Enough about the code. Let’s configure the xBees. You’ll need a windows computer and some sort of interface to connect it to the computer. I used one of these. Digi makes a program called X-CTU that will allow you to update firmware as well as read and write configurations to/from the xBee. This instructable gives a bunch of information on this process with a lot of screen shots.

Better Examples

Here’s an example packet that would be sent: 7E 00 00 81 00 00 40 00 01 33 E0 Ignore the length and checksum in my example, they’re just placeholders. Let’s assume that we’ve got DIO0 set to ADC. In this example, the value passed from the xBee is 01 33 which converts to 000100110011 in binary or 307 in decimal. If you had all 9 inputs set as digital inputs, this value would mean that inputs 0, 1, 4, 5 and 8 were high and 2, 3, 6 and 7 were low. If you received the packet 7E 00 00 81 00 00 40 00 01 33 00 3F E0, you could tell that you either had two ADCs enabled or DIO and a single ADC. I won’t bore you with any more detail but if you have any questions or comments, feel free to drop a line at brian@cribbstechnologies.com