Make It Dead Simple: Documentation

Lately I’ve been writing a lot of documentation, instructions, and guides for work, Hackster.io, and my side-project (Open Smart Hub). Most of the time the instructions needed to be compiled from multiple sources but kept simple and digestible. As a long time consumer of documentation, I’ve come to a couple realizations about instructions and guides. The most important is:

Make it dead simple. It should be fool-proof and easy to follow.

Don’t make assumptions about a reader’s skill level, the more knowledgable readers will skim over the instructions they already know, but newcomers will treasure those details.

How?

  1. Draw up a storyboard of the steps. Just like primary school, where they would tell you to brainstorm on a sheet of paper before writing an essay. This will help you figure out if there are any missing parts before you get into the nitty gritty details, whether or not the ordering makes sense, and if you need more research as well.
  2. Start with a schematic of the parts (if it’s a hardware related or multiple component documentation)
  3. Add pictures (these always help clarify for the unsure)
  4. Be concise. Make sure that each word added to your documentation adds value.
  5. Don’t overwhelm your reader. (Avoid using acronyms unless you have elaborated on them earlier in the documentation)

Making this kind of robust yet straightforward documentation takes time, but it will also reduce the amount of support and questions you might receive about it in the future.

Buy vs. Build a 3D Printer

I have been spending part of my spare time working slowly to get my Prusa i3 built and I am just now finishing the build. I’ve run into multiple problems throughout the experience and thought I would let you in on some of the frustrations. Here are some of those issues to keep in mind:

  • Sourcing all of the metric vs. inches components. Make sure that if you pick one, you stick with it for all the parts or be prepared to figure out which parts will require updates to the .scad files since they will need to be altered to fit your custom components. (Hint: metric is easier for following instructions but harder to source in the US)
  • While your dimensions may be right in the scad file, once printed, they may not match exactly to your specifications and may need to be reprinted.
  • There are many different models for each 3D printed part based on individual scenarios. If you are following instructions for a build, try to use their parts/print designs.
  • There are plenty of options for every component from the the hot-end to the extruder, bolts, rails, etc. and this makes sourcing the right 3D printed parts with the right bolts, nuts, etc. a lot more cumbersome than I initially expected.

Final Thoughts:

If you want to get the experience of building a 3D printer on your own or getting a cheaper 3D printer, the best solution is to buy a kit and then build it. You can alter most designs later to suit your desires. Since most kits for a Prusa i3 use the same Arduino Mega and RAMPS board setup, the software to control add-ons is pretty simple to change.

Now that I have gone through the process of sourcing and building my own, I wish I had just bought a kit and assembled all of those parts myself in order to save myself time, money, and frustration.

Node-OpenZWave on Raspberry Pi 2

As a continuation of my Open Smart Hub project I have been interested in adding Z-Wave and Zigbee devices to my supported devices and recently decided to swing for Z-Wave devices first. I bought a Z-Wave Z-Stick Series 2 USB Dongle from Aeon Labs and a simple Z-Wave Door Sensor in order to create the basic mesh network with just two devices.
z-wave-usb-stick

