Configuration

Home Screens stores all configuration as JSON files on disk. The main config file is data/config.json; a few feature-specific data files (meals, chores, rewards) live alongside it. There is no database, every file is read and written directly by the API with atomic writes (temp file + rename) to prevent corruption during power loss.

Data files

Chore definitions and chore completions are two separate files. Copying only data/chores.json leaves every completion (and therefore every earned point) behind.

Other files under data/ are written and managed by the app and are not meant to be edited by hand: backups/, thumbnails/, kiosk.conf, telemetry.json, background-cache.json, weather-today.json, audit.log, the update records (auto-update-setting.json, auto-update-state.json, update-notification-state.json, upgrade-failed.json, restart-needed.json), the Pi program records (system-packages.json, system-package-holds), the change journal behind family and restore writes (family-transaction.json), and the records of the one-time move to a shared family list (family-migration.json, family-migrations/).

The main config is read via GET /api/config and written via PUT /api/config. If you have set an editor password, both endpoints require an hs-session cookie: PUT accepts nothing else, and GET also accepts a display bearer token. With no password set, authentication is off and both are open on your local network.

API Keys & Credentials

API keys and credentials are managed through the editor UI under Settings > API keys and stored server-side in data/secrets.json via the /api/secrets endpoint. They are not stored in .env.local or in the config file.

Supported secret keys:

Environment variables

A few behaviors are set in the Home Screens service's environment rather than in the editor. Add them with sudo systemctl edit home-screens and then restart the service (see Networking), because upgrades rewrite the service file itself. PORT is the exception.

Schema

The configuration has the following structure:

• ScreenConfiguration contains a version number, a single GlobalSettings object, zero or more Screen objects, and zero or more Profile objects.
• Each Screen contains zero or more ModuleInstance objects.
• Each ModuleInstance has a ModuleStyle object, an optional ModuleSchedule, and a module-specific config object.
• Each Profile has an optional ModuleSchedule for auto-activation.

Top Level

The displays field is opt-in. When it is undefined or empty, Home Screens runs in single-display mode and renders screens directly, this is the default for fresh installs and the unchanged behavior for any existing config that predates the multi-display feature. When displays is populated, each entry has its own owned screens, dimensions, and rotation; see DisplayNode below and the Multi-display guide for the full multi-display flow.

GlobalSettings

SleepSettings

ScreensaverSettings

AlertSettings

BackupReminderSettings

UpdateNotificationSettings

WeatherSettings

CalendarSettings

The family grid and free time views join personSources against data/family.json. Manage people under Settings > Family and their calendars under Settings > Calendar > Whose calendars? A calendar that no person claims is shared by the whole household. Legacy people records are preserved by the schema upgrade until the coordinated family migration folds them safely.

ICalSource

ICloudSource

Account credentials (Apple ID + app-specific password) are not stored in the config file, they live in data/icloud-accounts.json and are referenced by accountId.

TransitionEffect

One of fade, slide, slide-up, zoom, flip, blur, crossfade, none.

Screen

BackgroundRotation

BackgroundShade

ModuleInstance

The three visibility gates (enabled, schedule, visibility) are AND-combined: a module renders only when it is enabled, its schedule window matches, and its visibility conditions are met.

ModuleSchedule

Controls when a module (or profile) is active based on day of week and time window.

ModuleVisibility

Shows or hides a module based on values published to the shared state bus. Most values come from plugins, via the SDK's publishState. Marking a plugin instance backgroundProvider keeps it publishing across screen rotation; the flag has no state-publishing effect on built-in modules, which do not publish anything of their own. Home Screens itself publishes two small sets of built-in values that need no module on screen and survive rotation. calendar.* comes from the display's shared calendar fetch (next event, how many events today, whether something is on right now) whenever a calendar source is configured. weather.* comes from the default weather provider whenever a location is set:

• weather.condition: clear, clouds, rain, drizzle, snow, thunderstorm, fog or wind, read from the current hour
• weather.temperature: the current reading in the household's unit, whole degrees
• weather.precip_chance_now: chance of rain or snow this hour, 0 to 100
• weather.precip_chance_next_6h: the highest chance in the next six hours
• weather.precip_chance_today: the highest chance for the rest of today, on the display's calendar day, including the forecast's own figure for the day
• weather.alert_active: true while a weather warning that has not expired is in force, otherwise false
• weather.alert_severity: minor, moderate, severe or extreme for the most serious active warning, blank when there is none
• weather.alert_title: that warning's name, such as "Winter Storm Warning", blank when there is none

