A Quick Note About API Modes
Setting Up API Modes
XBee Thermometer Part 2
XBee Thermometer Part 3
Using XBee Broadcast
More About XBee Broadcast (BEWARE)
Using the Arduino XBee Library Part 1
Using the Arduino XBee Library Part 2
Using the Arduino XBee Library Part 3
Integers, Floats, and Such Over XBee
XBee Pool Controller
XBee Acid Pump Timer
Monitoring My XBee Network
Raspberry Pi and XBee Part 1
Raspberry Pi and XBee Part 2
If Things Don't Work Right
There's about a million tutorials on XBee devices on the web and I'm not going to rehash other people's work in this area. The problem is that they seem to repeat themselves too much, and many times the examples only work once. You reprogram the radio and the system stops working. I had this happen several times and finally almost threw them in a box on the shelf in pursuit of something that actually worked. Blind stubbornness helped me overcome all the problems I ran into and I can now make them work. Not that I have a huge sophisticated network, but I can make them talk to each other.
First, some things that you need to know that aren't mentioned:
- The router and end devices have to be commissioned into the network. This has to be done every time the coordinator is reprogrammed. This takes 4 pulses on pin 20. This is because the data that is used to communicate is lost during the reprogramming process.
- When the commission finishes, the NI parameter (name) is blank on the router, the router must be reset to restore this. Of course you can reprogram the name back into the router as well
- The best software that I have worked with so far is ZigBee using a XB24-ZB modem. This is one of the choices offered by X-CTU
- A network reset (ATNR 1) will blow off all the devices on the network and you have to recommission each of them.
- The coordinator has to be running for the router and end device to commission into the network. So, start the coordinator first then commission the various routers.
OP Read the operating 64-bit PAN ID.
OI Read the operating 16-bit PAN ID.
CH Read the operating channel.
ZS Read the stack profile.
Now, most of us don't mess with the ZS command and zero seems to work fine so I leave it alone. The OI is set by the coordinator and we don't get to choose it when we first start up. The CH (channel) is also chosen by the coordinator. The only one we are usually told to mess with is the OP when we set the ID. So, what you have to do is record these when you get a working network and then keep them around to fix the network when you reprogram a coordinator or accidentally issue a network reset.
So let me illustrate how you can reprogram a coordinator node and then get the network back up and working. The assumptions are that you have:
- Two or more XBees already working in AT mode - this is the 'transparent' mode where you issue commands to the modem using some terminal program or X-CTU itself.
- These little guys are running Zigbee software with the modem set to XB24-ZB. The particular set is dependent on what the XBee's role is: Coordinator, Router or End Device. For simplicity I'm just going to consider coordinator and routers.
- Since you have already gotten a network set up, you've already come up with a way to talk to them using some terminal program or X-CTU. Remember, if you have two or more unused USB ports you can plug them into your computer and use multiple instances of X-CTU to control and monitor the devices.
ATOP (returns up to 16 hex digits for example 1234)
ATOI (returns up to 4 hex digits for example ABCD)
ATCH (returns the actual channel being used, 1 hex digit for example C)
ATZS ( returns one hex digit, usually zero)
Each of these will return a value that is necessary to a working network. So after reprogramming the coordinator to something (usually going from API mode to AT mode) you have to put these values back in. However, you don't just use the same command, since most of these are read only values. The commands below are used to put the values back into the reprogrammed coordinator:
ATID 1234 - this sets the PAN to the value you read from the OP parameter above.
ATII ABCD - this sets the initial operating 16 bit id to the value read from the OI above
ATZS 0 - this sets the stack profile as above (this is not a read only value)
ATSC 2 - this is a bitfield that specifies the channels that may be scanned. 0x02 allows
only the channel 0x0C to be used. This prevents the coordinator from moving
off the channel.
If you want to be sure the values get recorded to eeprom, issue the ATWR command, but the commands above should save the commands. I always do the write command because I want to be darn sure it worked.
As you issue these commands, the coordinator will exit the network and rejoin allowing the various other devices to join as well. After completing the commands the coordinator is running on a known set of network parameters and can be troubleshot without nearly as much difficulty. If you happen to notice, the ATII command is not documented in the command references that you find. It is documented in the Digi documentation under replacing the coordinator. This was hard to find and solved most of my problems when I came across it. Look in:
Regarding the routers, the easiest way to program them is to ground pin 20 on the XBee 4 times like you are pushing a switch. This will tell the device to leave the current network and rejoin. This process is called commissioning. The device will flash a couple of lights if you have them and join the network you just set up on the coordinator. This is how you add a new device and make sure it can talk. You can also program the router in the same fashion as above to make it join. There's also the command ATCB 4 that will cause the same action as grounding the commission pin.
Power cycles, unplugging, hardware resets (like grounding the reset pin) don't change the settings and the devices will work fine under these conditions. The problem now is that going from AT mode to API mode will always cause the coordinator to lose these items and they cannot be set with at commands because you just switched modes and typing AT commands doesn't work. This is the situation where I was ready to stomp a couple of the devices into fine dust on the floor.
I put together a simple script to work with Xbees in API mode and observe the various actions. You're welcome to grab it and modify it to your needs. This script was thrown together in a hurry and has the bare minimum necessary to command and observe the devices, don't expect massive sophistication or features. One thing that is not made clear in a lot of tutorials is that every device doesn't have to be in API mode. If your coordinator is running in API and the routers all in AT, the network will work just fine. So you can move into higher levels of sophistication at your leisure. A couple of things to note: I did not use the Arduino XBee library, that thing is just too darn hard to understand for me. Also, I used NewSoftSerial version 10C (in case you have trouble compiling). This allows me to have the XBee and the serial port active at the same time. Let's face it, switching the programming serial port around every time you test something slows testing down too much. http://arduiniana.org/libraries/newsoftserial/
There's a confusing paragraph in the Digi documentation for the Series 2 devices. Around page 99 under the description for the two API modes they say:
Escape characters. When sending or receiving a UART data frame, specific data values must be escaped
(flagged) so they do not interfere with the data frame sequencing. To escape an interfering data byte,
insert 0x7D and follow it with the byte to be escaped XOR’d with 0x20
Most people read this as requiring both API modes to escape the special characters. Not true. You only have to escape the special characters if you're using API mode 2. This is to allow the XON and XOFF ascii codes to be used for flow control. I haven't tried flow control with an XBee yet, so I don't know if it will work. So, using API mode 1 will allow all the features and you don't have to worry about escaping the special characters.
One other thing that isn't made clear in the documentation or any of the how-to guides I've looked at. You can mix and match API mode and transparent mode on these devices. For example the XBee I use to monitor what is going on is configured for transparent mode and it can see the broadcast sentences from every device broadcasting just fine. The packet headers and such are stripped off and the data is delivered out the serial line. This is a nice way to see what is going on over your network.
Additionally, you can mix API modes. A device using API mode 1 can talk to another device running API mode 2 just fine. So, however you have a device set up in terms of the API mode, it can talk to the other devices on your network. This is nice if you're updating your network and have some devices in mode 1, others in transparent and yet others in API mode 2. This is actually the state of my network right now (Feb 11, 2013) because I'm updating to use the Arduino XBee library in various devices. Right this second, the Pool Controller <link> is using transparent mode; the Acid Pump is using API mode 1, and the House Controller is using API mode 2. Eventually, they all will be using API mode 2 and the XBee library.
Update, July 7, 2012: I finally carried through on my threat to build an enclosure for this device and put it into permanent operation. It is working all the time now measuring the outside temperature. This makes the graph above accurate for local temperature and trends. The description of what I did is here <link>.