Since the Open Smart Hub is based in NodeJS, it only made sense to search for a Node port of the OpenZwave library. I stumbled upon Jonathan Perkin’s port of it to NodeJS (https://github.com/jperkin/node-openzwave)

Unfortunately, it does not work on Windows, and it seems to be having issues with the latest version of NodeJS… But luckily (or coincidentally) the Open Smart Hub runs on a Raspberry Pi 2 running Raspbian and NodeJS v0.10.28.

After the initial setup of my RPi2 with NodeJS, I got to work getting the node-openzwave module on my RPi2. I was seeing build errors when it was trying to install the module, but found a couple of blogs with information that in order to get it to work I might have to install a couple more tools.

sudo apt-get install build-essential make subversion
sudo apt-get install subversion libudev-dev make build-essential git-core python2.7 pkg-config libssl-dev

After that, it worked and I could call “npm install openzwave” and have it install properly.

Note: If you are interested in using it on Mac OSX, you will need to install the drivers for it. Read more about that process in a previous blog post.

Aeon Labs Z-Stick Series 2 on Mac OSX

z-wave-usb-stick

Aeon Labs, the makers of the Z-Stick, a USB dongle for implementing a Z-Wave controller, don’t seem to provide information on how to get it setup on various operating systems and using it for the OpenZWave library on Mac means that you’ll need to be able to access it through the /dev/ directory. In order to do this on Mavericks, you need to install the latest drivers for the USB stick: http://www.silabs.com/products/mcu/Pages/USBtoUARTBridgeVCPDrivers.aspx

After finishing the install, it should now be visible as /dev/tty.SLAB_USBtoUART if you open a console on OSX and type ls /dev/

From here you can begin to use the Z-Stick by calling on the /dev/tty.SLAB_USBtoUART endpoint.

Running NodeJS on Raspberry Pi

Getting NodeJS on a Raspberry Pi running the latest version of Raspbian isn’t as dead simple as it is on PCs, Mac OS X, or Linux. Only special versions of NodeJS were pre-built for Linux on ARM for Pi and a list of those versions doesn’t seem to be listed in an easy format.

In my case, I wanted to download NodeJS version 0.10.29 and the next closest NodeJS version for ARM was v0.10.28 or v0.10.30. You can search through each directory in the NodeJS distribution directory, but here is a small list of available Linux ARM versions when I last looked:

  • http://nodejs.org/dist/v0.10.28/node-v0.10.28-linux-arm-pi.tar.gz
  • http://nodejs.org/dist/v0.10.3/node-v0.10.3-linux-arm-pi.tar.gz
  • v0.11.12 through v0.11.0 all have Linux ARM versions for pi as well:
    • http://nodejs.org/dist/v0.11.12/node-v0.11.12-linux-arm-pi.tar.gz

In order to download them onto your Raspberry Pi you will need to type these commands into the shell, replacing the version for whichever you want:

wget http://nodejs.org/dist/v0.10.28/node-v0.10.28-linux-arm-pi.tar.gz
tar -xvzf node-v0.10.28-linux-arm-pi.tar.gz
node-v0.10.28-linux-arm-pi/bin/node --version

Now that you have it downloaded on your machine, you will want to add it to your path in order to allow it to be used from anywhere. So you will want to alter (or create if you don’t have one yet) a .bash_profile file in your root:

sudo nano ~/.bash_profile

then add these lines to the file:

Now after you reboot, you should see that you are able to use NodeJS regularly.

sudo reboot

 

NVM – Your Node.js Friend

I’ve been doing a lot of development on an old Node.js version lately (v0.10.28) and after realizing this, tried to update my Node version only to find out that a bunch of my previous code no longer worked due to base changes since my initial download of Node.js.

After some minor digging into hosting multiple Node.js versions but being able to switch between them whenever I wanted, I came across NVM (Node Version Manager). The NVM created by Creationix supports Mac and Ubuntu users, but for Windows users there are alternatives (nvm-windows and nvmw)

The basic gist of using it is to install NVM and call “nvm install 0.10.28” or whichever version you want to install. Then you can now call “nvm use 0.10.28” from your shell window and you are using that version! It makes it super simple to switch between versions of node and also check your development compatibility across the different versions and better inform your users.

Open Smart Hub

Ever since February 22 when I entered the Hackster Hardware Weekend in Seattle, I’ve had a growing passion for the open source side of home automation. What started as a simple idea to automate the closing and opening of windows became something bigger than I ever imagined.

The Hackster.io Hardware Weekend was how the Open Smart Hub was born. I started with a hacked together hub that could run on the Intel Edison and automate a servo to act as the window opening mechanism based on WeatherUnderground API information or light/motion from a Spark.io Core (now named Particle.io). Once the event finished I realized that my implementation couldn’t scale and was horribly confusing to recreate.

I began to research the implementations that were available to the public. What were the open source options? What were the professional products? How did they succeed or fail to solve the problem? My conclusion was that the home automation space was cluttered with all the different companies, organizations, products, and applications. What we as consumers and I as a programmer needed was a simple platform to expand, integrate, and customize my personalized home automation experience. IFTTT is a great alternative but it is impossible to add your own devices, actions, functions, etc. There is no communal collaboration! If you added a device and someone else wanted to use the same sort of device, they would have to recreate it themselves.

That is when I began to reimplement the Open Smart Hub with a modular design. I chose Node.js as my platform because of it’s low barrier to entry for programmers, abundant tutorials, and abundant library of open source modules. The core of the new implementation is the configuration file that declares the available device types (think WeMo switches, Hue light bulbs, Nest, Weather Underground data, etc.) as well as a user’s stored scenarios and devices. I chose an implementation where you could fully own and have the ability to control everything. After all it’s your home!

The implementation is split into two parts, a local hub run on a Raspberry Pi 2 within your home network which handles all the interaction between your devices and an online hub that gives you an accessible UI from anywhere.

Here’s a demo of a basic scenario implementation:

If you would like to check out the details or learn more check out the Hackster.io project: http://www.hackster.io/anthony-ngu/open-source-home-hub