EdS

A Music Inventory

Mon, 01 Jan 0001 00:00:00 +0000

Proposal: A Music Inventory


Status	Proposal, not decided and not built
Date	2026-10-24
Where	eds-inventory, a project of its own: repository, docs. It runs in EdS’s Deevnet IoTaaS tenant
Would extend	ADR-0022, ADR-0038, ADR-0041, ADR-0045, ADR-0046

A local inventory of the owner’s music, in every format, that holds one answer for each album and that EdS asks first. EdS would be its customer, the way lightd is a customer of palette.

Why

EdS answers “what album is this, what does it look like, what else is there” by asking a different place for each question:

ADR-0001: The Stand Renders Effects

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0001: The Stand Renders Effects Locally and Never Receives Frames


Status	Accepted
Date	2026-09-07
Scope	What travels from `lightd` to a stand, and where animation happens.
Backfilled	Decided with the first firmware and argued in `firmware/lp-stand/README.md`; written up here on 2026-10-10.
Related	ADR-0002, Scene Descriptor

Context

The stand is an ESP32 driving an addressable strip over WiFi from a broker it does not control. The light has to look deliberate at all times, including when the network is slow or gone, and the stand is meant to sit on a shelf unattended.

Background: Sound Around the House

Mon, 01 Jan 0001 00:00:00 +0000

Background: Sound Around the House

EdS did not bring music to the rooms of the house. A whole-house digital audio system was already doing that, was built years before EdS, and carries on exactly as it did. EdS listens in on it. This page is the short version; the project’s own page has the whole of it: S/PDIF Audio Distribution.

Whole-house digital sound distribution

One digital feed (S/PDIF) is sent from the basement to every room, and each room’s own stereo plays it.

Change Record Template (CHG)

Mon, 01 Jan 0001 00:00:00 +0000

Change Record Template (CHG)

The shape every change record takes. Copy the skeleton into a new file, fill it in before the change runs, and complete Outcome after. CHG-0001 is a worked example.

It follows Deevnet IoTaaS’s template, trimmed to what an application needs: no site or maintenance window, because EdS changes one tenant and its own devices.

Where it goes


Number	The next unused `CHG-NNNN`, in the order records are opened. Runs across years, never reused, and kept even if the change is abandoned.
File	`docs/content/docs/changes/<YYYY>/<NNNN>-<slug>.md`
Title	`CHG-NNNN: <What changed>`, from the point of view of what is running
Date	The day execution starts. While it is still planned, the planned date; with none yet, Unscheduled
Weight	`NNNN`, so records sort by number
Index	Add a row to Change Records and to that year’s page

Status

Planned → In progress → Complete, or Rolled back or Abandoned. A record is never deleted: a change that was abandoned or rolled back is exactly the one worth keeping.

CHG-0001: The LP Stand Joins Its Tenant

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0001: The LP Stand Joins Its Tenant


Date	2026-10-10
Change type	Deployment
Status	Complete 2026-10-10
Systems	`lp-stand-01` (ESP32-D0WD-V3); the `eds` tenant’s Grafana organization
How	`make build flash provision` in `firmware/lp-stand`; `terraform apply` in `infra/deevnet-tenant-eds`
Risk	Low. Nothing issued is replaced. Most likely to go wrong: a broker account missing a topic the firmware uses, which fails silently
Decisions	ADR-0004, ADR-0005
Related	None
Backfilled	Written after the change ran, from the session that ran it.

Summary

The stand had been flashed once, on 2026-09-09, built for plaintext MQTT on port 1883 and never provisioned. Deevnet IoTaaS’s broker is TLS only, so it had never reached the real broker; it sat lit in its default warm white, retrying WiFi with no key.

Firmware: lp-stand

Mon, 01 Jan 0001 00:00:00 +0000

Firmware: lp-stand

ESP-IDF in C, following the conventions of esp32-ma-bell-gateway: main/app/, main/config/, main/hardware/, main/network/, with a Makefile wrapper over idf.py.

The split that matters

Scene validation, effect rendering, gamma and event formatting are pure C with no ESP-IDF dependency, because that is where a bug is subtle: it shows up only as the light looks wrong, or, for an event that is not valid JSON, as nothing at all. They are tested with a compiler and nothing else:

INC-0001: The Beatles Played for a Request Nobody Made

Mon, 01 Jan 0001 00:00:00 +0000

INC-0001: The Beatles Played for a Request Nobody Made


Date	2026-10-24
Systems	`respeaker-01`, `eds-scribe` and `eds-voiced` on the services workload, nowplayd, the relay’s iTunes driver
Severity	An album nobody asked for replaced what was asked for. Recovery needed no more than asking again
Status	Open · Hardening
Times	UTC

Summary

The first request sent from the reSpeaker played Abbey Road. Its owner had asked for Aerosmith’s first album. scribe, given five seconds it could not make out, wrote back the prompt it had been given to spell names by - “Play Abbey Road by the Beatles.” - and voiced, which acted on any words scribe returned, read that as a request and sent play_album.

Now Playing

Mon, 01 Jan 0001 00:00:00 +0000

Now Playing

Knowing what is playing is the one thing every other subsystem needs, so it is a subsystem of its own and the others are built on it. It hears or asks each source of music, decides which one is current, completes what it was told, and publishes one answer for everyone else.

Running the Vertical

Mon, 01 Jan 0001 00:00:00 +0000

Running the Vertical

The whole chain on one machine, with no deevnet infrastructure.

1. Start the palette extractor

cd services/palette
make venv
make serve PORT=8731

2. Start a broker and lightd

cd services/lightd
make broker # mosquitto in podman on tcp://127.0.0.1:21883
make run

make run builds lightd and points it at the development broker. It expects palette on :8731.

3. Watch the topic tree

In another terminal:

cd services/lightd
make broker-watch # tail every eds/# topic

4. Send a cover

curl -F image=@jacket.jpg http://localhost:8732/v1/cover

A scene should appear on eds/lightstand/lp-stand-01/scene. Because gamma is applied on the device rather than on the wire, the colors you see here are the colors actually intended.

Scene Descriptor

Mon, 01 Jan 0001 00:00:00 +0000

Scene Descriptor

The payload lightd publishes and the LP stand renders. It is a description of what to render, never a frame.

{
 "v": 1,
 "effect": "breathe",
 "speed": 0.4,
 "brightness": 0.8,
 "palette": [
 { "rgb": [232, 77, 0], "weight": 0.5594 },
 { "rgb": [182, 159, 0], "weight": 0.3661 }
 ]
}

Field	Type	Meaning
`v`	int	Contract version. Currently `1`.
`effect`	string	`solid`, `breathe`, `sweep`, `morph`, `chase` or `scanner`.
`speed`	float	`0..1` dial, not a frequency.
`brightness`	float	`0..1`, applied before gamma on the device.
`palette`	array	Colors already corrected for the strip, ranked by weight.
`palette[].rgb`	`[int, int, int]`	sRGB, 0–255. Gamma is not applied.
`palette[].weight`	float	Share of the scene. Renormalized after filtering.

Version handling

A scene carrying a different v is refused, not guessed at. A scene that is malformed or unparseable is ignored, and the previously rendering scene keeps running — a stand that goes dark on a bad payload is worse than one that ignores it.

ADR-0002: Gamma Belongs to the Firmware

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0002: Gamma Belongs to the Firmware, Not the Wire


Status	Accepted
Date	2026-09-07
Scope	Which layer makes which color decision between a cover image and the strip.
Backfilled	Decided with the first vertical and argued in the project READMEs and Boundaries; written up here on 2026-10-10.
Corrected	2026-10-13: the consequence about OKLab said the conversion is implemented three times, in Python, Go and C. It is in two, and never was in the firmware. The decision is unchanged.
Related	ADR-0001

Context

A color passes through three programs on its way from a sleeve to a strip: palette extracts it, lightd turns swatches into a scene, and the firmware drives the LEDs. Several corrections have to happen somewhere along the way — rejecting dull swatches, boosting chroma, mapping into the strip’s gamut, and gamma, because WS2812 output is linear in duty cycle and perception is not.

Capturing Vinyl

Mon, 01 Jan 0001 00:00:00 +0000

Proposal: Capturing Vinyl


Status	Proposal, not decided and not built
Date	2026-10-25
Where	EdS listens and captures; eds-inventory knows what is captured and what is missing
Would extend	ADR-0021, ADR-0022, ADR-0026

Every record played is captured to FLAC, by itself: put a record on and it is kept, track by track, and a track already kept is skipped. Nobody presses record. Over time the digital collection comes to include what is held only on vinyl, and every capture teaches EdS to name that record itself.

CHG-0002: The Relay Pi, and Accounts for Now Playing

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0002: The Relay Pi, and Accounts for Now Playing


Date	2026-10-10
Change type	Deployment
Status	Complete 2026-10-10
Systems	the `eds` tenant’s broker accounts; `dv02rpi002p01` (a Pi lab host in the site inventory); iTunes on a PC on the home LAN
How	`terraform apply` in `infra/deevnet-tenant-eds`; `make -C deploy/relay image fetch card status pair`
Risk	Medium. A host is put on two networks the site otherwise keeps apart. Most likely to go wrong: the Pi’s Wi-Fi leg picking up a default route or DNS, which would send site traffic through the house
Decisions	ADR-0006, ADR-0010, ADR-0011, and, made during it, ADR-0015
Related	CHG-0001

Summary

iTunes runs on a PC on the home LAN. The broker is inside the Deevnet Mobile site. Neither can reach the other, so nothing that happens in iTunes can reach the stand.

Firmware: cover-screen

Mon, 01 Jan 0001 00:00:00 +0000

Firmware: cover-screen

The touch screen that shows the cover and has the five buttons (ADR-0020). ESP-IDF in C, laid out as lp-stand is, for an ESP32-2432S028R.

The split that matters

What a touch means and what is painted over the cover are pure C, because that is where a bug shows up only as it did the wrong thing when I touched it:

make test # needs gcc; no ESP-IDF, no hardware
make pictures # draws each screen to a BMP, with a made-up cover

make pictures runs the board’s own drawing code. Change an icon, run it, and look.

INC-0002: Deploys Hung the Core Router

Mon, 01 Jan 0001 00:00:00 +0000

INC-0002: Deploys Hung the Core Router


Date	2026-10-24
Systems	The mobile site’s core router; `deploy/` (`make ship`, `make load`), the Builder, the services workload
Severity	The mobile site’s routed traffic stopped, twice, until the owner rebooted the router; a deploy was left half done, with the services still on the version before
Status	Open · Hardening
Times	UTC

Summary

Every deploy sent every image from the Builder to the services workload, whether it had changed or not, as fast as it would go: about a gigabyte, most of it scribe’s 767 MB and palette’s 256 MB, through the core router that joins the Builder’s segment to the workload’s. That evening it was done eight times. During the eighth, and again when it was retried, the router hung, and the site’s routed traffic with it.

Incident Record Template (INC)

Mon, 01 Jan 0001 00:00:00 +0000

Incident Record Template (INC)

The shape every incident record takes. Copy the skeleton into docs/content/docs/incidents/<YYYY>/<NNNN>-<slug>.md, numbered with the next unused INC-NNNN, and add a row to the index.

Start the record while the incident is fresh, even with most sections empty. The timeline and the wrong turns are the parts memory loses first.

Status

An incident carries a status and a substatus. The status says whether anything is left to do; the substatus says how far along it is, and only moves forward.

LP Light Show

Mon, 01 Jan 0001 00:00:00 +0000

LP Light Show

The first subsystem, and EdS’s first idea of many: a record’s cover becomes the light on its stand. Prop the jacket on the LP stand and it is illuminated in its own colors, set slowly moving, for as long as the record plays. It is the first of what may be several light shows, which is why it is named for the LP.

Palette API

Mon, 01 Jan 0001 00:00:00 +0000

Palette API

POST /v1/palette — image bytes in, ranked color swatches out.

Accepts either a multipart upload or a raw body. Both return the same result: multipart is what a person uses, the raw body is what lightd uses.

curl -F image=@jacket.jpg 'http://localhost:8731/v1/palette?n=5'

curl --data-binary @jacket.jpg -H 'Content-Type: image/png' \
 'http://localhost:8731/v1/palette'

GET /openapi.json publishes the schema, which is how the contract stays honest across the Python/Go boundary.

Parameters

Name	Type	Default
`n`	int, 1–16	6	Swatches to return.

Response

{
 "v": 1,
 "swatches": [
 { "rgb": [225, 82, 26], "hex": "#e1521a",
 "oklab": [0.6264, 0.147, 0.1184],
 "weight": 0.3705, "chroma": 0.1888, "lightness": 0.6264 }
 ],
 "background_dropped": 0.8855,
 "fallback": false,
 "source": { "width": 600, "height": 600, "format": "jpeg" }
}

weight: Share of clustered pixels, so swatches are ranked by how much of the sleeve they actually cover.
background_dropped: Share of pixels discarded before clustering.
fallback: True when filtering removed so much that the unfiltered image was used instead. Genuinely monochrome art sets this rather than returning nothing.
chroma: How far the color is from neutral. Consumers should treat a low-chroma swatch as unfit to drive a strip regardless of its weight — see below.

Known characteristics

Low n on busy art returns low-chroma centroids. Asking for 2 swatches from a four-color sleeve forces one cluster to merge three of them, and the merged centroid is close to their average. This is arithmetic, not a bug — but it is why chroma is in the contract. The default n=6 avoids the situation for most art.

Provisioning a Stand

Mon, 01 Jan 0001 00:00:00 +0000

Provisioning a Stand

Credentials live in a dedicated creds NVS partition, not in the firmware image. The WiFi key and the broker password have no build-time option at all: NVS is the only place they can come from. A built binary therefore carries no secret and can be cached, copied and shared without care, and sdkconfig cannot hold one.

