Reference on EdS

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.

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.

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.

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.

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.