# Raspberry Pi with PiFace Reference ## Introduction 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. ### Licensing 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. ### Prerequisite 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. ## Getting started 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 ### Hardware Assembly 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 ### Initial configuration Once the operating system has booted, you will see the following image: ![Raspberry PI setup window](https://2423451286-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F42mDa58RoaDxb6t8mbaI%2Fuploads%2Fgit-blob-661c0db59783325a2f1f9089ca059c0c61a0cb39%2F1.png?alt=media) 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. ### Enabling SPI 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: ``` sudo reboot ``` This will force a reboot and after a startup you now end up in LXDE: ![LXDE](https://2423451286-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F42mDa58RoaDxb6t8mbaI%2Fuploads%2Fgit-blob-b9dc2040590519e6d9a3e4ac375b719a3f925f35%2F3.jpeg?alt=media) From here, we need to configure our Wi-Fi connection. Click on Preferences then Wi-Fi Configuration. ![wpa\_gui](https://2423451286-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F42mDa58RoaDxb6t8mbaI%2Fuploads%2Fgit-blob-88891cdc8a8806ebec6602690d8c82be72ad49ca%2F4.jpeg?alt=media) 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. ### Updating and upgrading 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: ``` sudo apt-get update sudo apt-get upgrade ``` These two commands will take quite a while to complete, depending on your internet speed. Please ensure both tasks complete without errors before continuing. ### Installing Pi4J 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: ``` curl -s get.pi4j.com | sudo bash ``` ### Optional USB drive support 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: ``` mkdir usbdrv ``` Next, we need to edit the file system table: ``` sudo nano /etc/fstab ``` Add the following line to the end of the file: {% code overflow="wrap" %} ``` /dev/sda1 /home/pi/usbdrv vfat uid=pi,gid=pi,umask=0022,sync,auto,nosuid,rw,nouser 0 0 ``` {% endcode %} IMPORTANT: This has to be ONE line in the file Press `Ctrl-X` and a capital `Y`, followed by Enter to save. Then reboot: ``` sudo reboot ``` Once the reboot has completed, insert the thumb drive and make sure you can access it. ### Allow root access 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: ``` sudo passwd root ``` Pick a good password and enter it twice. ### Starting the file manager We are now ready to start the file manager in root mode to copy the image into place. At the command prompt, type: ``` su ``` Enter the password you just set up, then type: ``` gksudo pcmanfm ``` This will start the file manager as root. ![file manager as root](https://2423451286-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F42mDa58RoaDxb6t8mbaI%2Fuploads%2Fgit-blob-3bd7be7a3632db78b5dad84633ffcfd3a8b7d6ef%2F5.jpeg?alt=media) 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: ``` cd /opt/local ln -s Tomorrow-Software-Server-10.0.0 Tomorrow ``` ### Setting the software to auto-start 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)*. ``` cd /etc/init.d update-rc.d tomorrowstart defaults ``` ### Starting the instance 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: ``` sudo reboot ``` 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. ### Defining the console type 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. ### Setting up the server definition 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:

### Required Updates The next step is to update/install the following components via the update server: `PiFace Rules` ### Testing the setup It is now time to test all the setup work. We will start by turning on LEDs on demand. #### Switching LED rule set 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. #### Test configuration Return to the console to create a new configuration in the LED Test repository:

Click on Create to create the configuration. #### Deployment and Testing 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: Provided you have followed every step above, LED 4 on the PiFace board will now turn on. You can turn it off using: ### Responding to button presses 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: This will trigger the space.vars.X\_Agent\_Name\_Single 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.