From the tenant

A stand on Deevnet IoTaaS is flashed with what the EdS tenant issued:

Services: palette and lightd

Mon, 01 Jan 0001 00:00:00 +0000

Services

palette

cd services/palette
make venv # .venv with editable install + dev extras
make test # pytest, no network
make serve PORT=8731

Run a single test:

.venv/bin/pytest tests/test_extract.py::test_name -q

Tuning by eye

The thresholds are judgment calls that no test can settle — where a color stops being a color, how much black field to discard. The CLI exists for that loop:

make palette COVERS=~/covers
make sheet COVERS=~/covers # PNG contact sheet
.venv/bin/eds-palette ~/covers --min-chroma 0.05 --min-lightness 0.08

It prints truecolor swatches in the terminal and can render a sheet of thumbnails beside their weighted palettes, so many sleeves can be compared at once.

ADR-0003: The Broker Is Deevnet IoTaaS's

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0003: The MQTT Broker Is Deevnet IoTaaS’s, Not a Tenant VM


Status	Accepted
Date	2026-09-07
Scope	Where EdS’s MQTT broker runs, and so how devices and services meet.
Backfilled	Decided when the tenant was first written and argued in `infra/deevnet-tenant-eds/README.md`; written up here on 2026-10-10.
Related	Deevnet ADR-0001, ADR-0003 and ADR-0012 (deevnet-docs)

Context

EdS’s services run on a workload in its own tenant on Deevnet IoTaaS. Its devices are ESP32s on Deevnet IoTaaS’s IoT network. Both need a broker.

CHG-0003: The Stand Follows What Is Playing

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0003: The Stand Follows What Is Playing


Date	2026-10-11
Change type	Deployment
Status	Complete 2026-10-11
Systems	the `services` workload of the `eds` tenant: `eds-lightd`, and a new `eds-nowplayd`; by consequence, `lp-stand-01`
How	`make -C deploy deploy WHERE=builder`
Risk	Low. `lightd` gains an input and loses none. Most likely to go wrong: a settings file that leaves `nowplayd` unable to log in to the broker, which shows as a unit restarting
Decisions	ADR-0006, ADR-0008, ADR-0009
Related	CHG-0002, whose follow-up this is

Summary

Since CHG-0002 the agent Pi has reported what iTunes is playing to the broker, and nothing has acted on it. The stand shows whatever cover was last sent to it by hand.

INC-0003: The Library Index Was Unreadable to voiced

Mon, 01 Jan 0001 00:00:00 +0000

INC-0003: The Library Index Was Unreadable to voiced, and Nothing Said So


Date	2026-10-24
Systems	`eds-voiced` on the services workload; `make -C deploy library`
Severity	Requests were answered as before the index (ADR-0045) rather than from it; some that it would have answered were not. Nothing wrong played
Status	Open · Hardening
Times	UTC

Summary

CHG-0040 copied the owner’s library index to /var/lib/eds-voiced with install, which labelled it var_lib_t. voiced’s container, which podman’s :Z gives container_file_t and its own categories, could not read it. voiced took an unreadable index for none, as it was written to, and said nothing: requests went on being guessed at.

MQTT Topics

Mon, 01 Jan 0001 00:00:00 +0000

MQTT Topics

The topic prefix defaults to eds and must match on both sides — lightd’s LIGHTD_TOPIC_PREFIX and the firmware’s LP_TOPIC_PREFIX.

Topic	Direction	Retained
`eds/lightstand/<id>/scene`	lightd → device	yes	what to render
`eds/lightstand/<id>/status`	device → broker	yes (LWT)	`online` / `offline`
`eds/lightstand/<id>/state`	device → broker	yes	what it is rendering now
`eds/lightd/status`	lightd → broker	yes (LWT)	the publisher’s presence
`eds/console/status`	console → broker	yes (LWT)	the console’s presence; the only thing it publishes
`eds/log/<id>`	device or agent Pi → broker	no	key events, for the log store: the stand’s, the cover screen’s, the power beacon’s, and the now-playing agent’s (`np-relay`)
`eds/nowplaying/source/<id>/…`	a driver → nowplayd	yes	what one player is doing; see Now Playing
`eds/nowplaying/current`	nowplayd → subscribers	yes	the one current track
`eds/nowplaying/current/art`	nowplayd → subscribers	yes	its cover, as image bytes; lightd lights the stand from it
`eds/nowplaying/current/art/small`	nowplayd → subscribers	yes	the same cover at 240 pixels, as a baseline JPEG; the cover screen shows it
`eds/nowplaying/command`	a controller → nowplayd	never	a button press, for whatever is current; see Now Playing
`eds/nowplaying/source/<id>/command`	nowplayd → a driver	never	the same press, passed to the current source; `play_album` to `NP_ALBUM_SOURCE` whatever is current (ADR-0040)
`eds/voice/<device>/utterance`	device → voiced	never	what followed the wake word: a WAV, 16 kHz 16-bit mono, at most 15 s (ADR-0042)
`eds/voice/<device>/woken`	device → voiced	never	`{"v":1}`: the wake word was just heard, so the music is turned down (ADR-0044)
`eds/voice/<device>/heard`	voiced → device, console	never	`{"v":1,"text","understood","artist","album","reason"}`: what was made of the request
`eds/voiced/status`	voiced → broker	yes (LWT)	its presence
`eds/screen/<id>/status`	device → broker	yes (LWT)	the cover screen’s presence
`eds/beacon/<id>/status`	device → broker	yes (LWT)	whether the switch a beacon is on has power: `online` while it does, the will’s `offline` when it has not. nowplayd reads the one that speaks for the turntable (ADR-0023)
`eds/nowplaying/current/look`	nowplayd → lightd	yes	whether that cover’s album has a look of its own, by name; see Now Playing
`eds/nowplaying/stand`	console → nowplayd	yes, as a setting	which sources the stand is lit for: `{"v":1,"sources":"records"}`, the default, or `"all"` (ADR-0039)

The log topic

eds/log/<id> is not EdS’s own layout. <tenant>/log/<device> is the one topic under log/ Deevnet IoTaaS lets a device account publish, and its log bridge carries what arrives there into the tenant’s device log partition. The stand sends one JSON object per event — boot, network, scenes, health — at QoS 1 and not retained: a log line replayed to every new subscriber would be an event that never happened again.

Powering the Strip

Mon, 01 Jan 0001 00:00:00 +0000

Powering the Strip

WS2812-class LEDs draw about 60 mA each at full white, so a long strip at full brightness is an amp-scale load. The ESP32 devkit adds roughly 250 mA with WiFi up and peaks near 500 mA on transmit.

What EdS actually draws

Brightness is applied before the gamma 2.6 table, which means current falls away far faster than the brightness figure suggests. Measured against the firmware’s own lookup table:

Remote Display

Mon, 01 Jan 0001 00:00:00 +0000

Remote Display

A small touch screen that shows the cover of whatever is playing, and can change it (ADR-0020). It is a stand-alone display and remote: for simple things, play or pause, back and next, it is handier than the phone app, and it is a way to enjoy the cover art in another room.

Tenant: deevnet-tenant-eds

Mon, 01 Jan 0001 00:00:00 +0000

Tenant: deevnet-tenant-eds

The EdS tenant as code: its overlay network, its workload and its DNS records, rebuildable from scratch against Deevnet IoTaaS without a Deevnet IoTaaS commit (Deevnet ADR-0006).


Index	1 (to be allocated in the factory’s `TENANTS.md`)
Subnet	`10.20.129.0/24`, gateway `10.20.129.1`
Zone	`eds.mobile.deevnet.net`
Service host	`10.20.129.10` — `palette` and `lightd`
Module	`tenant-module-v1.1.0`

Status: written, never applied

terraform validated against the real module, with derived addressing checked against Deevnet ADR-0002. It has not been planned or applied, and three things must happen first:

ADR-0004: Firmware Secrets Are NVS-Only

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0004: Firmware Secrets Are NVS-Only, and the Broker’s CA Is Provisioned


Status	Accepted
Date	2026-10-10
Scope	Where a device’s WiFi key, broker password and broker CA come from.
Related	CHG-0001, Provisioning a Stand

Context

The stand needs a WiFi key and a broker password, both issued by the EdS tenant, and the CA that the broker’s certificate is verified against. The repository is public, and the firmware image gets built, cached and copied.

CHG-0004: Spotify on the Agent Pi

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0004: Spotify on the Agent Pi


Date	2026-10-11
Change type	Deployment
Status	Complete 2026-10-11
Systems	the agent Pi `dv02rpi002p01`; the `np-relay` broker account of the `eds` tenant; `eds-nowplayd` on the `services` workload
How	`terraform apply`; `make -C deploy units`; `make -C deploy/relay push spotify`
Risk	Low to the stand, which this change is designed not to affect. Most likely to go wrong: the account change reissuing the relay’s password, which would silence iTunes too
Decisions	ADR-0012, ADR-0016
Related	CHG-0002, CHG-0003

Summary

The agent Pi follows iTunes. After this change it also follows a Spotify account, and reports what that account plays on the devices named as being in the room.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration

lightd

All environment, no config file: the broker credentials must never land on disk in a repository, and the same binary has to work under a systemd unit or a container without knowing which.

Variable	Default
`LIGHTD_ADDR`	`:8732`	listen address
`LIGHTD_PALETTE_URL`	`http://127.0.0.1:8731`	palette service
`LIGHTD_STAND_ID`	`lp-stand-01`	default stand
`LIGHTD_COVER_TOPIC`	unset	a topic of cover images to light the stand from, relative to the prefix, e.g. `nowplaying/current/art`
`LIGHTD_LOOK_TOPIC`	unset	a topic that says which covers have a look of their own, e.g. `nowplaying/current/look`. Needs `LIGHTD_COVER_TOPIC`
`LIGHTD_SPECTRUM_EFFECT`	`sweep`	how the `spectrum` look moves: `sweep`, the rainbow around the strip, or `morph`, each color in turn. Anything else stops the daemon
`LIGHTD_TOPIC_PREFIX`	`eds`	root of the topic tree
`LIGHTD_MQTT_URL`	`tcp://127.0.0.1:1883`	`tls://mqtt01…:8883` in production
`LIGHTD_MQTT_USERNAME` / `_PASSWORD`	—	broker credentials
`LIGHTD_MQTT_CA_FILE`	—	CA for the broker’s certificate
`LIGHTD_MQTT_INSECURE`	`false`	bring-up only; never with a real cert
`LIGHTD_EFFECT`	`breathe`	default effect: `solid`, `breathe`, `sweep`, `morph`, `chase` or `scanner`
`LIGHTD_SPEED` / `LIGHTD_BRIGHTNESS`	`0.4` / `0.8`
`LIGHTD_SWATCHES`	`6`	swatches requested from palette
`LIGHTD_MIN_CHROMA`	`0.05`	below this a swatch is a gray
`LIGHTD_SATURATION`	`1.25`	chroma multiplier for the strip
`LIGHTD_MAX_COLORS`	`4`	palette entries per scene

Invalid values stop the daemon rather than lighting the room wrong quietly.

EdS on One Pi

Mon, 01 Jan 0001 00:00:00 +0000

EdS on One Pi

Everything EdS needs can be put on one Raspberry Pi on the home network: the broker, the log store, Grafana, the four services and the now-playing agent. Nothing of Deevnet IoTaaS is behind it.

Not yet proven. The image is defined and has not run on a Pi. ADR-0033 is Proposed and lists what would settle it.

stand, screen, beacon ──TLS 8883──▶ ┌ Pi ────────────────────────────────┐
iTunes PC ◀── remote protocol ────▶ │ Mosquitto · log store · Grafana │
a browser ──────── 443 ───────────▶ │ palette · lightd · nowplayd │
turntable ── tape out, sound card ─▶│ console · npagent │
 └────────────────────────────────────┘

It is beside the tenant on Deevnet IoTaaS, not in place of it. Building the image and running the Pi change nothing there, and the stand, the screen and the beacon stay with the tenant until each is provisioned again.

INC-0004: The Stand Went Dark on One Channel

Mon, 01 Jan 0001 00:00:00 +0000

INC-0004: The Stand Went Dark Mid-Side, Because the Turntable Was Heard on One Channel and That One Went Silent


Date	2026-10-26
Systems	`npagent`’s turntable driver and `nowplayd` on the backend Pi; the UFO202 sound card; the Tape 1 output of the amplifier, an Onkyo A-8170 integrated amplifier from the mid-1980s; `lp-stand-01`
Severity	The stand dropped to standby for the rest of a side, and stayed there through a reboot. Nothing else was lost; every other source and device worked
Status	Open · Mitigated
Times	UTC

Summary

The turntable reaches the sound card through the Tape 1 output of an Onkyo A-8170, an integrated amplifier from the mid-1980s, whose aged tape selector contacts can drop a channel. Partway through a side, the left channel went silent. npagent records one channel, and what it records is the left, so it heard twenty seconds of silence, decided the record had stopped, and the stand went to standby while the record played on.

Now Playing

Mon, 01 Jan 0001 00:00:00 +0000

Now Playing

The contract between the programs that know what is playing and the programs that react to it. It is version 1, stamped on every message as "v": 1, and a message with any other version is refused rather than guessed at.

Why it is shaped this way: ADR-0006 and ADR-0008.

Topics

All under the tenant’s prefix, eds/.

