Run Pareto Anywhere on a Raspberry Pi

Our step-by-step guide to install and run Pareto Anywhere on a Raspberry Pi to make any physical space context-aware.

Run Pareto Anywhere on a Raspberry Pi

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

Learn how we at reelyActive run our Pareto Anywhere open source middleware on a Pi.

The Raspberry Pi will transform ambient wireless data into real-time context: who/what is where/how.

What will this accomplish?
The Pi will serve contextual APIs and web apps—accessible on the local network at pareto.local—and can forward data to a remote Elasticsearch instance for analysis.
Why use a Pi?
A Pi is ubiquitous and cost-effective, and can even collect ambient data using its onboard Bluetooth Low Energy radio.
Does this apply only to the Pi?
Most of the process applies equally well to other platforms, especially those running Linux. See also our tutorial to Run Pareto Anywhere on a PC.

Prerequisites

A Raspberry Pi (or equivalent) with Raspberry Pi OS Lite installed.

Installing Pareto Anywhere   Step 1 of 4

Clone our pareto-anywhere repository on GitHub and install all dependencies using npm.

Do I need to SSH into the Pi?
Yes, unless you've connected a keyboard and display directly to the Pi. If you forgot how to SSH in, recall Step 4 from the Pi Prep tutorial.
Do I need a GitHub account?
No. You can clone the public repository without a GitHub account.
Clone the pareto-anywhere 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 pareto-anywhere and its dependencies Part 2

First create a reelyActive folder under the home folder.

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

Next, install Pareto Anywhere under this folder.

  1. Clone the pareto-anywhere repository and submodules from our GitHub with the command git clone --recurse-submodules https://github.com/reelyactive/pareto-anywhere.git
  2. Change to the pareto-anywhere folder with the command cd pareto-anywhere
  3. Install all package dependencies from npm with the command npm install     1 min

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

Run Pareto Anywhere   Step 2 of 4

Confirm that everything works!

Do I need an ambient data source?
No. Pareto Anywhere runs even in the absence of source data.
Can I test my ambient data source?
Yes. In the second part of this step you'll find how to quickly validate the integration with common hardware/modules.
Pareto Anywhere on Pi

From the same terminal connected to the Pi via SSH, and from the pareto-anywhere folder:

Run Pareto Anywhere Part 1

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

  1. Run Pareto Anywhere 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 Pareto Anywhere 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 ambient data be available (see the tabs below), it is possible to validate its integration with Pareto Anywhere, replacing xxx.xxx.xxx.xxx with the Pi's IP address, where required.

Pareto Anywhere will automatically listen for ambient Bluetooth Low Energy data forwarded from reelyActive Owl-in-Ones and Minew G1 gateways. Follow the step-by-step tutorials below to forward data from these gateways.

Pareto Anywhere will automatically listen for ambient Bluetooth Low Energy data forwarded from compatible Aruba and Huawei APs. Follow the step-by-step tutorials below to forward data from these access points.

Forward UDP packets from the Huawei AP to the Pi on port 50010

Pareto Anywhere will automatically listen for ambient Bluetooth Low Energy data from its onboard radio provided an instance of barnowl-hci is running and forwarding the data. Follow the instructions below to install and run automatically each time the Pi boots.

Install barnowl-hci

From the same terminal connected to the Pi via SSH, complete the following:

  1. Return to the reelyActive folder with the command cd ~/reelyActive
  2. Clone the barnowl-hci repository with the command git clone https://github.com/reelyactive/barnowl-hci.git
  3. Change to the barnowl-hci folder with the command cd barnowl-hci
  4. Install all package dependencies from npm with the command npm install     1 min

Assign radio privileges

Allow Node.js programs the privilege to initiate scans with the command sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)

Run barnowl-hci once to confirm that it can listen for ambient data:

  • npm start will output radio decodings (raddecs) to the console for quick-and-dirty testing
  • npm run forwarder will forward raddecs to a local Pareto Anywhere instance

Enter Ctrl+C to stop either program.

Enable the barnowl-hci-forwarder service

Configure systemd to run the barnowl-hci-forwarder service by completing the following:

  1. Copy the unit file to the systemd system folder with the command sudo cp units/barnowl-hci-forwarder-pi.service /lib/systemd/system
  2. Enable the barnowl-hci-forwarder service with the command sudo systemctl enable barnowl-hci-forwarder-pi.service
  3. Start the barnowl-hci-forwarder service with the command sudo systemctl start barnowl-hci-forwarder-pi.service

The Pi will now automatically and continuously scan for ambient devices each time it boots, forwarding the data to Pareto Anywhere.

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

Pareto Anywhere will automatically listen for ambient Bluetooth Low Energy data forwarded from reelyActive reelceivers on UDP port 50000.

Pareto Anywhere will automatically listen for ambient RAIN RFID data forwarded from compatible Impinj and RF Controls readers. See the barnowl-impinj and barnowl-rfcontrols modules, respectively, for additional details.

Pareto Anywhere will automatically listen for ambient EnOcean Wireless Standard data from a connected USB dongle provided an instance of barnowl-enocean is running and forwarding the data. Follow the instructions below to install and run automatically each time the Pi boots.

Install barnowl-enocean

From the same terminal connected to the Pi via SSH, complete the following:

  1. Return to the reelyActive folder with the command cd ~/reelyActive
  2. Clone the barnowl-enocean repository with the command git clone https://github.com/reelyactive/barnowl-enocean.git
  3. Change to the barnowl-enocean folder with the command cd barnowl-enocean
  4. Install all package dependencies from npm with the command npm install     1 min

