Things Gateway, Part 2 - Zigbee

In part 1 of this missive, I talked about my own checkered history of trying to control devices in my home.   Today I'm going to talk about setting up the Things Gateway software.

Disclaimers and Setting Expectations: The Things Gateway is an experimental proof of concept, not a polished commercial product.  It is aimed at the makers of the technology world, not someone expecting an effortless and flawless plug-and-play experience.  You will encounter glitches and awkward interfaces.  You may even have to interact with the Linux command line.

The Mozilla IoT Gateway is not yet either a functional equivalent or replacement for the commercial products. There are features missing that you will find in commercial products. It is the hope of Mozilla that this project will evolve into a full featured product, but that will take time and effort.

This is where we invite everyone in.  The Things Gateway is open source.  We encourage folks to participate, help add the missing features, help add support for more and more IoT capable things.

Goal: I want to get the Things Gateway by Mozilla up and running on a headless Raspberry Pi.  It will communicate with a smart light bulb and a smart plugin switch using a Zigbee adapter.  The IoT system will be configured for operation exclusively on the local network with no incoming or outgoing communication with the Internet.


Okay, we've had the history, the disclaimers and the goal, let's start controlling things.  If there are terms that I use and you don't know what they mean, look to the Mozilla Iot Glossary of Terms.

To work with the Things Gateway software, you're going to need some hardware.  I'm going to demonstrate using the ZigBee protocol and devices. To follow exactly what I'm going to do, you'll need to acquire the hardware or equivalents in the chart below.  In future articles, I'm going show how to add Z-Wave, Philips Hue, Ikea TRÅDFRI and TPLink hardware. Then I'll get into programming to add support to devices we've not even thought of yet.


Item What's it for? Where I got it
A laptop or desktop PC This will be used to download the software and create the media that will boot the Raspberry Pi I'm going to use my Linux workstation, any PC will do
µSD Card Reader Needed only if there is no other way for the Desktop or Laptop to write to a µSD card I used a Transcend TS-RDF5K that I bought on Amazon years ago
Raspberry Pi Model 3 B This is the single board computer that will run the Things Gateway. These are available from many vendors like Amazon and Adafruit
5V µUSB Power Supply This supplies power to the Raspberry Pi I had a spare one lying around, but you can probably get one from the vendor that sold the Raspberry Pi to you.
µSD Card This will essentially be the Raspberry Pi's hard drive I got mine in the checkout isle of the grocery store, it needs to be at least 4G
DIGI XStick This allows the Raspberry Pi to talk the ZigBee protocol - there are several models, make sure you get the XU-Z11 model. The only place that I could find this was Mouser Electronics
CREE Connected ZigBee Compatible Light Bulb It's a thing to control I got one from my local Home Depot
Sylvania SMART+ Plug ZigBee Compatible Appliance Switch It's a thing to control I got this one from Amazon

Step 1: I downloaded the Things Gateway image file by pressing the Download button on the Build Your Own Web of Things page while using my Linux Workstation.  You should use a desktop or laptop. You can be successful using any OS, I just happen to be a Linux geek.

Step 2: I flashed the image onto my µSD card using my µSD Card Reader.  General instructions can be found on the installing images page. Since I'm using a Linux machine, I just used shell based tools like, lsblk and dd.  I had to identify my µSD card by its size.  I knew it would be the smallest device on my machine, so I identified it as the last on the lsblk list: sdh. Be very careful that you select the correct disk.  This is a very sharp knife, choosing the wrong disk could be a disaster.  Proceed at your own risk.
bozeman:~ ᚥ cd Downloads
bozeman:~/Downloads ᚥ unzip gateway-0.3.0.img.zip
bozeman:~/Downloads ᚥ lsblk | grep disk
sda 8:0 0 894.3G 0 disk
sdb 8:16 0 1.8T 0 disk
sdc 8:32 0 2.7T 0 disk
sdd 8:48 0 2.7T 0 disk
sde 8:64 0 2.7T 0 disk
sdf 8:80 0 2.7T 0 disk
sdh 8:112 1 14.4G 0 disk
bozeman:~/Downloads ᚥ sudo dd bs=4M if=gateway-0.3.0.img of=/dev/¿¿¿  # substitute your device name
[sudo] password for lars: **********
Because my Raspberry Pi is headless, having no keyboard or monitor, I need to have a way to communicate with it if something goes wrong. I'm going to enable the ssh server so I can connect to it from another computer.
bozeman:~/Downloads ᚥ mkdir rpi-boot
bozeman:~/Downloads ᚥ sudo mount /dev/¿¿¿1 rpi-boot  # substitute your device name
bozeman:~/Downloads ᚥ sudo touch rpi-boot/ssh
bozeman:~/Downloads ᚥ sudo umount rpi-boot
bozeman:~/Downloads ᚥ rmdir rpi-boot
bozeman:~/Downloads ᚥ

