Sunday, January 8, 2017

Saturday, February 28, 2015

Remote Arduino Programming

It's 2015 and we've had Arduino for 10 years now, but there is still not a widely accepted solution for remote programming, so I'm doing something about it! Oh, and I'm on medium now, mostly.

Monday, October 28, 2013

RXTX on Mac with Oracle Java 7

I've been using RXTX on the mac for quite some time with the -d32 vm argument. This was necessary with 64-bit Java since the native libraries for RXTX are only compiled for 32-bit mode. Without -d32, you'd get the following error:

java.lang.UnsatisfiedLinkError: librxtxSerial.jnilib: no suitable image found

Apple had always bundled Java with OS X, but about 3 years ago they announced they would no longer do so. Now, to get Java 7 for the mac you need to get it from Oracle. Recently I tried running one of my RXTX apps with Oracle's Java 7 and I got the following error:

Error: This Java instance does not support a 32-bit JVM.

Please install the desired version.

It seems that Oracle no longer supports the -d32 vm argument. You can still run the Apple version of Java 6. The Apple bundled Java versions can be found in


For example:

$ /System/Library/Frameworks/JavaVM.framework/Versions/1.6/Home/bin/java -d32 -version
java version "1.6.0_37"
Java(TM) SE Runtime Environment (build 1.6.0_37-b06-434-11M3909)
Java HotSpot(TM) Client VM (build 20.12-b01-434, mixed mode)

So to run Oracle Java 7 we need a 64-bit version of RXTX. A few searches led me to Arduino article that mentions Robert Harder's blog post In this post Robert describes how he compiled RXTX for 64-bit Java (apparently not a trivial task). After downloading his librxtxSerial.jnilib it worked, the first time; the second time I got an exception:

“ Unknown Application”

This was super annoying since I didn't have any other Java processes running that had the port open. I read through the comments and found a solution:

sudo mkdir /var/lock

sudo chmod a+wrx /var/lock

Apparently RXTX needs this directory to manage locks. This was also mentioned on the Arduino article but I missed it the first time. It seems that the Arduino IDE must rely on Java 6 since the RXTX library that comes with the IDE is 32-bit. At some point I imagine (Java 8 perhaps), we'll see more interest in 64-bit RXTX. Please leave a comment if you have any insight on this problem and/or alternative solutions.

Sunday, June 9, 2013

XBee on the Raspberry Pi

When I first started writing xbee-api in 2007, there were no options for a cost effective, low power host computer with Java support. In 2009 I purchased a Sheevaplug ARM computer and that worked for a while but proved to be problematic: the power supply failed after a year (a known issue), and it experienced periodic boot errors. Last year I received a Raspberry Pi after a long wait, due demand far exceeding supply.

In order to run Java on the the Raspberry Pi it requires the soft-float version of Debian OS, available from the Pi website. Once you get your Pi up and running, you'll need to install the Oracle Java for ARM. I don't recommend openjdk as I found it to be much slower and buggier on ARM.

Update Java8 is available and although it says "jdk" in the name, javac is not present. Choose the following version from the above link:ejdk-8u111-linux-arm-sflt.tar.gz This works on my raspberry pi version 1, model B. This version includes a few binaries, I've been using the first with no issues:



There are several versions of Java for ARM on the Oracle site. The version compatible with the Raspberry Pi is ARMv6/7 Linux - Headless EABI, VFP, SoftFP ABI, Little Endian. The current release as of this writing is ejre-7u21-fcs-b11-linux-arm-vfp-client_headless-04_apr_2013.tar.gz.

Move the gzip file to your Pi and unpack

gunzip ejre-7u10-fcs-b18-linux-arm-vfp-client_headless-28_nov_2012.gz 
tar xvf ejre-7u10-fcs-b18-linux-arm-vfp-client_headless-28_nov_2012

I installed it in /opt/java

sudo mv -v ejre1.7.0_10/ /opt/java/

Create the symbolic link

cd /opt/java/ejre1.7.0_10/
sudo update-alternatives --install "/usr/bin/java" "java" "/opt/java/ejre1.7.0_10/bin/java" 1
sudo update-alternatives --set java /opt/java/ejre1.7.0_10/bin/java

Open .bashrc and set the JAVA_HOME environment variable

export JAVA_HOME="/opt/java/ejre1.7.0_10"

Now you should be able to execute java

java -version

And see something like

