darrylhodgins / pi-kiosk-proxy

Serve up a webpage on a Raspberry Pi kiosk, but let the website interact with local hardware (e.g., backlight)

Kiosk Server

A proxying webserver and kiosk frontend for Raspberry Pi.

Why would someone want something like this?

• You can build and manage your kiosk on a remote web server. This can be shared amongst multiple Raspberry Pi kiosks.
• The kiosk website can make API calls that can control the Raspberry Pi hardware.
• You can cache large content files on the MicroSD card, which could be helpful if you have a relatively resource-heavy website that only needs to make lightweight API calls to a remote server.
• You can make the MicroSD card read-only, which can help protect the kiosk, while still allowing changes to the content on the remote server.

In my example (below), I'm using a basic PHP script to control the backlight on the official 7" touchscreen.

Installation

Raspbian

As of October 19, 2020, this is known to work on Raspberry Pi 3B with Raspberry Pi OS 2020-08-20-raspios-buster-armhf.img.

Flash a MicroSD card and do your usual network and localization setup. Important settings in sudo raspi-config are:

• Boot Options
  • Wait for Network at Boot - Enabled
  • Desktop/CLI - Desktop Autologin

I also recommend changing the default user password to something more secure, and enabling SSH so you can remotely log in to the kiosk to perform maintenance. I like to also turn off the Splash Screen.

Install Dependencies

Install the packages required for this project:

• git is required to get a copy of this repository from Github
• unclutter hides the mouse cursor after 5 seconds of inactivity
• nginx is a webserver; the brains behind the whole operation
• php-fpm allows you to run PHP scripts on the Raspberry Pi

sudo apt update
sudo apt install -y git unclutter nginx php-fpm

Clone this repository

cd /home/pi
git clone https://github.com/darrylhodgins/pi-kiosk-proxy.git

PiTFT

If you're installing on a PiTFT, follow the steps from Adafruit:

Install PiTFT

sudo pip3 install --upgrade adafruit-python-shell click==7.0
sudo apt-get install -y git
git clone https://github.com/adafruit/Raspberry-Pi-Installer-Scripts.git
cd Raspberry-Pi-Installer-Scripts
sudo python3 adafruit-pitft.py --display=28c --rotation=90 --install-type=fbcp

Modify Screen Resolution

sudo vi /boot/config.txt

# hdmi_cvt=640 480 60 1 0 0 0
hdmi_cvt=320 240 60 1 0 0 0

Enable GPIO for PHP

sudo usermod -a -G gpio www-data

Configuration

UI Autostart

Put this in /etc/xdg/lxsession/LXDE-pi/autostart:

@lxpanel --profile LXDE-pi
@pcmanfm --desktop --profile LXDE-pi
@xset s off
@xset -dpms
@xset s noblank

@/home/pi/pi-kiosk-proxy/scripts/run.sh

Symlink NGINX configuration

You could just symlink directly from the nginx-config/kiosk to NGINX's sites-enabled, but this extra symlink provides some breadcrumbs if you find yourself hunting around in /etc/nginx one day.

sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /home/pi/pi-kiosk-proxy/nginx-config/kiosk /etc/nginx/sites-available/kiosk
sudo ln -s /etc/nginx/sites-available/kiosk /etc/nginx/sites-enabled/kiosk
sudo systemctl restart nginx

Edit NGINX configuration

The default configuration points to a demo website. You'll want to modify the kiosk configuration to point to your remote webserver. Note that this must be the root of a website; you can't point to a subdirectory. If your web content resides in a subdirectory, you'll also want to modify the run.sh script.

Disable Chromium caching

Edit /etc/chromium-browser/default

CHROMIUM_FLAGS="--disk-cache-dir=/dev/null --disk-cache-size=1"

Control Local Hardware

This proxy provides a straightforward way to access local resources (on the Raspberry Pi), while still allowing the majority of your content to live on a shared remote server.

Your web app can make GET requests to control the Pi:

HDMI output

Turn on/off connected HDMI screen

Examples

curl http://localhost/pi/hdmi.php?power=off
curl http://localhost/pi/hdmi.php?power=on

Configuration

Add www-data user to video group and restart the web server.

sudo usermod -a -G video www-data
sudo systemctl restart nginx

Pi Official Touchscreen Backlight /pi/backlight.php

Turn on/off the backlight of the official Raspberry Pi touchscreen

Examples

curl http://localhost/pi/backlight.php?power=off
curl http://localhost/pi/backlight.php?power=on

Configuration

Add the following line to /etc/udev/rules.d/99-com.rules:

(TODO: This change seems to always get conflict with apt upgrades, so I may want to find a more elegant solution)

SUBSYSTEM=="backlight",RUN+="/bin/chmod 666 /sys/class/backlight/%k/brightness /sys/class/backlight/%k/bl_power"

Adafruit PiTFT Backlight /pi/tft-backlight.php

Turn on/off the backlight of an Adafruit PiTFT

Examples

Control simple on/off:

curl http://localhost/pi/tft-backlight.php?power=off
curl http://localhost/pi/tft-backlight.php?power=on

Or, control the brightness (you don't need to set power to control brightness; it automatically turns on if you select a value between 1..1023, and automatically turns off if you select 0):

curl http://localhost/pi/tft-backlight.php?brightness=0
curl http://localhost/pi/tft-backlight.php?brightness=511
curl http://localhost/pi/tft-backlight.php?brightness=1023

System Info /pi/system-info.php

Get the model number, MAC address and uptime of your Pi. This could be useful if you want to have several kiosks configured, and your remote webserver can serve different content to each.

Example

curl http://localhost/pi/system-info.php

{
	"system": "Raspberry Pi 3 Model B Rev 1.2",
	"mac": "de:ad:be:ee:ee:ef",
	"upSince": "2020-11-07 04:53:32"
}

Cache Large Files

You may copy large graphics or other resources into the html folder, if you know they won't be changing.

Optimization and other configuration

Disable the Pi configuration wizard

If you've configured your Pi from the command line, remove the Wizard that pops up when you boot into Desktop

sudo rm /etc/xdg/autostart/piwiz.desktop 

Configure Pi to use Overlay File System

After you've got it all working, set your Pi to use Overlay File System. This will prevent all changes to the Micro SD card, and help to avoid corrupted files.

1. Open raspi-config (sudo raspi-config).
2. Choose Performance Options, then Overlay File System.
3. When asked, Would you like the overlay file system to be enabled?, select Yes.
4. When asked, Would you like the boot partition to be write-protected?, select Yes.
5. Reboot