ZigBee with Samsung Smartthings

Me and a student have been trying to work out how to talk to a Samsung SmartThings hub using ZigBee.  The purpose of this is to make a device based on an Arduino which can offer up a sensor reading to the hub.  We are using this Zigbee module connected to an Arduino via this shield.

There are many things that took a while to work out, and I’ve collected a few of them here, in no particular order.  They may not be accurate; do let me know if you find mistakes.

Basics

There are two series (versions) of the XBee modules, series 1 and 2, and they are completely incompatible.  The Smartthings hub requires series 2.

The XBee module (XBee being Digi’s tradename for its ZigBee products) communicates with its host via serial.  The shield allows the module’s serial UART to be connected either to the Arduino or directly to the computer plugged into the Arduino’s USB port (via the switch on the shield).  The latter arrangement (with the switch to the USB setting) is very useful for development and debugging.  With a Linux host you can talk to the XBee module via /dev/ttyACM0 or similar.

The XBee module has two modes: transparent and API.  With transparent mode a pair of XBee modules operate as a replacement for a serial link.  I haven’t tried this out.  In API mode your module is prepared to be a part of a ZigBee network, which is the way we are using it.

A ZigBee network is pretty fully functional affair, with a protocol stack, TCP/IP-like addressing and so on.  The Wikipedia entry is worth reading if you are not familiar with it.

Getting onto the network

We followed this excellent guide to get our XBee to talk to the Smartthings hub.  You can do the negotiation in Python using the serial module without too much pain.

Frames

With a ZigBee network we communicate in frames.  These are made up of:

  • 0x7e
  • frame length MSB
  • frame length LSB
  • frame
  • checksum

To calculate the checksum, add every frame byte together, take the LSB and then subtract that from 0xff.

The first byte of the frame is the command ID.  The most interesting from our point of view is 0x91 (ZigBee explicit RX indicator); when the modem receives a ZigBee RF packet it is sent out to the UART using this message type.

More as we find it…