Topic	From	Retained	Payload
`nowplaying/source/<id>/state`	a driver	yes	what that player is doing
`nowplaying/source/<id>/status`	a driver	yes (last will)	`online` / `offline`
`nowplaying/source/<id>/art`	a driver	yes	the cover, as image bytes
`nowplaying/current`	nowplayd	yes	the one current track
`nowplaying/current/art`	nowplayd	yes	its cover, as image bytes
`nowplaying/current/art/small`	nowplayd	yes	the same cover, small: a baseline JPEG, 240 pixels on its longer side
`nowplaying/current/look`	nowplayd	yes	whether that cover’s album has a look of its own; with no cover, whether the room is waiting for one
`nowplaying/stand`	the console	yes	which sources the stand is lit for: `records` or `all`
`nowplaying/command`	a controller	never	a button press, for whatever is current
`nowplaying/source/<id>/command`	nowplayd	never	that press, passed to the current source
`nowplaying/source/spotify/switch`	the console	yes	whether the Spotify driver runs: `on` or `off`, and nothing is `off` (ADR-0051)
`nowplaying/status`	nowplayd	yes (last will)	`online` / `offline`

<id> names one driver deployment, such as itunes-den. It is lowercase letters, digits and hyphens, at most 63 characters, starting with a letter or digit.

This Site

Mon, 01 Jan 0001 00:00:00 +0000

This Site

Hugo with the hugo-book theme, following the deevnet-docs pattern. It lives at docs/ inside the monorepo so documentation and the thing it documents move in the same commit.

cd docs
make server # live reload on :1313
make html # build to public/

The theme is a git submodule. After a fresh clone:

git submodule update --init --recursive

Living in a monorepo

Two consequences, both handled:

A repository serves exactly one Pages site. The site is therefore published at https://cdeever.github.io/eds/ — the repository name, not the site name — and baseURL reflects that. BookEditPath carries the docs/ prefix so “edit this page” links resolve.

Voice Request

Mon, 01 Jan 0001 00:00:00 +0000

Voice Request

An album played because someone asked for it out loud: “play Aerosmith’s first album”, and it plays (ADR-0042). It is in development: one device listens so far, and it sits wherever it is being worked on. Ears are meant to be on several devices throughout the house, or on one carried from room to room.

ADR-0005: Device Events Over MQTT

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0005: A Device Reports Key Events Over MQTT, Not Its Serial Log


Status	Accepted
Date	2026-10-10
Scope	How an EdS device says what it is doing once the USB cable is gone, and how that is read.
Extended by	ADR-0017: an agent Pi is registered as a device and reports the same way
Related	CHG-0001, Deevnet ADR-0027 and CHG-0021 (deevnet-docs), MQTT Topics

Context

A stand on a shelf has no console. It fails soft by design, which makes its failures quiet: one that keeps showing the last good scene looks, from the room, exactly like one that was sent nothing.

CHG-0005: The Agent Reports Its Events

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0005: The Agent Reports Its Events


Date	2026-10-11
Change type	Deployment
Status	Complete 2026-10-11
Systems	the `eds` tenant’s device registry and the `np-relay` broker account; the agent Pi `dv02rpi002p01`
How	`terraform apply -target`; `make -C deploy/relay push`; one line added to the Pi’s settings
Risk	Low. Most likely to go wrong: giving the account a device replaces it and reissues its password, which would silence both drivers
Decisions	ADR-0017
Related	CHG-0004

Summary

The agent Pi follows iTunes and Spotify and says so only in its own journal. After this change it is a registered device of the tenant and reports its key events to the log store: each track that plays, and each time a driver comes or goes.

Layer Boundaries

Mon, 01 Jan 0001 00:00:00 +0000

Layer Boundaries

Each component of EdS is built to do one well-defined job, and to do it without knowing how its neighbors do theirs. It takes a plain input, returns a plain output, and keeps everything in between to itself: much as abstraction and encapsulation work in object-oriented programming, applied to services and devices in place of classes.

That is what lets each part be built, tested and tuned alone, and replaced without the others noticing. palette can be tuned against a folder of JPEGs with nothing else running. A different diffuser wants a different gamma curve, and that changes the firmware and nothing upstream of it.

ADR-0006: Now Playing Is a Bus of Small Drivers

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0006: Now Playing Is a Bus of Small Drivers Behind One Contract


Status	Accepted
Date	2026-10-10
Scope	How EdS learns what is playing across several players, and how that knowledge reaches whatever reacts to it.
Extended by	ADR-0020: a controller may send a command for the current track, and a driver that can carry one out reads its own command topic
Related	ADR-0003, ADR-0007, ADR-0008, and one record per player: 0011, 0012, 0013, 0014

Context

The stand lights from a cover image, but nothing tells EdS what is playing. lightd has carried POST /v1/cover since the first vertical as “the interface the future album-cover resolver will call”; this is what sits upstream of it.

CHG-0006: The Console

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0006: The Console


Date	2026-10-11
Change type	Deployment
Status	Complete 2026-10-11
Systems	the `eds` tenant: a new broker account and a DNS name; the `services` workload: a new `eds-console`, and its firewall
How	`terraform apply`; `make -C deploy deploy WHERE=builder`
Risk	Low. Nothing existing is changed except by being restarted. Most likely to go wrong: the console unable to bind port 80 as a user who is not root
Decisions	ADR-0018
Related	CHG-0003

Summary

EdS gains a page of its own: what is playing and on which player, its cover, each stand drawn in the colors and motion it was sent, and whether each part is up. It is served from the workload at http://console.eds.mobile.deevnet.net/ and only looks.

ADR-0007: Drivers Are Portable Go

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0007: Drivers Are Portable Go, in One Agent Binary


Status	Accepted
Date	2026-10-10
Scope	The language and packaging of the now-playing drivers and backend.
Related	ADR-0006

Context

The players run on Windows 11, which pulls toward Windows tooling. But development happens on a Mac against the Deevnet Mobile site, some drivers will run on a Raspberry Pi and some on the tenant workload, and lightd is already Go.

CHG-0007: The Console Over TLS

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0007: The Console Over TLS


Date	2026-10-11
Change type	Deployment
Status	Complete 2026-10-11
Systems	the `eds` tenant: a certificate, held in its state; the `services` workload: `eds-console`, and its firewall
How	`terraform init -upgrade`, `terraform apply`; `make -C deploy deploy WHERE=builder`
Risk	Low. Most likely to go wrong: the console unable to read its key as the user it runs as, which stops it at start with the reason in its log
Decisions	ADR-0018; Deevnet ADR-0037, which gave tenants a CA to ask
Related	CHG-0006; Deevnet CHG-0047, which built the Tenant Service CA this is the first use of

Summary

The console is served in the clear, because when it was built nothing on the site would certify a name a tenant serves. Deevnet IoTaaS now has a Tenant Service CA (Deevnet ADR-0037), and a tenant can ask it for a server certificate for a name in its own zone.

ADR-0008: nowplayd Picks the Track and Guarantees the Fields

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0008: nowplayd Picks the Current Track and Guarantees Title, Album and Art


Status	Accepted
Date	2026-10-10
Scope	What turns several sources’ states into one current track, and who is responsible for the fields subscribers rely on.
Extended by	ADR-0016: a source can be named as reported without its cover, and then the promise of art does not apply to it
Related	ADR-0006, ADR-0009

Context

Several drivers may report at once: a paused iTunes, a Spotify playing on a phone. Subscribers want one answer. They also need a title, an album and a cover, and the drivers cannot all supply those: TIDAL through Last.fm arrives with no art, and a locally read TIDAL has no album.

CHG-0008: The Stand Reports Its Colors

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0008: The Stand Reports Its Colors


Date	2026-10-11
Change type	Upgrade
Status	Complete 2026-10-11
Systems	`lp-stand-01`, over USB from the development Mac
How	`make -C firmware/lp-stand build flash PORT=/dev/cu.usbserial-0001`
Risk	Low. Most likely to go wrong: a flash that also erased the stand’s credentials, which would leave it off the network until provisioned again
Decisions	ADR-0005
Related	CHG-0001

Summary

When the stand applies a scene it reports the effect, how many colors and the brightness. It does not say which colors. The firmware that does has been on main since it was written for a dashboard panel that was not kept, and has never been on the stand.

ADR-0009: lightd Takes Covers From a Topic

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0009: lightd Takes Covers From a Topic as a Second Input


Status	Accepted
Date	2026-10-10
Scope	How the current track’s cover reaches `lightd`.
Extended by	ADR-0019: a cover may arrive with the name of a look, which `lightd` draws in place of the cover’s own colors
Related	ADR-0002, ADR-0008

Context

nowplayd publishes the current cover as image bytes on eds/nowplaying/current/art. lightd turns image bytes into a scene, and today takes them only over HTTP, at POST /v1/cover. Something has to carry the bytes from the topic to lightd.

CHG-0009: Two Effects for the Accents

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0009: Two Effects for the Accents


Date	2026-10-11
Change type	Upgrade
Status	Complete 2026-10-11
Systems	`lp-stand-01`, over USB; `eds-lightd` and `eds-console` on the `services` workload
How	`make -C firmware/lp-stand build flash`; `make -C deploy deploy WHERE=builder`
Risk	Low. Most likely to go wrong: `lightd` asking for an effect the stand does not know, which the stand shows as a steady color
Decisions	ADR-0001
Related	CHG-0008

Summary

The stand’s default effect, breathe, lights a cover’s dominant color and nothing else. The other colors lightd picks, the accents, reach the stand in every scene and are used only by sweep.

ADR-0010: A Dual-Homed Pi Relays the Home LAN

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0010: Home-LAN Drivers Reach the Broker Through a Dual-Homed Mobile Pi


Status	Accepted
Date	2026-10-10
Scope	How a driver that must be near a player on the home LAN reaches the broker at the Deevnet Mobile site.
Extended by	ADR-0015: the image is EdS’s own, and a relay is a way of configuring it
Related	ADR-0003, ADR-0006, the Deevnet network segmentation standard (deevnet-docs)

Context

The Windows PCs that run iTunes and MusicBee sit on a home LAN. The broker is inside the Deevnet Mobile site. There is no path from the home LAN into the site, and the site’s workloads cannot reach private addresses outside it. The iTunes and MusicBee drivers speak network protocols to their players, and pairing with iTunes needs multicast, so they have to be on the players’ LAN.

CHG-0010: A Look for One Album, and a Strip of Eighteen

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0010: A Look for One Album, and a Strip of Eighteen


Date	2026-10-11
Change type	Upgrade
Status	Complete 2026-10-11
Systems	the `eds` tenant: two broker accounts gain a topic; `eds-nowplayd`, `eds-lightd` and `eds-console` on the `services` workload; `lp-stand-01`, over USB
How	`terraform apply`; `make -C firmware/lp-stand build flash`; `make -C deploy deploy WHERE=builder`
Risk	Low. Most likely to go wrong: a grant that does not match the topic, which the broker refuses without saying so and which leaves every album lit from its cover as before
Decisions	ADR-0019
Related	CHG-0009

Summary

Two things, deployed together because they touch the same three programs.

ADR-0011: iTunes by Remote Pairing

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0011: iTunes Is Read by Remote Pairing, the Way the Phone Remote Does It


Status	Accepted 2026-10-10, after pairing with the real iTunes; see Evidence. Opened the same day as `Proposed`
Date	2026-10-10
Scope	How the iTunes driver learns of track changes and gets artwork.
Extended by	ADR-0020: the pairing is also used to play, pause, skip and set the volume
Related	ADR-0006, ADR-0007, ADR-0010

Context

The PCs run classic iTunes for Windows, not the Microsoft Store build and not the newer Apple Music app. A phone remote app already sees and controls it, after a one-time pairing and with no Apple ID sign-in. That pairing has to keep working for as long as Apple supports it.

CHG-0011: Spotify Turned Off

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0011: Spotify Turned Off


Date	2026-10-11
Change type	Configuration
Status	Complete 2026-10-11
Systems	the agent Pi: one line of its settings, and its agent restarted
How	`make -C deploy/relay drivers DRIVERS=itunes`
Risk	Low. Most likely to go wrong: the agent not coming back, which would stop iTunes being followed too
Decisions	ADR-0012, unchanged
Related	CHG-0004, which turned it on

Summary

The Spotify driver works, and nothing uses what it reports: the stand does not follow Spotify, by decision. Meanwhile it asks Spotify what is playing every ten seconds, all day. Its owner is not using it for now and will come back to it.

ADR-0012: Spotify by the Web API

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0012: Spotify Is Read From the Account, Through the Web API


Status	Accepted 2026-10-11, once the driver had run against the account; two observations are still wanted, under What would settle it
Date	2026-10-10
Scope	How the Spotify driver learns what is playing.
Amended	2026-10-11, before it was accepted: where the driver runs, how it is authorized, which devices count, and that it takes no artwork. The text below is the amended decision; What changed lists the differences
Extended by	ADR-0031: the driver takes the album’s picture after all, from the answer it already asks for. ADR-0032: the authorization also allows changing playback, and the driver carries out commands
Related	ADR-0006, ADR-0007, ADR-0016

Context

Spotify knows what an account is playing wherever it plays: start a track on the desktop and the phone shows it. Spotify must also work when the rack is away from the house, which rules out anything that depends on the home LAN.

CHG-0012: The Cover Screen

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0012: The Cover Screen


Date	2026-10-11
Change type	Deployment
Status	In progress
Systems	a new device, `cover-screen-01`; the tenant’s Terraform (one device, one broker account, grants on two others); `nowplayd` on the workload; the agent on the Pi
How	`make flash` and `make provision` in `firmware/cover-screen`; `make plan apply` in `infra/deevnet-tenant-eds`; `make -C deploy deploy WHERE=builder`; `make -C deploy/relay push`
Risk	Medium. It is the first change that lets anything alter what plays. Most likely to go wrong: the agent or `nowplayd` not coming back, which would stop the stand following the music
Decisions	ADR-0020, which this is the evidence for
Related	CHG-0002, which made the accounts this adds to

Summary

