Parcel

Electron kiosk application wrapper and machine configuration suite for minimal linux machines.

Overview

This is a simple wrapper application to manage the complete lifecycle of an electron application on a barebones Debian-based linux machine. It supports multiple monitors using either local or network content. It has a number of different configuration options, ranging from setting up wifi connections, static IP addresses, and creating Wifi Hotspots to managing soft shutdowns of the hardware after power loss using a battery backup. These configuration options are detailed below.

Features

Single Command Installation: This package enables any network-connected debian-based machine to be configured with a single command, detailed below. This process installs the electron wrapper, and then installs a specified github repository as the 'app', which contains all of the application specific customizations.

Custom Installation Scripts: Stele-lite will run a custom shell script, named 'install.sh', if it is found in the config directory of the 'app' repository. This allows for installation of additional system level dependencies, and other configuration options.

Machine Configuration: The parcel package includes a system service which monitors the config files in the application directory, and configures the computer accordingly. This process runs at each startup, and if it sees any changes to the machine.js file in the app 'config' folder, it makes the changes, and saves the current configuration.

USB updating: The configurator system service also manages an update system for the app using USB drives. When a USB drive is inserted into the host computer, it is automatically mounted, and the root directory is scanned for a folder called 'update'. If it is found, it loads 'update.js' from that folder, which contains a manafest of directories and files to be updated. The program will recurse through this list of files and copy the specified files from the USB drive to the corresponding location in the app folder. After copying the files, the service automatically ejects the USB drive, and reloads the electron application.

Git Repo Monitoring: The configurator can also optionally enable a system service which automatically checks for changes on the master branch of the application github repository. When enabled, the service checks the repository for new commits every 30 seconds, and automatically pulls them (and updates any submodules) if found. After the application files are updated, the service automatically restarts the electron service.

Keystroke Logging: The configurator service also runs a system level keystroke logger, which will monitor the keypresses from any USB keyboard, and executes commands based on that input. By default, the logger will stop the electron service when the 'escape' and 'left control' keys are pressed at the same time. These commands can be customized by adding directives to the 'keystroke.js' file in the 'app/config' folder.

Setup

Setup of the machine is meant to be a simple, one-command installation. See below for installation instructions for various machine types.

Raspberry Pi:

1. Obtain a Raspberry Pi 3 B+. The software will work on older models, but to use all of the features, the Raspberry Pi 3 B+ will give you the best results.
2. Using Etcher, burn an SD card (minimum 4GB) with the November 2018 version of Raspbian Stretch Lite.
3. Arrange for Network connection.
   1. Wifi:
      1. Once the card is written, re-insert it into your computer, and a drive named 'boot' should appear.
      2. If you wish to configure the Pi wifi connection, drop the contents of the 'pi boot directory' folder into the '/boot/' folder. The .conf file in the wifi folder is a template for a PEAP secured network. Fill this file in with the relevant network details. For more information about the wpa_supplicant.conf file, see this link.
      3. After booting the machine and logging in, run '/boot/wifi/setup.sh'. If the wpa_supplicant file is correct, the Pi should connect to wifi within ~10 seconds.
   2. Wired If not using the wifi connection, plug the Raspberry Pi into an active ethernet connection.
4. Eject the SD card from your computer, insert it into the Raspberry Pi, and plug in power.
5. Once the machine has booted, log in using the default credentials.
6. After logging in, run the following command: bash <(curl -sL parcel.makerspace.cc) -r REPO -a USER , where REPO is the repository name, and USER is the github user name that owns the repository.
7. Let the installer finish running. It will reboot once it has finished, and automatically start the application.

Ubuntu 18.04 Server

1. Download and create a bootable installer for Ubuntu 18.04 Server.
2. Install the operating system on the target machine.
3. Connect the target machine to an active ethernet connection, or configure wifi manually.
4. After installation, start the machine, and login with the credentials defined in the installation process.
5. Run this command in the terminal prompt: bash <(curl -sL parcel.makerspace.cc) -a USERNAME -r REPO

Configuration

All of the configuration options for the parcel wrapper are made from the individual application's config folder. This is done so that each app can carry it's particular machine setup instructions. These configuration options are detailed below.

machine.js:

Key	Values	Action
autostart	boolean	Configure the machine to autolaunch the electron application if true, disable autolaunch if false.
wifiHotspot	Javascript Object: { ssid: string, password: string, domainName: string }	Configures the computer to create a wifi hotspot using 'wlan0', with a SSID of 'ssid', password of 'password', and autorouting of traffic to 'domainName' to the ip address of this computer.
wifi	Javascript Object: { ssid: string, password: string, }	Configure the computer to join 'ssid' using 'password'.
preventSleep	boolean	Configures xserver to prevent screen blanking. This command also sets the mouse to be invisible, which should probably be a separate command.
staticIP	string	String with the desired IPv4 address, formated "XXX.XXX.XXX.XXX"
wifiUser	Javascript Object: { ssid: string, user: string, password: string, domainName: string }	Connect to a PEAP wifi network, using a username and credentials. Password in this case is the hashed version of the user password, obtained using: echo -n 'password_in_plaintext' | iconv -t utf16le | openssl md4 > hash.txt
autostartNode	boolean	Configures automatic startup of a node.js script named 'index.js' in the main app directory.
softShutdown	Javascript Object: { monitorPin: number, controlPin: number, delayTime: number, }	Configures a battery-backup enabled softshutdown. 'delayTime' milliseconds after the computer sees the voltage on 'monitorPin' go to zero, the computer will shutdown, and cause 'controlPin' to go high. Pin numbers are specified in BCM pin numbers.
gitWatch	boolean	Configures a service to automatically track changes to the app github repository. When changes are detected, pull them, and restart the electron app.

app.js

Key	Values	Action
showDevTools	boolean	Display developer tools within the application.
windows	Array of window config objects	Each of these objects is used to create a window for the application. If this variable is not declared, application will automatically create window pointing to 'app/local/index.html'

Window Config Object for app.js

Key	Values	Action
label	string	Names a given window. Used for storing display bindings and sending inter-window messages.
fullscreen	boolean	Tells the application to open the window full screen.
alwaysOnTop	boolean	Prevent windows from other applications from appearing over this window.
displayId	string	Explicitly tell the program which display to use for the window.
file	string	Relative address of the html file to open in this window.
url	string	If file not declared, application will navigate the window to the web address specified in this variable.
size	Object: { height: number, width: number }	Size, in pixels to draw the window, if not fullscreen.
position	Object: { x: number, y: number }	Coordinates, in pixels, to display the window.

keystroke.js:

This is a javascript file, in which you can define actions to occur on given keypresses. There is a keylogger which launches as a part of the configurator file, which emits events that can be interpreted by this file. The list of available keys can be found in this file.

=======

Parcel

5ffbc7b069359c789705b9bc7f4bf9c25d5745d5