Install our open source software suite on a Pi

Our step-by-step guide to make a Raspberry Pi into an open RTLS, RFID and M2M platform.

Install reelyActive's Hyperlocal Context Server on a Raspberry Pi

The TL;DR (Too Long; Didn't Read)

Learn how we at reelyActive deploy our open source software suite on a Raspberry Pi.

  Although this tutorial is still valid, we recommend instead following the updated version:

What will this accomplish?
The Pi will accept data from IoT/RFID hardware, providing a comprehensive suite of interactive web applications and APIs.
Is there an easier way?
Yes, you can simply flash a ready-made disk image to a SD card.
Does this apply only to the Pi?
Most of the process applies equally well to other platforms, especially those running Linux.

Prerequisites

A Raspberry Pi (or equivalent) with Node.js, npm and git installed.

Installing pi-suite   Step 1 of 3

Clone our pi-suite repository on GitHub and install all dependencies using npm.

Do I need to SSH into the Pi?
Yes. If you forgot how, recall Step 4 from the Pi Prep tutorial.
What's pi-suite?
It's a convenience wrapper around our hlc-server package, facilitating deployment on the Pi.
Clone the pi-suite repository from GitHub

Prerequisites

Both the Pi and the computer used for its configuration must be on the same network, with which they can access the Internet.

Boot the Pi and connect via SSH Part 1

With the prepared micro SD card inserted into the Pi, complete the following:

  1. Apply power to the Raspberry Pi
  2. Open a terminal on the computer and SSH into the Pi with the command ssh pi@xxx.xxx.xxx.xxx replacing the x values with the Pi's IP address
  3. When prompted enter the password (berryinsecure is the default)

If you're still using the default password, this is as good a time as any to change it. Simply run sudo raspi-config

Install pi-suite and its dependencies Part 2

First create a reelyActive folder under the home folder.

  1. Change to the home folder with the command cd
  2. Create (if it does not already exist) a reelyActive folder with the command mkdir reelyActive
  3. Change to the reelyActive folder with the command cd reelyActive

Next, install the pi-suite software under this folder.

  1. Clone the pi-suite repository from our GitHub with the command git clone https://github.com/reelyactive/pi-suite.git
  2. Change to the pi-suite folder with the command cd pi-suite
  3. Install all package dependencies from npm with the command npm install     3 mins

It is possible that some dependencies produce warnings or errors. Do not despair: in most cases these have no impact on functionality.

Run and validate the pi-suite installation   Step 2 of 3

Confirm that everything works.

Do I need a data source?
No. The software runs even in the absence of source data.
Can I test my data source?
Yes. In the second part of this step you'll find how to quickly validate the integration with common hardware/modules.
Browsing to hlc-server running on the Pi

From the same terminal connected to the Pi via SSH, and from the pi-suite folder:

Run and validate the vanilla pi-suite Part 1

Start the software and browse to the Pi to confirm that it is running as follows:

  1. Run the software with the command npm start
  2. From the computer , point a web browser at the Pi on port 3001, xxx.xxx.xxx.xxx:3001 replacing the x values with the Pi's IP address, as before

Observe the hlc-server landing page. It is normal not to observe any real-time data as a source has yet to be connected.

The software can be stopped by entering Ctrl+C from the command line.

Run and validate a specific configuration (OPTIONAL) Part 2

Should a source of data be available (see the tabs below), it is possible to validate its integration with the software suite.

Owl-in-One providing data to Pi

No additional steps are required!

The software listens for raddecs on UDP port 50001. Data should appear in the web interface.

Reel providing data to Pi

No additional steps are required!

The software listens for reel packets on UDP port 50000. Data should appear in the web interface.

Pi onboard Bluetooth radio

Instead run the command: sudo npm run start-hci

The software will additionally listen for data from the onboard Bluetooth radio*—first introduced on the Pi 3. Data should appear in the web interface.

* Kindly let us know should you be aware of an elegant way to run as pi user rather than as root!

Reel module on Pi

Instead run the command: npm run start-reel

The software will additionally listen for serial data on /dev/serial0 (GPIO header pins). Data should appear in the web interface.

Running as a systemd service   Step 3 of 3

Configure the software to run as a service each time the Pi boots.

Why systemd?
It is becoming the de facto standard for system and service management among Linux distributions.
Is this specific to the Pi?
Many Linux distributions have adopted systemd, to which these instructions should apply equally well.
Run pi-suite on boot with systemd

From the same terminal connected to the Pi via SSH, and from the pi-suite folder:

Enable the pi-suite service Part 1

Configure systemd to run the pi-suite service by completing the following:

  1. Copy the unit file to the systemd system folder with the command sudo cp units/pi-suite.service /lib/systemd/system
  2. Enable the pi-suite service with the command sudo systemctl enable pi-suite.service
  3. Start the pi-suite service with the command sudo systemctl start pi-suite.service
  4. From the computer , browse again to xxx.xxx.xxx.xxx:3001 replacing the x values with the Pi's IP address

Observe the hlc-server landing page.

Alternatively use the pi-suite-reel.service or the pi-suite-hci.service.

Set the environment variables, if any Part 2

This optional step applies only if custom environment variable configuration is required.

Should your configuration require any environment variables to be set differently than the defaults, for example to run on port 80 and to connect to a remote Elasticsearch database, these variables can be added to .conf files associated with the pi-suite.service as follows:

  1. Create a pi-suite.service configuration file with the command sudo systemctl edit pi-suite.service
  2. In the file editor, add a [Service] line followed by the environment variables, one on each line, as in the example below: 
    [Service]
Environment="PORT=80"
Environment="ELASTICSEARCH_NODE=https://user:pass@server.com:9243"
  3. Save the file as /etc/systemd/system/pi-suite.service.d/environment.conf (or similar)

The environment variables from this .conf file will be observed each time the service runs.

Confirm that pi-suite runs on boot Part 3

Reboot and again observe the hlc-server landing page as follows:

  1. Reboot the Pi with the command sudo reboot now     1 min
  2. From the computer , browse again to xxx.xxx.xxx.xxx:3001 replacing the x values with the Pi's IP address

Once again observe the hlc-server landing page. The software suite will indeed run each time the Pi boots.

If necessary, it is possible to disable the service with the command sudo systemctl disable pi-suite.service.

All software packages are now installed and will run on each boot. The Pi can now optionally be configured as a kiosk display, which is the subject of the next tutorial:

Next tutorial

Where to next?

Continue exploring our open architecture and all its applications.