Smart Building Lab 1 / Part 2: Z-Wave

This is a template of a Python flask-based REST application for controlling a Z-Wave IoT deployment.

N.B. Python 3 is now the default interpreter in most recent Linux distributions. Do not use Python 2! If unsure, check with:

$ which python
$ python -V

The reference Python version for this lab is 3.7. If both Python 2 and 3 are installed, you might need to call explictly:

$ python3 -V

The REST API documentation is in doc/index.html and can be directly viewed in a Web browser. It can be regenerated by running the following command (you need to install the package apidoc) inside your Git checkout directory:

$ apidoc

The flask-main.py file implements the REST API frontend (server), as described by the doc/index.html documentation page. There's nothing to be done with it, but you shall peruse it to understand how the backend API methods are called. The server has some command options which override the default configuration options coming from file configpi.py. Check them with (if you are not in a GNU/Linux shell, you might need to put python before the script name):

$ ./flask-main.py -h

The backend.py file implements an OpenZWave-based control layer and is to be completed in the parts marked by:

#### COMPLETE THIS METHOD ####

backend.py is normally a symlink to backend.py.incomplete. If your OS doesn't understand symlinks... D'oh! then, rename backend.py.incomplete to backend.py before editing.

Once done, you can start your server with the following command -- y = 1 (Ethernet) or 2 (Wi-Fi); x = your Raspberry ID:

$ ./flask-main.py -H http://192.168.1.yx

then, wait a bit (~1 minute max should be OK) for the network to stabilize, and check the connection with a browser, normally at the URL:

http://192.168.1.yx:5000

You should see the corresponding API documentation page.

Raspberry set-up

The provided Raspberry Pi is already installed with the full OZW stack, based on the following package versions:

• OZW system library: openzwave-1.5
• Python (3.7) OZW wrapper: python_openzwave-0.4.19 installed in the pi's user home

Please, do not try to upgrade the system nor the Py-OZW installation! However, should you really need to upgrade or install new packages, please mind that.

• system packages (included OZW and main Python packages) must be manipulated via apt[itude], whereas
• Py-OZW-related packages must be manipulated via the pip3 --user CLI.

Never ever run pip3 as root or without the --user switch!

Your Raspberry is configured to automatically connect to the predefined Wi-Fi AP IoT-Labo. Please, do not modify the related configuration! If you need to work outside the classroom, you'll probably have to connect a keyboard and a monitor to your Raspberry and set up an additional different network connection -- the MAC address of your Raspberry is noted in the file Raspberry-install.md. An SSH client is the best way to interact with your Raspberry:

your-computer$ ssh pi@192.168.1.1x

Testing

A CLI-based client script is available: post_client.py. See how to use it with:

$ ./post_client.py --help

To get specific help on a command class:

$ ./post_client.py network --help

To get a detailed manual page with examples:

$ ./post_client.py --manual

Other GNU/Linux distribution support

If you want to install the OpenZWave stack on a different GNU/Linux distribution, follow its package management instructions.

As for the kernel, make sure that it has support for "USB Modem (CDC ACM)". Check with:

$ zgrep USB_ACM /proc/config.gz
# CONFIG_USB_ACM is not set

If you see the above, then you'll either have to load the appropriate module:

# modprobe cdc_acm

or recompile your kernel with CONFIG_USB_ACM set.

Installation

Install the low-level libraries and toolchain:

• openzwave-1.5/6.x
• cython
• virtualenvwrapper (Python virtual env wrapper -- optional but strongly recommended!)

Install the Python modules inside a virtual env:

$ git clone https://gitedu.hesge.ch/lsds/teaching/master/iot/Smart-Building.git
$ cd Smart-Building
$ mkvirtualenv -p /usr/bin/python3 -a ./ --system-site-packages smart-building
$ pip3 install python_openzwave cython six pyserial 'PyDispatcher>=2.0.5' louie watchdog Flask

If you decide not to go with a virtual env, replace the last command with (notice the --user switch):

$ pip3 install --user python_openzwave cython six pyserial 'PyDispatcher>=2.0.5' louie watchdog Flask

In any case, avoid running pip as root: it might mess up your system Python installation!

Make sure you got Flask >= 1.1.x, else expect problems! Check your OZW config-path installation, usually /etc/openzwave/ or /var/lib/openzwave/. Then Connect your OZW controller and test it with (you might need to use sudo or login as root):

$ mkdir -p ~/tmp/OZW
$ pyozw_check --config_path /etc/openzwave/ -i -d /dev/ttyACM0 --user_path ~/tmp/OZW
$ pyozw_check --config_path /etc/openzwave/ -l -d /dev/ttyACM0 --user_path ~/tmp/OZW

OZW artifacts (logs, sqlite DB, etc) are placed in ~/tmp/OZW.

Technical documentation

Z-Wave.me UZB stick device

Maintenance

This section is for code maintainers. Students are however encouraged to read :-)

Most tasks are available via the included Makefile. See:

$ make help

Source code for the solution build and other sensitive files are encrypted. If you have just cloned this repo and need to work on sensitive stuff, the first thing to do is to run (your GPG public key must be registered by a repo's owner/maintainer -- see here):

$ make unlock

Unlocked content will be anyway encrypted on subsequent push operations. It won't work if the working dir is dirty! Labo's files usually come in two versions: <whatever>.complete and <whatever>.incomplete. At any time, only one of them (by default the .incomplete)is simlinked from a deployable <whatever> file -- i.e., this latter is a symlink and should never, ever by removed. Thus , you can just edit <whatever>

It is good practice to have this repo labo-ready, thus before pushing new stuff, you should always call:

$ make reset

To deploy a (complete) build/solution somewhere, use (remot user, host and path might need to be adapted):

$ [RUSER=... RHOST=... RPATH=...] make deploy