Configuration¶

School Bell accepts a JSON object directly or a path to a JSON file. The configuration is validated completely before the service is initialized. Unknown fields are rejected and errors include their full nested path.

This page explains how to build and maintain a configuration. Use the Configuration reference when you need the type, default and meaning of every available parameter. The JSON Schema page describes machine-readable validation for editors, CI and deployment tooling.

Minimal configuration¶

{
    "schedule": {
        "Mon": {"08:30": "0"}
    },
    "wav": {
        "0": "bell.wav"
    },
    "root": "/home/pi/samples",
    "timezone": "Europe/Brussels"
}

Use school-bell --demo-config or the repository’s demo.json for a complete example.

How the configuration fits together¶

A useful way to read the file is as four layers:

schedule decides when a bell should ring and selects a key.
wav translates that key into a local WAVE filename.
output settings decide where it rings: ALSA, GPIO and optional remote bells.
optional integrations suppress bells, accept manual triggers or report health without becoming a dependency for normal local scheduling.

For example, "Mon": {"08:30": "lesson"} selects the lesson entry from wav every Monday at 08:30 in the configured timezone. If root is /home/pi/samples and wav.lesson is bell.wav, School Bell plays /home/pi/samples/bell.wav.

Core fields¶

schedule: Maps three-letter weekdays and HH:MM[:SS] local times to keys in wav. WAV references should be strings.
wav: Maps identifiers to WAVE filenames. Files are resolved relative to root.
root: Directory containing local audio files. Environment variables such as ${HOME} are expanded at runtime.
timezone: IANA timezone used to evaluate schedules. The default is Europe/Brussels.
timeout: Timeout in seconds for applicable network and SSH operations.
holidays: Optional OpenHolidays country/language group such as BE-NL.
disable_calendar: Optional HTTP(S) iCalendar URL. Matching events suppress scheduled bells.

See Holidays and calendar exceptions for supported calendar events, refresh behavior and the difference between scheduled and manual signals.

Outputs and triggers¶

device selects an ALSA playback device. The legacy buzz_gpio setting activates one or more outputs for every WAVE key. Use relays when outputs must respond only to selected WAVE keys or need different polarities. The two forms cannot be combined. See GPIO, relays and manual button before selecting pins or connecting a relay.

manual_bell configures one physical input button. Its gpio cannot also be an output, and its wav_key must exist. mode is once or hold; pull is up, down or floating. Optional remote_bells entries use SSH or authenticated HTTP webhooks. GPIO, relays and manual button includes the basic button wiring and test procedure.

The top-level trigger mapping configures legacy SSH destinations. The webhook section can expose an authenticated POST /bell endpoint. Bind the built-in HTTP server to localhost and use a TLS reverse proxy before exposing it to an untrusted network. Follow Remote bells and webhooks for SSH-key setup, request examples and safe exposure of the endpoint.

Monitoring¶

The optional monitoring object configures device identity, labels, heartbeat events, remote syslog and read-only HTTP status endpoints. See Remote monitoring for examples and security considerations.

Choosing optional integrations¶

Start with only schedule, wav, root and timezone. Add one integration at a time and run --check after every change. A typical order is:

confirm local WAVE playback;
add legacy or key-specific GPIO relay outputs if the installation uses them;
add holiday or calendar suppression;
add a physical manual button or authenticated webhook;
add monitoring and verify Graylog or the HTTP health endpoint.

This keeps faults easy to locate and ensures the autonomous local path works before central services are introduced.

Validation and normalization¶

Validate changes before deployment:

school-bell /home/pi/schema.json --check

Pydantic uses strict field types and rejects misspelled or unknown fields. Documented historical forms remain accepted where their meaning is unambiguous—for example integer WAV references, numeric strings and case-insensitive option values. New configurations should use the canonical forms shown in the examples.

config_hash and schedule_hash are generated runtime metadata. They, along with debug, test, check, prog and info, are not valid JSON configuration fields. Hashes are calculated from the original parsed JSON before defaults or normalization are applied.

Configuration lifecycle¶

Use this sequence for a controlled change:

edit the source configuration;
run --check against the candidate;
deploy it to the node;
verify the deployed checksum or content;
restart School Bell;
confirm schedule_loaded and health monitoring;
retain the previous configuration for rollback.

The Ansible playbooks preserve an existing configuration unless an intentional replacement is requested. See Deploying with Ansible.