java version "1.7.0_10"
Java(TM) SE Embedded Runtime Environment (build 1.7.0_10-b18, headless)
Java HotSpot(TM) Embedded Client VM (build 23.6-b04, mixed mode)

Although the Pi has a GPIO serial port that is well suited for XBee, since it runs at 3.3V, I'm using a usb-serial XBee Explorer since I already had this hardware available and the configuration is less complicated. These can be found relatively cheap from Chinese vendors on ebay, or from a local supplier if you need it quicker. I'm using the SparkFun USB Explorer.

Install RXTX to provide serial port access to Java

sudo apt-get install librxtx-java

Now when you plug your XBee into the Pi, via USB, it should appear as /dev/ttyUSB0 and can be opened with xbee-api

XBee xbee = new XBee()"/dev/ttyUSB0")

Now, to run your xbee-api application on the Pi, you need to provide a few key arguments to Java.

java -Djava.library.path=/usr/lib/jni/ -classpath ".:/usr/share/java/RXTXcomm.jar" com.fooYourApp

The -Djava.library.path argument tells Java where to find the native RXTX library (JNI).

 If you exported your application from Eclipse into an executable JAR, use "*:/usr/share/java/RXTXcomm.jar" for classpath. This tells Java to load all JAR files in the current directory, in addition to the RXTX JAR. Alternatively, if you copied your Eclipse folder to the Pi, the classfiles are in the bin directory, so use "bin:/usr/share/java/RXTXcomm.jar". Of course replace com.fooYourApp with the package + class name of the main class. It's a good idea to put the full Java command in a script (e.g. Then make it executable with chmod u+x

Now modify add the non-root user that you run your apps to the group that owns the device. This is only necessary if you don't run as root:

ls -l /dev/ttyUSB0 
crw-rw---- 1 root dialout 188, 0 Dec 31  1969 /dev/ttyUSB0

Only root and the dialout group has read/write to the device, so add your user to the dialout group, ex:

sudo usermod -a -G dialout arapp

If you want your app to start every time the Pi boots, add the script to the do_start() function in /etc/init.d/rc.local

