spike: validate neolink MQTT behavior against real Reolink hardware (blocks #25)

[badbread]

Goal

Validate neolink's real MQTT behavior against a real Reolink before building the actuator-control backend in #25. The exact topic strings are documented, but the behaviors the backend depends on (floodlight revert semantics, siren timing, and whether control messages are retained) are not — and building against assumptions would produce wrong or unsafe code. This blocks #25's backend.

Hands-on hardware task (no agent can watch a physical light/siren). Run against one mains-powered Reolink that has a floodlight and/or siren.

Confirmed topic map (source: neolink README, to be verified live)

Prefix neolink/{CAMERANAME}.

Control:

• /control/floodlight [on|off] — direct lamp on/off (the on-demand button; separate from auto)
• /control/floodlight_tasks [on|off] — automatic triggers only
• /control/ir [on|off|auto] — IR lights (note the explicit auto = revert value)
• /control/led [on|off]
• /control/pir [on|off]
• /control/siren on — one-shot, no off (self-terminates)
• /control/reboot

Status: /status (connection + LastWill = offline detection), /status/motion [on|off], /status/pir (XML), /status/battery_level, /status/floodlight_tasks.

Docs are silent on retained/QoS — that is the single most important thing to nail.

Runbook

1. Point neolink at one camera + an MQTT broker (see neolink's sample_config.toml; Reolink Baichuan port is 9000). Run it (Docker). Note and pin the neolink image tag used.
2. Subscribe to the full tree: mosquitto_sub -h <broker> -v -t 'neolink/#'. Confirm the topics above appear.
3. Run each test and record the result:

Test	Command	Record
Floodlight on-demand	mosquitto_pub -t neolink/<cam>/control/floodlight -m on	Lamp on now? Command→light latency?
Floodlight revert	... control/floodlight -m off	Lamp off? Does the auto night/motion behavior still work afterward?
IR revert value	... control/ir -m auto	Returns to auto light-detection?
Siren	... control/siren -m on	Sounds? Duration? Any stop/off? Retrigger interval?
Retained (safety)	publish floodlight on, restart the broker, reconnect	Does neolink re-fire it? (retained ON re-firing a siren after a broker restart would be a real hazard — the backend must publish non-retained)
Status echoes	watch status/motion, status, status/floodlight_tasks	What updates, how fast?

Deliverable

The filled-in table above + the pinned image tag. That converts #25's assumptions into confirmed facts; the #25 backend build proceeds from there.

Open questions this resolves (that shape #25's design)

• Floodlight momentary/revert model (publish on, TTL, publish off; does auto behavior resume cleanly?).
• Siren state model (confirm one-shot self-terminating → trigger + Crumb-side cooldown, no revert).
• Retained/QoS (determines the boot-sweep + non-retained publish requirements).
• Actuation latency (optimistic vs confirmed UI state).

Blocks #25.

[badbread]

Morning quick-start: prove the floodlight is controllable (30-second test)

The fast "does it even work" before the full behavior table. Needs: neolink running against the target camera, an MQTT broker, and mosquitto-clients (for mosquitto_pub/mosquitto_sub).

1. Minimal neolink config — match exact field names against neolink's sample_config.toml; the Reolink Baichuan port is 9000:

[[cameras]]
name = "spikecam"
username = "admin"
password = "<reolink-password>"
address = "<cam-ip>:9000"
# plus the MQTT/broker section per sample_config.toml, pointed at <broker>:1883

Run neolink (Docker) with that config. No broker handy? A throwaway one:

docker run -d --name mqtt -p 1883:1883 eclipse-mosquitto

2. Watch the traffic (in a second terminal):

mosquitto_sub -h <broker> -v -t 'neolink/#'

3. The command — flip the light on, then revert:

mosquitto_pub -h <broker> -t 'neolink/spikecam/control/floodlight' -m on
# look outside — light on?
mosquitto_pub -h <broker> -t 'neolink/spikecam/control/floodlight' -m off

Topic is confirmed from neolink's docs: control/floodlight [on|off] is the direct lamp control (separate from floodlight_tasks).

Result:

• Light flips on then off → concept proven, camera is controllable. Continue with the full behavior table above (floodlight revert-to-auto, the retained-message safety test, latency, siren duration).
• Nothing happens → sanity-check the camera actually has a white-LED spotlight first (doorbell models often don't); if not, use an outdoor spotlight cam instead.