A touch screen is added beside the stand. It shows the cover of what is playing and, when touched, five buttons: play or pause, previous, next, volume up, volume down.

ADR-0013: MusicBee by the Remote Plugin's Protocol

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0013: MusicBee Is Read Through the MusicBee Remote Plugin’s Protocol


Status	Proposed — the protocol has been read and does what is needed; it has not been tried against a real MusicBee. See What would settle it
Date	2026-10-10
Scope	How the MusicBee driver learns of track changes and gets artwork.
Related	ADR-0006, ADR-0007, ADR-0010, ADR-0011

Context

MusicBee plays local files and has no cloud. Anything that reads it runs on or near the PC. Its extension point is a plugin: a .NET DLL loaded into MusicBee, with a notification when the track changes.

CHG-0013: The Turntable Driver

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0013: The Turntable Driver


Date	2026-10-11, run on 2026-10-12 UTC
Change type	Deployment
Status	Complete 2026-10-12
Systems	the tenant (one broker account), the agent Pi (its agent, its unit, a recognizer installed, two lines of its settings)
How	`make apply` in the tenant; `make -C deploy/relay push`, `turntable`, `drivers`
Risk	Medium. Most likely to go wrong: the agent’s unit, which changes how it is confined, not starting, which would stop iTunes being followed too
Decisions	ADR-0021
Related	CHG-0002, which made the account; CHG-0012, in progress on the same Pi

Summary

The agent Pi gains a third driver, which listens to the amplifier’s tape output through a USB audio interface and reports the record that is playing.

ADR-0014: TIDAL by Last.fm

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0014: TIDAL Is Read Through Last.fm, Because Nothing Better Is Offered


Status	Proposed — until it has been tried against the account; see What would settle it
Date	2026-10-10
Scope	How the TIDAL driver learns what is playing.
Priority	The lowest of the four players, by the owner’s choice. Built last.
Related	ADR-0006, ADR-0007, ADR-0012

Context

The wish was for TIDAL to work like Spotify: ask the account, from the cloud, with nothing on the PC, so that it also works away from home.

CHG-0014: The Owner's Collection

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0014: The Owner’s Collection


Date	2026-10-12
Change type	Deployment
Status	In progress — a record from the collection is shown with its own sleeve; one that is not in it has not been tried
Systems	the services workload: nowplayd’s image, its unit, one settings file changed and one added. The console’s image, for one line of its page
How	`make -C deploy deploy WHERE=builder`
Risk	Medium. Most likely to go wrong: nowplayd’s unit, which names a new settings file, not starting; nothing would then be current and the stand would hold its last scene
Decisions	ADR-0022
Related	CHG-0013, which put the turntable on the bus

Summary

nowplayd learns to ask its owner’s Discogs collection which record a track from the turntable is on.

ADR-0015: EdS Builds Its Own Pi Images

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0015: EdS Builds Its Own Pi Images, on Deevnet IoTaaS’s Base


Status	Accepted
Date	2026-10-10
Scope	Where the definition of an EdS Raspberry Pi image lives, what it is built from, and what “the relay” is.
Extends	ADR-0010, which decided there would be a dual-homed Pi and did not say whose image it would run
Related	ADR-0004, CHG-0002

Context

The Pi that carries now-playing reports from the home LAN to the broker needed an image. Deevnet IoTaaS has an image factory that builds Raspberry Pi images, and the first relay image was built there, as a new variant beside Deevnet IoTaaS’s own.

CHG-0015: The Turntable's Power Beacon

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0015: The Turntable’s Power Beacon


Date	2026-10-12
Change type	Deployment
Status	In progress
Systems	a new device, `turntable-power-01`; the tenant’s Terraform (one device, one broker account, a grant on two others); `nowplayd` and the console on the workload
How	`make flash` and `make provision` in `firmware/power-beacon`; `make plan apply` in `infra/deevnet-tenant-eds`; `make -C deploy deploy WHERE=builder`
Risk	Low to medium. `nowplayd`’s rule for what is current changes, for the turntable only and only once its beacon has been heard. Most likely to go wrong: `nowplayd` or the console not coming back, which would stop the stand following the music or blank the page
Decisions	ADR-0023, which this is the evidence for
Related	CHG-0013, whose follow-up about a lifted needle this answers; CHG-0012, the last device added, and the shape this follows

Summary

A bare ESP32-S2 goes on the outlet that is switched with the turntable. It is connected to the broker while the turntable is on and says nothing else.

ADR-0016: A Source Can Be Reported Without Its Cover

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0016: A Source Can Be Reported Without Its Cover, and Spotify Is


Status	Accepted
Date	2026-10-11
Scope	Whether everything that is reported as playing also lights the stand.
Extends	ADR-0008, which promised that `current` carries a cover whenever something is playing
Extended by	ADR-0028: a source can also be reported with its cover and still not lit, by a look that says so. ADR-0031: Spotify is no longer reported this way. It has its cover, and is kept off the stand as iTunes is; the setting remains, with no source in it
Related	ADR-0009, ADR-0012

Context

The stand was built to stand beside a record that is playing. iTunes plays a library of albums the owner chose, and the stand follows it.

CHG-0016: Idle, the Screen on the Console, and No Buttons for a Record

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0016: Idle, the Screen on the Console, and No Buttons for a Record


Date	2026-10-12
Change type	Upgrade
Status	In progress
Systems	`nowplayd`, `lightd` and the console on the workload; the cover screen’s firmware; the tenant’s Terraform (one grant on the console’s account)
How	`make plan apply` in `infra/deevnet-tenant-eds`; `make -C deploy deploy WHERE=builder`; `make flash` in `firmware/cover-screen`
Risk	Medium. What lights the room changes: the stand dims by itself for the first time. Most likely to go wrong: the stand dim when something is playing, or lit when nothing is
Decisions	ADR-0024 and ADR-0025, which this is the evidence for
Related	CHG-0015, on whose branch this is built and whose console change this adds to

Summary

Three things, asked for together.

ADR-0017: An Agent Pi Is a Registered Device

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0017: An Agent Pi Is a Registered Device, and Reports Its Events Like One


Status	Accepted
Date	2026-10-11
Scope	How the now-playing agent’s key events reach the tenant’s log store, and what the Pi it runs on is to the tenant.
Extends	ADR-0005, which gave devices a way to report and said a program that is not a device “needs another route”
Related	ADR-0015, ADR-0010

Context

The stand reports its key events to the tenant’s log store, and they are read on a dashboard. The agent Pi reported nothing: what it saw playing, and whether its drivers were working, was in its own journal, reached by SSH through the Builder.

CHG-0017: The Gap Between Tracks, and a Silent Turntable

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0017: The Gap Between Tracks, and a Silent Turntable


Date	2026-10-12
Change type	Upgrade
Status	In progress
Systems	`npagent` on the agent Pi (`np-relay`); `nowplayd` and the console on the workload
How	`make -C deploy/relay push`; `make -C deploy deploy WHERE=builder`
Risk	Low. Most likely to go wrong: a wrong title for a few seconds after a quiet passage, or a room that dims while a record is being turned over and surprises someone
Decisions	ADR-0026, which this is the evidence for
Related	CHG-0013, CHG-0016

Summary

Three things about silence, asked for together.

ADR-0018: A Console of EdS's Own

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0018: EdS Has a Console of Its Own, Fed From the Bus, and It Only Looks


Status	Accepted 2026-10-11, once it had been watched in a browser on the site with tracks changing
Amended	2026-10-11, before it was accepted: served over TLS, not in the clear. When this was written nothing on the site would certify a name a tenant serves; Deevnet ADR-0037 has since given tenants a CA to ask. CHG-0007
Date	2026-10-11
Scope	Where a person looks to see what EdS is doing: what is playing, what the stand is showing, and whether the parts are up.
Extended by	ADR-0039: its first control, which switches the stand between records and every source
Related	ADR-0005, ADR-0006, ADR-0009, ADR-0016

Context

What EdS is doing was visible in three places, none of them a picture: the tenant’s Grafana dashboard, which lists events; mosquitto_sub; and the services’ journals. The stand has no LEDs attached yet, so nothing at all showed its colors.

CHG-0018: Counting What Is Asked of Outside Services

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0018: Counting What Is Asked of Outside Services


Date	2026-10-12
Change type	Upgrade
Status	In progress
Systems	`npagent` and its recognizer on the agent Pi (`np-relay`); `nowplayd` on the workload; the tenant’s Terraform (one dashboard added)
How	`make plan apply` in `infra/deevnet-tenant-eds`; `make -C deploy/relay push`; `make -C deploy deploy WHERE=builder`
Risk	Low. Nothing that lights the room changes. Most likely to go wrong: the log store refuses `nowplayd`, and its counts stay in the journal
Decisions	ADR-0027, which this is the evidence for
Related	CHG-0017, which is on the Pi and the workload from a branch of its own and is not in this one: see the procedure

Summary

npagent and nowplayd count what they ask of services that are not EdS’s, and say so once a minute. The agent’s counts arrive as events. nowplayd writes its own to the tenant’s log store, which no EdS workload has done before. A dashboard, Outside Services, shows both.

ADR-0019: An Album Can Have a Look of Its Own

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0019: An Album Can Have a Look of Its Own, Named on the Music Side and Drawn on the Light Side


Status	Proposed — until the first one has been seen on the stand
Date	2026-10-11
Scope	How one particular album gets a scene that is not derived from its cover, without the part that makes scenes learning what an album is.
Extends	ADR-0009, which gave `lightd` covers and kept tracks and albums on the other side of the topic
Extended by	ADR-0028: a look can name no cover, and is then the look of there being none. ADR-0030: a single piece of music can have one too, by its title
Related	ADR-0008, ADR-0001

Context

Every scene so far is made the same way: the cover’s colors, picked by palette, turned into a scene by lightd. That is right for almost every record and wrong for a few. The Dark Side of the Moon is a black sleeve with a thin spectrum across it. The colors a fair extraction finds on it are not what anyone would light a room with for that album, and what they would light it with is obvious: the spectrum.

CHG-0019: The Stand Is for Records

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0019: The Stand Is for Records


Date	2026-10-13
Change type	Upgrade
Status	In progress
Systems	`nowplayd` and `lightd` on the workload
How	`make -C deploy deploy WHERE=builder`
Risk	Low. Most likely to go wrong: a stand that is dark when someone expects it lit, and is taken for dead
Decisions	ADR-0028, which this is the evidence for
Related	CHG-0016, which gave the stand its idle scene; CHG-0015, whose beacon now decides between dim and dark

Summary

The stand was lit all day: dim whenever nothing played, and from iTunes' cover whenever iTunes did. It is an LP stand, and from this change it is lit by records only.

ADR-0020: A Touch Screen That Can Change What Plays

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0020: A Touch Screen Shows the Cover and Can Change What Plays, by Asking nowplayd


Status	Proposed — until a button on the screen has paused the real iTunes; see What would settle it
Date	2026-10-11
Scope	A second device, a small touch screen, that shows the cover of what is playing and has five buttons: play or pause, previous, next, volume up, volume down. This is the first thing in EdS that changes anything outside itself.
Extends	ADR-0006, in which a driver reports and reads nothing, and ADR-0011, which paired with iTunes as a remote and used the pairing only to read
Extended by	ADR-0032: Spotify’s driver carries the commands out too; ADR-0040: a sixth command names an album, and goes to iTunes whatever plays
Related	ADR-0008, ADR-0010, ADR-0016, ADR-0018, which said controls would be a decision of their own

Context

The stand shows a record’s colors. A screen beside it can show the cover itself, and a screen that can be touched is the obvious place for the few controls a listener reaches for.

CHG-0020: The Stand Starts Dark, Blinks, Opens and Scans

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0020: The Stand Starts Dark, Blinks, Opens and Scans


Date	2026-10-13
Change type	Upgrade
Status	In progress
Systems	The LP stand (`lp-stand-01`), flashed; `nowplayd`, `lightd` and the console on the workload
How	`make build flash` in `firmware/lp-stand`; `make -C deploy ship WHERE=builder`
Risk	Low. Most likely to go wrong: a stand flashed with something that does not start, which is put right by flashing the build before it; or an opening that is too much for a living room
Decisions	ADR-0029 and ADR-0030, which this is the evidence for
Related	CHG-0019, which made the room dark and left the stand’s own start dim

Summary

Three things asked for in one afternoon, and one flash.

ADR-0021: The Turntable Is Identified by Listening

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0021: The Turntable Is Identified by Listening, With a Recognizer That Can Be Replaced


Status	Proposed — until a record on the platter has lit the stand; see What would settle it
Date	2026-10-11
Scope	A third driver in `npagent`, `turntable`: it listens to the amplifier’s line-level output on the agent Pi, has a recognizer name what it hears, and reports that as a source on the now-playing bus.
Extends	ADR-0006, which said a turntable that identifies its record would be one more driver, and ADR-0007
Related	ADR-0008, ADR-0012 and ADR-0014, which each declined an unpublished interface; ADR-0015, ADR-0017

Context

The stand was built to stand beside a record that is playing. So far it follows iTunes, because iTunes can be asked what it is playing and a turntable cannot.

CHG-0021: A New Sound Card for the Turntable

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0021: A New Sound Card for the Turntable


Date	2026-10-13
Change type	Configuration
Status	Complete
Systems	`npagent` on the agent Pi (`np-relay`)
How	`make -C deploy/relay turntable DEVICE=plughw:CODEC`
Risk	Low. One line of the agent’s settings, and a restart of the agent
Decisions	ADR-0021
Related	CHG-0013, which named the first input; CHG-0019, since which only a record lights the stand

Summary

The sound card the turntable is heard through was replaced with another USB adapter. The agent was still told to listen to the old one by name, plughw:UA4FX, which was no longer there, so the turntable’s driver heard nothing and reported nothing. With the stand lit for records only, that was a stand that did nothing for a record.

