muxen-config — Overview

muxen-config is the boat's configuration store. It holds the description of the installation — which devices are fitted, what each one is called, which button drives which output, which tank sensor feeds which gauge, what the screens show — and it publishes exactly one of those descriptions as the configuration the boat actually runs on.

Nothing on board reads a project directly. Every other MUXEN service reads one file, /etc/muxen/deploy.json, and that file is a copy of the project that was last deployed. Editing a project changes nothing until someone deploys it; deploying it changes the whole boat at once.

The daemon itself has no user interface. The configuration interface on the boat's screen talks to it over HTTP, and so does anything else that needs to read or write the installation.

The problem it solves

A MUXEN installation is not described by any single device. A keypad knows it has four buttons; it does not know that button 2 is "saloon lights". A power output knows it is on or off; it does not know it feeds a fridge. The equations that tie them together live in the devices as parameters, and the names, the screens and the sensor scaling live nowhere at all unless something stores them.

muxen-config is that something. It keeps the whole installation as one JSON document per boat configuration — a project — and gives it:

• A place to live. /etc/muxen/configuration/<id>.json, one file per project, on the Brain, surviving reboots and package upgrades.
• An editing surface. A REST API over HTTP, so the configuration interface can add a device, rename it, attach a sensor or wire a button without ever handling the file.
• A single act of publication. PUT /project/<id>/deploy copies the project over /etc/muxen/deploy.json. That copy is atomic: consumers read a complete file or the previous one, never a half-written mixture.
• Somewhere to fall back to. A daily job keeps up to 30 dated copies of deploy.json, and any project can be exported and re-imported whole.

Where it sits

 configuration UI  ──HTTP──►  nginx  ──►  muxen-configd  ──►  /etc/muxen/configuration/<id>.json
 (screen, laptop)             :8080       127.0.0.1:12000            │
                                                                     │ PUT …/deploy
                                                                     ▼
                             every other muxen-* service  ◄──  /etc/muxen/deploy.json

It reads	From	Purpose
/etc/muxen/configuration/*.json	disk, per request	the projects being edited
/usr/share/muxen-config/templates/*.json	disk, read-only	factory templates, offered alongside projects
/etc/muxen/deploy.json	disk, per request	what GET /deploy serves
/etc/muxen/apps/*	disk, per request	opaque per-application blobs

It writes	To	Purpose
/etc/muxen/configuration/<id>.json	disk	every project edit
/etc/muxen/deploy.json	disk, atomically	the deployed configuration
/etc/muxen/apps/<id>	disk	whatever an application asked it to keep

It is a purely local, purely file-backed service. It joins no bus, publishes no MQTT topic, opens no outbound connection, and listens on 127.0.0.1 only — reaching it from anywhere else means going through nginx.

What a project is

A project is one JSON document describing one complete boat configuration. It carries metadata (name, id, creation and modification times), and a section per concern:

Section	What it holds
settings	boat-wide values: languages, degraded-mode names, feature flags, the optional project password
devices	every MUXEN device fitted, with its function, instance and parameter list
muxing	the switching rules — which input drives which output — and the device parameters they generate
sensors	analogue sensor definitions: input channel, output unit, scaling
energy	the electrical zones
buttonMapping	physical button → named function
views	the screen pages, their elements and their translations
media	images and other blobs, base64-encoded inside the project
commissioning	option groups that strip a template down to the boat actually built
synapse	automation instances, keyed by instance id

The project file documents every section field by field.

Templates and commissioning

A boat is rarely configured from nothing. The package creates /usr/share/muxen-config/templates/, and any project file placed there appears in the project list marked type: template. Templates are on a read-only filesystem, so they can be read and duplicated but never edited.

Duplicating a template is also where commissioning happens: the duplicate request may carry the answers to the template's option groups — "is there a watermaker?", "how many cabins?" — and the daemon applies them while copying, removing the devices, sensors, views and switching rules the boat does not have. What comes out is a project for that hull, not a catalogue.

Projects covers the whole lifecycle.

Passwords

A project can carry a password setting. Once it does, every request touching that project — reading it, editing it, deploying it, deleting it, overwriting it, restoring over it — must present the matching credential. There is no user database and no session: the setting stores a SHA-256 hash, the client sends it in an Authorization header, and the daemon compares the two.

Document map

Document	Content
Getting started	install, verify, create and deploy a first project
Projects	projects, templates, commissioning, passwords, backup and restore
Deployment	deploying, deploy.json, serving it, caching, the daily backups
Troubleshooting	symptom → cause → check → fix, plus FAQ and tips
Reference	CLI, units, paths, the full endpoint table, status and exit codes
The project file	the project JSON document, section by section