Two Bells

Know when to leave. Live trains and buses for your station and stops in Great Britain, with the walk already worked out: a departure board by the door and a dashboard on your phone, from one small app you run at home.

One install is one app with two views of the same departures:

• The board: a Raspberry Pi with a four-colour Inky pHAT (250x122). The app also draws for a Waveshare 10.85" e-Paper (G) (1360x480), a Waveshare 7.9" HDMI screen (1280x400, on its side) and an 11.3" HDMI bar screen (1920x440); those are tested in software but not yet on the hardware.
• The dashboard: a web page for a phone or computer at home, with the next 10 trains and buses, calling points, bus strips and maps, the weather, disruptions and punctuality history.

A Pi can run either view or both; Docker and a desktop run the dashboard. Each install has one settings site, at /settings on port 8090, with one password and a setup wizard that finds your station, stops, walk times and bus companies from your postcode. The examples use Glossop, with trains to Manchester and buses from two nearby stops (examples/glossop.toml).

Why it's worth a place by your door

• It tells you when to leave, not just when it goes. Every train and bus comes with your walk to its stop, so the page says Leave now, Leave in 4 min or Go now, and can remind you a minute before.
• Live trains, properly. National Rail Darwin gives the platform, coaches, delays and their reasons, every calling point, and where the train is right now.
• Live buses, for free, all day. Worked out the way bustimes.org does it, from the BODS timetable plus live bus positions. A strip under each bus shows how many stops away it is.
• The things that change your plan. Disruptions on your journeys, rain on its way, a new timetable starting soon, and which trains are often late.
• Yours, at home. It runs on a Pi, a NAS or a laptop on your own network, with free API keys and no cloud account. The Pi's web server never connects to the internet, and releases are signed.
• Easy to read for everyone. It is built to WCAG 2.2 AA, for the keyboard and screen readers, and always says what it means in words. Colour only backs the words up.

The dashboard

The next trains and buses side by side, each with its walk, its countdown and where it is now:

Open a train for its whole journey, or the area map for every bus on your lines:

Where there is room, the line runs across the page with each train placed on it:

Light, dark, or the amber Board look, at any size from a phone to a wall tablet (/?kiosk):

The board

An e-paper board needs no attention: it redraws only when what it shows changes. It comes in two looks: sign, an amber dot-matrix station board whose font was drawn for this project one pixel per LED, and plain, black on white with a red accent.

On the 10.85" e-paper there is room for platforms (as the app draws it; not yet run on the panel itself):

An HDMI screen redraws every second, with a running clock and countdowns, and a page showing where your next bus is (again as the app draws it, not yet tried on a real screen):

Set up in a few minutes

No config files to write. Give the setup wizard your postcode or address: it finds your nearest stations and bus stops, works out the walk to each along real streets, finds your bus companies and builds their timetable.

Everything else is on the settings site, in plain words, behind one password:

What it covers

New here? The user guide explains what everything on the board and the dashboard means, how to install it, how to use the settings, and how to look after it. Getting your keys covers the free keys it needs.

• Where it works: trains anywhere in Great Britain (National Rail Darwin). Bus times and positions from BODS cover England only. The rain warning works anywhere. Bank holidays follow England and Wales, Scotland or Northern Ireland.
• Trains: National Rail Darwin, via the Rail Data Marketplace. Free.
• Buses: worked out the way bustimes.org does, from the DfT's Bus Open Data Service (BODS) timetable for your stops plus live bus positions, free and checked all day. On the board, TransportAPI (free plan: 30 hits a day) can stand in while there is no usable timetable, or be the only source.
• E-paper takes about 20 s to refresh, so the board redraws only when what it shows changes, and never more than once every 2 minutes. An HDMI screen redraws every second, with a running clock, countdowns and a page showing where the next bus is.
• Two looks for the board: sign, an amber dot-matrix station board (its font drawn for this project at one pixel per LED), and plain, black on white with a red accent.
• Meaning is always in text (On time, Exp 07:49, Delayed, Cancelled, No report, sch, Not updating). Colour only reinforces it, so both views work for colour-blind viewers, and the board works on a mono panel.

Install

• Raspberry Pi (the board, and the dashboard if you like): download a release tarball and its SHA256SUMS, check it with sha256sum --check --ignore-missing SHA256SUMS, unpack it and run sudo ./deploy/pi/install.sh. Nothing is piped from the internet into sudo bash. Then open http://<pi name>.local:8090/settings. sudo ./deploy/pi/upgrade.sh VERSION moves it to another release, checked the same way. See On a Raspberry Pi.
• Docker (a NAS, say; the dashboard): copy the folder, copy deploy/secrets.env.example to secrets.env, and docker compose up -d --build. The container is twobells, keeping its data in the twobells-data volume. See Docker. From the first release, deploy/docker/docker-compose.ghcr.yml runs the published, signed image instead; Docker on other NASes and on Linux covers QNAP, Unraid, TrueNAS SCALE, and Docker or Podman.
• Desktop (a Mac or Linux laptop; the dashboard): uv tool install twobells or pipx install twobells (from PyPI from the first release), then twobells serve. deploy/desktop has a launchd agent and a systemd user service to start it at login. See Desktop.