A chance key is blank when the provider does not report one, which a numeric condition treats as not met. Only Pirate Weather and NOAA send warnings, so the three warning keys appear in the key picker only while the household's default weather provider is one of those; on every other provider they are still published, with weather.alert_active at false, so a condition saved earlier keeps evaluating. Conditions follow Home Assistant-style semantics.

VisibilityCondition

Each condition is one of these shapes, told apart by its kind:

kind: "state": Compares a published value as text

kind: "numeric": Compares a published value as a number

kind: "time": A day-and-time window on the display's clock, with the same fields as ModuleSchedule. It reads no published value, so it never waits on one

kind: "and": Holds when every condition inside it holds

kind: "or": Holds when any condition inside it holds

kind: "not": Holds when none of the conditions inside it hold

sourceKey references a published state key (plugin keys are prefixed plugin:<id>:, built-in ones are not). Conditions are edited visually in the module's Conditions section in the editor; the key picker lists the built-in values first, under Built-in, followed by the keys plugins declare in their manifest's providesState field or compute from their config via a deriveProvidedKeys export. Check the Or equal to box next to a numeric bound to make it inclusive. See the Plugins guide for the publishing side.

Save-time limits: at most 32 conditions per module (leaves and groups combined) and 5 levels of and / or / not nesting, and a group condition must have at least one child. Exceeding any of these makes PUT /api/config fail with a 400 rather than saving.

Profile

Named groups of screens that can be activated manually or on a schedule.

Profiles support overnight windows (e.g. 23:00–06:00). Scheduled profiles take precedence: at each tick the first profile in list order whose schedule matches, and that still resolves to at least one screen, wins. settings.activeProfile is the fallback used when no scheduled profile matches. If neither produces screens, all screens are shown.

DisplayRule

A condition → action rule owned by a display. Rules reuse the VisibilityCondition tree and evaluator unchanged, but are edge-triggered: a rule fires only on the false→true transition of its conditions, never while they merely stay true, so a reboot or a restarting state producer never slams the display onto an alert screen for a condition that has been true for hours. Rules live under Settings > Automation > Rules and are per-display in multi-display setups.

When multiple rules could fire at once, the first one in list order wins; reorder rules by dragging their cards. In multi-display setups, a rule can be copied to another display, since screens are per-display, a copied showScreen action arrives with its target screen cleared, ready to point at a screen on the new display.

Save-time limit: at most 64 rules per display. The when tree obeys the same condition and nesting limits as ModuleVisibility above.

RuleAction

kind: "showScreen": Show one screen

kind: "wake": Wake the display; nothing happens if it is already awake

kind: "sleep": Put the display to sleep, like the remote sleep command, and end any screen a rule is holding

DisplayNode (multi-display)

A named display device. Each display owns its own list of screens, designed at its own resolution and orientation. Used in multi-display deployments where one server drives multiple Pi displays. See the Multi-display guide for the install and adoption flow.

Like screens, the profiles field is owned by the display: owned profile screenIds reference the display's own screens, not the global pool. When the first additional display is added to a single-display install, the existing config.profiles and config.settings.activeProfile migrate onto the auto-created main display alongside its screens; subsequent displays start with profiles: [] so they build fresh against their own screens. In multi-display mode profiles are always per-display, there is no "shared pool" escape hatch, because a pool profile's screenIds would silently diverge from each display's owned screens as soon as either one is edited.

DisplayNodeSettings is a subset of GlobalSettings that can be overridden per display. Nested objects (sleep, screensaver, alerts) are full-replacement, not deep-merged, override the whole object or omit it:

Per-display location overrides (latitude, longitude, locationName, timezone) are intentionally not available: the weather, air-quality, and calendar API routes read location via readConfig() directly rather than through filterConfigForDisplay, so a per-display override would only affect client rendering while the upstream fetch still used the hub's coordinates.

Per-display dimension fields (top-level on the DisplayNode) override the equivalents nested inside settings. Per-display settings override the global settings on a per-key basis. Rotation is authoritative for canvas orientation: the hub sorts the (width, height) pair so the long edge points along the landscape axis when the rotation is normal/180 and along the portrait axis when it's 90/270.

