Welcome to the Tomorrow Software reference for interacting with the PiFace Digital 2 I/O board for Raspberry Pi. In this guide we will provide instructions on how to set up a Raspberry Pi and PiFace combo to accept button input and control a few LEDs and relays.
The licensing of the PiFace Extension is the same as most other extensions that we provide. You simply need a valid Tomorrow Software license.
The PiFace Extension uses the Pi4J open source (LGPL V3 license) library. This is a free unencumbered license for private and commercial use.
It is assumed in this document that you have prior experience with Tomorrow Software and that concepts such as server definitions and rule writing are familiar to you.
The very first thing you need to get started is some hardware. The following photo shows the most essential components:
What you need is as follows:
HDMI cable plus a TV/monitor with HDMI input (not shown)
Micro-USB power supply (Preferably 2A)
Raspberry Pi 2 board
Case designed for the Raspberry Pi and PiFace together (optional)
Multi-meter (Optional but really handy)
USB Wi-Fi dongle
Raspberry Pi Noobs SD Card
PiFace Digital 2 board
Standard USB mouse
Standard USB keyboard
The assembly of the hardware is incredibly simple:
Mount the PiFace on top of the Raspberry Pi board
Insert the Wi-Fi dongle, keyboard and mouse into the USB slots
Remove the micro-SD card from inside the Noobs SD pocket and insert it into the bracket on the underside of the Raspberry Pi
Connect the HDMI cable from your Raspberry Pi to your monitor
Connect the power supply and wait for it to boot up
Once the operating system has booted, you will see the following image:
Using your cursor keys, space bar to select and Tab key to navigate options, set up your time zone, locale and select the option to boot to desktop.
The PiFace board communicates with the Raspberry Pi over an interface known as SPI. This interface is not enabled by default, so we need to do so. From within the configuration tool, select Advanced Options and SPI.
Enable SPI and load by default. Once done, return to the main menu, hit the Esc key and type:
This will force a reboot and after a startup you now end up in LXDE:
From here, we need to configure our Wi-Fi connection. Click on Preferences then Wi-Fi Configuration.
Next click on Scan. After a short while, your Wi-Fi network should appear and you can double-click on it to provide a password. Once done, simply click on Add and your internet connection will be established.
Wait for the IP address to show up and note it down for later.
Because our project requires the latest drivers and software, the next step is to update the operating system.
Open a terminal window and type the following commands:
These two commands will take quite a while to complete, depending on your internet speed. Please ensure both tasks complete without errors before continuing.
The Tomorrow Software PiFace extension relies on an open source project known as Pi4J. We need to install this next. At the command line, type:
Next, we need to get the Tomorrow Software installed. There are two options:
Downloaded from the web
Install using a USB thumb drive
If you have received the software on a USB thumb drive, you need to perform some additional configuration. If you downloaded the image, please skip to the next section.
In the terminal window, create a folder where the USB drive will be mounted:
Next, we need to edit the file system table:
Add the following line to the end of the file:
IMPORTANT: This has to be ONE line in the file
Press Ctrl-X and a capital Y, followed by Enter to save.
Then reboot:
Once the reboot has completed, insert the thumb drive and make sure you can access it.
Tomorrow Software is required to be installed as the user root as it uses ports such as 80 (http) and 443 (https).
To achieve this, you need to be able to switch to root using the su command.
To enable root access, type the following command:
Pick a good password and enter it twice.
We are now ready to start the file manager in root mode to copy the image into place.
At the command prompt, type:
Enter the password you just set up, then type:
This will start the file manager as root.
Locate the “Tomorrow-Software-Server-10.0.0.zip” image you either downloaded or on your thumb drive, then right click and select Copy.
Change the folder to /opt and create a new folder named “local”.
Copy the zip file to this location, right click it and select “Extract Here”.
In the terminal window (as root), create a symbolic link to the distribution as follows:
Right click the file tomorrow.sh in /opt/local/Tomorrow/server/bin, select Properties, then the Permissions tab and make sure Execute is set to “Only owner and group”.
Copy the file tomorrowstart from /opt/local/ Tomorrow /server/bin to /etc/init.d.
Right click the file, select Properties, then the Permissions tab and once again make sure Execute is set to “Only owner and group”.
Then enter the following commands in a terminal window (logged in as root).
Everything is now ready for the first run of the Tomorrow Software engine. Reboot your Raspberry Pi. You can either do this from the menu or by typing:
Once rebooted, wait for CPU to settle down after startup – it can take quite a while (2-3 minutes on a PI 2). Do NOT attempt to log in during this phase.
Logging in to the instance should happen from some other computer. The best way to do this is to modify the hosts file on the computer in question to give it a valid name. For example: homeauto.local
Then, simply open a browser and point it to the following URL:
Log in using the user admin and the password admin. You will access the main console. Select Administration then Console Setup:
Change the console type to “Forwarding Proxy without console” and click on Save.
This will shut down Tomorrow Software on the Raspberry Pi. Give it a minute or two to complete, then return to the Raspberry Pi and reboot it.
At this point there will no longer be a console running on the Raspberry Pi. It is instead required to be managed from another Tomorrow Software console instance. To enable this, we need to log in to that alternate console instance and set up a new server definition:
As well as the basics above, we also need to set up the protected hosts, remove the client IP restrictions and disable the browser proxy:
Make the required changes and click on Save.
If all your settings are correct, your instance will now show green in the Servers section:
The next step is to update/install the following components via the update server:
PiFace Rules
It is now time to test all the setup work. We will start by turning on LEDs on demand.
From within the Tomorrow Software console, create a new repository named “LED Test”, then create a new rule set named “LEDSwitch” in that repository.
Hit update on the rule set and create the following:
Properties are:
Click on the Save button to save the new rule set.
Return to the console to create a new configuration in the LED Test repository:
Click on Create to create the configuration.
It is now time to deploy the configuration to the PiFace Server. Deploy the configuration selecting the “Restart immediately” option.
Wait for the deployment to complete. This can take several minutes, especially the first time. Once the deployment is complete, return to a browser and enter the following URL:
http://homeauto.local/?onoff=on&LED=4
Provided you have followed every step above, LED 4 on the PiFace board will now turn on. You can turn it off using:
http://homeauto.local/?onoff=off&LED=4
When a button is pressed or released, this needs to trigger an event. For this purpose, there is a rule named “PiFace Button Listener”, which applies to each button.
You place these rules in a startup rule set.
The following shows a startup rule set that will turn LED 1 on when button 1 is pressed and turn it off when button 2 is pressed:
We also need to modify the configuration to accept the startup rule:
Deploy the configuration the the PiFace server and once again enter the following URL in a browser:
http://homeauto.local/?onoff=off&LED=4
This will trigger the X Engine startup and activate the button listeners. Now try to press button 1 on the PiFace. LED 1 will turn on. If you press button 2, LED 1 will turn off.
Notice that LED 1 is linked to a relay. You can hear it click when the LED turns on or off.
