Configuration

Byonk embeds all screens, fonts, and configuration in the binary itself. This means you can run Byonk with zero configuration - it works out of the box.

For customization, Byonk uses a YAML configuration file to define screens and map devices to them.

Configuration Structure

# Screen definitions
screens:
  transit:
    script: transit.lua        # Lua script in screens/
    template: transit.svg      # SVG template in screens/
    default_refresh: 60        # Fallback refresh rate (seconds)

  weather:
    script: weather.lua
    template: weather.svg
    default_refresh: 900

# Device-to-screen mapping
devices:
  "94:A9:90:8C:6D:18":         # Device MAC address
    screen: transit             # Which screen to display
    params:                     # Parameters passed to Lua script
      station: "Olten, Bahnhof"
      limit: 8

  "AA:BB:CC:DD:EE:FF":
    screen: weather
    params:
      city: "Zurich"

# Default screen for unmapped devices
default_screen: default

Screens Section

Each screen definition has three properties:

The default_refresh is used when the Lua script returns refresh_rate = 0 or omits it entirely.

Devices Section

Each device entry maps a MAC address to a screen:

MAC Address Format

• Use uppercase letters with colons: "94:A9:90:8C:6D:18"
• The MAC address must be quoted (it’s a YAML string)

Parameters

The params section can contain any YAML values:

params:
  # Strings
  station: "Olten, Bahnhof"

  # Numbers
  limit: 8
  temperature_offset: -2.5

  # Booleans
  show_delays: true

  # Lists
  rooms:
    - "Rosa"
    - "Flora"

These are available in Lua as the global params table:

local station = params.station or "Default Station"
local limit = params.limit or 10

Default Screen

The default_screen specifies which screen to show for devices not listed in the devices section:

default_screen: default

If omitted, unknown devices receive an error response.

Hot Reloading

Byonk loads Lua scripts and SVG templates fresh on every request. You can edit these files without restarting the server.

However, config.yaml is only loaded at startup. Changes to device mappings or screen definitions require a server restart.

Example: Complete Configuration

# Byonk Configuration

screens:
  # Default screen - shows time and a message
  default:
    script: default.lua
    template: default.svg
    default_refresh: 300

  # Public transport departures
  transit:
    script: transit.lua
    template: transit.svg
    default_refresh: 60

  # Room booking display
  floerli:
    script: floerli.lua
    template: floerli.svg
    default_refresh: 900

devices:
  # Kitchen display - bus departures
  "94:A9:90:8C:6D:18":
    screen: transit
    params:
      station: "Olten, Südwest"
      limit: 8

  # Office display - room booking
  "AA:BB:CC:DD:EE:FF":
    screen: floerli
    params:
      room: "Rosa"

  # Lobby display - different bus stop
  "BB:CC:DD:EE:FF:00":
    screen: transit
    params:
      station: "Olten, Bahnhof"
      limit: 6

default_screen: default

Embedded Assets

Byonk includes default screens, fonts, and configuration embedded in the binary. This enables zero-config operation:

# Just run it - embedded defaults work immediately
byonk serve

To see what’s embedded:

byonk init --list

Customization Modes

1. Zero-config (embedded only):

byonk serve
# Uses embedded screens, fonts, and config

2. Full customization (env vars + volume mounts):

export SCREENS_DIR=/data/screens
export FONTS_DIR=/data/fonts
export CONFIG_FILE=/data/config.yaml
byonk serve
# Empty paths are auto-seeded with embedded defaults
# Then uses external files (with embedded fallback)

3. Extract for editing:

byonk init --all
# Extracts embedded assets to ./screens/, ./fonts/, ./config.yaml

Init Command

The byonk init command extracts embedded assets to the filesystem:

# List embedded assets
byonk init --list

# Extract everything
byonk init --all

# Extract specific categories
byonk init --screens
byonk init --fonts
byonk init --config

# Force overwrite existing files
byonk init --all --force

# Extract to custom locations (via env vars)
SCREENS_DIR=/my/screens byonk init --screens

Auto-Seeding

When you set an environment variable pointing to an empty or missing directory, Byonk automatically seeds it with embedded assets on startup:

# This creates /data/screens with embedded screens on first run
SCREENS_DIR=/data/screens byonk serve

Merge Behavior

External files take precedence over embedded assets:

1. If external file exists → use it
2. If external file is missing → fall back to embedded

This lets you customize individual screens while keeping embedded defaults for others.

Environment Variables

When a path env var is not set, embedded assets are used exclusively (no filesystem access).

File Locations

Docker Usage

For Docker, mount volumes and set env vars to enable customization:

services:
  byonk:
    image: ghcr.io/oetiker/byonk
    ports:
      - "3000:3000"
    environment:
      - SCREENS_DIR=/data/screens
      - FONTS_DIR=/data/fonts
      - CONFIG_FILE=/data/config.yaml
    volumes:
      - ./data:/data  # Empty on first run = auto-seeded

Or run without volumes for pure embedded mode:

services:
  byonk:
    image: ghcr.io/oetiker/byonk
    ports:
      - "3000:3000"
    # No volumes = uses embedded assets only

Next Steps

• Understand the architecture
• Create your first screen