ADR-0022: The Owner's Collection Names the Record

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0022: For a Source That Plays the Owner’s Records, the Owner’s Collection Names the Record


Status	Proposed — until a record on the platter has been shown with its own sleeve; see What would settle it
Date	2026-10-12
Scope	How nowplayd completes a track from a source that plays physical records: it asks the owner’s collection at Discogs before any catalog, and the collection’s answer replaces the album the source named.
Extends	ADR-0008, in which a known album is never renamed. For the sources named here, it is.
Related	ADR-0021, which left this open; ADR-0016, the other setting that treats named sources differently

Context

The turntable driver names a track by what it sounds like. A recording is pressed on many records - the album, its reissues, compilations, box sets - and nothing in the sound says which. The recognizer names an album anyway. On the bench it called one track of Chicago Transit Authority a box set, and a track of No Jacket Required a singles collection.

CHG-0022: Spotify Shown, and On Again

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0022: Spotify Shown, and On Again


Date	2026-10-13
Change type	Upgrade
Status	In progress
Systems	`npagent` on the agent Pi (`np-relay`); `nowplayd` on the workload
How	`make -C deploy/relay push`; `make -C deploy/relay drivers DRIVERS=itunes,spotify,turntable`; `make -C deploy units`
Risk	Low. Most likely to go wrong: the Spotify authorization given on 2026-10-11 no longer stands, and the driver stops and says so; or the agent does not come back after the push
Decisions	ADR-0031, which this is the evidence for
Related	CHG-0011, which this undoes; CHG-0004; CHG-0020, whose scanner is what was missed from Spotify

Summary

Spotify was reported with no cover, and its driver was off. The driver now takes the album’s picture, Spotify is kept off the stand the way iTunes is, and the driver is on again.

ADR-0023: A Source That Is Switched On Holds the Stand

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0023: A Source’s Equipment Can Say It Is On, and a Source That Is On Holds the Stand


Status	Proposed — until the beacon has been timed on the switch it shares and a record has been held through its silences; see What would settle it
Date	2026-10-12
Scope	How EdS knows the turntable is switched on: a small device on the same switched outlet, whose connection to the broker is the whole of what it says. And what nowplayd does knowing it.
Extends	ADR-0008, whose rule now has one thing before it. ADR-0018: the console reads one more topic, and still only looks.
Related	ADR-0021, whose driver this is for and whose account of the wiring this corrects; ADR-0016 and ADR-0022, the other settings that treat named sources differently

Context

The turntable driver (ADR-0021) reports what it hears, and three things it cannot hear are in the way.

CHG-0023: Spotify Takes Commands

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0023: Spotify Takes Commands


Date	2026-10-13
Change type	Upgrade
Status	In progress
Systems	`npagent` on the agent Pi (`np-relay`); the agent’s broker account, in the tenant; the Spotify authorization
How	`make -C deploy/relay push`; `make apply` in `infra/deevnet-tenant-eds`; `make -C deploy/relay spotify AGAIN=1`
Risk	Low. Most likely to go wrong: the authorization is given again and something about it fails, leaving Spotify unreported until it is done once more
Decisions	ADR-0032, which this is the evidence for
Related	CHG-0022, which put Spotify on the cover screen; CHG-0012

Summary

The cover screen’s buttons did nothing while Spotify was current. The Spotify driver now carries out play or pause, next, previous and volume through Spotify’s Web API. Three things have to change for a press to arrive: the agent, the broker account that lets it hear the command, and what Spotify has authorized it to do.

ADR-0024: Paused Long Enough Is Not Playing

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0024: A Track Left Paused Is Not Playing for Ever, and a Room With Nothing Playing Is Dim


Status	Proposed — until it has been seen in the room; see What would settle it
Date	2026-10-12
Scope	What nowplayd says when the current track has sat paused, or nobody is reporting; how that reaches the stand; what the stand shows then.
Extends	ADR-0008, which left “what a subscriber does with stopped” to the subscriber and “paused on B is more use than silence” without an end. ADR-0009: an emptied cover topic now means something to lightd.
Extended by	ADR-0028: the idle scene is for a room where something is switched on; with nothing switched on, a room with nothing playing is dark
Related	ADR-0016, whose “no cover sent” this must not be mistaken for; ADR-0023, whose held source is left alone; ADR-0020, whose play button must go on working

Context

Pause iTunes and walk away, and the stand goes on showing the album for as long as nothing else plays: hours, overnight. The console says “Paused on iTunes” over the same sleeve. Neither is false, and neither is what the room is doing, which is nothing.

CHG-0024: Spotify Turned Off Again

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0024: Spotify Turned Off Again


Date	2026-10-16
Change type	Configuration
Status	Complete 2026-10-16
Systems	the agent Pi: one line of its settings, and its agent restarted
How	`make -C deploy/relay drivers DRIVERS=itunes,turntable`
Risk	Low. Most likely to go wrong: the agent not coming back, which would stop iTunes and the turntable being followed too
Decisions	ADR-0031 and ADR-0032, unchanged
Related	CHG-0022, which turned it on; CHG-0011, the same change once before

Summary

The Spotify driver was asking Spotify what is playing six times a minute, all day, as the Outside Services count showed. Its owner does not want that for now and will come back to it. The agent Pi now runs the iTunes and turntable drivers only. Nothing is removed: the driver, its authorization on the Pi, the broker grants and the app at Spotify all stay, and one command turns it back on.

ADR-0025: Current Says When There Are No Controls

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0025: The Current Track Says When There Is Nothing a Controller Could Do


Status	Proposed — until the screen has been touched with a record playing; see What would settle it
Date	2026-10-12
Scope	One optional field in `current`, said by nowplayd, and what the cover screen does with it.
Extends	ADR-0020, which noted that “a source that takes commands does not say so anywhere”. Now the current one does.
Related	ADR-0023, which made the turntable current for as long as it is on, and so made the screen’s buttons idle for as long

Context

Touch the cover screen and five buttons come up. With a record on the turntable every one of them does nothing: a command goes to the source that is current, and nothing can skip a record. Since ADR-0023 the turntable is current the whole time it is switched on, so that is the whole evening. The sleeve is what the screen is for then, and buttons over it are wrong twice: they hide it, and they lie.

CHG-0025: Presence Repeated, and Updates Through the Broker

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0025: Presence Repeated, and Updates Through the Broker


Date	2026-10-16 (planned)
Change type	Upgrade
Status	Complete 2026-10-17
Systems	The tenant’s broker accounts; `cover-screen-01`, `turntable-power-01` and `lp-stand-01`, by cable; lightd, nowplayd and the console on the services workload; `npagent` on the agent Pi
How	`make plan apply` in `infra/deevnet-tenant-eds`; `make build flash` in each firmware; `make -C deploy deploy WHERE=builder`; `make -C deploy/relay push`; `make ota`
Risk	Medium. Most likely to go wrong: the plan replacing a device’s broker account instead of changing it, which issues a new password and strands that device until it is reprovisioned
Decisions	ADR-0034 and ADR-0035, which this is the evidence for
Related	CHG-0024, the day’s other change

Summary

Two decisions go out together, because the firmware for both goes on by the same cable.

ADR-0026: What Silence Means on the Turntable

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0026: A Gap Between Tracks Is Listened For, and a Silent Turntable Is Idle in Twenty Seconds


Status	Proposed — until a side has been played to it; see What would settle it
Date	2026-10-12
Scope	What the turntable driver does with a short silence, and how long nowplayd keeps the cover of a source that is stopped and held.
Extends	ADR-0021, whose “no single answer after that” now has one exception, and ADR-0024, whose five minutes for a stopped, held source is taken back
Related	ADR-0023, which is why a stopped turntable is still current; ADR-0022

Context

Two things were seen with records playing, on the day the driver went into service.

CHG-0026: The Cover Screen Sleeps

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0026: The Cover Screen Sleeps


Date	2026-10-17
Change type	Upgrade
Status	Complete 2026-10-17
Systems	`cover-screen-01`
How	`make build ota` in `firmware/cover-screen`
Risk	Low. Most likely to go wrong: the screen sleeping when someone is there, because a source that should count does not name itself in `current`
Decisions	ADR-0036
Related	CHG-0025, which made updates over the air possible

Summary

The cover screen is lit all the time, showing a drawn record to nobody when nothing plays. After this, it goes dark five minutes after current last said something was playing, and lights again for music, a touch, or a lost broker.

ADR-0027: What Is Asked of Outside Services Is Counted

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0027: What EdS Asks of Other People’s Services Is Counted, a Minute at a Time, and nowplayd Writes Its Counts to the Log Store Itself


Status	Proposed — until the counts have been seen on the dashboard; see What would settle it
Date	2026-10-12
Scope	Counting the calls `npagent` and `nowplayd` make to services that are not EdS’s; how those counts reach the tenant’s log store from each; the dashboard that reads them.
Extends	ADR-0005 and ADR-0017: the agent’s counts are one more event. A workload gets a route of its own, which neither gave it.
Related	ADR-0021, whose recognizer is the service least entitled to be leaned on; ADR-0022, ADR-0012, ADR-0008; Deevnet ADR-0027 (the tenant log store) and Deevnet ADR-0024 (dashboards)

Context

EdS asks things of services that are not its own. The turntable’s recognizer is Shazam’s, through an endpoint nobody offered. The owner’s collection is read from Discogs. Spotify’s Web API is polled. Covers are looked up at Deezer, the iTunes Search API, MusicBrainz and the Cover Art Archive.

CHG-0027: The Beacon on an ESP32

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0027: The Beacon on an ESP32


Date	2026-10-18
Change type	Upgrade
Status	Complete 2026-10-18
Systems	`turntable-power-01`: a new board, a plain ESP32, in place of the ESP32-S2
How	`make build flash provision` in `firmware/power-beacon`, by cable
Risk	Low. Most likely to go wrong: the old S2 powered at the same time as the new board. Both log in as `turntable-power-01`, the broker takes the account from one for the other, and each time says `offline` for the turntable
Decisions	ADR-0023, unchanged: any ESP32 with WiFi and 4 MB will do
Related	CHG-0015, the first beacon; CHG-0025, where the S2 needed an external antenna to join from the turntable

Summary

The beacon moves from an ESP32-S2 to a plain ESP32 that fits the case its owner bought. The case has no opening for an external antenna, and the S2 could not join from the turntable without one. The new board’s antenna is on the board.

ADR-0028: The Stand Is for Records

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0028: The Stand Is Lit for Records Only, and Is Dim Only While the Turntable Is On


Status	Proposed — until it has been seen in the room; see What would settle it
Date	2026-10-13
Scope	Which sources light the stand; what it shows when nothing is playing; and how lightd is told, without learning what a source is.
Extends	ADR-0024, whose idle scene is now for one case of two, and whose “it is not dark” no longer holds for the other. ADR-0019: a look can be named for there being no cover, and a look can be “light nothing”. ADR-0016: a second way for a source to be reported and not lit, which keeps its cover. ADR-0023: the switch says one thing more.
Extended by	ADR-0029: the stand is dark from power on too, and blinks when it cannot reach the broker. ADR-0030: one look is shown from a dark source too. ADR-0039: records-only is the default, and the console can switch the stand to every source
Related	ADR-0009, whose boundary this keeps; ADR-0026, whose dimmed room between two sides is the case that stays dim

Context

ADR-0024 gave a room with nothing playing a scene of its own: steady, warm, at 0.15. It chose that over dark because “a dark stand cannot be told from a dead one”.

CHG-0028: The Back End on One Pi, Tried on DVNTM

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0028: The Back End on One Pi, Tried on DVNTM


Date	2026-10-18
Change type	Deployment
Status	In progress
Systems	`dv02rpi003p01` (a Pi 4, wired to DVNTM’s IoT segment on `Gi1/0/11`, `10.20.30.13`, and on DVNT-CORE by Wi-Fi), with a new card. Nothing of the tenant’s, the workload’s, the relay Pi’s or the devices'
How	`make -C deploy/backend image fetch`; the card flashed by its owner; `make card`; first boot; `make status`
Risk	Low. Most likely to go wrong: the card’s first boot not finishing (`deevnet-kit` or `eds-backend-setup`), which leaves a Pi to reflash and nothing else touched
Decisions	ADR-0033, whose evidence this is
Related	Deevnet CHG-0048, which gave `dv02rpi003p01` its switch port; Deevnet CHG-0049, which rebuilt the take-home image this is built on

Summary

The whole of EdS on one Pi, beside the tenant: its own broker, log store, Grafana, the four services and the agent. It is tried on the kit’s network first, where the devices are, and goes to the home network only once it works.

ADR-0029: The Stand Starts Dark, and Blinks What Is Wrong

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0029: The Stand Starts Dark, and Says in Red Blinks How Far It Got


Status	Proposed — until each blink has been seen on the stand; see What would settle it
Date	2026-10-13
Scope	What the stand’s strip shows from power on until it is sent a scene; what it shows when it cannot get that far; and how it comes on and goes off.
Extends	ADR-0028, which made a room with nothing playing dark and left the stand’s own first seconds dim. ADR-0001: the stand now draws one thing nobody sent it.
Related	ADR-0005, the stand’s other way of saying what happened, which needs the broker this is for the lack of; ADR-0004, whose unprovisioned stand gets a blink of its own

Context

The firmware has always lit the strip the moment it had power: a dim warm white, “so an unconfigured or unreachable stand looks deliberate rather than broken”. Since ADR-0028 the stand is dark unless a record is on or the turntable is switched on. The warm white at power on is then the one time the stand is lit with nobody having asked: for a few seconds on every start, and for as long as the network is away.

CHG-0029: The Turntable's Album by What Is on It

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0029: The Turntable’s Album by What Is on It


