E•NOTE•ION

A self-hosted, code-first content scheduler for Vestaboard split-flap displays. Define your board content as version-controlled JSON — cron schedules, templated messages, live data integrations, and a priority queue — with no web UI or cloud dependency required. Supports both the Note (3×15) and the Flagship (6×22).

This project is primarily agent-developed using Claude, with human design, decision-making, guidance, and review. See Philosophy for more on the approach.

Who this is for

E•NOTE•ION is built for developers and power users who want to treat their board like infrastructure: content in files, schedules in cron, secrets in config.toml, deploys in Docker.

If you'd prefer a friendlier experience — a web UI, drag-and-drop scheduling, and a polished setup flow — check out FiestaBoard, which nails that use case beautifully.

See also

The Vestaboard community has built a lot of great tooling:

Running with Docker (recommended)

Pre-built multi-arch images (linux/amd64, linux/arm64) are published to the GitHub Container Registry on each release.

First copy config.example.toml to config.toml and fill in your API keys and settings (see Configuration below). Then run:

docker run -d \
  --name e-note-ion \
  --restart unless-stopped \
  -v /path/to/config.toml:/app/config.toml:ro \
  ghcr.io/jasonpuglisi/e-note-ion:latest

To mount personal content, add a volume pointing at /app/content/user:

  -v /path/to/your/content:/app/content/user \

Display model, public mode, and enabled contrib content are all configured in config.toml under [scheduler] — no environment variables needed for these settings. See Configuration for details.

Contrib integrations require their own API keys and configuration — see content/README.md for details.

Unraid

An Unraid Docker template is available in a separate repository. It exposes config file path, user content directory, timezone, and webhook port as UI fields.

Viewing container logs

Some integrations print important messages to stdout during startup or operation — for example, an authentication code and URL you need to visit to complete an OAuth flow. Check the container logs to see these messages.

Docker:

docker logs e-note-ion
# or follow live:
docker logs -f e-note-ion

Unraid: In the Unraid web UI, go to Docker → click the container icon next to e-note-ion → Logs.

Integrations that require interactive auth

Some integrations (e.g. Trakt.tv) use an OAuth device code flow: the scheduler prints a short code and URL to the container logs, you visit the URL on any device and approve access, and tokens are automatically saved to config.toml. No browser on the scheduler host is required.

For this to work, config.toml must be mounted read-write (not :ro) so the scheduler can persist the tokens:

# Correct — read-write (required when using auth-based integrations):
-v /path/to/config.toml:/app/config.toml

# Wrong — read-only prevents token persistence:
-v /path/to/config.toml:/app/config.toml:ro

Until auth is complete, templates from that integration are silently skipped and the display shows other content normally. See each integration's sidecar doc under content/contrib/ for setup details.

Upgrading

Breaking changes and the steps to move between major versions are in MIGRATIONS.md. Check it before upgrading across a major.

Configuration

Copy config.example.toml to config.toml and fill in your values:

cp config.example.toml config.toml
# edit config.toml — add your Vestaboard API key and any integration settings

config.toml is git-ignored and contains secrets — never commit it.

Key [scheduler] settings:

Calendar-driven gating

Optionally let calendar events open or close template gates at runtime. When the gate is closed, the cron continues to fire but the enqueue is silently dropped until a covering event reopens it. The motivating use case: "show BART only on days I commute" — list bart.departures in gated_templates, then mark commute days on a calendar event with vestaboard:bart.departures in the description.

Reuses the calendars already configured under [calendar] (both ICS and CalDAV). In any event description, write vestaboard:<token> keywords (one per line, case-insensitive). The token is a file stem (bart) or fully-qualified template id (bart.departures); prefix with ! to deny instead of allow. Deny wins on conflict. Webhook and refresh enqueues are not gated — only cron firings are.

[scheduler.calendar_schedule]
gated_templates = ["bart.departures"]   # closed by default; calendar opens

See config.example.toml for the full keyword grammar and edge cases.

Health monitoring

Credentials are validated once at startup. An integration whose key the service rejects (HTTP 401/403) is marked unhealthy immediately and shows on /health, rather than staying silent until its cron next fires — up to a day later for the daily ones. Startup continues either way: one expired token does not take the board down.

When the webhook listener is enabled, a health endpoint is available at GET /health. It returns a JSON summary of all registered integration statuses, useful for uptime monitoring (e.g. UptimeRobot).

Authentication: A credential is auto-generated on first startup — check the container logs for the plaintext secret. Pass it as X-Webhook-Secret: <secret> (preferred) or ?secret=<secret>.

HTTP status codes:

• 200 — everything healthy (or unknown)
• 503 — one or more targets degraded or errored

Response format:

{
  "status": "healthy",
  "uptime_seconds": 3600,
  "vestaboard": {
    "status": "healthy",
    "last_success": "2026-01-01T12:00:00+00:00",
    "last_expected_empty": null,
    "last_error": null,
    "last_error_message": null,
    "last_locked": "2026-01-01T07:00:00+00:00",
    "locked_events": 2,
    "success_rate": 1.0,
    "total_events": 10,
    "registered_at": "2026-01-01T08:00:00+00:00"
  },
  "integrations": {
    "weather": {
      "status": "healthy",
      "last_success": "2026-01-01T12:00:00+00:00",
      "last_expected_empty": null,
      "last_error": null,
      "last_error_message": null,
      "last_locked": null,
      "locked_events": 0,
      "success_rate": 1.0,
      "total_events": 10,
      "registered_at": "2026-01-01T08:00:00+00:00"
    }
  }
}

The vestaboard key tracks the display send path itself (POST to the Read/Write API) separately from integrations, so a Vestaboard outage does not smear across every integration's status — and vice versa. Each target tracks the last 20 events in a rolling buffer. Status levels: healthy (≥70% non-error rate), degraded (below threshold), error (all errors), unknown (no events yet). Expected empty data (e.g. nothing playing, no events today) counts as healthy — only API failures trigger degraded/error. Vestaboard locked responses (HTTP 423 during quiet hours) are tracked separately via last_locked / locked_events and do not affect status.

Health events are persisted to data/health.jsonl so that history survives container restarts. Events older than 7 days are automatically purged. In Docker, the data/ directory is an anonymous volume — no user configuration is needed for persistence across stop/start cycles.

A periodic health summary also logs to the console every hour, showing non-healthy integrations and their recent error rates.

Board state endpoint

When the webhook listener is enabled, GET /state returns the current board content plus the runtime mode toggles:

{
  "modes": { "quiet": false, "public": false },
  "source": "board",
  "grid": [[8, 0, 0]],
  "rendered": "HELLO",
  "timestamp": "2026-01-01T12:00:00-08:00"
}

modes is always present; grid/rendered/timestamp are null when no content is known. source is board (last grid sent), virtual (quiet-mode buffer), or empty. Add ?refresh=true to force an authoritative fetch from the Vestaboard API. Authentication uses the auto-generated state credential (X-Webhook-Secret header or ?secret=), like /health.

Apple Home (HomeBridge)

Quiet and Public modes can be exposed as native Apple Home switches via HomeBridge — manual toggles, Siri, and Home automations. The GET /state endpoint above keeps the switches in sync, and an optional [homebridge] config section pushes mode changes to HomeBridge instantly. See docs/homebridge.md for the full setup.

Installing from PyPI

Requirements: Python 3.14+

pip install e-note-ion

Create a config file and run:

cp config.example.toml config.toml  # fill in your API key
e-note-ion                           # or: e-note-ion --config /path/to/config.toml

Use e-note-ion --help for CLI options.

Running from source

Requirements: Python 3.14+, uv

uv sync
cp config.example.toml config.toml  # fill in your API key
uv run e-note-ion

Display model, public mode, and content filter are set in config.toml under [scheduler]. See Configuration for details.

Content files

Content is defined as JSON files in two directories:

• content/contrib/ — bundled community-contributed content, disabled by default. Enable via [scheduler].content_enabled in config.toml.
• content/user/ — personal content. Loaded automatically when content_enabled is absent; filtered alongside contrib when it is set. Git-ignored; mount your own directory here or symlink to a private repo.

See content/README.md for the full content format reference, including template fields, variables, color squares, priority guidelines, schedule overrides, and available integrations.

Philosophy

Content as code. Board messages live in JSON files alongside your other dotfiles and configs. They're version-controlled, diff-able, and deployable the same way as everything else. There's no database to back up, no UI state to sync, and no vendor lock-in — just files, cron, and a single Python process.

An AI development experiment. E•NOTE•ION is also an ongoing exploration of agentic software development. Most of the implementation is written by Claude, with a human setting direction, reviewing plans, and making architectural calls. The goal isn't to remove the human — it's to see how far thoughtful human–AI collaboration can go on a real project with real constraints.

Development

uv sync
uv run pre-commit install

Run the full check suite before committing:

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run bandit -c pyproject.toml -r .
uv run pip-audit
uv run pre-commit run pretty-format-json --all-files
uv run pytest --cov --cov-report=term-missing

Every check except pytest also runs as a pre-commit hook.

Integration tests

Integration tests hit the real APIs and are excluded from the default pytest run. To run them locally:

cp .env.example .env
# fill in your API keys — bare values, no surrounding quotes
uv run pytest -m integration -v

Required keys:

.env is git-ignored — never commit it.