Assign serial privileges

Include the pi user in the dialout group to facilitate serial access to the USB dongle with the command sudo usermod -a -G dialout pi

Run barnowl-enocean once to confirm that it can listen for ambient data:

  • npm start will output radio decodings (raddecs) to the console for quick-and-dirty testing
  • npm run forwarder will forward raddecs to a local Pareto Anywhere instance

Enter Ctrl+C to stop either program.

Enable the barnowl-enocean-forwarder service

Configure systemd to run the barnowl-enocean-forwarder service by completing the following:

  1. Copy the unit file to the systemd system folder with the command sudo cp units/barnowl-enocean-forwarder-pi.service /lib/systemd/system
  2. Enable the barnowl-enocean-forwarder service with the command sudo systemctl enable barnowl-enocean-forwarder-pi.service
  3. Start the barnowl-enocean-forwarder service with the command sudo systemctl start barnowl-enocean-forwarder-pi.service

The Pi will now automatically listen to a connected EnOcean USB dongle each time it boots, forwarding the data to Pareto Anywhere.

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

👌 Celebrate Part 3

Pareto Anywhere Runs at the Edge

Pareto Anywhere now #RunsAtTheEdge on your Pi!

Feedback from our user community guides & motivates the continuous evolution of our open source technologies—and our obscure memes—so don't by shy to reach out moving forward!

Jeffrey Dungen, reelyActive

Enjoy the data Part 4

Our cheatsheet details the raddec and dynamb JSON output from the Pareto Anywhere open source middleware.

Automatically run on boot   Step 3 of 4

Configure a systemd service to run Pareto Anywhere 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, for which these instructions should apply equally well.
Pareto Anywhere with systemd

From the same terminal connected to the Pi via SSH, and from the pareto-anywhere folder:

Enable the pareto-anywhere service Part 1

Configure systemd to run the pareto-anywhere service by completing the following:

  1. Copy the unit file to the systemd system folder with the command sudo cp units/pareto-anywhere-pi.service /lib/systemd/system
  2. Enable the pareto-anywhere service with the command sudo systemctl enable pareto-anywhere-pi.service
  3. Start the pareto-anywhere service with the command sudo systemctl start pareto-anywhere-pi.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 Pareto Anywhere landing page.

Set any environment variables (OPTIONAL) Part 2

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

To configure the Pi to forward data to the Elastic Cloud, first follow this tutorial to retrieve the Node URL which will serve as the ELASTICSEARCH_NODE environment variable.

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

  1. Create a pareto-anywhere-pi.service configuration file with the command sudo systemctl edit pareto-anywhere-pi.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="ELASTICSEARCH_NODE=https://user:pass@server.com"
  3. Save the file as /etc/systemd/system/pareto-anywhere-pi.service.d/environment.conf (or similar)

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

Confirm that Pareto Anywhere runs on boot Part 3

Reboot and again observe the Pareto Anywhere 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 Pareto Anywhere landing page. The middleware will indeed run each time the Pi boots.

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

Pareto Anywhere is 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 following tutorial:

Discover pareto.local   Step 4 of 4

Configure mDNS and route port 80 for discoverability as http://pareto.local

What's mDNS?
mDNS is a zero-configuration service that resolves human-friendly hostnames to machine-friendly IP addresses.
Why port 80?
Port 80 is assigned to HTTP, and hence the default location for your web browser to retrieve a web page from a server, such as our Pi.
Discoverable as pareto.local

Change hostname from raspberrypi to pareto Part 1

From the command prompt on the Pi , enter the command sudo raspi-config which will open a text-based menu.

raspi-config menu

Update the configuration as per the following table where the settings are indicated in [ ].

# Option Action(s)
1 System Options S4 Hostname
  • Please enter a hostname [pareto]

Upon completing the above, select <Finish> and select <Yes> when prompted to reboot. Once rebooted, try SSHing back into the Pi from your computer with the command ssh pi@pareto.local in preparation for Part 2 below.

Because mDNS is not supported by all networks and operating systems, SSHing to pi@pareto.local may fail. In this case, revert to ssh pi@xxx.xxx.xxx.xxx where the x values are the Pi's IP address.

Route Pareto Anywhere to port 80 Part 2

By default, Pareto Anywhere runs on port 3001, which makes it accessible to a web browser at pareto.local:3001. By default, web (HTTP) traffic is served on port 80, which can be accessed by simply browsing to pareto.local (the :80 is implicit).

To serve Pareto Anywhere on pareto.local, from a terminal, update iptables to redirect traffic from port 80 to port 3001 with the command sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3001

From a computer on the same network as the Pi, browse to pareto.local and observe the Pareto Anywhere web page.

Browse to pareto.local

To make this redirection persistent (i.e. every time the Pi boots), install the iptables-persistent package with the command sudo apt-get install iptables-persistent and when prompted, select <Yes> to save the current IPV4 rules.

Validate the redirect rule at any time with the command sudo iptables -t nat -L and observe the REDIRECT in the PREROUTING chain.

Because mDNS is not supported by all networks and operating systems, browsing to pareto.local may fail. Pareto Anywhere will nonetheless be accessible at http://xxx.xxx.xxx.xxx where the x values are the Pi's IP address.

Any time you visit a context-aware physical space, try browsing to pareto.local while connected to the local WiFi—imagine what you can discover!

Contributor
reelyActive half-barnowl

Tutorial prepared with ♥ by jeffyactive.

You can reelyActive's open source efforts directly by contributing code & docs, collectively by sharing across your network, and commercially through our packages.

Where to next?

Continue exploring our open architecture and all its applications.