Step 3: I put the newly minted µSD card, the X-Stick and the network cable into my Raspberry Pi and applied power. It took about 45 seconds to boot to the point that the ssh server was working. While I waited, I set up my two test lamps.



Step 4: I'm going to depend on ssh to communicate with the Raspberry Pi, so I need to make sure ssh is secure. We can't let the "pi" account sit with the default password, so we must change it.
bozeman:~/Downloads ᚥ ssh pi@gateway.local
pi@gateway.local's password: raspberry
Linux gateway 4.9.59-v7+ #1047 SMP Sun Oct 29 12:19:23 GMT 2017 armv7l
...
pi@gateway:~ $ passwd
Changing password for pi.
(current) UNIX password:raspberry
Enter new UNIX password: **********
Retype new UNIX password: **********
passwd: password updated successfully
pi@gateway:~ $ exit
logout
Connection to gateway.local closed.
bozeman:~/Downloads ᚥ



Step 5: By this time, the Thing Gateway web server was up and running and I connected to it with Firefox on my workstation by typing "gateway.local" in the URL bar.


I'd rather have my Gateway communicate over its Ethernet cable, so I don't want to setup WiFi.  I pressed Skip.


At this point in the setup, the Raspberry Pi is going to reboot.  For me, it took about two minutes before I was able to move on.

Step 6: After the delay, I retyped "gateway.local" into the URL bar to continue with the setup.  In this step, one would normally choose a subdomain so that their Things Gateway would be accessible from the Internet.  I do not intend to use that feature.


Again, I pressed Skip.



Step 6: Next, it registers a username and password.  I'll use this to login to the Things Gateway from my browser on my local network.  Notice that the Firefox URL Bar shows that this Web Site is insecure.  When you type your user name and password, you'll be warned again.

Because we're on our own network, this a tolerable situation for the moment.  We could add a self signed certificate and add a security exception to get rid of the warnings, but for now, I'm going to live with it.


Step 7: The Things Gateway is now up and running.  It shows us that it has not detected any devices yet.  However, before we move on, we can enable some more features in the Zigbee Adapter by updating it.  The simplest way to do that is to delete the Add-on that controls it and immediately reinstalling it.

Go to settings, by clicking the 3 horizontal bar drop-down menu icon in the upper left, selecting Settings, then Add-ons:


Remove the zigbee-adapter add-on:


Then Click the "+" and to add it back in.  This ensures we've got the latest code.  I think this is an awkward way to get an update, hopefully the project will improve that particular piece of UX.

Step 8: Leave settings by backing out using the Left Arrow buttons in the upper left until you're back to the Main Menu:


Select "Things"  Then press the "+" button.


Step 9: For me, it immediately found my two devices: the plug on/off switch and the CREE dimmable light bulb.  I gave them more understandable names, pressed "Save" on each and then "Done".


Step 10: Next I got to enjoy the ability to control lights from my computer for the the first time since the 1990s.  I explored the interface, and made a few rules.


In future editions in this series, I'm going to setup lighting for an old fashioned photo darkroom.  I want an easy way to switch between white and red safety lighting.  So I'll make a rule that will not allow both red and white lights to be on at the same time. This sounds like a perfect use of Philips Hue color changing bulb, eh?

Why do we need lighting for a photo darkroom?  I'll reveal that in a future blog post, too.