Processing

I'm on show schedule now, which theoretically means I have a little time to get back to ongoing projects. It works out more like a four-day weekend, though, with the 40-hour work week condensed into several twelve-hour days. Plus meetings, rehearsals, brush-ups, school matinees, and of course ongoing repairs and maintenance.

So every time, as much as I look forward to going on show schedule, I end up burning all that "free" time in errands and catching up on sleep. And then feeling guilty for not getting more accomplished on outside projects. Such as my -- very slight -- progress in theater electronics this "weekend."




I've been learning about the Xbee. These are small digital radio transceivers that can be built into a number of theatrically-useful projects.

The Xbee itself is one implementation of the greater Zigbee standard, which was dreamed up by the Zigbee Alliance as an implementation of the 802.15.4 standard for wireless networks. Specifically, Zigbee is designed for low data rate, low battery usage, and flexible network topologies; it was intended for applications like remote monitoring and home automation.

XBee is a brand name from Digi International, for a series of inexpensive transceiver modules sharing an identical form factor. The later modules incorporate more of the Zigbee protocols, especially the security measures.

You can get an Xbee module for under twenty bucks US at many vendors, including SparkFun, Adafruit, and of course Digikey. The Series 1 modules come out of the box set up for point-to-point bi-directional buffered serial communication at 250 Kb/s and an indoors range of about 30 meters. The "Pro" version of Series 1, with a radiated power of 100 mW, extends that to 100 meters.

Most of them are in the 2.4 GHz range, which is getting increasingly crowded, but the modules are fully addressable and designed to work with poor conditions; depending on how they are configured they will re-transmit, or even seek out a clear channel in which to communicate.

In the basic point-to-point configuration, they are basically invisible; treat it as a cable from one serial port to another (a slow cable, but anyhow...!) This by itself makes it simple to wirelessly connect the micro of your choice to a computer, or rig a wireless MIDI or DMX connection, but the power of these devices does not stop there.




Of course it is never quite that simple. The Xbee's are 3.3v devices (like the Lilypad wearable computer, and an increasing number of Arduino compatibles), but worse (from a hobbyist standpoint) is while they are through-hole devices, the pin spacing is 2mm.

So while you could solder to one, to make it easier to breadboard and otherwise connect to the rest of the world, you want some kind of breakout.

