This thread outlines the process for using a Propeller with a Digi xBee Pro ZB to connect to a public ZigBee Home Automation network.
Why would you want to do this?
The ZigBee Home Automation (HA) spec is used by all the new Home Automation controllers you are seeing pop up at Home Depot, Lowes, SmartThings and SmartenIT. How cool would it be to have a propeller based gizmo controlled by these home automation devices. If your device adheres to the public ZigBee HA spec it will be able to join and communicate with these networks.
This is a logical next step for the Parallax community several propeller projects in this forum have been based on Digi's 802.15.4 xBee, the ZigBee Home Automation profile is based on the same 802.15.4 standard and it defines a very detail protocol for devices to communicate with each other and to the outside world. Yes it is a bit overwhelming at first the ZigBee Spec is 604 pages and the ZigBee Cluster library is 442 pages but if you take the time to figure it out the power of communicating directly with other things is amazing!!
I had to pick a hub to connect to and SmartThings (recently purchase by Samsung) was designed to be an open platform for Home Automation devices. They sell a ZigBee hub and several devices that work with it but they also allow you to add any standard Home Automation device by creating a custom device type. They even have a web based IDE to help you do this. All SmartThings devices are controlled by their Android and iPhone apps. So once a device joins the SmartThings Home Automation network you can see it and control it on the iPhone app!! How cool is that your propeller based gizmo shows up right next to your ZigBee Hue Bulb on the smart phone app.
The goal of this thread is to create a very simple (hello world) standard Home Automation device that will allow you to use your smart phone (running the SmartThings app) to simply turn on a LED connected to a propeller. Once I get some feedback I plan on publishing the SPIN ZigBee HA driver on the object exchange.
You may notice that SmartThings has an Arduino shield available. If you decide to go that route I would like to point out a huge shortcoming of that device. It will only work with SmartThings, it is not based on standard Home Automation device types and clusters. It is a very proprietary solution that only works with their hub. I dont mean to bash their shield I dont think it was ever intended to be used on anyone's network but theirs. Enough said about that (I hope anyway).
Your favorite propeller board http://www.parallax.com/product/32210
Digi xBee Pro ZB SMT (Surface Mount) Digi part number XBP24CZ7PIS-004 you can order one here http://www.digikey.com/product-search/en?x=13&y=12&lang=en&site=us&keywords=XBP24CZ7PIS-004
Other Digi xBee Pro ZB chips will work with limited support for the full ZigBee HA spec. If you want to take advantage of all features outlined in this post you need to use the ZB SMT version.
Two 2MM connection headers Digi Key part number 952-1316-ND. These headers will be soldered to the above xBee Pro SMT to make it a through-hole component so it will plug into your bread board. $5.40 for 10
Xbee USB Adapter board http://www.parallax.com/product/32400
We will use this board to program the xBee Pro ZB SMT
SmartThings Hub from SmartThings.com $99
Digi XCTU configuration program http://www.digi.com/products/wireless-wired-embedded-solutions/zigbee-rf-modules/xctu
Digi XCTU configuration file (XCTU_Cfg.zip
Propeller ZigBee Home Automation driver (ZigBee-HA_Communications.zip
SmartThings Custom Device Type https://github.com/JohnRucker/Nuts-Volts/blob/master/devicetypes/johnrucker/parallax-propeller-demo.src/parallax-propeller-demo.groovy
xBee-Pro ZB SMT RF Modules product guide http://ftp1.digi.com/support/documentation/90002002_M.pdf
ZigBee Specification http://www.zigbee.org/Standards/ZigBeeSmartEnergy/Specification.aspx
ZigBee Cluster Library http://www.zigbee.org/Products/ZigBeeClusterLibraryDownload.aspx
ZigBee Home Automation Public Application Profile
Phase I Setup and configure Digi xBee Pro ZB SMT to join a ZigBee HA network
For a device to join a ZigBee HA (Home Automation) network a strict join process must be followed that is built around the exchange of 128 bit security keys. The ZigBee HA Coordinator (the SmartThings Hub is a ZigBee coordinator) controls the keys and will allow or not allow new devices to join the HA network.
Solder pins as show in the picture to the xBee Pro ZB SMT. This will allow you to use the xBee Pro ZB SMT just like it was a through-hole xBee.
Plug the xBee Pro ZB SMT into the xBee USB Adapter board and connect it to your windows PC. Download and install the latest XCTU software from Digi http://www.digi.com/products/wireless-wired-embedded-solutions/zigbee-rf-modules/xctu
Use the XCTU program to search for and connect to your xBee Pro SB SMT
Use the XCTU program to make sure your xBee Pro ZB SMT is on the current firmware version 4043 or newer.
Use the XCTU program to load the ZigBeeHAPropeller.xml (XCTU_Cfg.zip
) and write it to xBee Pro ZB SMT.
The above process will change the following parameters on the xBee:
ZS ZigBee Stack Profile: 2=ZigBee-Pro. This is required to communicate with a ZigBee HA network
NJ Node JoinTime: 0x5a This setting allows devices to join a network it must not be at the default or it will allow devices to join at any time causing a security problem.
EE Encryption Enable: enable. Security has to be enabled to join a ZigBee Home Automation network
EO Set Bit 1 = 1. This will force the network security key to be transmitted encrypted.
KY Encryption Key = 0X5A6967426565416C6C69616E63653039 This is the encryption key for all ZigBee Home Automation networks. It is required to join the SmartThings hub and other standard ZigBee Home Automation networks. I will discuss the security keys and joining process in a future post.
BD Baud Rate is set to 115200
D6 is set to RTS flow control. The Propeller ZigBee Home Automation driver uses RS232 hardware flow control to communicate with the xBee. It is possible to get by without flow control but there is a lot going on and it is best to not miss any packets so it is worth the two extra wires on your board.
AP API Enable = true
AO API Output Mode = 3 ZDO pass-through
Step 3) verify that you can still communicate with the xBee Pro ZB SMT by reloading its configuration. Make sure the above settings are correct and the firmware version is 4043 or newer. At this point your xBee is configured to join a home automation network and will start searching for a coordinator to join.
Now move your xBee ZB Pro SMT to your Propellers proto board and connect it as outlined in the attached JPG
Phase II install the sample SPIN code and configure it for your hardware
Install the sample (ZigBee-HA_Communications.zip
) application. Make sure to set the Pin configurations for your hardware's xBee and LED pins! The application is documented and it should be easy to find the locations to make these changes.
This application will send status messages to the Parallax Serial Terminal connected to pins 30 and 31 at a baud rate of 250000.
Phase III install the SmartThings custom device type
After you setup and install your SmartThings hub connect to your SmartThings developer account at https://graph.api.smartthings.com
and install the custom device type in the My Device Types section. The easiest way to do this is to click on the "New SmartDevice" button and fill in the required fields with bogus information (It will all be replaced in the next step) and hit create. This opens an online editor. Select all the text in this window and replace it with the text located at https://github.com/JohnRucker/SmartThings/commit/1c8bec805913cd5e8b3e9f989ead335ea5d7ddc6
. Hit the save button and then hit then hit the publish button. Now your SmartThings account has a new custom device type that will be assigned to your propeller when it connects to the hub the first time.
Phase IV Boot it all up.
Before proceeding with this step make sure your SmartThings hub is all setup and configured, plugged in and you can connect to it with your smart phone.
Make sure the propeller and xBee are close to the hub so there is no issue with communications. Boot up the propeller and note the propeller is searching for a network to join. The SmartThings hub wont allow new devices to join until you use your smart phone to add a new device. Click on the plus sign at the bottom of the SmartThings dash board and then click on "Connect New Device" the LED on your SmartThings hub will start to flash green and after a few moments the xBee will join the home automation network and the propeller will go to the next step of identifying itself to the hub. The hub will query the propeller for its configuration and then match that configuration to the footprint in the SmartThings custom device type discussed in Phase III above. Follow the prompts on your phone to configure the new tile.
Now all you have to do to turn on your LED is tap the little plug symbol. The tile will turn green and you will see a packet arrive on the propeller and the LED will switch on.
Let me know how this works. This is a complex process with a lot of moving parts and I will be happy to make changes to the code if it makes things eraser or more reliable.