Once the Portal Box is completely built, the Raspberry Pi configured, and the network and backend set up the Portal Box should be fairly simple to set up and use. The short video below goes over basic use of the portal boxes when they are hooked to a piece of equipment.

How to use the Portal Box once it is connected.

Hooking the Portal Box to your Equipment

The Portal Box uses three methods to limit access to a piece of equipment:

the Portal Box can switch power (up to 15 A at 110VAC) using the universal power connectors on the back,
interrupt electrical continuity using a small on-board relay (< 1A) which is typically used to interface with an interlock on a piece of equipment,
or disconnect the 5V and data lines on a USB cable which interrupts dataflow effectively disconnecting a controlling computer from a machine.

Connectors for each of these are available on the back of the Portal Box.

Managing Access and Users

Initial Setup

Setting up a new portal box begins with several important changes to the configuration of the Raspberry Pi operating system.

Modify cmdline.txt

If the portal box is using the Version 2.6 hardware (a Pi 0 W with an Arduino to control NeoPixels) then the /boot/cmdline.txt file must be edited to remove the string “console=serial0,115200” so that serial port 0 can be used to communicate with the Arduino.

Modify config.txt

The Raspberry Pi processor has a variety of hardware peripheral devices that can be made available to the user, but many of these are disabled by default. The portal box application needs to use the UART and SPI peripherals so these need to be enabled. The SPI 0 interface is used to communicate with the RFID card reader. In Version 3 hardware SPI 1 is used to control the DotStar LEDs. Both hardware versions use the main UART, either to communicate with the onboard Arduino (Version 2.6) or as a serial console (Version 3). The Version 3 hardware also provides a pushbutton that can be used to shutdown the Raspberry Pi OS, or to reboot the OS if it has been shut down.

The raspi-config utility can be used to configure these interfaces, or one can edit the /boot/config.txt file directly. For the 2021-05-07 version of the Raspberry Pi OS, add the lines shown below to /boot/config.txt to enable the peripherals used for the portal box application. For other versions of the OS, check /boot/overlays/README for the appropriate syntax.

# enable SPI
dtparam=spi=on
# spi0 is used for RFID reader in all versions of box
dtoverlay=spi0-1cs
# spi1 is used for DotStars in Version 3 box
dtoverlay=spi1-1cs
# for serial console (Version 3) or Arduino communication (Version 2.6)
enable_uart=1
# shutdown/reboot button in Version 3 box
dtoverlay=gpio-shutdown
# cooling fan in Version 3 box
dtoverlay=gpio-fan,gpio-pin=12,temp=55000

Change the hostname

Each of the portal boxes must have a unique hostname. A simple way of selecting the hostname is to use the string ‘portalbox-‘ appended with the unique MAC address of the box’s Wi-Fi interface. The hostname can be changed manually using raspi-config or with these bash commands:

NEWHOSTNAME=$(echo -n 'portalbox-' | cat - /sys/class/net/wlan0/address | sed 's/://g' -)
sudo raspi-config nonint do_hostname $NEWHOSTNAME

Reboot

The portal box must be rebooted after modifying the hostname, /boot/cmdline.txt, or /boot/config.txt

Enable WiFi

Configure Wi-Fi access for your location and verify that the portal box can establish a connection. If desired, other configuration options such a keyboard layout, timezone, and locale can be changed at this time. For simple situations the raspi-config utility can be used for this purpose.

Install portal box application

The portal box application software should be copied to /opt/portal-box. The application uses several Python modules that need to be manually installed. A list of these modules is provided in /opt/portal-box/requirements.txt

sudo apt-get --yes install python3-pip
sudo pip3 install --requirement /opt/portal-box/requirements.txt

The portal-box application is distributed with a template for the portal-box configuration file, /opt/portal-box/example-config.ini This file has placeholders for two necessary sets of URLs and passwords, one for the SQL database and one for the SMTP email host. The template file must be renamed as /opt/portal-box/config.ini and the placeholders must be replaced with the correct URLs and passwords.

Registering with the database server

The new portal box needs to be “registered” with the SQL database before it can be managed by the web interface. This can be accomplished by executing the following on the portal box:

cd /opt/portal-box
sudo python3 register.py

Registering the portal box in this way simply tells the SQL database that a box with a certain hostname exists. Configuring the details of the equipment connected to the portal box is done through the web interface.

Activate the portal box service

The portal box application runs as a systemd service. The service must be configured, enabled, and started. Once enabled, the portal box service will be started automatically when the Rasberry Pi is booted.

sudo cp -pf /opt/portal-box/portal-box.service /etc/systemd/system/portal-box.service
sudo systemctl enable portal-box
sudo systemctl status portal-box

Set Up & Use