do_start() {
        if [ -x /etc/rc.local ]; then
                cd /home/pi/path-to-your-app && sudo -u pi nohup ./ &

I've been running my Garage Door XBee application on the Pi for about 6 months now and it has been very reliable. The only problems I've encountered so far were related to a failing power supply. When the voltage drops below 4.75, mysterious things can start to happen. My power supply dropped to 4.69 and I noticed periodic crashes.

I'm running my Pi with ethernet connectivity. The Pi can use Wifi but due to the limited current supply of the USB port, it only works with a select number of Wifi chips. Perhaps later versions of the Pi will supply more power to the USB to overcome this limitation.

In a future post I'll show how to interface the Pi's GPIO Serial port directly with the XBee UART.

Saturday, October 1, 2011

XBee/Google Talk Garage Door

I had been thinking about doing a garage door controller project for years, but never found the time to work on it.  On occasion I had forgotten to close my garage door at night, and it wasn't until after hearing about a theft from a neighbor's garage that I decided to get started. Initially I just wanted a system to send notifications to my phone if the door was left open, but I decided door control would also be useful.

Edit: this project has since been updated to use my Arduino remote firmware solution. I no longer use Google Talk and instead use a simple REST API with embedded Jetty on a Raspberry Pi to send XBee messages to the Arduino. I use Cloud Messaging to send door events to my Android phone.

I did some research and found several garage door projects, using a variety of technologies: WiFi, Arduino, XBee and providing varying capabilities: monitor only, control only and both.  I wanted to be able to control and monitor the door from my Android phone.  I considered using WiFi.  This would have involved a web server on the Arduino, but Arduino cannot support https (TLS) due to memory/processing limitations, so that rules out essentially all APIs for sending notifications back to a mobile phone.  Another problem is accessing the web server from the internet would require configuring port forwarding from my router to the Arduino (not SSL), so bad idea.  Additionally, the Arduino Wifi hardware is quite expensive at this time.  I settled on XBee and Google Talk.  Of course Google Talk is supported on both Android and IPhone, so both me and my wife (IPhone) could control and monitor the door.  The downside to this solution is it does require running a server to bridge communication with both Google Talk and the Arduino.  For this I'm using my Sheevaplug (plug computer), since it's very low power (~3W). Edit: I swapped this with a Raspberry Pi a few years later.

Controlling a garage door requires a relay. Fortunately there's a good reference circuit for relays on the Arduino site.  I wired the relay to the Arduino and uploaded a simple script to verify I could make it open and close it. At first I wasted a lot of time troubleshooting what I thought was a circuit issue but turned out to be a bad breadboard. Note: the relay has a NO (normally open) and NC (normally closed). The garage door should be wired to the NO pin.

Note: The circuit above needs a 1K resistor from the transistor base to ground or it will not function!

I'm using magnetic sensors (reed switch) to provide door position.  These are the same sensors used in security systems and are very reliable.  The door sensors of course can tell you if your door is open or closed and identify a door failure (e.g. door started closing but failed to fully close).

I had to attach a 1x1 post to the joist to position the sensor at the open door position. The sensors close at around 1/2", so I connected them at around 1/4", allowing for sufficient door clearance.

The close-door contact was easily mounted on the wall. I used twist connectors to connect the sensor wire to the extension wire.

The door contacts should be wired to ground and one of the Arduino digital inputs. I'm using Arduino's built in pull up resistors to drive the pin HIGH when the circuit is open. When the magnetic reed switch closes, the pin will go LOW since it it grounded.  The sketch expects the close door sensor to be wired to digital pin 8 and the open door sensor to digital 9.

XBee Configuration

I used series 2 XBees in this solution, however series 1 would work just as well. The radios need to be configured with API firmware.  Refer to XBeeConfiguration. I recommend configuring your XBees to use encryption for security.


You can download all the software for this project from my Google Code site

Arduino Sketch

The loop function looks for incoming XBee requests (close door, open door, door status), and detects changes in the closed and open door magnetic contacts.  When the sketch receives an XBee packet (initiated by a Google Talk message), it performs the action (e.g. open door, close door, or status) and returns a acknowledgment packet.  Similarly, when it detects a change in the door sensors (e.g. door opening or closing), whether initiated from Google Talk or the garage door button, it sends the corresponding event to Google Talk.

The sketch requires only one change: update with the XBee address of the remote XBee.  Find COORD_MSB_ADDRESS and COORD_LSB_ADDRESS and replace with 64-bit address of the remote XBee (the one connected to the Java app).  The sketch assumes pins 8, 9, and 10 are used for the close-door sensor, open-door sensor and relay.  Adjust if necessary.

The sketch requires the xbee-arduino library to communicate with the XBee radio.  The library must be installed in your Arduino's "libraries" folder.  The project page includes installation instructions and information on getting started. 

#define DEBUG 0

uint8_t openContact;
uint8_t closeContact;

// state variables
bool doorFailure = false;
bool closing;
bool opening;
bool relayActivated;

// last time a contact fired
long lastDoorActionTime;
// last time the relay was activated
long lastRelayActionTime;

const uint8_t closePin = 8;
const uint8_t openPin = 9;
const uint8_t relayPin = 10;

// TX Commands
const uint8_t DOOR_OPEN = 4;
const uint8_t DOOR_CLOSED = 5;
const uint8_t DOOR_OPENING = 6;
const uint8_t DOOR_CLOSING = 7;
const uint8_t DOOR_FAILURE = 8;
const uint8_t DOOR_ALREADY_OPEN = 9;
const uint8_t DOOR_ALREADY_CLOSED = 10;
const uint8_t CMD_ACK = 11;
const uint8_t STARTUP = 12;

// RX Commands
const uint8_t DOOR_STATE_REQUEST = 1;
const uint8_t OPEN_DOOR_REQUEST = 2;
const uint8_t CLOSE_DOOR_REQUEST = 3;
// TODO 
const uint8_t GET_DOOR_STATS = 4;

const int MAX_DOOR_OPENCLOSE_TIME = 20000;
const uint8_t debounceDelay = 50;

uint16_t sendErrors = 0;

// Define NewSoftSerial TX/RX pins
// Connect TX of usb-serial device to NSS RX
uint8_t ssRX = 6;
// Connect RX of usb-serial device to NSS TX
uint8_t ssTX = 7;
// Remember to connect all devices to a common Ground: XBee, Arduino and USB-Serial device
NewSoftSerial nss(ssRX, ssTX);

XBee xbee = XBee();
XBeeResponse response = XBeeResponse();

// one byte payload
uint8_t payload[] = { 0 };

// TODO replace with address of your coordinator (Connected to the Java app)
uint32_t COORD_MSB_ADDRESS = 0x0013a41c;
uint32_t COORD_LSB_ADDRESS = 0x403ef3b1;

// Coordinator/XMPP Gateway
XBeeAddress64 addr64 = XBeeAddress64(COORD_MSB_ADDRESS, COORD_LSB_ADDRESS);
ZBTxRequest tx = ZBTxRequest(addr64, payload, sizeof(payload));
ZBTxStatusResponse txStatus = ZBTxStatusResponse();
// create reusable response objects for responses we expect to handle 
ZBRxResponse rx = ZBRxResponse();

void setup() {  
  // start serial
  if (DEBUG) {
    // start soft serial
  // turn on internal pull-ups for magnetic switches
  pinMode(openPin, INPUT);
  digitalWrite(openPin, HIGH);
  pinMode(closePin, INPUT);
  digitalWrite(closePin, HIGH);
  pinMode(relayPin, OUTPUT);
  digitalWrite(relayPin, LOW);
  openContact = digitalRead(openPin);
  closeContact = digitalRead(closePin);
  opening = false;
  closing = false;
  doorFailure = false;
  lastDoorActionTime = 0;

void activateDoor() {
  digitalWrite(relayPin, HIGH);
  digitalWrite(relayPin, LOW);
  relayActivated = true;

bool isDoorOpen() {
  // door is open only if open contact is closed and closed contact is open
  // 0 == closed contact, 1 == open contact
  return (openContact == 0) && (closeContact == 1);

bool isDoorClosed() {
  return (openContact == 1) && (closeContact == 0);

void handleXBeeResponse() {

  if (xbee.getResponse().getApiId() == ZB_RX_RESPONSE) {
    // now fill our zb rx class
    // Make sure this is coming from our XBee (note: this is weak security.. using XBee encryption is highly recommended) 
    if (!(rx.getRemoteAddress64().getMsb() == COORD_MSB_ADDRESS && rx.getRemoteAddress64().getLsb() == COORD_LSB_ADDRESS)) {
      if (DEBUG) nss.println("WARN: unknown source address");
    if (rx.getData(0) == OPEN_DOOR_REQUEST) {
      // open door
      if (isDoorClosed()) {
        if (DEBUG) nss.println("Opening door");
        // tell the sender the request was successful  
      } else {
        // closed contact = 1 (open)
        // tell sender door is already open
        if (DEBUG) nss.println("Door already open!");
    } else if (rx.getData(0) == CLOSE_DOOR_REQUEST) {
      // close door
      if (isDoorOpen()) {
        if (DEBUG) nss.println("Closing door");
        // tell the sender the request was successful
      } else {
        if (DEBUG) nss.println("Door already closed!");
        // tell sender the door is already closed
    } else if (rx.getData(0) == DOOR_STATE_REQUEST) {      
      sendDoorEvent((openContact & 1) + ((closeContact << 1) & 2));
    } else {
      // unknown command // TODO log
      if (DEBUG) nss.print("Unknown RX:");
      if (DEBUG) nss.println(rx.getData(0));
  } else {
    // unsupported api -- TODO handle
    if (DEBUG) nss.print("Unsupported RX packet:");
    if (DEBUG) nss.println(xbee.getResponse().getApiId(), HEX);

void sendDoorEvent(uint8_t message) {
  payload[0] = message;
  switch (message) {
     case DOOR_OPEN:
     case DOOR_CLOSED:
      lastDoorActionTime = millis();
  // TODO set frame id with millis & 256
  // after sending a tx request, we expect a status response
  // wait up to half second for the status response
  if (xbee.readPacket(STATUS_RESPONSE_TIMEOUT)) {
    // got a response!

    // check if series 1 or series 2 tx status       
    if (xbee.getResponse().getApiId() == ZB_TX_STATUS_RESPONSE) {

      // get the delivery status, the fifth byte
      if (txStatus.isSuccess()) {
        // good
      } else {
        if (DEBUG) nss.print("sendDoorEvent no ACK:");  
        // TODO resend with same frame id
  } else if (xbee.getResponse().isError()) {
    if (DEBUG) nss.print("sendDoor TX error:");  
    if (DEBUG) nss.println(xbee.getResponse().getErrorCode());
  } else {
    if (DEBUG) nss.print("sendDoor TX timeout");  
    // local XBee did not provide a timely TX Status Response -- should not happen if radio is configured and wired correctly
    // did you switch the TX/RX jumpers back to XBee?
    // is your baud rate correct?
    // in API mode?

// detect pin state change with debounce
bool pinChange(int pin, int current) {
  if (digitalRead(pin) != current) {
    // debounce
    // if state still the same, send event
    if (digitalRead(pin) != current) {
      return true;
    } else {
      // ignore spurious event
      // TODO log
      return false;
  return false;

void loop() {    
  // reads a packet from Serial, if data is available; otherwise continues on
  if (xbee.getResponse().isAvailable()) {
    // got something
  } else if (xbee.getResponse().isError()) {
    if (DEBUG) nss.print("RX packet loop() error:");
    if (DEBUG) nss.println(xbee.getResponse().getErrorCode(), DEC);

  // detect if open-door contact just tripped
  if (pinChange(openPin, openContact)) {
    // open-door contact tripped -- toggle it
    openContact = !openContact;

    // Remember that then the circuit is closed when the contacts meet, which makes the wire go to 0V (logical false).  An open contact is 5V (logical true)
    if (openContact) {
      // Open contact is now OPEN -- door is closing
      if (DEBUG) nss.println("Door closing");
      closing = true;
      lastDoorActionTime = millis();
    } else {
      // Open contact is now CLOSED -- door has completed opening
      if (DEBUG) nss.println("Door finished opening");
      opening = false;
      doorFailure = false;
      lastDoorActionTime = 0;

  // detect if closed-door contact just tripped
  if (pinChange(closePin, closeContact)) {
      // closed-door contact tripped -- toggle it
      closeContact = !closeContact;  
      if (closeContact) {
        // Close contact is now OPEN -- door is opening
        if (DEBUG) nss.println("Door opening");
 // door opening
 opening = true;
 lastDoorActionTime = millis();
      } else {
        // Close contact is now CLOSED -- door has finished closing
        if (DEBUG) nss.println("Door finished closing");
 closing = false;
 doorFailure = false;
 lastDoorActionTime = 0;
  if ((opening || closing) && (millis() - lastDoorActionTime) > MAX_DOOR_OPENCLOSE_TIME) {
     // Problem: door started opening or closing but did not complete with the expected time
     doorFailure = false;
     if (DEBUG) nss.println("Door failure");
     opening = false;
     closing = false;

The Java Part

Unless you have multiple Google accounts, you'll need to create a Google account for the garage door (e.g. If you reuse an existing account, remember that anyone that is in your roster list (friends), will be able to control your door, unless your remove them. For this reason it's better to create a separate account.

There are a few changes that need to be made in the Java app. Open (I recommend using an IDE such as Eclipse or Netbeans) and make the following changes. Find garageDoorAddress and replace with the 64-bit address of the garage door XBee. Find"yourcomport", 9600); and enter the com port of XBee connected to your computer (Coordinator).
In initGoogleTalk, add a roster friend for each Google account that should be allowed to control the Garage Door, for example:


The software will automatically subscribe to and accept messages from this Google account. Only Google accounts specified here will be able to control and receive messages from the garage door.

Find the following line:

xmppClient.connect(new GtalkConnector("", "password"), new MessageListener() {

and replace with the email/password of the Google account that was created for the garage door.

Once all changes have been made, you can run the application from your IDE.  All required libraries are included in the software download, so your IDE should find them automatically.  If not, add all JAR file in the "lib" folder.

The Google Talk commands are simple for easy operation with a mobile phone.  The commands are o=Open Door, c=Close Door, and s=Door Status. If you send a command that is not understood, the menu is returned.  Disregard the x (Extended menu), which I never got around to implementing.

In addition to sending open/close door events via Google Talk, the Java application will send a reminder if the door is left open for 10 minutes.


Google Talk authentication and communication occurs over TLS (transport layer security), so you can consider it to be quite secure, to the extent that you protect your credentials and choose a strong password. Additionally, only users that you specify can send messages to the garage door account, so you don't have to worry about a spammer playing with your door.  You could add additional security by requiring a pin number to be entered for each door control request.

The Arduino Sketch is configured to only accept XBee packets from your radio. It does this by checking the source address (64-bit serial high/low). This however is not good security as it could be defeated, but is somewhat safe in that Digi firmware will not let you spoof addresses. I strongly recommend using XBee's built-in support for encryption.


For the case I found a plastic pizza dough container from Whole Foods in my recycle bin. You can see I'm lazy by using a breadboard instead of assembling the components on protoboard. I recommend mounting the Arduino such that you can access the jumpers and USB cable for updating the sketch.


  • Omron G5SB Relay This 5V relay is Arduino safe, in that the coil impedance is high enough that the Arduino can safely power it.
  • 2N2222A transistor Doesn't have to be this exact one
  • Couple 1K Resistors.  I'm guessing you have some of these
  • 1N4004 Diode Can also be found at Radio Shacks, in the US
  • 2 Magnetic door contacts. I got mine on ebay: Keep in mind that if you order from China, be prepared to wait 3 weeks, unless of course you live in China.
  • Low voltage wire to connect Arduino circuit to the garage door unit and magnetic sensors. Measure first to get an idea of how much you need. I bought a 65' spool of 20 gauge at Home Depot which was more than enough
  • Wire connectors caps, similar to this
  • Obviously you'll need two Series 2 XBees, one Arduino or clone (e.g. RBBB). A USB Explorer or equivalent for the PC side, and a XBee socket or XBee Shield to interface with the Arduino.
  • 9V Arduino power supply and possibly an extension cord.
  • Standoffs and zip ties to mount the Arduino in the enclosure.
  • Some screws and washers to mount the enclosure to wall

Saturday, November 21, 2009

Chatduino: An AIM Client for Arduino/Wiznet 5100

This is an AIM instant messenger client for Arduino/Wiznet 5100, which allows you to communicate with your Arduino project from anywhere on the internet, in near real-time. You can communicate with your project through any AIM client or even your cell phone by using text messaging with Mobile AIM, and since communication is channeled though the AIM server, both the Arduino+Wiznet and chat client can exist behind firewalls.

At first I looked into creating an Arduino library for XMPP/Jabber. This would allow you to connect to Google Talk/App Engine or any other XMPP service. The problem which this approach is most XMPP services require TLS for security, and TLS isn't going to happen on an ATmega328 (thinly veiled challenge going out to anyone who can prove otherwise). I looked at a few other chat services and finally settled on AOL instant messenger (AIM) because it's very popular and the protocol (TOC) is easy to implement on the Arduino. Although the protocol is proprietary, it is well understood and there are many open source libraries/apps available.


Arduino + Wiznet W5100 Ethernet chip. This comes packaged together nicely with the Arduino Ethernet Shield. See below for parts.

Installation and Setup

If you don't already have an AIM account, go to and register for a free screen name.

Download Chatduino and open in Arduino

The official Arduino ethernet library does not support DHCP. Because of this we need to specify the IP address of the Wiznet. For example:
static byte ip[] = { 192, 168, 1, 99 };
Choose an IP address that is not in use and one that is not used by DHCP. I chose since my router (Linksys) uses and up for DHCP.

The Arduino ethernet library also does not support DNS, so we need to use the IP address of the AIM server. I have provided the two IP addresses for the TOC domain ( at this time. Either should work but these could change over time. If you are having connection problems you may need to do a domain lookup on to get the new IP addresses.
//static byte server[] = { 64, 12, 202, 14 };
static byte server[] = { 64, 12, 202, 7 };
The default port of the AIM server is 5190. If you are having connectivity issues, it's possible that your network is blocking this port. Try using port 80 instead.

Update: Some users have suggested an alternate Ethernet library that supports both DNS and DHCP. You might want to give this a try.

Scroll down toward the bottom of the sketch and specify your screen name and password:
char screenName[] = "yourscreenanme";
char pass[] = "yourpassword";
Specify the length of the message array. You will still be able to receive messages that are larger but of course only "msgLen" of the message will be stored in the array. Remember that the ATmega has limited memory (1K), so you don't want to make the arrays excessively large.
const uint16_t msgLen = 50;
Specify the length of the "from" screen name. This value should be at least (+1) larger than the largest screen name you expect.
const uint16_t fromLen = 18;
Now add your code inside the if (readMessage(from, fromLen, msg, msgLen) == 0) { block. This statement evaluates to true whenever a message is received.

The from string contains the screen name that sent the message and the msg string contains the message. For example:
if (strcmp(from, "myscreenname") == 0) {
// a message from "myscreenname"
if (strcmp(msg, "get temp") == 0) {
// return analog reading of temp sensor
itoa(analogRead(0), msg, 10);
sendMessage(from, msg);
else if (strcmp(msg, "turn on led") == 0) {
// turn on led
digitalWrite(ledPin, HIGH);
sendMessage(from, "ok");
Because of the bi-directional nature of chat, it's also possible to send messages based on external events. Here's an example:
//Place outside of readMessage block
if (digitalRead(motionPin) == HIGH) {
sendMessage("anyscreenname", "motion detected!");
Now you should be able to upload your Sketch and it should sign-on to AIM.

I have provided a few functions that you may find useful. The processPinRequest function provides I/O pin control. For example ar5 returns an analogRead of pin 5, and dw4=1 performs a digitalWrite(4, HIGH). Analog write (PWM) and digital read are also supported. It's recommend that you restrict write operations to verified screen names. To accomplish this, you can set authUser to a specific screen name that is allowed to manipulate the I/O pins. By default all users are allowed to perform pin readings. Refer to the function comments for more information.

It is highly recommended to sign-off from AIM before uploading a new sketch or powering off the unit, or AIM gets confused and may not allow reconnects for a period of time. You can sign-off by sending a "signoff" message. I've encountered a few instances where the Sketch failed to connect to AIM after it was previously connected and signed off. Hitting the reset button a few times seems to fix this issue (wait at least 15 seconds between resets).

The Sketch will automatically attempt to reconnect if disconnected from AIM. You can send the "reconnects" message to get the number of reconnects. I've been running the service for over a week with zero reconnects.

Serial debug can be turned on by setting #define CHATDUINO_DEBUG to 1 at the top of the sketch.

Note: I am using the Wiznet module (WIZ812MJ) directly, without a shield. This means I need to explicitly reset the device on startup. This is done by connecting the Wiznet reset pin to 9 (use a resistor, 1K or so), and setting #define WIZNET812MJ (top of sketch) to 1. The Arduino Ethernet Shield will reset automatically and does not require this step.


Seeedstudio currently has the best price on the Arduino Ethernet Shield ($29), although they are out of stock at the time of this writing. This is actually a clone but is functionally equivalent to the official shield.

NKC Electronics sells the official Arduino Ethernet Shield for $40 or you can get their version for $32 (requires assembly).

Whatever you choose, make sure you get a Wiznet based device and not Microchip's ENC28J60.

If you're looking for the most cost effective solution (less then the cost of the ethernet shield alone), and you don't mind wiring it together, I recommend an Arduino clone, such as Modern Device's RBBB (~$12) and the WIZNET812MJ (~$21). This setup requires a breadboard/protoboard, 3.3V power, some female/male jumpers, and a USB-serial device to program the RBBB.


Currently the sketch only processes incoming messages. Other commands: CONFIG2, UPDATE_BUDDY2, PING etc. are ignored. In a future release I would like to support buddy list updates, which would allow you to receive notifications when your friends signon/signoff.
Other improvements may include using EEPROM to save memory and not blocking on readMessage if the receive buffer is empty. Of course at this time it's just a sketch but if people find it useful, I may release it as an Arduino library.

Saturday, September 12, 2009

Droplet on the SheevaPlug

Droplet requires a Java service to listen for requests from remote Droplets and run background threads for push services. At first I used my notebook to run the service, but it wasn't very convenient since it tended to not stay put, or powered on for very long. Around this time I received a SheevaPlug, after a 1.5 month wait. The SheevaPlug is a low power, compact, ARM based Linux computer and is perfect for running the Droplet service. In this blog entry I describe how to get the Droplet service running on the SheevaPlug.


If you are using a FTDI usb-serial device to interface with XBee (e.g. XBee Explorer USB), you'll need to upgrade the kernel since the kernel shipped with the plug does not have usb-serial driver support. (Arduino uses the same FTDI usb-serial chip). Fortunately, for those of us not comfortable with compiling Linux, there are prebuilt kernels available with usb-serial support. Here's the wiki entry that describes the installation process.

The SheevaPlug only has 512MB of disk space, so you can quickly run out of disk space after installing a few packages (Java itself requires over 300MB). The solution to this problem is to install an SD card as your primary file system. This step is optional but strongly recommended for the reason that in addition to more disk space, the plug will also run quite a bit faster. Here's a guide that explains how to add an SD card.

Since this is an ARM computer and not x86, we can't simply install Sun's version of Java for Linux. Fortunately Sun open-sourced Java several years ago and the folks at Sun and RedHat have been hard at work on OpenJDK, rewriting the proprietary parts and porting it to additional architectures (ARM, MIPS, PowerPC etc).

Install OpenJDK

apt-get install openjdk-6-jdk
Install RXTX. RXTX provides serial port communications for Java applications

apt-get --no-install-recommends install librxtx-java
Now we are ready to install Droplet.

Make a folder for the application. I'm using "/root/apps/droplet". Zip up your Eclipse project, transfer it to the plug and unzip in the new folder.

Since we don't have Eclipse on the plug, we need a script to start the application. Create the following script and in a file called


# application entry point

# specify path to the rxtx jar.  default is for librxtx-java

# location of rxtx modules when installed with apt-get

# FTDI should appear as /dev/ttyUSB0 if this is the only USB device

# build classpath
JAR_LIST=`find lib -name '*.jar'`

# add all jar libraries to classpath
for file in $JAR_LIST
#echo "adding $file to classpath"

# append droplet compiled classes (bin) and rxtx jar to classpath

# start Java with a 16MB heap, using the Cacao JIT compiler
java -cacao -Xms16m -Xmx64m -classpath $CLASSPATH -Djava.library.path=$RXTX_LIB_PATH $MAIN_CLASS $COM_PORT 2> droplet.err 1> /dev/null
Make the script executable:

chmod u+x
Note: I'm running the application as root. This probably isn't a good practice but the plug is running inside my firewall, with no ports open to the public, so I think it's fine.

Since we installed RXTX with the lib-rxtx package, we want to remove the RXTX Java library from the project so we don't have multiple RXTX libraries in the classpath.

rm lib/RXTXcomm.jar
And for good measure remove the RXTX native Linux library.

You should now be able to to start Droplet:

Check the log if things aren't working as expected (log file is ./logs/droplet.log). Go ahead an kill the app (Ctrl-c).

We are not quite done yet. To have the application start whenever the SheevaPlug boots, we need to add a startup hook. But first we'll need to create another script to start the application in the background. Save this script as


cd /root/apps/droplet/
nohup ./droplet &
Make it executable

chmod u+x
To add the startup hook, insert a call to the script at the end of the "do_start" function in /etc/init.d/

# startup droplet
sudo /root/apps/droplet/
Now reboot the plug and it should automatically start Droplet.


The performance of OpenJDK Java on the plug is not great but mostly sufficient. I had to rewrite the Twitter service, replacing XPath with StAX because the XPath implementation was consistently timing out. It was taking 20 seconds or more just to parse the friends's timeline! In comparison, the StAX implementation completes in about 5 seconds. In hindsight I could have used JSON, which is quite fast and is already used for Twitter search.

One possible explanation for the slow performance is the lack of Hotspot in OpenJDK. A significant portion of Hotspot was written in assembly, making it very difficult to port. The IcedTea project has been working to address this gap, first with Zero and now with Shark, which is based on LLVM. See this article for more information.

What Else?

I've been running Droplet on the SheevaPlug for the last couple weeks. Overall I've been quite pleased although there is one issue that has popped up a few times. For no apparent reason the Twitter service thread will block indefinitely on what appears to be the HTTP call. When this occurs the rest of the app continues to function but you won't see new Tweets. If you encounter this issue just restart the app.

You may need to adjust the timeout if you are getting "Application Timeout" messages. Usually this will only occur for the Twitter services. This is a two step process. First open the Arduino Sketch and adjust the following line:

Then open and adjust the timeout:

private long serviceTimeoutMillis = 6000. 
The Arduino timeout will always need to be about 1.5 seconds longer than the Java timeout to account for the packet roundtrip transmission time. Unless you have installed the Java compiler on the plug, you'll need to make this change in Eclipse, then copy the "bin" folder to the plug.

Now that you are using the only USB port, if you need additional ports you can add a USB hub. I've found that the Belkin F5U407 USB hub works great with the SheevaPlug. Keep in mind you should not be drawing much power from the USB hub, unless you are using a powered hub.


So now you have an always on Droplet service! Place your plug at the back of your desk, or anywhere you have an ethernet connection and forget about it. You should be able to place Droplet remotes anywhere, within range, and they will just work. Of course since the SheevaPlug is a general purpose Linux computer, you can use for other purposes, web server, file server etc.

Update: I installed a 90 day evaluation of Sun's Java SE for Embedded and the performance is now significantly improved. They have several different versions but the one that's compatible with the SheevaPlug is Java SE for Embedded 6.0 Update 10 ARMv5 Linux Early Access, EABI, glibc 2.5, Soft Float, Little Endian (Headless or Headful). Now I just need to figure out how to purchase the full version, as there is no hint on their site of how to do so.