Installation

This chapter takes a new bell from an empty Raspberry Pi to a locally tested School Bell service. You need basic command-line access, but no Python programming knowledge. For several bells, first complete one node and then use Deploying with Ansible to repeat the installation with Ansible.

Requirements

School Bell requires Python 3.11 or newer. A typical Raspberry Pi deployment also needs:

  • Raspberry Pi OS or another supported Linux distribution;

  • ALSA and aplay for WAVE playback;

  • an lgpio-compatible GPIO backend when GPIO is configured;

  • network access during installation;

  • online or local NTP for reliable clock synchronization.

Reference hardware

The reference platform for School Bell 1.0 is a Raspberry Pi 3B+ with 1 GB of memory running the 64-bit edition of Raspberry Pi OS Lite. This is the recommended setup for new installations. The Lite edition is sufficient for a bell node; a desktop environment is not needed for normal operation. More powerful hardware is generally unnecessary, so a modest model keeps hardware and energy costs down.

School Bell is lightweight and is also known to run on older Raspberry Pi models with 512 MB of memory. Other models are expected to work when they provide Python 3.11 or newer, ALSA and the required GPIO interfaces, but they are not part of a formal compatibility matrix. Raspberry Pi Zero models still require more extensive testing and should therefore be treated as unverified for production deployments.

Before you begin

Prepare the following:

  • a Raspberry Pi, microSD card, power supply and wired or wireless network;

  • an audio output or USB sound card, amplifier and speaker for the first test;

  • Raspberry Pi OS Lite 64-bit written with Raspberry Pi Imager;

  • a hostname, user account and SSH access configured in Raspberry Pi Imager;

  • one short PCM WAVE file;

  • the intended timezone and bell times.

Do the first test with a speaker at a safe volume. Do not connect mains voltage, an existing school bell circuit or an amplifier’s high-power output directly to a Raspberry Pi GPIO pin. Use a correctly rated and electrically isolated relay interface, installed by someone qualified for the circuit involved.

Prepare Raspberry Pi OS

Boot the Pi, connect over SSH and confirm its clock, OS and Python version:

ssh pi@pibell.local
timedatectl status
python3 --version

School Bell requires Python 3.11 or newer. Apply available operating-system updates before installing it:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

Reconnect after the reboot. Ensure NTP reports a synchronized clock before relying on a schedule; see Networking and time synchronization for local NTP and outage behavior.

Install one bell manually

Install the operating-system packages:

sudo apt update
sudo apt install -y alsa-utils git python3 python3-pip python3-venv

Verify the Python version before creating the environment:

python3 --version

Clone the project, create an isolated environment and install School Bell:

git clone https://github.com/psmsmets/school-bell.git
cd school-bell
git checkout YOUR_TESTED_TAG_OR_COMMIT
python3 -m venv /home/pi/.local
/home/pi/.local/bin/python -m pip install --upgrade pip
/home/pi/.local/bin/python -m pip install .

Replace YOUR_TESTED_TAG_OR_COMMIT with a release tag or exact commit that you have tested. Do not follow a changing branch for a production bell.

The included Ansible setup uses the same /home/pi/.local environment by default. The py3 prompt configured by Ansible is only a shell prompt label; it is not part of the path.

Prepare audio and configuration

Copy the included test sounds and generate an editable example:

mkdir -p /home/pi/samples
cp samples/*.wav /home/pi/samples/
/home/pi/.local/bin/school-bell --demo-config > /home/pi/schema.json

Open /home/pi/schema.json in an editor. At minimum, review schedule, wav, root and timezone. The generated example uses ${HOME}/samples and the included audio files. It also demonstrates optional remote bells, webhooks and internet calendars with placeholder addresses and tokens; remove those sections for the first local test. See Configuration for the concepts and Configuration reference for every available option.

Test the sound outside School Bell first:

aplay /home/pi/samples/SchoolBell-SoundBible.com-449398625.wav

If no sound is heard, solve that before continuing. Audio and ALSA explains device selection, volume, USB sound cards and multiple audio zones.

Initial verification

Check the executable and configuration before starting a service:

/home/pi/.local/bin/school-bell --version
/home/pi/.local/bin/school-bell /home/pi/schema.json --check

--check validates configuration, WAVE files and configured external calendar services without playing audio, changing GPIO outputs, opening HTTP listeners or starting the scheduler.

When the check succeeds, test one configured WAVE key without waiting for its scheduled time:

/home/pi/.local/bin/school-bell /home/pi/schema.json --play 0

Only after audio works should you test GPIO with --test. That flag plays a short part of every configured sound and activates configured outputs, so disconnect the real bell circuit until the test behavior is understood. See GPIO, relays and manual button for BCM pin numbering, supported relay polarity, the Waveshare board pin mapping, button wiring and a safe commissioning procedure.

Systemd

Generate a basic unit for the current user:

school-bell --demo-service | \
    sudo tee /etc/systemd/system/school-bell.service
sudo systemctl daemon-reload
sudo systemctl enable --now school-bell.service

For production deployments, prefer the Ansible-generated unit described in Deploying with Ansible. It sets the virtual-environment path and GPIO backend explicitly.

Verify unattended operation

After installing the service, use:

systemctl status school-bell.service
journalctl -u school-bell.service -n 100 --no-pager

Temporarily add a schedule entry a few minutes ahead, validate the file and restart the service. Confirm the sound and any relay output, then restore the real schedule. Finally reboot the Pi and verify that the service starts again. Also test with central services disconnected: an already configured bell must continue using its local schedule.

What to do next

Upgrading

Validate the existing configuration against the new release before restarting. Back up the configuration and retain a known working package version so the deployment can be rolled back. Python virtual environments are tied to their interpreter; recreate an environment after a major Python upgrade instead of assuming an old one remains usable.