Pi-Appliance Framework

Pi-Appliance is a template for building appliances in Python on the RaspberryPi. We are focused on appliances which connect to various AWS services, so we assume an AWS environment configuration.

It includes:

• a configuration manager ("builder") to configure and package the appliance code for your Pi
• an installer ("installer") which bootstraps the appliance
• a web UI for the appliance
• a minimal framework for building and running your appliance code

Getting Started

1. Download or git clone this repo.

• If you downloaded it, extract the file to wherever you want to work with it.
• If you cloned it, delete the .git directory in your clone.

1. Modify the pyproject.toml configuration file:

[tool.poetry]
name = "{{Put Your Project Name Here}}"
version = "0.1.0"
description = "{{Put Your Project Description Here}}"
authors = [{{Put Your Name/email Here}}]

1. Install Poetry is you haven't already.
2. Run poetry install to create and populate the Virtual Environment for the project.
3. Write your code. See Write Your Appliance Code, below. Code, test, repeat.
4. Use the Builder (see below) to configure the appliance and write that configuration to your Pi's SD Card.
5. Boot the Pi, run initial-setup, rejoice in the magic.

Write Your Appliance Code

All appliance code goes in the appliance folder, in appliance.py and any other code files you deem necessary. appliance.py contains a skeleton you can use to start your work. See the appliance README for futher details.

By default, pytest and pylama are installed as dev dependencies; feel free to make use of them, or don't.

builder: Configure Your Appliance

The builder module configures the features and requirements of your appliance.

Run it as:

$ poetry run python -m builder

Read more in the builder module docs.

Bootstrapping the Pi

After you've used the builder to deploy the bootstrap files to the SD card:

1. Unmount the SD card
2. Install it into the Pi, and boot the Pi
3. (Use ping raspberrypi.local to see when it comes on-line)
4. SSH into the Pi using your favorite tool; password defaults to raspberry
   • Putty on Windows
   • Command line: ssh pi@raspberrypi.local
   • If you're working on your n-th pi, the "raspberrypi.local" host is probably already in your known_hosts file; remove it as needed.
5. Run bash /boot/initial-setup.sh {new-hostname} {new-password}
   • Use a new-hostname which is NOT already on your network
   • Make sure to note (or use an established pattern for) the new-password
6. Take another coffee break while ↑ completes
   • This will clone the repository your appliance code is in. Make sure it's pushed to the remote!
7. Unless there are errors - watch the screen - the Pi will reboot and start running your appliance code

Automatic Update

Every time the appliance starts up, either due to reboot, or by operation of the WebUI, the appliance will pull all code updates from the repository's default branch (whatever you define that as). To update your appliance code, just push it to the default branch and reload/reboot the appliance.