GPIO, relays and manual button

School Bell can switch one or more relay outputs while a sound is playing. An optional push button can start a manual bell signal. Audio-only installations do not need GPIO configuration.

This page uses Raspberry Pi GPIO terminology. GPIO pins provide logic signals; they must not power a bell, amplifier, relay coil or mains-voltage circuit directly. Use a suitable relay interface with electrical isolation and have fixed or high-voltage wiring installed by a qualified person.

Conceptual low-voltage control and relay-contact wiring. Follow the relay manufacturer’s instructions and keep the external bell circuit isolated from the Raspberry Pi.

Understanding pin numbers

All GPIO numbers in config.json are BCM GPIO numbers. They are not the physical header positions and not wiringPi numbers. For example, BCM GPIO 17 is physical header pin 11.

Check the header diagram for the exact Raspberry Pi model before connecting anything. The Raspberry Pi GPIO Pinout shows BCM numbers, physical pins, power and ground pins together. Never select a 3.3 V, 5 V or ground pin as a GPIO number merely because its physical header position has that number.

Relay outputs

Key-specific relays

Use relays when different outputs must respond to different WAVE keys. A relay accepts one key as a string or multiple keys as a list:

{
  "relays": [
    {
      "gpio": 26,
      "wav_keys": "bell",
      "active_high": false
    },
    {
      "gpio": 20,
      "wav_keys": ["workshop", "bell-and-light"],
      "active_high": false
    }
  ]
}

Only relays matching the requested WAVE key are active during playback. A key without a matching relay remains a valid audio-only signal. Scheduled, webhook and manual-button signals all use the same selection rule. The manual button remains one input and selects outputs through its configured wav_key.

Every relay key must exist in wav. GPIO pins must be unique and cannot reuse manual_bell.gpio. active_high defaults to true independently for each relay.

Legacy relay outputs

buzz_gpio accepts one BCM GPIO number or a list. With multiple entries all configured relays switch together for every WAVE key:

{
  "buzz_gpio": 17
}

{
  "buzz_gpio": [26, 20, 21],
  "buzz_active_high": false
}

buzz_active_high describes the relay input:

• true (the default) drives an output high to ring;

• false drives an output low to ring and is required for active-low boards.

Do not combine buzz_gpio with relays. Existing configurations can keep using the legacy settings until key-specific switching is needed.

School Bell initializes every output to its configured inactive state and returns it to that state after ringing. Confirm the polarity for the actual relay board before connecting the bell circuit; the wrong value can energize a relay as soon as the software starts.

Waveshare RPi Relay Board

The three channels of the Waveshare RPi Relay Board use these values:

Relay channel	BCM GPIO	Label printed on board
1	26	P25
2	20	P28
3	21	P29

The printed P25, P28 and P29 labels use wiringPi numbering. Put the BCM values 26, 20 and 21 in the School Bell configuration. This board has active-low inputs, so configure "buzz_active_high": false for legacy outputs or "active_high": false on each key-specific relay.

Consult the board manufacturer’s documentation as well. Revisions or other relay boards can use different pins and polarity.

Connect the bell circuit safely

For fail-safe switching, normally connect the external bell circuit through the relay’s COM (common) and NO (normally open) contacts. The circuit then remains open when the relay is not energized. Do not use NC (normally closed) unless that behavior has been deliberately designed and assessed.

Software polarity alone cannot guarantee a safe state during boot, shutdown, loss of Pi power or an unpowered relay input. Before connecting the real bell:

1. disconnect the external bell or high-voltage circuit;

2. verify the GPIO number and active-high/active-low setting;

3. measure or observe the relay contacts while booting, ringing and shutting down;

4. confirm that COM and NO are disconnected whenever the bell should be silent;

5. only then connect the external circuit.

Manual push button

manual_bell assigns a BCM GPIO input to a physical momentary push button:

{
  "manual_bell": {
    "gpio": 17,
    "wav_key": "0",
    "mode": "once",
    "pull": "up",
    "bounce_time": 0.05
  }
}

With the default "pull": "up", connect the button between the configured GPIO input and a ground pin. The internal pull-up keeps the input high while the button is open; pressing it connects the input to ground. pull can also be down or floating for hardware designed that way. A floating input requires a suitable external resistor and should not be left electrically unconnected.

The input pin must not also occur in buzz_gpio or relays. bounce_time filters short contact bounce after pressing the button. In once mode one press finishes the selected sound; in hold mode releasing the button stops it, with the sample duration as the maximum. The button’s wav_key selects the same key-specific relay outputs as a scheduled or webhook signal.

Manual signals are deliberate overrides and are not suppressed by holiday or disable calendars. Only one bell signal can run at a time. See Configuration reference for remote SSH and webhook actions that can be attached to the button.

Test before commissioning

First validate configuration and files without operating the hardware:

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

Then disconnect the real bell circuit and run the hardware test:

$ school-bell /home/pi/schema.json --test

--test activates every configured legacy or key-specific relay output sequentially for one second and returns it to the inactive state before testing the next output. WAVE-key filters do not limit this hardware test. It also tests the configured WAVE samples, so keep audio at a safe level.

If an output does not behave as expected, stop and check the BCM number, relay polarity, board power, connections and service-user permissions. Continue with Troubleshooting only while the external bell circuit remains safely disconnected.