These range from the basic pin breakout (such as the one from NKC Electronics) to a variety of breakout boards with built-in 3.3V regulators and level shifters (so you can connect to micros and other devices with a 5V logic level -- Adafruit as usual has a nice inexpensive one in kit form -- all the way up to an Arduino XBee shield and to the Xbee Explorer USB (available from several manufacturers and vendors) which breaks your XBee out into a USB connection your computer can see.

I am using two Series 1 modules to experiment with at the moment, with one of them on a SparkFun Xbee Explorer USB, and the other on Lady Ada's XBee Adapter, which in turn is connected to an Adafruit FTDI Friend (a small breakout board for the ubiquitous FTDI USB-to-Serial chip, which also includes a mini-USB jack and on-board level-shifting and even a 3.3V regulated power supply!)

And, horribly, it took me ten hours just to confirm that the modules were actually sending clean serial from one to the other.




Why? Well, therein lies the story behind the title of this entry. The various USB devices are actually serial devices which smuggle themselves in through the USB port. You can talk to them using something like OSX's Terminal application. But there are...difficulties.

The first step in Terminal is the command "ls /dev" which will print out a list of all devices connected to the Mac. Look for something like "cu.usbserial-A6007uEn" -- you don't want any of the "tty" devices.

Then a command like "screen /dev/cu.usbserial-A6007uEn" (use the actual device name you found in the list) will connect your terminal window to the USB connection to the XBee -- anything you type will be sent to the XBee and vice-versa.

You will notice a problem right off -- the XBee sends a carriage return, not the new line character the Mac is expecting, meaning your cursor stays right in the corner and everything you or the XBee writes piles up on top of itself.

Oh, sure, you can still work like this. But it is annoying!

Sure, it would probably be simple to write a quick runtime command in the Terminal that would parse the text correctly. But I'm not exactly a programmer. Dealing in naked UNIX like this is a bit much for me.

So I turn to, first, work that has already been done for me. Tom Igoe, he of "Making Things Talk," (the great introductory book on sensors and communications for microcomputing) wrote a nice little terminal application for communicating with XBee modules.

Unfortunately the version I found -- a later, more updated version -- had the wrong kinds of bells and whistles.




You can communicate with the XBee merely by sending it serial data, and it will (if it is in the right mode) faithfully transmit that data to any devices configured to listen on that network and channel. However, to get full value out of your XBees you want to be able to enter Command Mode.

Digi International of course distributes, free, the program X-CTU -- which is the only way (unfortunately!) to update the firmware in the XBee modules.

However, other functions are as easy to get to as entering Command Mode and then typing the appropriate strings. The pdf guide is probably sufficient for someone with the time to wade through and understand what they are reading, but...!

To enter Command Mode, type "+++" and wait one second. Do not hit "Return!" After one second, the module will enter Command Mode, and will stay there unless thirty seconds goes by without an additional serial entry (at which point it will go back to normal operation).

All the commands are suffixed "AT." The most useful that I've found, so far, are;

ATMY -- the node's personal ID code.
ATDL -- the second (low) bit of the ID code of the node it wants to talk to.
ATID -- the PAN ID#; a 2-digit (hex) unique identifier of the network your node belongs to.
ATCH -- the channel your node is using.
ATRE -- restore node to factory defaults
ATWR -- write the current settings to non-volatile memory (otherwise they will be lost when you disconnect it from power).
ATCN -- exit Command Mode.

Not all of these commands take a data byte. In the case of ATWR, say, execution is immediate. If you send, however, "ATMY" the node will return the current value for the personal ID#. If you want to change it, follow "ATMY" with a value, aka "ATMY2" in order to set the ID to "2."

You can easily burn up an hour just messing around querying your devices, changing their settings, querying them again, and so forth. But, as I said, doing it in Terminal can be annoying.



The Rob Faludi-modified Tom Igoe program now known as "Xbee Terminal Max" is very cute. As you type a command, it automatically puts in the "+++," test to see if the node is in command mode, and at the end of each command automatically issues "ATCN." This makes changing the units settings a breeze.

It also means that it suppresses display of the serial communication I was looking for in the first place!

So I went back to the original Tom Igoe program as written up in "Making Things Talk" and entered it by hand. Writing programs out by hand is actually a great exercise. It makes you think about each line, about the syntax, about the purpose of it. Just like many comic book artists first learned by tracing, and composers learn by performing, typing out another person's program can help you learn to program.

The programming environment in this case is Processing.

Processing is part of the same ball of wax that contains Wiring, and the Arduino IDE. It is, in short, an artist-friendly wrapper for Java. The advantages for a project like this is, like the Arduino IDE, it is free and open source, and manifests as a friendly little "Sketch" window, where you can jot down a simple program and then either run it or generate a stand-alone Java ap right from the programming window.

This is not CodeWarrior. This is not about version control and extensive debugging modes...it is about quickly cobbling up something and running it. Processing has a number of built-in and third-party libraries, but the downside is that most of them are oriented towards graphics, video, 3D rendering, machine vision -- stuff the computer-based visual performance artist wants.

However, one of those third-party libraries is a nice simple serial library that makes building a basic terminal in Processing relatively simple.

(I say "relatively" because I had to borrow the code from Tom. I could monkey with it (pun intended) but I am not quite up to speed enough on Processing yet to write something like this from scratch.

Of course there were bugs. I'm going to assume neither Tom nor O'Reilly Media made any errors (I've met Mr. O'Reilly, actually -- at the East Bay Mini Maker's Faire). So the errors were in my transcribing, and in any changes to Processing core or the attached libraries since the code was written down.

Fortunately I already knew the nodes worked (I'd been sending them commands and getting back good replies). And there are status LEDs on the Xbee Explorer USB (yay for blinkenlights!) So I knew my serial messages were getting in, and I even could confirm it had entered Command Mode on the appropriate "+++" prompt.

So it was the usual method of commenting out suspect lines of code, and adding new print commands at various random places. My first hack of that kind was inserting at the very top of the function call "void serialEvent(Serial myPort)" a print statement to the order of "inString = "Serial Event Detected!"".

This is a great way of debugging simple programs. Put in print events that will put something -- the current value of a loop counter, the expected return from a function call, etc. -- on the terminal. Then you can see if the program made it that far, and if what it is doing at that point is what you expected it to be doing.

Anyhow, the inserted line popped up and I knew the XBee was trying to talk to me. At that point it only took another twenty minutes of debugging to track down the remaining errors and to get the terminal application I was writing to properly display the serial output of the XBee node.

At which point I could clean it up a little (inserting some carriage returns and stuff), export a stand-alone java ap, load that ap up on my laptop, and start sending random strings from one computer to the other via the airwaves.



Okay, and part of why it took the better part of a couple of days (that time not spent at the gym, getting groceries, or catching up on sleep) is that while the Xbee Explorer USB worked like a charm, I had to mess around with the connection on the other unit. First, there was a confusing legend on the XBee Adapter. The "Power" LED doesn't light when the unit is getting good power through the regulator; it is actually showing received RF strength! The "Activity" LED is, also, reversed with the Power LED. It took a while of tracing wires and messing around with a VOM before I was sure the breakout board was properly wired and functional.

Then the pinout did not match that of the FTDI Friend, meaning I couldn't just put one into the other but had to run jumpers. The node confirmed it was getting power and even that it could see the other node -- once I understood what the activity LEDs actually meant! -- but it wouldn't reply to serial prompts.

The mistake appeared to be using the provided 3.3V setting on the FTDI Friend. I changed the jumper settings on the FTDI Friend to use 5V logic level instead, and changed the pins I was using on the Xbee Adapter to go through the onboard level shifter instead. And at that point the XBee finally picked up and started answering commands.



And, well, now I'm now into the next show weekend and I'm not sure what I'll get done for the next few (twelve hour) days. Except for one thing -- I mean to borrow a PC laptop just long enough to run X-CTU and upgrade the firmware. Neither of my modules have the firmware version that implements a very, very useful function for remote monitoring; the functions that turn some of the pins into AD converters. Meaning you can hook an analog sensor into an XBee node, and with no additional circuitry but a 3.3V regulator, you have a remote sensor.

And this is exactly what I want for my digital trigger finger project.