Files

T

serversdownandClaude Opus 5 48f2ab7954 docs: write the changelog on dev, not on feature branches

Reverses the "entry goes in with the work" rule from two commits ago. That was
wrong on the evidence: of the docs(changelog) commits in history, 3 of 4 in
seismo-relay and 2 of 4 in Terra-View were made directly on dev. The rule was
generalized from one unrepresentative commit rather than from the pattern.

It also caused the exact problem it was supposed to avoid. With four worktrees
in flight, every branch edits the same few lines at the top of CHANGELOG.md;
feat/ach-rescue-on-connect and feat/sensor-check-h5 collide on that file and
nothing else. Writing the entry once, on dev, after the merge removes the
whole conflict class.

The second benefit is accuracy: an entry written after the merge describes
what actually landed, including anything that changed during conflict
resolution. The sensor-check branch is a live example — its Unreleased
preamble describes a release that no longer looks like that.

The failure mode of writing it later is forgetting, so the merge is explicitly
not finished until Unreleased is updated — same sitting, reconstructed from the
branch commit messages.

Unchanged: no preamble under Unreleased, the mandatory operational consequence,
and cutting the version on dev when ready to ship to main.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qcu9ByJfuKBQxmrWb8rSrN

2026-09-18 18:52:17 +00:00

6.4 KiB

Raw Permalink Blame History

CLAUDE.md — SLMM (Sound Level Meter Manager)

Device module for Rion NL-43 / NL-53 sound level meters. Translates Terra-View's REST calls into the meter's ASCII command protocol over TCP, and pulls stored data over FTP. Current version: v0.4.0.

Stack-level context (which repo owns what, version pairing) lives in ../terra-view/docs/tmi-stack.md, which is also loaded as ~/CLAUDE.md.

Terra-View never talks to a meter directly — it always goes through here. SLMM owns the protocol; Terra-View owns the UI and the measurement records.

Where things stand (updated 2026-08-29)

v0.4.0 (2026-06-22) is the current release. The three things that define the current design:

Fan-out live monitor. The NL-43 has one TCP control connection, and every dashboard used to fight for it. Now a single poller reads the device and all subscribers share one cached feed: WS /api/nl43/{unit_id}/monitor delivers an instant first frame from cache, then live updates. Poll rate adapts to demand, unreachable devices back off, and the background poller skips units already covered by an active monitor so nothing double-polls.
Alert engine. Per-device threshold rules (metric + threshold + cooldown) with full CRUD, an onset/clear state machine, and acknowledgement. Enabled rules pin the monitor on, so they evaluate 24/7 with no UI client connected. Editing or deleting a rule resets its state and closes any open event.
History for chart backfill. A downsampled trail persists to nl43_readings and is served from GET /api/nl43/{unit_id}/history, so live charts can fill in recent history on load. L1/L10 percentiles are surfaced in status and the live feed.

CHANGELOG.md is the authority for anything older; prefer it over prose here.

Changelog & release convention

Adopted 2026-09-18, to match seismo-relay and Terra-View. SLMM had no written practice before this — earlier releases used ad-hoc commits like chore: version bump. This is the standard going forward.

Feature branches do NOT touch CHANGELOG.md. Write the entry on dev, as part of finishing the merge, under ## [Unreleased]. Cut the version on dev in a dedicated release commit when you are ready to ship to main.

The changelog is written on dev, never on a feature branch. With several branches in flight they all edit the same few lines at the top of the file and conflict every time. Writing it once, after the merge, also lets it describe what actually landed — including anything that changed during conflict resolution.
⚠ The merge is not finished until ## [Unreleased] is updated. Same sitting, not "later" — that is the one failure mode of writing it after the fact. Reconstruct from the branch's own commit messages: git log --oneline dev..<branch> before you merge, or git log --oneline <merge-base>..<branch> after.
No preamble under ## [Unreleased] — just the ### Added / ### Changed / ### Fixed lists. The themed opening paragraph gets written at release time, when the whole release is visible and can be named honestly. A theme written when the first item landed is stale by the third.
⚠ State the operational consequence, including when it is "none." Silence is ambiguous; "none" is information. For this repo that means:
- DB migration — whether a migrate_*.py script is needed, which one, and whether it is safe to re-run. These live at the repo root and are easy to forget at deploy time.
- Meter-connection impact — anything touching the NL-43/NL-53 TCP path, polling cadence, or the monitor fan-out. The meter has a single TCP slot, so a change that bounces the connection is an operational event, not just a code change.
Releases are cut on judgement, not on a schedule or a merge. Unreleased is the staging area for whatever is going into the next release; when enough has accumulated to be worth shipping, it gets a number and a date. Nothing about a merge to dev triggers a release.
Cutting a release is its own chore(release): vX.Y.Z commit on dev, renaming ## [Unreleased] → ## [X.Y.Z] - YYYY-MM-DD and bumping the version in app/main.py (the FastAPI version= argument).
main carries only released versions. No ## [Unreleased] section there; it lands via the dev → main PR.

Layout

app/
  main.py              FastAPI app + health checks
  routers.py           all REST endpoints
  services.py          NL43Client — TCP + FTP protocol
  monitor.py           the fan-out live feed
  background_poller.py scheduled polling
  alerts.py            rule evaluation + event state machine
  models.py            NL43Config, NL43Status, nl43_readings
  database.py          SQLAlchemy / SQLite (data/slmm.db)
  device_logger.py
docs/     manuals/     templates/     nl52/     SLM-stress-test/

Key docs: docs/API.md (endpoint reference with curl examples), docs/COMMUNICATION_GUIDE.md and docs/nl43_Command_ref.md (protocol).

API surface

GET/PUT /api/nl43/{unit}/config
GET     /api/nl43/{unit}/status            cached snapshot
GET     /api/nl43/{unit}/live              fresh read
POST    /api/nl43/{unit}/{start|stop|pause|resume|reset|store}
GET     /api/nl43/{unit}/{battery|clock|results|settings}
WS      /api/nl43/{unit}/monitor           fan-out live feed
POST    /api/nl43/{unit}/monitor/{start|stop}
GET     /api/nl43/_monitor/status
GET     /api/nl43/{unit}/history           backfill trail
        .../alerts/rules  .../alerts/events  .../events/{id}/ack
POST/GET /api/nl43/{unit}/ftp/{enable|disable|status|files|download}
GET     /api/nl43/{unit}/overwrite-check   BEFORE changing a store name

Gotchas

One TCP connection per meter. This is the constraint the whole monitor design exists to work around. Never add a code path that opens its own connection alongside the monitor.
1-second minimum between commands. The NL-43 protocol requires it; SLMM enforces it automatically. Do not "optimise" it away.
Check overwrite-check before changing a store name — otherwise you can destroy data on the meter's SD card.
FTP is active mode — the device connects back to the server on port 21.
network_mode: host in compose, for direct network access to meters.
Environment: PORT (8100), CORS_ORIGINS, TIMEZONE_OFFSET, TIMEZONE_NAME.

6.4 KiB Raw Permalink Blame History