Validation rules (enforced when the config is written):

ModuleType

There are 45 built-in module types. Plugin modules use the plugin:<name> format.

One of clock, calendar, weather, countdown, dad-joke, text, image, video, quote, todo, sticky-note, greeting, news, fullscreen-news, stock-ticker, crypto, word-of-day, history, moon-phase, sunrise-sunset, photo-slideshow, qr-code, year-progress, traffic, sports, air-quality, todoist, rain-map, multi-month, garbage-day, standings, affirmations, date, display-control, meal-planner, iframe, icon, shape, chore-chart, timetable, fullscreen-calendar, fullscreen-chore-chart, fullscreen-meal-planner, fullscreen-photo, fullscreen-weather.

ModuleStyle

title and titleFontSize only apply to modules that render the standard card frame. Plugin modules and Display Control draw their content without the card, so a title strip can never appear on them, the editor hides the Card Title fields for those modules, and both keys are dropped from a plugin manifest's defaultStyle when a module is placed.

fontFamily stores a font registry id, not a raw CSS stack. The available ids are inter, roboto, poppins, system-ui, playfair, lora, dm-serif, georgia, jetbrains, mono, bebas, caveat, and pacifico. The fonts themselves are bundled at build time, so only these ids are guaranteed to load. A raw CSS stack is still accepted for backward compatibility, but anything the registry does not recognize is passed to the browser verbatim and will fall back to a system font.

Module Configs

Each ModuleInstance.config object holds the fields for its module type. Those fields, with their defaults and allowed values, are documented one table per module in the Module Reference: that page is the source of truth for module options, and the stored JSON matches it exactly.

Shared data files

Several features deliberately keep their data outside config.json: the four below, and the timetables, routines and running timer listed in Data files. The per-module config holds display options only; the data itself lives in a shared file so every module instance stays in sync, and so a save from the editor can never clobber something changed from /remote or tapped on a display.

data/meals.json

The meal library, weekly plan, grocery check-offs, and household-wide planning settings, written atomically via /api/meals/data. Settings live here rather than on each module so /remote and every meal-planner instance agree.

SavedMeal

Each entry in savedMeals:

Each of its ingredients:

MealSettings is edited from the /remote Meals tab so every meal module on every display stays consistent:

timeFormat is optional: when omitted (the default), meal times follow the household GlobalSettings.timeFormat; an explicit '12h'/'24h' wins everywhere meals are shown. Versions before this setting existed wrote '12h' into every file whether or not the user had touched the picker, so on first read after upgrading, a stored '12h' is treated as never-configured and removed once (a timeFormatLegacyStripped marker in the file keeps a later deliberate '12h' pick from being stripped again). A stored '24h' was always deliberate and survives as an explicit override.

Each PlannedMeal uses an ISO date string to support multi-week planning:

Old configs that used day: number (day-of-week index) are automatically migrated to ISO date format on first read.

data/family.json

The shared household roster, edited under Settings > Family or /remote > Settings > Family. /api/family returns its members and groups and a revision required for writes; groups are edited through /api/family/groups.

Each entry in members:

Chore identities survive migration and legacy restore by ID. Calendar identities are matched by ID or alias first, then by a unique normalized name. Existing rosters over 64 people and long legacy names are retained. The authoring API limits new additions to 64 people and new names to 40 characters.

data/chores.json

Chore definitions, served by /api/chores/data and edited from the /remote Chores tab. Family members are read separately from /api/family.

Completions live in a separate file, data/chore-completions.json, served by /api/chores:

Each entry in completions:

data/todos.json

The family's shared to-do lists (see Lists). Each list has a name, a colour, an optional start-fresh repeat, and its items with done state, due day and who it is for. A To-Do module only stores which list it shows, so editing a screen never touches a list and the same list can sit on any number of screens. The phone, the wall and the editor all write through /api/todo/lists.

Display Resolution Presets

In the editor you pick a resolution and an orientation separately: four presets, labelled 720p HD, 1080p Full HD, 1440p QHD, and 4K UHD, each with a Portrait/Landscape toggle that swaps the two dimensions. That gives eight combinations:

Config Migrations

Config files include a version number. When the schema changes between releases, migrations in src/lib/migrations/ automatically transform older configs to the current format on load. The current schema version is 16.