Date	2026-10-19
Change type	Upgrade
Status	In progress
Systems	The home backend Pi, `dv01rpi001p01` (`192.168.2.40`): nowplayd and npagent, with the other services restarted
How	`make -C deploy/backend push PI=192.168.2.40` from `main` at `44828a9`
Risk	Low. Most likely to go wrong: a lookup that names the wrong album for a record not in the collection; the stand is lit from the wrong sleeve until the next track
Decisions	ADR-0038, whose evidence this is
Related	CHG-0028, the Pi this goes to

Summary

On the first evening at home, Animals put on a minute after The Dark Side of the Moon kept Dark Side’s rainbow: the driver held a side’s first album for ten minutes of silence. ADR-0038 names the album by what is on the record instead, and prefers the original album. This puts it on the Pi.

ADR-0030: A Piece of Music Can Have a Look, From Any Source

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0030: One Piece of Music Can Have a Look of Its Own, Shown Whatever Plays It, and the Stand Learns to Scan


Status	Proposed — until it has been seen on the stand with the theme playing; see What would settle it
Date	2026-10-13
Scope	A look for a single track, known by its title; the one exception to the stand being lit for records only; and a sixth effect in the firmware to draw it with.
Extends	ADR-0019, whose looks were albums’. ADR-0028, whose dark sources now have one thing that lights them. ADR-0001: the stand has one more effect.
Related	ADR-0029, whose opening and closing are how this comes on and goes off in a dark room

Context

Its owner wants the stand to do what the front of KITT does while the theme from Knight Rider is playing: one red light, going from side to side.

CHG-0030: The Console Switches the Stand

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0030: The Console Switches the Stand


