WPE/Cog kiosk browser block for Balena. Runs a fullscreen browser on a DRM display without an X11 or Wayland compositor, and exposes a small HTTP API for URL navigation and health checks.

• 🖥️ Fullscreen WPE/Cog browser on DRM/KMS display — no X11 or Wayland compositor required
• 🌐 HTTP API for URL navigation, reload, status, and health checks
• 🔄 Display rotation with automatic touch coordinate calibration via udev hwdb
• 🔁 Automatic crash recovery with exponential backoff (up to 30 s); instant detection via process exit channel
• 💾 URL persistence in a named volume — survives Cog crashes, container restarts, and image updates
• ⏳ Startup readiness check — waits for the target URL to be reachable before launching Cog

Set these fleet variables in Balena Cloud to get going:

Set ROTATE_DISPLAY to rotate both the framebuffer and (when TOUCH_DEVICE is also set) the touch coordinate matrix:

For advanced use, COG_PLATFORM_PARAMS accepts a comma-separated list of DRM parameters. The two supported keys are renderer (modeset (default) or gles) and rotation (0–3, counter-clockwise 90° steps). Rotation requires renderer=gles. ROTATE_DISPLAY sets both automatically — only use COG_PLATFORM_PARAMS to override.

TOUCH_DEVICE is a glob matched against the evdev NAME attribute of your touchscreen. The controller logs all detected input device names at startup — check the container logs in Balena Cloud to find the right pattern:

Detected input devices:
  Waveshare WS170120
  ...

Then set TOUCH_DEVICE=*Waveshare* (or whatever matches your device) as a fleet variable. Without this, touch coordinates are not corrected for rotation.

Pass any of these via COG_EXTRA_ARGS:

For WebKit-level settings (fonts, JavaScript, media, etc.) run cog --help-websettings on the device.

# Current URL
curl http://<device>:5011/url

# Navigate (no Cog restart)
curl -X POST http://<device>:5011/url \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com"}'

# Soft reload (no Cog restart)
curl -X POST http://<device>:5011/refresh

# Hard restart (re-applies touch calibration)
curl -X POST http://<device>:5011/restart

# Diagnostics (includes uptime, cog version, last crash time, readiness)
curl http://<device>:5011/status

How to setup the development environment.

You need the following tools to get started:

• uv - A Python virtual environment/package manager (for dev tooling)
• Go (1.23+) - The programming language
• golangci-lint - Go linter

1. Clone the repository
2. Install the dev tooling dependencies

uv sync --dev

3. Setup the pre-commit hooks

uv run pre-commit install

4. Build the controller binary

go build -o kiosk_controller .

As this repository uses the pre-commit framework, all changes are linted with each commit. You can run all checks manually using the following command:

uv run pre-commit run --all-files

To run only on staged files:

uv run pre-commit run

• The controller is a static Go binary — no runtime dependencies in the image.
• URL navigation and page reloads use D-Bus (org.gtk.Application.Open on com.igalia.Cog) so Cog never needs to restart for a URL change. A D-Bus session daemon is started by start.sh and its address is exported as DBUS_SESSION_BUS_ADDRESS. If D-Bus is unavailable, all navigation falls back to a hard restart.
• After a D-Bus navigation, udevadm trigger --action=change is fired after 500 ms so libinput re-reads the hwdb calibration matrix for any input device opened by the new WPEWebProcess.
• Cog and all its WPE subprocesses run in their own process group; on a hard restart the entire group is signalled so DRM/GL resources are fully released before the new instance starts.
• A 500 ms settle delay after stopping Cog prevents "Cannot set mode (Permission denied)" DRM errors when using the gles renderer.
• Cog crashes are detected instantly (via process exit channel) and restarted with exponential backoff (max 30 s). The crash counter resets only after 30 s of stable uptime.
• /health returns 503 when crash_count exceeds 5, signalling a crash loop to external monitors.
• The active URL is persisted to /data/kiosk-url (a named Docker volume). It survives Cog crashes, container restarts, and image updates. LAUNCH_URL is only used when no persisted URL exists. Mount the browser-data volume at /data in your docker-compose.yml.
• udev is started in-container; io.balena.features.udev does not reliably mount /run/udev on all Balena OS versions. A warning is logged to stderr if udev fails to start.
• Setting ROTATE_DISPLAY without TOUCH_DEVICE logs a warning — touch coordinates will not be corrected for rotation.

Distributed under the MIT License - see LICENSE for details.