Migration runs when the config is read and the result is written back to disk automatically, so version in data/config.json updates itself the first time newer code reads an older config. If a migration fails, the un-migrated config is returned as-is rather than falling back to defaults, so a bad upgrade can never quietly replace your setup with an empty one.

Do not hand-edit version. A config marked with a version newer than the running code is left alone; there is no downgrade path.

Validation CLI

Home Screens ships a standalone validator for data/config.json that you can run without starting the dev server. It checks the schema version, module types, screen and module structure, profile references, multi-display registry constraints, and settings bounds, then reports a typed list of diagnostics with colored output.

npm run config:check

A clean config exits with status 0 and a "Config is valid" summary. Any errors, unknown module types, duplicate screen IDs, profile references to non-existent screens, out-of-range display dimensions, etc., exit with a non-zero status and a list of diagnostic entries, making the CLI safe to wire into a pre-commit hook or CI step on a server that mounts data/. The same validation rules are exposed programmatically from src/lib/validate-config.ts if you want to reuse them from your own tooling.

Backup & Restore

• Save a backup (under Save a copy in Settings > Backups & data) in the editor, or Backup All Data in the remote's Settings sheet, downloads a backup as JSON. The bundle contains your config, family, chores, chore completions, rewards, meals, routines, to-do lists and school timetables, plus your icons when Include your icons is on.
• Import replaces everything the uploaded file carries (available in both the editor and the remote); a section the file leaves out, such as the icons, is kept as it is
• A configurable backup reminder shows a toast in the editor and a banner on the remote when you haven't backed up recently (Settings > Backups & data)

Backing up your keys

By default a backup carries no keys at all. This part needs an editor password (Settings > Security): without one, anything on your network can ask the hub for your keys, and there is no way for it to tell you apart from anyone else. Until you set one, the checkbox below stays switched off.

In the editor, Settings > Backups & data > Save a copy has two checkboxes:

• Include my keys and connected accounts adds your weather and map keys, your Google, iCloud, Immich and OneDrive sign-ins, your plugin logins, and your editor password to the file. Both boxes start unticked every time you open the page, so an accidental tick never becomes your standing default.
• Protect them with a password locks that part of the file. You choose the password, and you need it again to put the keys back.

A backup that carries keys is named home-screens-backup-with-keys-<date>.json, so you can tell it apart in a downloads folder.

There is no way to recover the password. If you lose it you can still restore the backup, choose Restore without my keys at the prompt, and everything except the keys comes back. Losing the password costs you the keys, not your setup.

Restoring a backup that includes your editor password signs you out, because the password on this device becomes the one from the backup. Sign in again with that password. If the backup also had network address rules turned on and this device isn't on the restored list, the rules are left switched off so you can't lock yourself out; turn them back on in Settings once you've added this device.

The remote control's Settings sheet has no password prompt. Restoring a key-carrying backup there restores everything except the keys and tells you so, finish that part in the editor.

Example

{
  "version": 16,
  "settings": {
    "rotationIntervalMs": 30000,
    "displayWidth": 1080,
    "displayHeight": 1920,
    "latitude": 40.0150,
    "longitude": -105.2705,
    "timezone": "America/Denver",
    "weather": {
      "provider": "pirateweather",
      "latitude": 40.0150,
      "longitude": -105.2705,
      "units": "imperial"
    },
    "calendar": {
      "googleCalendarId": "",
      "googleCalendarIds": ["primary"],
      "icalSources": [],
      "daysAhead": 7
    }
  },
  "screens": [
    {
      "id": "abc-123",
      "name": "Main",
      "backgroundImage": "/backgrounds/sunset.jpg",
      "modules": [
        {
          "id": "mod-1",
          "type": "clock",
          "position": { "x": 20, "y": 40 },
          "size": { "w": 1040, "h": 220 },
          "zIndex": 1,
          "config": {
            "view": "classic",
            "format24h": false,
            "showSeconds": true,
            "showDate": true
          },
          "style": {
            "opacity": 1,
            "borderRadius": 12,
            "padding": 16,
            "backgroundColor": "rgba(0,0,0,0.4)",
            "textColor": "#ffffff",
            "fontFamily": "inter",
            "fontSize": 16,
            "backdropBlur": 12,
            "borderWidth": 1,
            "borderColor": "rgba(255,255,255,0.15)",
            "shadowSize": 8
          }
        }
      ]
    }
  ]
}