Date	2026-10-19
Change type	Upgrade
Status	In progress
Systems	The home backend Pi, `dv01rpi001p01` (`192.168.2.40`): nowplayd, the console, the `nowplayd` and `console` broker accounts; the other services restarted
How	`make -C deploy/backend push PI=192.168.2.40` from branch `adr-0039-stand-for-every-source` (PR #60), before it is merged
Risk	Low. Most likely to go wrong: the two accounts made again with grants the broker refuses, and nowplayd or the console unable to log in until they are put back
Decisions	ADR-0039, whose evidence this is
Related	CHG-0029, the push before this one

Summary

The console gets a switch that lights the stand for every source, for working on the stand’s looks with iTunes and Spotify. Pushed from the PR’s branch so it can be tried before it is merged.

ADR-0031: Spotify Is Shown, Like iTunes

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0031: Spotify Is Reported With Its Cover, and Treated as iTunes Is


Status	Proposed — until the driver has fetched a cover from the real account and the screen has shown it; see What would settle it
Date	2026-10-13
Scope	Whether Spotify’s track comes with a cover, where the cover is from, and what the stand does for it.
Extends	ADR-0012, whose driver took no artwork and now takes the album’s. ADR-0016: a source can still be reported without its cover, and Spotify no longer is. ADR-0028: Spotify becomes a dark source, as iTunes is.
Related	ADR-0030, whose “any source” this makes true of Spotify; ADR-0027, which counts the new requests; ADR-0018, whose page shows the cover

Context

ADR-0016 reported Spotify without a cover for two reasons. The owner did not want the lights to follow it. And Spotify’s developer pages have a line about not synchronizing its recordings with visual media, which ADR-0012 left to the owner’s judgment; fetching no artwork and lighting nothing stepped around it.

CHG-0031: The Turntable Heard Through a UFO202

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0031: The Turntable Heard Through a UFO202


Date	2026-10-21
Change type	Configuration
Status	Complete 2026-10-21
Systems	`dv02rpi003p01`, the back-end Pi: one line of its agent’s settings, and its agent restarted
How	`make -C deploy/backend turntable DEVICE=plughw:CODEC PI=192.168.2.40`
Risk	Low. Most likely to go wrong: the agent not coming back, which would stop iTunes being followed too
Decisions	ADR-0021, unchanged
Related	CHG-0028, which named `plughw:UA4FX`

Summary

The turntable was heard through a Roland UA-4FX, and the Pi’s agent listened to plughw:UA4FX. Its owner found a Behringer UFO202 and plugged it into the Pi in the UA-4FX’s place. ALSA names it CODEC (card 3, USB Audio CODEC), and the UA-4FX is no longer there, so the agent is told the new name. Nothing else changes: the same line-level feed from the selector, the same driver, the same recognizer.

ADR-0032: Spotify Takes Commands

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0032: The Spotify Driver Carries Out Commands, With a Wider Authorization, for What Is Playing Here


Status	Proposed — until a press on the cover screen has paused Spotify; see What would settle it
Date	2026-10-13
Scope	Whether a controller’s command reaches Spotify, what the agent must be authorized for to carry it out, and which playback a command may touch.
Extends	ADR-0020, whose commands only iTunes carried out. ADR-0012, whose authorization only read.
Related	ADR-0031, which put Spotify’s sleeve on the cover screen above buttons that did nothing; ADR-0025, the other answer to that; ADR-0027

Context

Since ADR-0031 the cover screen shows what Spotify is playing, with the same five buttons it shows for iTunes. Pressed, they do nothing: nowplayd passes the command to the current source (ADR-0020), and Spotify’s driver reads no command topic. It was built to read, with an authorization that only reads, and both the code and the broker account say that changing it is a decision. This is that decision.

CHG-0032: American Idiot Has a Look

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0032: American Idiot Has a Look


Date	2026-10-23
Change type	Upgrade
Status	Complete 2026-10-23
Systems	`dv02rpi003p01`, the back-end Pi: nowplayd and lightd replaced, and the four services restarted
How	`make -C deploy/backend push PI=192.168.2.40`, from #60’s branch with this change on it
Risk	Low. Most likely to go wrong: a service not coming back after the push, which leaves the stand dark until it is pushed again
Decisions	ADR-0019, a second album on its list
Related	CHG-0030, whose branch is what runs on the Pi and is pushed again here

Summary

Green Day’s American Idiot was lit from the owner’s own pressing once the record was added to the Discogs collection. That sleeve’s picture is a photograph, and lightd read it as one red in four shades (#df0040 56%, #b90237 16%, #92122f 14%, #671c2b 14%), which a strip of LEDs shows as one red going nowhere. Deezer’s clean scan of the same sleeve, a few minutes earlier, had read as two reds with the pale pink of the hand and a salmon among them (#d90018 45%, #e22f28 31%, #efb6b0 13%, #e35f55 12%), and its owner liked that better.

ADR-0033: The Whole Back End on One Pi

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0033: The Whole Back End Can Run on One Pi, as an Image Built on Deevnet’s Take-Home One


Status	Proposed — until a card has been built, booted and run; see What would settle it
Date	2026-10-13
Scope	Whether EdS can run with nothing of Deevnet IoTaaS behind it, on one Raspberry Pi; what that Pi’s image is built from; how its services run, where its secrets come from, and what its console presents.
Extends	ADR-0015: a second image, on a second base. ADR-0003: on Deevnet the broker is still Deevnet’s; on this Pi it is the Pi’s. ADR-0010: this Pi has one leg and is no relay. ADR-0018: the console’s certificate, where there is no Tenant Service CA.
Related	ADR-0017, ADR-0027, Deevnet’s runbook “Convert a Tenant to a Pi Image”

Context

EdS runs in two places. Four services (palette, lightd, nowplayd, the console) are containers on a workload in the EdS tenant. The agent, npagent, is on a Pi with a leg on the home network (ADR-0010). The broker, the log store and Grafana are Deevnet IoTaaS’s.

CHG-0033: An Album Asked For on the Bus

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0033: An Album Asked For on the Bus


Date	2026-10-23
Change type	Upgrade
Status	In progress
Systems	The tenant’s services workload (`services.eds.mobile.deevnet.net`): the four services rebuilt and restarted. `dv02rpi002p01`, the relay: `npagent` replaced
How	`make -C deploy ship WHERE=builder` and `make -C deploy/relay push`, from the branch `voice-play-album`
Risk	Low. Most likely to go wrong: a service not coming back, which leaves the mobile site’s stand and screen without a current track until shipped again. The home back-end Pi is not touched
Decisions	ADR-0040, whose command this puts on the bus
Related	CHG-0032, the last change, made on the back-end Pi

Summary

play_album is the first command that chooses what plays (ADR-0040). npagent play-album has already played Van Halen’s first album from the relay by hand; this puts the same request behind the bus. nowplayd passes play_album to itunes whatever is current, and the iTunes driver asks for the album and then asks what plays.

ADR-0034: Presence Is Heard, Not Remembered

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0034: Presence Is Heard, Not Remembered: Everything Says It Is There Every Thirty Seconds


Status	Proposed — until a stand unplugged across a broker restart is seen gray; see What would settle it
Date	2026-10-16
Scope	What `online` on a `…/status` topic means to whoever reads it: the console, and nowplayd for sources and beacons.
Extends	ADR-0023, whose consequence “a will needs a broker to send it” this removes. ADR-0018: the console now shows a part as up only if it has heard from it lately.
Related	ADR-0003, the broker that keeps retained messages across restarts

Context

Every part of EdS says it is there the same way: on connecting, it publishes online, retained, to its status topic, and leaves the broker a last will of offline, retained. The broker sends the will when it sees the connection die.

CHG-0034: voiced and scribe on the Workload

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0034: voiced and scribe on the Workload


Date	2026-10-24
Change type	Deployment
Status	In progress
Systems	The tenant’s Terraform on the mobile site’s API: broker accounts for `voiced` and `respeaker-01` and the device `respeaker-01` created; `console` and `nowplayd` given `nowplaying/stand`. The services workload: `eds-scribe` and `eds-voiced` added, the other four rebuilt and restarted
How	`make -C infra/deevnet-tenant-eds apply`, then `make -C deploy kit-env deploy WHERE=builder`, from the branch `voice-play-album`
Risk	Medium. The workload has two cores and two gigabytes, and scribe’s model takes a few hundred megabytes of it: most likely to go wrong is memory, which would stop a service. `eds-scribe` is held to 900 MB for that reason. Updating `console` and `nowplayd` in place keeps their passwords
Decisions	ADR-0042; ADR-0039, whose grant this applies to the tenant at last
Related	CHG-0033, which put `play_album` on the bus; CHG-0030, which switched the stand on the back-end Pi only

Summary

A spoken request is written down by scribe and made a command by voiced (ADR-0042). Both have run on a Mac against the development broker. This puts them on the workload, with voiced’s own broker account, and registers the reSpeaker, whose account is the one that may publish a request.

ADR-0035: Firmware Is Updated Through the Broker

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0035: Firmware Is Updated Through the Broker, and a Build That Cannot Reach It Is Undone


Status	Accepted 2026-10-17, after each device was updated over the air, one rolled back by itself, and one refused a build not its own; see Evidence. Opened 2026-10-16 as `Proposed`
Date	2026-10-16
Scope	How a new build reaches the stand, the cover screen and the beacon once each is in place; what a device does with one; and how a bad one is undone.
Extends	ADR-0029: the stand that cannot reach the broker still blinks, and now also gives up a new build that caused it.
Related	ADR-0003, why the broker sits where devices can reach it and nothing else of EdS can; ADR-0023, the beacon whose connection is its message; ADR-0034, the change that showed why this is wanted

Context

Every change to a device’s firmware has meant a USB cable: the stand unscrewed from its shelf, the beacon taken off its outlet, and the cover screen and the beacon taking turns on the Mac’s one serial port. ADR-0034 is the case in point: three devices to flash before three services could be deployed.

CHG-0035: Only Words scribe Is Sure Of

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0035: Only Words scribe Is Sure Of, and the reSpeaker Asked From Its Console


Date	2026-10-24
Change type	Upgrade
Status	Complete 2026-10-24
Systems	The services workload: the six services rebuilt, `eds-scribe` and `eds-voiced` changed, all restarted. `respeaker-01`: firmware flashed by cable
How	`make -C deploy ship WHERE=builder`; `make -C firmware/ears build flash`, from `e9ed753` on `voice-play-album`
Risk	Low. Most likely to go wrong: scribe’s thresholds refusing speech it should take, which is a request said again, not a record played wrongly
Decisions	ADR-0042, ADR-0043
Related	INC-0001, which this corrects

Summary

The reSpeaker’s first request played Abbey Road, which nobody asked for (INC-0001): scribe’s model wrote its own prompt back, a request in words, and voiced acted on it. scribe’s prompt is now a list of names, and scribe says whether the words are worth acting on, by Whisper’s own thresholds; voiced acts on nothing else.

ADR-0036: The Screen Sleeps When Nothing Plays

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0036: The Cover Screen Sleeps When Nothing Has Played for Five Minutes, and Wakes for Music


Status	Accepted 2026-10-17 — slept and woken on the board (CHG-0026); see What would settle it
Date	2026-10-17
Scope	The cover screen’s firmware: when it turns its panel off, and what wakes it. Nothing on the bus changes.
Extends	ADR-0020, the screen itself
Related	ADR-0023, which makes a turntable that is switched off not heard; ADR-0024, which turns a long pause into stopped; ADR-0025, the last time the screen had to be told something without knowing a source; ADR-0029, the stand’s dark that is not a fault

Context

The cover screen is lit all the time. With nothing playing it shows a drawn record all night, to nobody. Its owner asked first for it to sleep when the turntable’s power, iTunes and Spotify are all gone, and to come back when one of them is.

CHG-0036: The reSpeaker Wakes to "Hey Jarvis"

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0036: The reSpeaker Wakes to “Hey Jarvis”, and Hears a Request Until It Ends


Date	2026-10-24
Change type	Upgrade
Status	Complete 2026-10-24
Systems	`respeaker-01`: firmware flashed by cable. The services workload: `eds-voiced` rebuilt with the others and all restarted
How	`make -C firmware/ears build flash`; `make -C deploy ship WHERE=builder`
Risk	Low. Most likely to go wrong: the device waking for something that is not its name, which sends a few seconds of the room; voiced acts only on a request it is sure of (INC-0001)
Decisions	ADR-0043
Related	CHG-0035

Summary

The reSpeaker listens for a wake word: microWakeWord’s “Hey Jarvis”, ESPHome’s model, on TensorFlow Lite Micro with the audio frontend it was trained on. What follows it is heard until the speaker stops - 0.7 s quieter than the room by 10 dB, at most six seconds - and sent, with the 350 ms before the wake was decided on, so that a “play” said straight after keeps its P. voiced allows a word or two before “play”, for the end of the wake word that comes with it, but never a negation.

ADR-0037: Hand-Kept Secrets Are Encrypted in the Repository

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0037: The Secrets Nothing Else Can Issue Are Kept Encrypted in the Repository, with sops and age


Status	Proposed — until the first secrets have moved and a second machine has read them; see What would settle it
Date	2026-10-18
Scope	Where EdS keeps the secrets it is the only holder of, and how its tools read them. Not the secrets Deevnet IoTaaS issues, and not those made on a device or a card.
Extends	ADR-0004, whose rule (no secret compiled in) stands; ADR-0022, whose token “is never committed” in plain text, and now is committed encrypted
Related	ADR-0033, whose first card went out without the Discogs token

Context

On 2026-10-18 the first backend card was written from a worktree, and went out with no Discogs settings. make card looks for deploy/discogs.env in the checkout it runs in; the file is gitignored, so a worktree never has it; and the script says “no Discogs settings” and carries on, as it should for an owner who has none. Nothing was wrong except where the secret lived.

CHG-0037: A Request Answered Sooner

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0037: A Request Answered Sooner


Date	2026-10-24
Change type	Upgrade
Status	In progress
Systems	`respeaker-01`: firmware flashed by cable. The services workload: all six rebuilt, `eds-voiced`’s unit changed and `/var/lib/eds-voiced` made
How	`make -C firmware/ears build flash`; `make -C deploy deploy WHERE=builder`
Risk	Low. Most likely to go wrong: a request cut before its last word, which is a request said again
Decisions	ADR-0042, ADR-0043
Related	CHG-0036, whose request took 21 s from the wake word to the music

Summary

From “Hey Jarvis” to the music took 21 s in CHG-0036: 6.4 s heard, because the room never got as quiet as the floor learned from its quietest moments; 5.3 s to send 200 KB at -80 dBm; 4.6 s to write down; 5 s to count Aerosmith’s albums in MusicBrainz after a restart had forgotten them.

ADR-0038: The Turntable's Album Is the Original One the Track Is On

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0038: The Turntable’s Album Is the One the Track Is On, and the Original One, Not a Time Since the Last


Status	Proposed — until a side of one record and then another by the same artist have been played; see What would settle it
Date	2026-10-19
Scope	Which album nowplayd names for a track heard on the turntable, and so which cover lights the room. The turntable driver, nowplayd’s resolution for the turntable, and the catalogs it asks.
Supersedes	ADR-0026’s “the driver remembers the album for ten minutes”; the rest of ADR-0026 stands
Extends	ADR-0022, the owner’s collection first, which stands and still comes first
Related	ADR-0019, whose album looks follow the album named; ADR-0027, which counts every call this adds

Context

On 2026-10-18, the first evening on the home Pi (CHG-0028), The Dark Side of the Moon was played, lifted, and Animals put on 52 seconds later. The recognizer named “Pigs On the Wing, Pt. 1” and then “Dogs”, which are right. The stand kept Dark Side’s rainbow look for both, because both were reported as on The Dark Side of the Moon.

CHG-0038: A Misheard "Play", and a Longer Pre-roll

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0038: A Misheard “Play” Is Taken for One Where the Rest Is an Album by Its Place, and the Pre-roll Is 600 ms


Date	2026-10-24
Change type	Upgrade
Status	In progress
Systems	The services workload: nowplayd and voiced sent and all restarted. `respeaker-01`: flashed by cable
How	`make -C deploy ship WHERE=builder`, the first with `load.sh` (INC-0002); `make -C firmware/ears build flash`
Risk	Low. Most likely to go wrong: a sentence that is not a request read as one; only “X’s Nth album” and “the Nth album by X” are read behind a misheard “play”
Decisions	ADR-0042, ADR-0043
Related	CHG-0037

Summary

After CHG-0037 and ADR-0044, “Hey Jarvis, play Aerosmith’s first album” played in 8 s from the wake word: 2 s heard, sent in 89 ms, 4 s to write down, 1.7 s to count. The music dipped while it listened. “Play Van Halen’s first album”, straight after, was written “Tae Van Halen’s first album.” and was not a request.

ADR-0039: The Console Can Light the Stand for Every Source

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0039: The Console Can Light the Stand for Every Source, Until It Is Switched Back


Status	Proposed — until it has been switched both ways from the console in the room; see What would settle it
Date	2026-10-19
Scope	A switch on the console that lights the stand from iTunes and Spotify as well as records; where its state is kept; who may change it.
Extends	ADR-0018: the console gets its first control, and its account its second topic to publish. ADR-0028: records-only stays the default, and becomes a setting that can be changed while running.
Related	ADR-0020, whose commands are never retained; this is not one of them. ADR-0030, whose any-source look is unchanged. ADR-0009, whose boundary this keeps.

Context

The stand is lit for records only (ADR-0028): NP_DARK_SOURCES=itunes,spotify makes nowplayd give those sources’ covers the look dark, and lightd draws it as a dark stand. That is right for the room and stays the default.

CHG-0039: scribe in Two, and "Hey Jarvis" in Its Prompt

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0039: scribe Is a Base Sent Once and Its Code Built on the Workload, and “Hey Jarvis” Is in Its Prompt


Date	2026-10-24
Change type	Upgrade
Status	In progress
Systems	The services workload: `eds-scribe-base` loaded, `eds-scribe` built there, nowplayd and voiced sent, all restarted
How	`make -C deploy ship WHERE=builder`
Risk	Medium. Most likely to go wrong: the core router under the base’s one transfer (INC-0002), which is compressed to 256 MB and held to 5 MB/s
Decisions	ADR-0042
Related	INC-0002, whose follow-up this is; CHG-0038

Summary

The end of the wake word, kept with each request, was written “Lee Jarvis”, “Jay Jarrus”, “Travis”, “The band was very generous”, and the request after it was misheard with it. With “Hey Jarvis” in scribe’s prompt, the same recordings, cut as the device cuts them, were written “Jarvis,” each time, and nothing else changed.

ADR-0040: A Request Can Name an Album to Play

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0040: A Request Can Name an Album to Play, and iTunes Plays It From Its Own Library


Status	Proposed — until `play_album` sent to `nowplaying/command` has played an album through nowplayd and the driver (the driver’s half is shown); see What would settle it
Date	2026-10-23
Scope	A sixth command, `play_album`, that names an album rather than pressing a button; which player carries it out; and what the iTunes driver asks of the player’s library to do it. The first thing to send it is meant to be a voice (“Hey Ed, play Van Halen’s first album”), which is a decision of its own.
Extends	ADR-0020, whose five commands press buttons on whatever is playing, and ADR-0011, whose pairing has only read what plays and pressed those buttons
Related	ADR-0032, which added no command; ADR-0038, which already knows an artist’s original albums

Context

Every command so far is a button. It acts on whatever is playing, so a controller never needs to say where it is sent, and ADR-0020 made that a rule: a controller never names a source. A request to play an album is not a button. Nothing may be playing at all, and if something is, it may be the turntable, which takes no command.

CHG-0040: The Owner's Library for voiced

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0040: voiced Matches Requests Against an Index of the Owner’s Library


Date	2026-10-24
Change type	Upgrade
Status	In progress
Systems	The services workload: voiced sent and its unit replaced; `library.json` copied to `/var/lib/eds-voiced`. The relay Pi: npagent, for the driver’s title matching
How	`make -C deploy ship WHERE=builder`, `make -C deploy units`, `make -C deploy library XML=…`; the relay’s push
Risk	Low. Most likely to go wrong: a near but wrong artist or album chosen; without the index, voiced is as it was
Decisions	ADR-0046
Related	CHG-0039

Summary

voiced gains NP_LIBRARY, an index of the owner’s iTunes library made from its XML, and chooses from it the artist and album a request means, by the library’s own names. The driver asks iTunes for the whole title first and its plain start after.

ADR-0041: An Artist's Nth Album Is Counted in MusicBrainz

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0041: An Artist’s First Album Is Their First Studio Album, Counted in MusicBrainz


Status	Proposed — until an album asked for by its place has played; see What would settle it
Date	2026-10-24
Scope	What “Aerosmith’s first album” means, where the count comes from, and how the name it gives is made to match a library. Not how a request is heard, nor what plays it.
Extends	ADR-0038, whose idea of an original album, a studio album with nothing else to it, is the one counted here
Related	ADR-0040, which plays an album by its names and cannot ask the library what it holds; ADR-0022, the owner’s Discogs collection

Context

A request to play “Van Halen’s first album” has to become the names ADR-0040 plays an album by: the artist, and the album’s title, as the iTunes library writes them. The library cannot be asked which albums it has. Something else has to know the order of an artist’s albums.

CHG-0041: voiced Asks eds-inventory

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0041: voiced Asks eds-inventory for the Owner’s Albums


Date	2026-10-24
Change type	Upgrade
Status	Complete 2026-10-24
Systems	The services workload: eds-inventory installed beside EdS’s services (eds-inventory’s CHG-0001); voiced sent and its unit replaced
How	In eds-inventory: `make -C deploy image load unit WHERE=builder`, then `make -C deploy library XML=…`. Here: `make -C deploy ship WHERE=builder`, `make -C deploy units`
Risk	Low. Most likely to go wrong: the inventory not answering, and albums guessed at as with no library; `make deploy`’s restart of every EdS service
Decisions	ADR-0047
Related	CHG-0040, the index this replaces

Summary

eds-inventory’s inventoryd goes onto the services workload with the owner’s iTunes library collected into it, and voiced is pointed at it with NP_INVENTORY_URL. library.json stays where it is, unread while the inventory is configured.

ADR-0042: A Request Is Heard on the Workload

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0042: A Spoken Request Is Sent Whole to the Workload, Written Down There, and Made a Command


Status	Proposed — until a request said in the room has played its album; see What would settle it
Date	2026-10-24
Scope	How “Hey Ed, play Van Halen’s first album” travels from a microphone to `play_album`: what the device sends, where speech becomes words, and how words become a command. Not the device’s firmware, which is a decision of its own.
Extends	ADR-0040, whose command this sends, and ADR-0041, whose count it asks
Related	ADR-0003, the broker as the one way a device reaches EdS; ADR-0034

Context

The microphone is a reSpeaker Lite: an XMOS chip that cleans up what a room says, and a small ESP32-S3 beside it. The ESP32-S3 can listen for a wake word and keep a few seconds of audio. It cannot turn speech into words. A device can reach nothing of EdS’s but the broker (ADR-0003).

CHG-0042: The Home Pi Becomes a Deevnet Pi

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0042: The Home Pi Becomes a Deevnet Pi, and the Devices Hold Both Sites


Date	2026-10-26
Change type	Migration
Status	Complete
Systems	The home backend Pi, `192.168.2.40` on DVNT-CORE, with a new card named `dv01rpi001p01` (the card in it now calls itself `dv02rpi003p01`); `turntable-power-01`, `cover-screen-01`, `lp-stand-01`, `respeaker-01`; the tenant’s Terraform (one `deevnet_certificate`); the home network’s DNS
How	`make -C deploy/backend image fetch card`; `deevnet-kit cert request` and `cert install`; `terraform apply` in `infra/deevnet-tenant-eds`; `make pair spotify turntable drivers status devices`; `provision_tenant.py --site home --also mobile=terraform` on each device
Risk	Medium. Most likely to go wrong: a device refusing the broker’s new certificate. No ESP32 has yet verified a server through Deevnet’s Tenant Service CA to the Root
Decisions	ADR-0033, ADR-0049; Deevnet ADR-0040 (site-less names) and ADR-0041 §2 (a Deevnet Pi)
Related	CHG-0028, which built the card this replaces; Deevnet CHG-0054 and CHG-0056, which built the names and the kit’s `cert` commands

Summary

The home Pi runs EdS on a card whose certificate is signed by that card’s own CA, for names entered by hand in the home DNS. The devices dial its address and trust that CA, and hold one site’s settings.

ADR-0043: The reSpeaker Runs Firmware of EdS's Own

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0043: The reSpeaker Runs Firmware of EdS’s Own, and Sends a Request When Its Button Is Held, Then When It Hears Its Name


Status	Proposed — until a request said into the reSpeaker has played its album; see What would settle it
Date	2026-10-24
Scope	What runs on the reSpeaker Lite’s XIAO ESP32-S3: how it hears, when it sends, and how it is provisioned and updated. Not what a request becomes, which is ADR-0042’s.
Extends	ADR-0042, whose `voice/<device>/utterance` this sends
Related	ADR-0004, ADR-0035, ADR-0034

Context

The reSpeaker Lite is two chips. An XMOS XU316 takes two microphones and gives one cleaned-up voice: echo cancelled, noise suppressed, beam steered. Its firmware (1.0.8, read over DFU on 2026-10-24) sends that over I2S to a XIAO ESP32-S3 (8 MB PSRAM, 8 MB flash), which came with an Arduino test sketch from Seeed. The XIAO is what can be programmed.

CHG-0043: The Backend Pi Names the Record the Recognizer Heard

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0043: The Backend Pi Names the Record the Recognizer Heard


Date	2026-10-29
Change type	Deployment
Status	Complete
Systems	The home backend Pi, `eds-backend` (`192.168.2.40`): its five services and the agent
How	`make -C deploy/backend push`, from the branch of PR #109
Risk	Low. Most likely to go wrong: a service not coming back after the push, which `push.sh` checks
Decisions	ADR-0038, as revised by PR #109
Related	CHG-0042, during whose last check the fault was found

Summary

At the end of CHG-0042, Journey’s “Wheel in the Sky”, heard on Infinity, was named Alive in America, a live album, and the stand lit from its cover. Deezer lists the track on live albums, best-ofs and a 2008 re-recording, never on Infinity, and the recognizer’s album was asked about only when the catalog had nothing.

ADR-0044: The Music Is Turned Down While a Request Is Heard

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0044: The Music Is Turned Down While a Request Is Heard, and Comes Back by Itself


Status	Proposed — until a request said over the music has been heard to its end and played; see What would settle it
Date	2026-10-24
Scope	What happens to what is playing between the wake word and the answer: who says the device woke, which command lowers the music, and what brings it back.
Extends	ADR-0020, whose commands this adds two to; ADR-0042 and ADR-0043, whose request it is
Related	ADR-0040

Context

The reSpeaker’s XMOS chip cancels the echo of its own speaker, not of the stereo. With an album playing beside it, a request asked over the music was heard as speech until its six-second limit, sent at twice the size, and written down with the music in it (CHG-0037). Smart speakers lower their music while they listen. EdS’s music comes from players EdS controls.

CHG-0044: Spotify Is Switched From the Backend Pi's Console

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0044: Spotify Is Switched From the Backend Pi’s Console


Date	2026-10-29
Change type	Deployment
Status	Complete
Systems	The home backend Pi, `eds-backend` (`192.168.2.40`): its services, the agent, and the broker accounts `eds-console` and `eds-np-relay`
How	`make -C deploy/backend push` and `make drivers DRIVERS=itunes,spotify,turntable`, from the branch of PR #106
Risk	Low. Most likely to go wrong: Spotify asked all day again, which the switch defaulting to off is there to prevent
Decisions	ADR-0051
Related	CHG-0024, whose follow-up this answers; CHG-0043, the push before

Summary

The backend Pi ran 4e51363 and did not run the Spotify driver. After: it runs ADR-0051’s agent and console. Spotify is allowed in NP_DRIVERS, and whether it runs is the console’s switch, off unless switched on.

ADR-0045: An Nth Album Not Owned Is the Next One That Is

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0045: An Artist’s Nth Album, When the Library Does Not Have It, Is the Next of Theirs It Does


Status	Proposed — until a first album the library lacks has been asked for and the next one played; see What would settle it
Date	2026-10-24
Scope	What “Genesis’ first album” plays when the owner’s library does not have From Genesis to Revelation.
Extends	ADR-0041, whose count this goes on along; ADR-0040, whose command gains alternatives

Context

“Genesis’ first album” was heard right, twice, and counted right: From Genesis to Revelation, 1969. The owner’s iTunes has it as its reissue, And the Word Was…, and so was asked for a title it has not got. With nothing matched it played the band’s other songs from Abacab, the first by name, which the driver rightly took for a miss; where nothing at all matches, having emptied its queue, it stops. The library cannot be asked what it has (ADR-0040), so a miss is only found by trying.

CHG-0045: The Backend Pi's iTunes Pairing Is Kept

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0045: The Backend Pi’s iTunes Pairing Is Kept


Date	2026-10-29
Change type	Deployment
Status	Complete
Systems	The home backend Pi, `eds-backend` (`192.168.2.40`): its tools and its iTunes pairing; iTunes on MEDIA-SERVER, which gained a remote; the owner’s Mac, which gained an age key
How	`secrets/new-key.sh`; `make -C deploy/backend push`, `make pair`, `make pairing`, from the branch of PR #107
Risk	Low. Most likely to go wrong: the Pi left unpaired by a test, which a copy set aside guarded
Decisions	ADR-0052, and ADR-0037’s first step
Related	CHG-0044, the push before

Summary

The backend Pi’s iTunes pairing lived on its card alone, under the name “EdS”. After: it pairs as “EdS home”, and the pairing is kept in the repository, encrypted to the owner’s age key, so a new card for this Pi starts paired.

ADR-0046: Requests Are Matched Against the Owner's Library

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0046: Requests Are Matched Against the Owner’s Library, as Its XML Lists It


Status	Proposed — until the requests below play on the first try; see What would settle it
Date	2026-10-24
Scope	How voiced turns a heard artist and an album, or an album’s place, into the titles `play_album` names.
Extends	ADR-0041, whose count orders the library’s albums; ADR-0045, whose `instead` carries the library’s titles now

Context

Every miss on 2026-10-24 was a guess at how the library spells something. iTunes will not list its library to EdS (ADR-0040), so voiced asked for MusicBrainz’s titles and the driver checked what played. Each fix covered the miss before it: Genesis’ first is the reissue And The Word Was in the library; Skynyrd’s is Pronounced leh-nerd skin-nerd, not “(pronounced ’lĕh-’nérd ‘skin-’nérd)”; “Arrowsmith” and “Leonard Skinner” are how speech writes two bands down.

CHG-0046: The Backend Pi Is on Its Cable Alone

Mon, 01 Jan 0001 00:00:00 +0000

CHG-0046: The Backend Pi Is on Its Cable Alone


Date	2026-10-30
Change type	Configuration
Status	Complete
Systems	The home backend Pi, `eds-backend`; the backend image (`images/backend`) and `deploy/backend/card.sh`
How	`nmcli` on the Pi, over its cable; the image’s playbook and `card.sh` changed for the next card
Risk	Low. Most likely to go wrong: the session that makes the change riding the Wi-Fi it removes, which connecting to the wired address prevents
Decisions	None of its own. It is ADR-0053’s “radio off by default” before that record’s window is built, and CHG-0028’s “one address at home”
Related	CHG-0042, whose card asked for Wi-Fi; CHG-0028

Summary

The backend Pi had two addresses on the home network: 192.168.2.40 on its cable and 192.168.2.228 on Wi-Fi. Both were on DVNT-CORE. The Wi-Fi was deevnet-kit-wifi, which deevnet-kit made on the first boot from the network make card asked for. A second address on the same network bought nothing, appeared in the kit’s address warning, and could answer for eds-backend.local.

ADR-0047: voiced Asks eds-inventory

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0047: voiced Asks eds-inventory for the Owner’s Albums, in Place of Its Own Index


Status	Accepted 2026-10-24 — settled by CHG-0041
Date	2026-10-24
Scope	Where voiced finds the owner’s artists and albums when it turns a request into `play_album`. Not how it parses a request, or counts an artist’s albums in MusicBrainz, which are unchanged.
Extends	ADR-0046, whose matching moves to the inventory unchanged
Related	A Music Inventory, the proposal this begins; eds-inventory’s ADR-0002 and ADR-0003

Context

voiced matches requests against library.json, an index of the owner’s iTunes library that EdS makes from the XML and copies to voiced by hand (ADR-0046). Knowing what the owner has is an inventory concern, and eds-inventory now does it: it collects the same XML, keeps the same albums, and answers the four questions voiced asks with the same matching and thresholds, carried over from EdS’s internal/library.

ADR-0048: The Turntable Is Heard on Both Channels

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0048: The Turntable Is Heard on Both Channels, and One Gone Silent Is Said on the Console


Status	Proposed , until a side has played through with one channel unplugged; see What would settle it
Date	2026-10-25
Scope	How many channels the turntable’s driver listens to, what it decides from each, and how a channel gone silent is reported: a retained topic beside the source’s status, one event, and the console’s “Song detector” line. Not how silence, gaps or stops are timed, which is unchanged.
Extends	ADR-0026, whose silence is now the louder channel’s, and ADR-0034, whose “Song detector” pill gains a third color for an input heard on one side only
Related	ADR-0018, the console that only looks; ADR-0021, the driver; ADR-0017, the agent’s events

Context

On the evening of 2026-10-25 (about 01:34 UTC on the 26th) the stand went to standby in the middle of a side. A record was playing, the Eagles' Live, and the music could still be heard in the room. The turntable’s driver had heard twenty seconds below -55 dBFS and said stopped, as ADR-0026 has it do, and nowplayd dimmed the room a second later.

ADR-0049: A Device Holds Two Sites, and Is Told Which

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0049: A Device Holds Two Sites’ Settings, and Is Told Which to Use by a Message


Status	Proposed , until a device has been switched both ways and has undone a switch it could not complete; see What would settle it
Date	2026-10-26
Scope	What a device’s `creds` partition holds for more than one site, the keys it is held under, the message that switches a device from one site to the other, and what a device does when the switch fails. Not what is in a site’s settings, which is unchanged.
Extends	ADR-0004, whose partition now holds a second site’s secrets beside the first’s, and ADR-0035, whose topics, sender and undo-it-yourself rule a switch follows
Related	ADR-0033, the backend Pi that is the second site; ADR-0034, whose status says where a device is

Context

EdS’s devices now live at two sites. The tenant’s broker at Deevnet IoTaaS’s mobile site, on its IoT network, and the backend Pi at home, on the home network. Each site has its own Wi-Fi, its own broker accounts and, until the home Pi took a certificate from Deevnet’s Tenant Service CA, its own CA.

ADR-0050: How Each Track Was Completed Is Written Down

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0050: How Each Track’s Album and Cover Were Found Is Written Down, One Line a Track, and nowplayd Sends It to the Log Store


Status	Proposed , until the lines have been read on the dashboard from a side of a record; see What would settle it
Date	2026-10-27
Scope	What `nowplayd` writes down about completing a track: who named its album, where its cover came from, how long each step took and why one gave up; the owner’s collection being read; how those lines reach the tenant’s log store; the dashboard that reads them. Not how a track is completed, which is unchanged.
Extends	ADR-0027, whose `api.calls` was the only line `nowplayd` sent to the store
Related	ADR-0008, the completing; ADR-0022, the collection; ADR-0038, the original album

Context

On the evening of 2026-10-26 the turntable played “Over the Hills and Far Away”, the recognizer named it, and the stand did not follow it: the track was published with no cover. Finding out why took the journal. Houses of the Holy was not in the owner’s Discogs collection; naming its original album, through Deezer and then MusicBrainz at one call a second, used the whole lookup time; and the cover’s lookup had been given the same time, already spent. That last fault is fixed (eds#101). Nothing showed any of it.

ADR-0051: Spotify Is Switched On and Off From the Console

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0051: Spotify Is Switched On and Off From the Console, and Off Asks Spotify Nothing


Status	Accepted : switched both ways from the console’s page on the backend Pi, 2026-10-29 (CHG-0044); see What would settle it
Date	2026-10-28
Scope	A switch for the Spotify driver: where its state is kept, what “off” stops, who reads it, and the console’s second control.
Extends	ADR-0039: a second retained setting, and the console’s second control, which that record said would bring back the question of a login.
Related	CHG-0024, whose follow-up this is. ADR-0027, whose count shows the switch working. ADR-0020, whose commands are never retained; this is not one of them. ADR-0034.

Context

The Spotify driver asks Spotify what is playing every ten seconds, all day, whether or not anything plays. Its owner does not want that all the time, and does want Spotify followed sometimes.

ADR-0052: Each Pi's iTunes Pairing Is Kept, Encrypted, in the Repository

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0052: Each Pi’s iTunes Pairing Is Kept, Encrypted, in the Repository, and a New Card Starts Paired


Status	Accepted : a pairing kept, put on a card’s boot partition and taken by the first boot’s setup, with nobody at iTunes, 2026-10-29 (CHG-0045); see What would settle it
Date	2026-10-28
Scope	Where an agent’s iTunes pairing is kept between cards, how it reaches a new card, and one pairing per Pi. Not Spotify’s authorization, and not the other hand-kept secrets.
Extends	ADR-0037: its `secrets/`, its age key and `sops` are built here, for this first secret. A pairing is “made where it is used”, which that record leaves where it is made; this record says why a pairing is kept anyway. ADR-0011, whose consequence “lose it and pairing is repeated” this ends.
Related	ADR-0010, the relay Pi. ADR-0033, the backend Pi.

Context

The iTunes driver controls iTunes as a paired remote (ADR-0011). Pairing takes a person at the iTunes PC, typing a four-digit code that the Pi prints. What it leaves behind is one small file on the Pi, /var/lib/eds-npagent/itunes-pairing.json:

ADR-0053: A Home Pi Opens a Maintenance Leg for the Van

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0053: A Home Pi Opens a Maintenance Leg for the Van, for a While, When Asked From Inside


Status	Proposed : until a window has been opened, used and closed on the backend Pi; see What would settle it. It takes effect when the Pi’s cable leaves DVNT-CORE
Date	2026-10-28
Scope	How the mobile site reaches an EdS Pi that lives at home: a Wi-Fi leg onto the home LAN, off unless opened, and what it admits. The day-2 jobs that use it are named here and decided elsewhere.
Extends	ADR-0010: a second leg, fenced, now off by default and opened for a time. ADR-0033: the backend Pi, now at home.
Related	CHG-0042, which moves the backend Pi home. CHG-0028, which chose one address at home. ADR-0052, one of the jobs. Deevnet ADR-0011, ADR-0013, ADR-0020 and ADR-0041, and Deevnet’s network segmentation standard.

Context

The backend Pi has moved home (CHG-0042), and others may follow. At home it is on the home LAN, DVNT-CORE (192.168.2.0/23, behind the home OPNsense). Its certificate, its tenant’s Terraform and the tools that look after it are on the mobile site, dvntm.