No config.toml is needed: the setup wizard saves your settings in the install's store. examples/config.example.toml lists everything that can be set by hand.

The settings password is claimed with a code shown on the board, or put in the log where there is no board. Or set it from the command line; in Docker:

docker exec -it twobells python -m twobells serve --set-password --state-dir /data
docker exec -it twobells python -m twobells serve --reset-code --state-dir /data

Releases

CI runs ruff, the tests on Python 3.11, 3.12 and 3.13, and builds the wheel and the container (amd64, arm64) on every push and pull request. A tag vX.Y.Z matching pyproject.toml's version publishes a release: the package on PyPI, a signed container image on GHCR (ghcr.io/acornelissen/twobells), and a source tarball for the Pi with SHA256SUMS, signed with Sigstore. twobells --version prints the installed version. See .github/workflows/release.yml for how to verify the signatures.

Develop on your laptop

With mise (it pins python, ruff, node and uv in mise.toml):

mise install                 # the pinned tools
mise run setup               # .venv with the package and its dev tools, as uv.lock pins them
mise run test
mise run lint                # ruff
mise run typecheck           # pyright
mise run demo                # sample board to preview.png, no keys
mise run emulate             # the browser panel emulator on sample data
mise run serve               # the dashboard and settings, with ./config.toml and ./secrets.env

CONTRIBUTING.md lists the checks a change must pass.

Without mise: uv sync && uv run pytest.

Then, with the venv active (. .venv/bin/activate, or any shell where mise is activated):

twobells demo --png preview.png            # sample data, no keys
twobells demo --png big.png --display waveshare-10in85g   # or hdmi-1280x400, hdmi-1920x440
twobells run --png preview.png --config config.toml --secrets secrets.env
twobells serve --config config.toml --secrets secrets.env   # the dashboard and settings

Emulator

A browser page that draws the panel at true proportions and logs every tick, so you can see when the board redraws and when it leaves the panel alone. E-paper panels show in e-paper colours and play the slow colour refresh; the HDMI screen swaps frames at once and ticks every second.

twobells emulate --demo                       # fake data, 1 simulated minute every 2 s
twobells emulate --fake-train \
  --config config.toml --secrets secrets.env        # fake trains, live buses
twobells emulate --config config.toml --secrets secrets.env   # all live
twobells emulate --demo --display hdmi-1280x400                # another panel

It opens http://127.0.0.1:8780/, or the next free port (--port picks another; --no-browser leaves the browser alone). Live modes emulate the display in your config; --display overrides it. Choose realistic (20 s), quick or instant refresh, and the scale (1× to 4× for the pHAT, ½× or 1× for the bigger panels); 1× is the panel's real pixel count. --tick SECONDS sets the tick (e-paper: 2 in the demo, 60 live; the screen: 1), and --accent red or yellow the demo's colour. The demo drops the bus feed from 07:30 to 07:52 simulated time, so the "Not updating" badge shows up.

On start the emulator fetches every source once, even outside its windows, so the board fills straight away; after that it polls only inside the windows. Bus times from the BODS timetable cost nothing. Where TransportAPI gives them (source = "transportapi", or standing in while there is no timetable), a live start costs one hit per bus stop; the daily budget still applies, and when it is spent the first fetch is skipped too. twobells run does the same on its very first run, when there is no saved state yet. Live modes keep state in the store, so the TransportAPI budget holds across restarts.

The dashboard's API

The server and the dashboard page talk through a read-only JSON and SSE API, specified in docs/dashboard-api.md; the page is vanilla JS modules with no build step, under a strict CSP.

Layout

One package, src/twobells, a folder per part of the app. Each folder's __init__.py says what it holds.

Tests mirror the package: tests/<folder>/test_<module>.py, with tests/test_deploy.py keeping the deploy files and their docs in step. deploy/ holds the Pi's units and scripts (pi/), the published image's compose file and the image's pinned requirements (docker/), the desktop's login files (desktop/), the Unraid template (unraid/) and secrets.env.example; Dockerfile and docker-compose.yml stay at the top, where docker compose looks.

To add a provider, implement fetch() -> list[Departure] with a name and add it to settings/config.py.

Security

Found a vulnerability? Please report it privately, as SECURITY.md says.

Licence

MIT: see LICENSE. The data the app shows comes under its providers' own terms.

Data credits

See NOTICE.md for every data source and licence.