cleanupses

This commit is contained in:
legop3
2026-11-17 00:34:27 -05:00
parent 2d9b6e4a36
commit c384a1389a
27 changed files with 64 additions and 1346 deletions
-80
View File
@@ -1,80 +0,0 @@
# Rover hardware configuration notes
This document records hardware-specific requirements while the roverd rework is in progress. Media profiles and shared audio routing are implemented. The standalone bootstrap creates the managed checkout and invokes the shared installer. Configuration selections are recorded below.
## Universal configuration requirements
- Audio capture and playback devices must be selectable on every supported architecture. An ARM machine need not use an AIY HAT, and an AMD64 machine need not use its first sound card.
- Keep the Google AIY Voice HAT as an explicit selectable profile, not a default applied to every Pi or every ARM binary.
- Prefer stable ALSA card identifiers over card numbers where supported; discover the actual identifier on the rover rather than assuming it from this document.
- Preserve concurrent TTS, horn, and forwarded audio playback and their independent volume controls. Device selection must cover these paths as well as the microphone streamer.
- Hardware-specific boot overlays, PWM pin allocation, and package setup belong to an explicit hardware choice or documented host setup. They must not be unconditional bootstrap side effects.
## Agreed audio routing design
Roverd configuration selects one physical input device and one physical output device. These may be on different sound cards. Roverd generates ALSA routing from those settings on startup, using the ordinary configuration save/restart flow when they change.
The microphone streamer uses the selected input. TTS, horn, and forwarded audio share the selected output while retaining simultaneous playback and separate volume controls. Profiles use the generated logical devices supplied through their environment; they do not each hardcode or independently select physical audio hardware. Use ALSA conversion where supported instead of requiring all devices to accept the existing HAT playback format.
AIY setup enables its hardware and uses this same routing system. The bootstrap still asks only for rover name and server address. Audio routing and the standalone bootstrap are implemented; hardware verification remains pending.
## Historical AIY Voice HAT setup
These facts record the previous installer/configuration, not a live hardware check or the current implementation:
- The Pi installer enables `dtoverlay=googlevoicehat-soundcard` and `dtparam=i2s=on`, and disables onboard audio with `dtparam=audio=off`.
- The README records that this setup worked on Raspberry Pi OS Bookworm and had problems on Trixie. The rework must not imply that the HAT is verified on every Debian release.
- The current ALSA routing uses `hw:0,0` and mixer card `0`. A comment identifies the HAT card as `sndrpigooglevoi`; verify the actual card identifier on the deployed rover before replacing numeric device references.
- Logical playback devices are `tts`, `horn`, and `forward`; capture has the `rovermic` alias. They share a playback mixer configured for 16 kHz mono S16_LE and expose `TTSMaster`, `HornMaster`, and `ForwardMaster` volume controls.
- The existing source places a kernel-module `options` line in `asound.conf`. During audio-profile implementation, separate module configuration from ALSA PCM configuration instead of copying that assumption into the generic setup.
- The installer enables PWM on GPIO12/13 with `dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4`, explicitly leaving GPIO18/19 free for I2S. The sample servo uses GPIO12, while the checked-in local config has a disabled servo on GPIO19. Do not enable that saved GPIO19 servo setting for the HAT setup without checking wiring and I2S ownership.
For the new internal GPIO peripheral, enable `piGpio.enabled` on a rover that uses these GPIO features, then configure its children for the actual wiring:
| Feature | Existing setup to preserve |
| --- | --- |
| BRC | Enabled, GPIO4 on `gpiochip0`, pulse every 1 minute for 1 second |
| Headlight | Enabled, GPIO22 on `gpiochip0`, active-low, initially off |
| Laser | Optional, GPIO27 on `gpiochip0`, active-high, initially off |
| Camera servo | Optional; sample GPIO12, 50 Hz, cycle length 20000, 900–2100 microseconds, -15 to 30 degrees, home 0, nudge 2 degrees |
The parent switch now defaults to disabled. Saved child settings do not enable GPIO on their own. External peripherals must not advertise the same enabled role unless the conflicting internal role is disabled.
## Implementation and verification tracking
- [x] Add AIY capture/playback profiles alongside generic selectable ALSA device profiles.
- [x] Make TTS, horn, forwarded audio, and mixer routing use configured devices consistently.
- [x] Generate ALSA routing from the shared input/output configuration, including distinct input/output cards, logical profile devices, format conversion, and independent playback volume controls.
- [x] Audit fixed card numbers, named PCM assumptions, capture formats, camera orientation/sensor defaults, serial device defaults, and architecture-specific TTS assets. Findings and deployment checks are below.
- [x] Keep required one-time host boot changes visible; distinguish a hardware-overlay reboot from ordinary roverd update/restart behavior.
- [x] Add exact final profile selections and JSON settings for the existing AIY rover.
- [ ] Verify on the actual HAT and at least one non-HAT audio device; record results rather than assuming compatibility.
## Implemented profile/audio selections (2026-11-16)
The new supervisor and generated ALSA routing are implemented, but not hardware-verified. See [media profile documentation](rover-media-profiles.md). Bundled setup/run commands are contained in YAML, not repository shell helpers.
For the existing AIY v1 setup, start with these fields in a complete current config:
- `media.video.profile`: `rpicam`, enabled for the CSI camera; retain the existing resolution/bitrate, inverted mounting, and sensor mode if appropriate.
- `media.audioCapture.profile` and `media.audioPlayback.profile`: `aiy`, enabling each required streamer. Their inline setup enables I2S and the Google Voice HAT overlay. Reboot once if setup changes boot configuration.
- `audio.inputDevice` and `audio.outputDevice`: `hw:CARD=sndrpigooglevoi,DEV=0`, **after verifying that identifier on the rover**.
- `audio.mixerCard`: `sndrpigooglevoi`, matching the verified output card.
- `audio.outputSampleRate`: `16000`; `audio.outputChannels`: `1`, preserving the old HAT mixing format.
- `audio.ttsEnabled`: true if desired; choose `audio.defaultEngine` explicitly. Chrome speech assets now live outside the checkout under `/var/lib/roverd/googletts`.
- Enable the parent `piGpio.enabled` and the desired child roles as described above. The old automatic PWM-overlay installer is gone; the GPIO12/13 PWM overlay remains a documented host wiring requirement, not an audio-profile side effect.
The HAT setup does not disable unrelated onboard audio or force a card index. Use the configured stable device/card names. Existing installed media systemd units must be removed/disabled before running the new supervisor. Remove any old roverd-specific host ALSA configuration before deployment: the generated config includes the system ALSA definitions, whose hooks can still load host configuration. The old media launchers are no longer used.
## Hardware assumption audit (2026-11-16)
- New configs use a non-inverted camera and automatic CSI sensor mode (empty `media.video.sensorMode`). The AIY/CSI sample and checked-in rover config retain the existing inverted mount and `1296:972` selection. For your existing rover set `media.video.inverted` to true and retain that sensor mode only if supported by the connected camera. V4L2 uses `media.video.device` and `inputFormat`; its profile ignores the CSI mode.
- `serial.device` defaults to `/dev/ttyUSB0`, but accepts a stable `/dev/serial/by-id/...` path. Select the Roomba adapter explicitly to avoid depending on USB enumeration. Peripheral discovery excludes that device.
- Audio card zero and 48 kHz stereo are editable defaults, not mandatory hardware. Set the physical input/output separately and use the HAT's 16 kHz mono output values above. Logical plug devices perform format conversion; the physical output still needs to support the chosen dmix format. Verify microphone channels/rate against actual hardware.
- Chrome TTS assets are chosen by installed OS architecture; ARMv6 has no bundled Chrome library and should use `audio.defaultEngine: "flite"` or `"espeak"`. Chrome libraries/voices still require on-device verification. TTS, horn, and forwarded audio use the generated routing; verify independent gains after each logical PCM has opened, when ALSA creates its soft-volume control.
- Pi firmware voltage/throttle probes run only when `vcgencmd` is installed. Native GPIO access remains controlled by `piGpio.enabled`, independently of host-health telemetry.
- AIY profile setup adds new boot settings under `[all]`. If existing matching settings are inside a model-specific section, ensure that section applies to your Pi. The profile does not rewrite existing host sections.
- Keep `dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4` in an applicable boot-config section for the existing GPIO12 servo wiring. Keep GPIO18/19 free for the HAT's I2S. Reboot after overlay changes.
No camera, ALSA device, firmware command, or GPIO operation was exercised during this source audit. Host installation, browser flows, and physical hardware verification remain required.
+23 -31
View File
@@ -1,12 +1,19 @@
# Rover media profiles and audio
# Writing rover media profiles
Roverd reads three YAML catalogs directly from its checkout: `rover/profiles/video.yaml`, `audioCapture.yaml`, and `audioPlayback.yaml`. Each is a list of profiles with `id`, `name`, `description`, optional `setup`, and `run`.
Bundled profiles live in `rover/profiles/video.yaml`, `audioCapture.yaml`, and `audioPlayback.yaml`. Each catalog is a YAML list with these fields:
Commands live in the YAML itself. Bundled profiles must not delegate their setup or run implementation to an in-repository shell helper. Multiline shell commands, arrays, and pipelines are supported through Bash with error/pipe failure handling. Profile identifiers use lowercase letters, digits, underscores, and hyphens; `custom` is reserved.
- `id`: lowercase letters, digits, underscores, or hyphens; `custom` is reserved.
- `name` and `description`: displayed in Fleet Management.
- `setup`: optional Bash command, safe to repeat at every roverd startup.
- `run`: Bash command that stays running to stream media.
Each enabled streamer runs its selected setup on every daemon startup. Setups are serialized to avoid competing package-manager operations; successful setup is not tracked on disk. Each run command then starts independently and retries after two seconds on exit. A failed setup leaves only that streamer stopped. Shutdown kills the complete process group and waits for it. Nothing installs media systemd services.
Put commands directly in YAML, not in repository shell helpers. Bash arrays and pipelines work. Commands run as root with error and pipeline failure handling, in `/var/lib/roverd/profiles/<category>/<id>`. That directory persists across restarts and updates.
Working directories are `/var/lib/roverd/profiles/<category>/<id>`. Commands receive environment variables, not interpolated shell source. Quote variables normally.
Enabled profiles run setup serially, then stream independently. Setup failure stops only that streamer. Exited run commands retry after two seconds without repeating setup. Shutdown stops the complete process group. Output and status appear in Fleet Management; output buffering is bounded.
## Command variables
Variables are supplied through the environment. Quote expansions normally, for example `"$ROVER_VIDEO_DEVICE"`.
| Variables | Meaning |
| --- | --- |
@@ -20,38 +27,23 @@ Working directories are `/var/lib/roverd/profiles/<category>/<id>`. Commands rec
| `ROVER_AUDIO_SAMPLE_RATE`, `ROVER_AUDIO_CHANNELS`, `ROVER_AUDIO_BITRATE` | Microphone encoding settings |
| `ROVER_AUDIO_NORMALIZE`, `ROVER_AUDIO_NORMALIZE_FILTER` | Forwarded-audio normalization |
The bundled options are `v4l2` / `rpicam` for video and `alsa` / `aiy` for capture and playback. Hardware encoders or other transports can be supplied as custom commands without adding roverd code.
## Configuration and UI
Fleet Management supports one custom profile per category, saved at `/etc/roverd/profiles/<category>.yaml`. Saving a custom profile restarts roverd; choose it in the streamer's configuration to use it.
Select `media.video.profile`, `media.audioCapture.profile`, and `media.audioPlayback.profile`, with each category's `enabled` switch. Fleet management renders profile names from the catalogs and has a “Media profiles and output” section for descriptions, current status, output, and custom editing.
## Audio constraints
There is one custom profile per category, stored under `/etc/roverd/profiles/<category>.yaml`. Saving it restarts roverd; select `custom` in configuration to use it. Bundled files remain in the checkout. The admin API is `roverManagement:saveProfile` with `{ roverId, category, profile }`.
Use the supplied logical audio routes so microphone, TTS, horn, and forwarded audio follow the configured devices. Physical input/output are selected separately through `audio.inputDevice` and `audio.outputDevice`. Find stable identifiers with `arecord -l` and `aplay -l`.
Output is always forwarded while management is connected, without viewer subscriptions. Rover queues and server/browser history are bounded; a noisy process can lose old output but cannot indefinitely block streaming or grow history. Current streamer status is retained separately and included in management hello.
The output must support a hardware dmix slave with the configured sample rate/channels. Client format conversion uses ALSA plug devices. Independent volume controls may appear only after their PCM first opens. ARMv6 hosts use flite/espeak rather than Chrome TTS.
## Audio routing
For the existing AIY Voice HAT, verify card ID `sndrpigooglevoi` before using `hw:CARD=sndrpigooglevoi,DEV=0`; the previous output format was 16000 Hz mono. GPIO18/19 are used by I2S. The existing GPIO12 servo requires `dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4` in an applicable boot-config section. Reboot after overlay changes.
`audio.inputDevice` and `audio.outputDevice` select physical ALSA devices independently. Use hardware PCM identifiers such as `hw:CARD=Device,DEV=0`; find the actual identifiers with `arecord -l` and `aplay -l`. The output must support ALSA dmix's hardware slave; arbitrary sound-server/plugin PCM names are not interchangeable with a hardware PCM.
## Verification still required
`audio.mixerCard` selects the output card's mixer identifier. `audio.outputSampleRate` and `audio.outputChannels` configure its hardware mix format. Choose a format supported by that device; `plug` handles client conversion to that format. Input and output may be on separate cards.
Implementation has passed local build/syntax checks; live deployment remains unverified:
Roverd generates `/var/lib/roverd/asound.conf` and sets `ALSA_CONFIG_PATH` for its children. It does not overwrite the host's ALSA configuration. Its system ALSA include can still load host configuration through ALSA hooks; remove old roverd-specific host ALSA definitions before deployment. Logical devices are `rover_capture`, `rover_tts`, `rover_horn`, and `rover_forward`. TTS, horn, and forwarded audio share a dmix output and have independent soft-volume controls. `amixer` targets the configured mixer card, never a fallback card zero. Some soft-volume controls appear only once their PCM has first been opened; verify volume behavior after playback begins.
- Bootstrap, configuration saves, fleet field changes, and update results after reconnection.
- Camera, microphone, simultaneous TTS/horn/forwarded audio, individual gains, and GPIO/serial operation.
- Streamer retries on a brief connection loss and complete child shutdown on config restart. The separate control watchdog reboots after six minutes offline.
Chrome TTS uses the same generated playback route. Its architecture-specific library/voice files are runtime data under `/var/lib/roverd/googletts`; the installer invokes the independent TTS dependency installer. ARMv6 hosts must use flite/espeak if no matching Chrome library is available. The server no longer substitutes Chrome TTS when a command omits an engine; roverd's configured default applies.
## Inspection without hardware or setup execution
```sh
./dist/roverd-linux-amd64 -repo "$PWD" -print-media-profiles
./dist/roverd-linux-amd64 -config rover/roverd/roverd.sample.json -check-config
./dist/roverd-linux-amd64 -config rover/roverd/roverd.sample.json -print-audio-config
```
These commands do not install packages, open devices, or start streams. Configuration/schema and architecture binaries have changed together; old JSON objects are not migrated.
## Deployment checks still required
Before deploying over an old installation, explicitly disable/remove its old media units so they cannot compete for devices or publish duplicate streams. This rework does not migrate an installed host. The checkout installer now installs only the roverd service and runtime dependencies; the standalone bootstrap and shared updater use that installer. See [installation and updates](roverd-installation.md).
On the actual rover, confirm all selected profiles complete setup, observe output/status in fleet management, and verify video, microphone, forwarded audio, TTS, horn, simultaneous playback, and each gain control. Restart the server or interrupt Wi-Fi: media commands should retry without restarting roverd. The existing control-disconnection watchdog separately seeks the dock after one minute and reboots the host after six minutes; use a shorter interruption to isolate streamer retries. Save configuration and verify no media child processes remain from the previous daemon. Capture journal output and observed results. AIY overlay changes require a one-time host reboot; ordinary configuration saves only restart roverd.
Before replacing an old installation, disable its streamer services and remove its roverd-specific host ALSA definitions; system ALSA hooks can still load those definitions.
+2 -2
View File
@@ -379,9 +379,9 @@ All native settings live under `piGpio`, whose parent switch defaults to disable
}
```
This is a layout excerpt, not a complete configuration file. Use the JSON sample or `-print-default-config` for all required fields.
This is a layout excerpt, not a complete configuration file. Use Fleet Management to edit the complete configuration, or `-print-default-config` to inspect all initial fields.
While the parent is disabled, saved child settings cause no GPIO probing or initialization. When enabled, the internal peripheral appears as `pi-gpio` / “Pi GPIO” and offers its enabled roles. BRC runs as its automatic background function, not a user control. Pin, chip, servo calibration, and timing settings all remain inside this section. This applies to every architecture build. See the JSON sample config for complete settings; the WebUI configuration editor is a later rework step.
While the parent is disabled, saved child settings cause no GPIO probing or initialization. When enabled, the internal peripheral appears as `pi-gpio` / “Pi GPIO” and offers its enabled roles. BRC runs as its automatic background function, not a user control. Pin, chip, servo calibration, and timing settings all remain inside this section. This applies to every architecture build. Configure these settings in the Fleet Management configuration editor.
### Shared controller interfaces
-21
View File
@@ -1,21 +0,0 @@
# Rover installation and updates
Download `rover/bootstrap.sh` from the repository onto a Debian-based rover, then run `sudo bash bootstrap.sh`. No preexisting checkout is required. Enter the rover name and full server address, for example `ws://server:8080/rover` or `wss://example.org/rover`.
Bootstrap installs prerequisites, clones into `/opt/roverd`, invokes `rover/install_roverd.sh`, and starts the root roverd service. The checkout is root-owned and dedicated to installation and updates; keep development changes elsewhere. Rerunning bootstrap preserves an existing configuration rather than replacing its identity with the prompt answers.
The shared installer selects AMD64, ARM64, or ARMv6/ARMv7 for a 32-bit ARM OS. A Pi Zero 2 W uses ARM64 on a 64-bit OS and ARMv7 on a 32-bit OS. Binaries come from `dist/` in the repository; no release publishing or on-rover compilation is required.
Fleet Management configures the remaining settings. Media and native GPIO start disabled. Profiles are already in the checkout; selecting one causes its inline setup to run on roverd startup. See [media profiles](rover-media-profiles.md) and [AIY hardware settings](rover-hardware-config.md).
## Updates
The management update action launches `roverd-self-update` as an independent transient systemd service. It fast-forwards the registered checkout, invokes the same installer, and restarts only roverd. A modified/diverged checkout can make Git refuse the update; it is not forcibly reset.
The installer preserves `/etc/roverd.json`, `/etc/roverd/profiles/`, and `/var/lib/roverd/`. Replacing the installed executable and updater uses rename so running processes retain their existing executable/script. Update progress and the last result are atomically written to `/var/lib/roverd/update-status.json`, forwarded through management, and shown in Fleet Management after reconnecting. This reports completion of installation/service restart, not camera or audio health.
For detailed command output use `journalctl -u roverd-self-update`; for daemon startup use `journalctl -u roverd`. Failed update jobs report failure and release the old daemon's pending management action if it is still running. There is no rollback system. If installation fails after changing files, fix the reported error and rerun the installer/update.
## Deployment checks still required
On a fresh rover, run bootstrap and confirm management connects with the supplied identity. Select the hardware profiles and verify their output. Trigger an update and confirm progress, reconnection, final status, and preservation of JSON/custom profiles. Confirm a failed update reports its error and allows another management action. These host/systemd/network flows have not been executed on the development machine.
-79
View File
@@ -1,79 +0,0 @@
# Roverd configuration and management
Roverd now reads `/etc/roverd.json`. YAML settings are no longer accepted. Repository samples and installer paths use JSON; there is no configuration migration or legacy reader.
The schema is generated from the Go configuration types. Both configuration files and remote submissions must contain the complete object. Derived media URLs are excluded from saved settings and still included in control hello metadata.
## Local configuration commands
These commands do not open hardware, start media, or connect to the server:
```sh
./dist/roverd-linux-amd64 -print-default-config
./dist/roverd-linux-amd64 -print-config-schema
./dist/roverd-linux-amd64 -config rover/roverd/roverd.sample.json -check-config
```
Select the appropriate architecture binary on a rover. The default object supplies initial values; edit the name and server URL before installing it. The initial serial path may need configuration for the actual hardware.
## Connections and state
- `/rover`: control commands, acknowledgements, sensors, and complete `roverState` snapshots.
- `/rover/management`: configuration hello, management commands/acknowledgements, host statistics, and daemon events.
- Derive the management address from the configured `ws://host[:port]/rover` or `wss://host[:port]/rover` control URL; there is no second server address to maintain.
- Management starts independently of hardware initialization and remains available after serial/peripheral startup failure.
- Control disconnect docking/reboot behavior still depends on control connectivity. A live management connection does not count as a working control connection.
- The server maintains management records independently of the control roster, only in memory. Management disconnect removes the record; hello repopulates it.
- Profile catalogs and current media status arrive in hello; see [media profiles](rover-media-profiles.md).
## Configuration page
Open `/admin?section=fleet` as an admin or lockdown admin. Select a management-connected rover, edit its schema-driven form, and use “Save to this rover”. For a fleet change, select the field below the form and use “Apply this field to all rovers”; its value comes from the current draft. Review individual results. Offline rovers are not queued.
## Admin Socket.IO API
Each request receives a callback containing either `{ success: true, ...result }` or `{ error: "..." }`. Authorization uses the existing admin/lockdown-admin role check.
| Event | Payload | Result |
| --- | --- | --- |
| `roverManagement:list` | `{}` | `rovers`, including management-only rovers |
| `roverManagement:get` | `{ roverId }` | Current configuration, schema, profiles, host statistics, recent notices |
| `roverManagement:save` | `{ roverId, config }` | Request ID after roverd acknowledges the complete object |
| `roverManagement:applyField` | `{ path: ["piGpio", "enabled"], value: false }` | Individual `results` containing rover ID, success/error, and successful request ID |
| `roverManagement:command` | `{ roverId, type, reboot?, media? }` | Request ID after acknowledgement; types are `reboot`, `update`, `media` |
Admin notifications are `roverManagement:changed`, `roverManagement:offline`, `roverManagement:hostStats`, and `roverManagement:event`. Requests time out if no acknowledgement arrives. Disconnect before acknowledgement reports an unknown outcome as an error; reconnect and read the actual configuration rather than assuming it was not saved.
The existing reboot/update UI paths use management delivery and retain `commandAck` notifications. The separate user “reboot my rover” permission/cooldown checks remain in place. Generic media-management commands now require admin privileges.
## Save lifecycle
1. Validate the complete JSON object against the schema and existing semantic checks.
2. Block new control commands and stop motion when a control runtime exists.
3. Write and sync a temporary file, then atomically replace the configuration file with mode `0600`.
4. Attempt the acknowledgement, cancel the daemon runtime, and release hardware resources.
5. Re-execute roverd, reload the saved file, and send a new management hello.
Once the file has been replaced, roverd restarts even if the acknowledgement cannot be delivered. The server does not optimistically overwrite its cached configuration. Invalid submissions leave the file untouched.
## Deployment verification still required
Do this on the intended server/rover, not the development machine:
1. Deploy the changed server and the matching rover binary/config together. Capture `journalctl -u roverd -f` and server logs.
2. With an authenticated admin Socket.IO session, call `roverManagement:list` and `roverManagement:get`. Expect configuration and schema even when the rover's serial device cannot open.
3. Change a harmless setting such as description in the returned full object and call `roverManagement:save`. Expect an acknowledgement, disconnect/reconnect, and a new hello containing that setting. Confirm `/etc/roverd.json` matches and survives a service restart.
4. Submit an incomplete object. Expect an error, no file replacement, and no restart.
5. Confirm host statistics and autocharge/watchdog/daemon notices still reach their existing UI/alert consumers through management. Headlight/laser state must arrive as a complete `roverState` snapshot on control.
6. Verify reboot/update requests use management, the normal user reboot restrictions still apply, and non-admin clients cannot read/save configuration or invoke the admin command endpoint.
7. Confirm new movement commands cannot execute while a save/reboot/update is stopping the rover, and that control disconnect safety still works independently of management.
Record acknowledgement errors, reconnect hello contents, relevant journal/server output, and physical stop behavior in the implementation tracker. Do not treat CLI validation or compilation as evidence of these deployed flows.
## Pending stages
YAML media catalogs, child supervision, shared ALSA routing, and Fleet Management profile controls are implemented. Browser/live verification of configuration, operational state, media, and audio remains pending. Standalone bootstrap and shared self-update are implemented; host verification remains pending. See [installation and updates](roverd-installation.md). Update status is included as `updateStatus` in hello and sent as `{type: "updateStatus", status: {state, message, timestamp}}` when it changes.
Apply-field targets the currently management-connected fleet. It clones each rover’s own configuration, replaces an existing field, and sends the complete object for rover-side validation. Inspect individual results for failures. Missing fields and changed connections are reported; offline changes are not queued. Paths traverse object fields, not array elements. Array-valued fields can be replaced as a whole.
Control state messages have the shape `{ "type": "roverState", "state": { "headlightOn": false, "laserOn": null } }`. Null indicates an unavailable role. Each message replaces the server object; disconnect clears it. The roster exposes `roverState` directly, rather than per-device `state` objects.
-311
View File
@@ -1,311 +0,0 @@
# Roverd rework plan and implementation tracker
Status: implementation authorized on 2026-11-16; repository/build, internal GPIO, JSON/management, Fleet UI, rover state, media profiles/supervision, and shared audio routing implemented; standalone bootstrap and shared self-update are also implemented; source cleanup/hardware audit is complete; deployment and hardware verification remain pending.
This is the persistent plan and progress record for the roverd rework. Update it as implementation proceeds, recording completed work, decisions, verification evidence, and remaining work. Keep unfinished work unchecked; distinguish implemented behavior from runtime-verified behavior.
## Authorization and working rules
- The user explicitly authorized implementation with `IPI` on 2026-11-16.
- No backward compatibility: no migrations, old-path aliases, legacy fallbacks, or dual protocols. Roverd, server, and WebUI move together.
- Prefer the simplest effective implementation. The behavior below is the intended outcome; avoid adding frameworks or bookkeeping without a concrete need.
- Follow repository verification rules: no new tests unless requested, no automatic full-project checks, and use the smallest useful verification. This development machine is not the deployed server or rover hardware.
## Agreed design
### Repository and builds
- Rename `pi/` to `rover/`; update paths, imports, scripts, build commands, and documentation.
- Replace machine-specific builds and the `debian_laptop` distinction with architecture-specific Linux builds: ARMv6, ARMv7, ARM64, and AMD64.
- Hardware support depends on configuration and available hardware, not a Pi/laptop classification. Remove the existing laptop-specific hardware stubs as part of resolving this split.
- Keep prebuilt binaries committed in `dist/`. No published releases or release bundles are required.
- Detect the installed OS architecture during installation, including 32-bit ARM installations; do not select solely from CPU capability.
- Debian is the target platform across rover hardware.
### Internal Pi GPIO peripheral
- Provide one `piGpio` configuration section, presented as “Pi GPIO peripheral”, with a parent `enabled` switch defaulting to disabled.
- Keep all native GPIO settings inside this section, beneath the parent switch in the editor:
- Camera servo: enablement, pin, PWM, calibration, limits, and movement settings.
- Headlight and laser: individual enablement, pin/chip, polarity, and initial state.
- BRC: enablement, pin/chip, pulse interval, and pulse width.
- Disabling the parent switch disables the entire internal peripheral without probing, initializing, or accessing GPIO resources. Preserve its saved settings for later re-enablement. No Pi GPIO settings remain scattered elsewhere in configuration.
- When enabled, register one internal peripheral named “Pi GPIO”, with a stable ID such as `pi-gpio`, offering only the configured enabled camera-servo/headlight/laser roles.
- Separate peripheral identity and role ownership from the Firmata transport. Use a small common provider interface for external Firmata peripherals and the internal GPIO peripheral, reusing the existing camera-servo and toggle controller interfaces.
- Call GPIO implementations directly in process; do not simulate serial connections or Firmata messages.
- The internal peripheral owns BRC startup and shutdown as an automatic background function, not a fake user-facing control.
- Apply one role-conflict rule across providers: if multiple peripherals advertise the same role, report the providers and leave that role unavailable until corrected. Keep management accessible. Remove the current implicit native-GPIO priority; different roles may come from different peripherals.
- Operational state uses the same `roverState` object regardless of whether its provider is internal GPIO or an external peripheral.
- This runtime switch replaces the machine-specific GPIO build distinction. GPIO being disabled must permit operation on non-Pi hosts without GPIO errors.
### Configuration ownership and saves
- Roverd owns one `/etc/roverd.json` object containing all rover settings and supplies its JSON Schema.
- Include selected media profiles, enablement, devices, and media settings in configuration. Derive runtime values such as complete streaming URLs in roverd.
- Management hello sends current configuration, schema, and available media profiles.
- The server holds these only in memory. Reconnection repopulates them; there is no configuration database or offline change queue.
- Every save transmits the complete configuration object, even when only one field changed.
- Roverd validates the proposed configuration, atomically writes it, acknowledges the save, stops motion and child processes, and restarts. Its next hello reports the configuration actually loaded.
- Invalid submissions return an error without replacing the file.
- No deltas, configuration versions, or rollback system.
- Existing JSON tags omit some settings; do not mistake current hello metadata serialization for a complete configuration representation.
### Communication channels
Control channel:
- Driving and other rover actions, with their acknowledgements.
- Roomba sensor telemetry.
- Complete `roverState` messages.
Management channel (a separate WebSocket):
- Configuration and profile management.
- Reboot and software update commands/results.
- Media process control, status, and output.
- Host statistics.
- Daemon status notices, including autocharge timer notices and watchdog diagnostics.
Classify existing events by purpose rather than moving the entire existing event stream wholesale. Update server handlers and UI consumers along with their producers. Headlight and laser state are operational state, not management.
Start management before hardware initialization so hardware configuration errors remain remotely diagnosable and fixable. Use the existing admin authorization path for management operations. Preserve motion-stop behavior for reboot, update, and configuration restart. Control-connection safety behavior must remain tied to control availability, not be satisfied by a live management connection.
### One current rover state
- Roverd owns one `roverState` JSON object for operational state such as headlight and laser states.
- Send the full object on control connection/reconnection and whenever its contents change.
- The server replaces its current object for that rover and uses that single copy for all consumers and UI updates.
- Remove separate headlight/laser state stores and per-field state events. No patches or deltas.
- Clear current state on disconnect so stale values are not presented as live.
- Roomba telemetry and management status remain separate from `roverState`.
### WebUI
- Reuse the existing React JSON Schema form library for each rover's configuration page.
- “Save to this rover” submits the complete configuration.
- “Apply this field to all rovers” replaces that field in each connected rover's own configuration, then sends each its complete resulting object. Preserve every rover's other settings.
- Show individual results; skip offline rovers without queued changes.
- Include profile selection, custom profile editing, media status/output, reboot, and software update controls.
### Audio devices and ALSA routing
- One audio configuration selects the physical input device and physical output device on every architecture. Input and output may belong to different sound cards; prefer stable ALSA device names over fixed card numbers.
- The microphone streamer uses the selected input. Forwarded audio, TTS, and horn share the selected output, with simultaneous playback and independent volume controls.
- Roverd generates ALSA routing from these settings as part of configuration startup. Supported format conversion belongs in the ALSA routing rather than assuming every device accepts the AIY format.
- Media profiles consume the resulting logical audio devices through the command environment instead of hardcoding physical devices such as `hw:0,0`.
- AIY-specific setup enables the HAT hardware; it uses this same audio configuration and routing system, not a separate set of device settings.
- Audio changes use the ordinary whole-object configuration save/restart flow. Device selection remains in the WebUI configuration, not the bootstrap questionnaire.
### Media profiles
- Keep three accessible YAML catalogs under `rover/profiles/`: video publishing, microphone publishing, and audio playback.
- Each profile has an identifier, name, description, optional `setup` command, and `run` command. Support multiline shell commands and pipelines.
- Read bundled profiles directly from the managed repository checkout. No separate profile installation or registration.
- Allow exactly one custom YAML profile per category under `/etc/roverd/profiles/`, editable through management. These files remain outside the checkout and survive updates.
- JSON configuration selects profiles and supplies settings such as devices, resolution, and bitrate.
- Profiles may contain hardware-specific configurations contributed by rover builders; no plugin API or custom code module is needed for each encoder.
- Preserve Google AIY Voice HAT support as an explicit option, while supporting configurable audio devices on every architecture. Do not treat Pi/ARM as synonymous with AIY hardware or assume sound card zero.
- Audit setup-specific assumptions beyond streamers, including TTS/horn/mixer routing, boot overlays, PWM/I2S pin conflicts, cameras, serial devices, and TTS assets. Generalize where useful and document the exact selections needed for the existing rover in [hardware configuration notes](rover-hardware-config.md).
### Command variables and setup
- Launch commands through a shell. Supply string values through environment variables rather than inserting them into shell source or creating a template language.
- Supply rover name, server host, audio/video devices, media settings, complete publish/playback URLs, and profile working directory to both setup and run commands.
- Example: `ffmpeg -i "$ROVER_VIDEO_DEVICE" … "$ROVER_VIDEO_PUBLISH_URL"`.
- Each profile gets a persistent working directory under `/var/lib/roverd/profiles/` for downloads, builds, and other generated files.
- At every roverd startup, run each selected enabled profile's setup command before its run command. Commands must be safe to repeat.
- No persistent setup-success tracking. Profile changes save configuration and restart roverd, naturally running setup for the newly selected profile.
- Routine streamer retries run only the run command.
- Setup failure is visible and prevents that streamer from launching, without stopping roverd or the other streamers.
### Media supervision and output
- Roverd directly supervises the three media commands as child processes.
- Restart exited commands after a short retry delay. Server restarts and Wi-Fi interruptions are routine retry situations.
- Streamer failure never stops or restarts roverd. Management connection loss does not stop streamers.
- Shutdown stops complete child process groups, including pipelines.
- Capture stdout/stderr and continuously forward output through management while connected. Use bounded buffering so noisy commands or disconnections cannot block streamers or consume unlimited memory.
- No viewer subscriptions or output-demand tracking.
- Remove old streamer systemd services and the code managing them. Systemd supervises only roverd, running as root.
### Standalone bootstrap
The bootstrap script works without an existing repository on the rover:
1. Install basic Debian prerequisites.
2. Clone the repository into `/opt/roverd`.
3. Invoke the checkout's installation script.
4. Automatically select the committed binary matching the installed OS architecture.
5. Create initial configuration and working directories.
6. Install and start the single root roverd service.
Ask for only rover name and server address. Everything else starts with defaults and is configured through management; no camera, encoder, audio, or machine-profile questionnaire.
`/opt/roverd` belongs to roverd and is not a development working directory. Profile setup handles hardware-specific dependencies.
### Self-update
- Use a helper that survives roverd restarting.
- Update the managed checkout, invoke the same installation script used by bootstrap, install the matching committed binary, and restart roverd.
- Bundled profiles update with the checkout. Preserve local JSON configuration, custom profiles, and persistent profile working directories.
- Forward progress through management while available and make the update result available after reconnection.
- Routine updates restart the service without rebooting the computer.
## Implementation checklist
The order below is a working sequence, not a requirement to leave incompatible intermediate states deployed.
- [x] Receive explicit `IPI` before code implementation (2026-11-16).
- [x] Rename `pi/` to `rover/` and update references.
- [x] Replace machine-specific build targets/tags with architecture-specific artifacts and resolve hardware support split.
- [x] Group every native GPIO setting under the disabled-by-default Pi GPIO peripheral switch in the current configuration and samples.
- [x] Expose the grouped Pi GPIO configuration in the new JSON schema/UI.
- [x] Register Pi GPIO through the common peripheral provider path, including BRC lifecycle ownership and uniform role-conflict handling.
- [x] Connect peripheral operational state to the new shared `roverState` object.
- [x] Gate GPIO provider registration, initialization, and BRC startup behind the parent switch; retain saved child settings. Hardware validation remains pending.
- [x] Implement complete JSON configuration serialization, schema, validation, atomic saves, and restart flow (live save/reconnect verification pending).
- [x] Implement separate management connection and in-memory server management state.
- [x] Move reboot, update, media management, host statistics, and daemon status messages to management; update consumers. Preserve the separately authorized user reboot path.
- [x] Separate management lifecycle from hardware startup failures (deployment verification pending).
- [x] Implement full-object `roverState` and consolidate server/UI operational-state consumers (live verification pending).
- [x] Add bundled YAML catalogs and one custom YAML profile per media category. (Live verification pending.)
- [x] Preserve AIY HAT as an explicit profile and expose ordinary audio-device selection on every architecture, including TTS/horn/mixer paths. (Live verification pending.)
- [x] Generate ALSA routing from shared input/output selections; connect microphone, TTS, horn, forwarded audio, and independent volume controls to the resulting logical devices. (Live verification pending.)
- [x] Document exact configuration for the existing AIY rover and audit other machine-specific assumptions.
- [x] Implement command environments, persistent working directories, and setup on each daemon startup. (Live verification pending.)
- [x] Replace media systemd management with child-process supervision and continuous bounded output forwarding. (Live verification pending.)
- [x] Implement per-rover schema editor and complete-object saves (browser/live verification pending).
- [x] Implement apply-one-field-to-all-connected-rovers with individual results (browser/live verification pending).
- [x] Add profile editing/selection, media output/status, reboot, and update UI. (Live verification pending.)
- [x] Implement standalone bootstrap with only name/address input and automatic OS architecture selection. (Host verification pending.)
- [x] Implement shared checkout installation and self-update with reconnect-visible results. (Host verification pending.)
- [x] Remove obsolete services, configuration files, scripts, build distinctions, and documentation.
- [x] Update user/contributor documentation, including profile variables, setup expectations, building, installation, and updates.
- [x] Perform focused available verification and record results below.
- [x] Record deployment/hardware checks still required; do not claim those verified locally.
- [ ] Complete live rover/server/browser and hardware verification recorded below.
## Verification record
2026-11-16, foundation stage:
- Focused existing peripheral tests passed: `go test . -run 'Test(DisabledNativeRolesResolveToFirmataOnEveryHostBuild|MissingNativeAndFirmataRolesRemainDisabled|ConflictingRolesRemainUnavailableWithoutInitializingGPIO|Peripheral)' -count=1` in `rover/roverd`. Adapted existing expectations for the deliberately changed config/role-conflict behavior; no new test files were created. These exercise Firmata behavior, parent-disabled selection with enabled saved children, and conflicts that must not initialize native hardware.
- An initial test invocation from the repository root failed because the Go module is under `rover/roverd`; reran from that module as above.
- Architecture builds passed for ARMv6, ARMv7, ARM64, and AMD64. Regenerated all four artifacts after final shutdown/error-handling corrections; all builds passed.
- `git diff --check` passed for tracked changes.
- `bash -n rover/install/profiles.sh` passed. Actual installation was not run on this development machine.
- GPIO electrical behavior, BRC timing, and AIY audio remain unverified on hardware. On the actual rover, check startup inventory/role conflicts and exercise configured light/servo/BRC outputs; capture journal output and observed behavior.
Record each meaningful check with the affected behavior, command or action, result, and limitations. In particular, distinguish local evidence from actual rover/server verification of connection recovery, motion stopping, process cleanup, media streaming, and updates.
## Progress and decisions
- 2026-11-15: Consolidated the agreed design and user corrections into this persistent tracker. Implementation is pending `IPI`.
- 2026-11-16: Added the internal Pi GPIO peripheral design after inspecting current role ownership and BRC handling. All native GPIO options belong under one parent enable switch; disabled means no GPIO access. Implementation remains pending `IPI`.
- 2026-11-16: Received `IPI` and started the repository/build and internal GPIO foundation. The user additionally required universal device options while retaining an explicit AIY HAT setup; recorded existing assumptions in `rover-hardware-config.md`.
- Rejected complexity: release publishing, separate profile installation, persistent setup tracking, viewer-dependent output forwarding, and backward compatibility.
- Settled state boundary: operational state uses complete `roverState` objects on control; configuration/host/process/daemon management uses the management connection.
## Remaining implementation details
Resolve these with the simplest approach during implementation and record the result here; they do not change the agreed behavior:
- Exact profile YAML shape, environment variable names, and architecture artifact names.
- Exact management message shapes and remaining existing event classifications.
- Update target selection using the existing repository workflow, without introducing release publishing.
- Startup defaults that let a newly installed rover connect for configuration before its hardware is configured.
### Foundation implementation notes (2026-11-16)
- Added common role providers and the internal `pi-gpio` peripheral. Conflicts and role initialization failures leave that role unavailable while other roles continue; existing hello/controller behavior remains until the communication rework.
- BRC belongs to the internal peripheral and waits for its writer to stop before releasing GPIO. Shutdown interrupts long pulses.
- The installer now chooses the architecture artifact independently of its existing media setup profile. Media setup profiles and YAML config are still the old implementation, pending their planned replacement; this is not a parallel compatibility path.
- Removed obsolete generic/laptop daemon artifacts and the duplicate daemon binary inside the source tree. New architecture binaries live in `dist/`.
- JSON configuration/schema and management backend were subsequently implemented below. Full rework and hardware deployment verification are not complete.
### JSON and management backend (2026-11-16)
- Replaced YAML settings with complete JSON configs, including repository samples and dummy configs. No legacy decoder or migration path. The existing media implementation remains until its planned replacement.
- Added generated draft-7 JSON Schema using `invopop/jsonschema` and validation using `santhosh-tekuri/jsonschema/v6`; retained semantic validation and excluded derived media URLs from persisted configuration.
- Added CLI default/schema export and hardware-free configuration checking. Atomic saves block new control commands, stop motion, acknowledge, unwind hardware, and re-execute roverd.
- Added `/rover/management` and admin Socket.IO read/save/command endpoints. Management state is separate from the control roster, so startup failures do not hide a rover from management.
- Moved host statistics and daemon events (including autocharge notices) to management. Operational toggle events remain on control until the unified state stage.
- Existing admin reboot/update and the user-owned-rover reboot path now use management transport. The existing user authorization/cooldown policy is preserved; generic media management now requires admin access.
- Management hello currently has empty profile catalogs: profiles are not implemented yet. Shared audio-device fields will be introduced with functioning ALSA routing, not exposed as inactive settings.
- See [protocol and deployment checks](roverd-management.md). No live server or rover services were started on this development machine.
Verification for this stage:
- The actual AMD64 daemon's `-check-config` accepted both JSON samples, the checked-in rover config, and the first dummy config. It rejected `{}` with missing-required-property errors before hardware initialization. Schema export also succeeded.
- Syntax checks passed for the new management server service, WebSocket routing, command routing, and control connection handler.
- Refreshed ARMv6, ARMv7, ARM64, and AMD64 artifacts successfully after the final shutdown changes. Server management syntax and tracked diff whitespace checks passed.
- Live acknowledgement/save/restart/reconnect, motion stopping, role authorization, and hardware-failure recovery remain unverified. Follow the deployment checks above and record their results here.
### Handoff after usage-budget notice (2026-11-16)
- Stopped after the JSON/management backend stage; no UI or ALSA implementation started in this stage.
- Final shutdown handling pauses automatic charging, blocks control commands and watchdog recovery, and cancels disconnect actions before stopping motion. If a management action fails before commitment, control and automatic charging resume. Live motion behavior remains unverified.
- Existing media helper scripts, machine-specific installer setup, and Chrome TTS variants are still present intentionally as unfinished rework items, not completed universal audio support.
- Next work: the schema-driven WebUI editor and field-to-all save flow against the documented management API, followed by unified rover state and the media/audio stages. Existing IPI authorization remains in effect.
- No live server/rover processes were launched or left running. No commits were made. Work remains in the shared working tree, including newly added files and generated architecture binaries.
### Apply-field backend (2026-11-16)
- Implemented admin-only `roverManagement:applyField` with object-field paths, independent whole-object submissions, connection-change detection, and individual outcomes. Offline rovers are not queued.
- Node syntax check passed. Live fleet saves remain unverified. WebUI editor and apply-field controls are still pending; the combined checklist item remains unchecked.
### Configuration WebUI (2026-11-16)
- Added `/admin?section=fleet` for admins and lockdown admins, independent of lockdown-only server configuration.
- The page lists management connections, renders the rover-supplied schema, saves complete objects, and lets an administrator select a field from the draft for fleet-wide application with individual results.
- Offline drafts remain mounted; server reconnection refreshes the roster. Authoritative changed configuration replaces the draft. Switching the selected rover starts its form from the latest reported configuration.
- Focused ESLint passed for the new component and AdminApp, after correcting the initial command working directory to `webui`. No full build or browser/server process was started.
- Verify the page against actual server/rover connections: admin access, hardware-failure management visibility, form validation, save/reconnect, and fleet success/error reporting. Production WebUI assets have not been regenerated.
- Configuration UI/backend implementation is now present; end-to-end deployment verification remains pending. Profile/status/output controls, unified rover state, audio/media supervision, and bootstrap/update rework are still separate outstanding stages.
- Placement correction: rover configuration is embedded in the existing fleet management panel alongside the rover roster. Removed the separate administration tab.
### Unified operational state (2026-11-16)
- Roverd owns a complete `roverState` object with `headlightOn` and `laserOn`; null indicates an unavailable role. Sends on control connection/reconnection and logical changes. Pending notifications coalesce to the latest complete snapshot.
- Server replaces one current object, exposes it in roster snapshots, and clears it on disconnect. Superseded sockets cannot overwrite state or remove a newer connection. Removed per-toggle event handling and separate server state stores.
- Desktop/mobile/HUD controls, darkness reward restoration, and learning snapshots read the shared object. Telemetry and daemon management remain separate.
- All four architecture binaries rebuilt successfully; focused frontend lint and server syntax checks passed. The two existing roster lifecycle tests passed after updating their state fixture. No new tests added.
- Still verify live initial state, toggles through both GPIO/Firmata, reconnect state, disconnect clearing, and darkness restoration. Production UI assets have not been rebuilt.
- Next implementation stage: YAML media profiles, command environments and child-process supervision, alongside the planned universal audio routing.
### Media profiles, supervision, and audio (2026-11-16)
- Added three YAML catalogs with six profiles: V4L2/rpicam video, generic ALSA/AIY microphone and playback. All bundled setup/run commands are inline YAML; the user explicitly rejected delegation to repository shell helpers, and the AIY helper was removed.
- Each enabled streamer has a persistent working directory, startup setup, independent command restart, complete process-group cleanup, and bounded continuously forwarded output. Setup is serialized for package-manager access with no persistent completion markers.
- Management hello includes catalogs and current media status. Fleet management exposes profile selection, exactly one editable custom profile per category, status, and output. Output is not emitted as chat alerts.
- Shared audio input/output settings generate a private ALSA config for microphone, TTS, horn, and forwarded audio, retaining mixing and independent gains. Hardware output PCM, mixer card, rate, and channels are explicit settings. See hardware notes for AIY values and limitations.
- Removed old media services/launchers, old machine-specific installer modules, static ALSA configs, and duplicate Chrome daemon. The checkout installer now installs only roverd plus runtime dependencies. Standalone bootstrap and self-update redesign remain unfinished.
- The server now respects roverd's configured default speech engine. TTS assets live under `/var/lib/roverd/googletts`; the generic dependency helper selects architecture-specific libraries.
- Added real CLI inspection for catalogs and generated ALSA configuration, without setup execution or hardware access.
- Verification: all four architecture builds passed; six profiles loaded through the actual daemon and all setup/run commands passed Bash syntax checks; current sample config validation and ALSA config rendering passed; installer/TTS shell syntax and server JS syntax passed. Focused frontend lint passed including the final status-display changes. No camera/audio streaming, setup commands, host installation, or browser/server processes were run here.
- Next: verify the remaining frontend check, then standalone bootstrap and update flow. Actual device formats, concurrent playback/gains, child cleanup and network recovery still require the documented rover-side checks.
### Standalone bootstrap and shared updates (2026-11-16)
- Added `rover/bootstrap.sh`: prompts only for name/server WebSocket address, installs prerequisites, clones into `/opt/roverd`, invokes the shared installer, and starts roverd. Existing configuration is preserved on rerun.
- Installer selects committed architecture binaries from OS architecture (and ARM generation for 32-bit ARM), writes initial identity only on first installation, and preserves custom profiles/data. Running binary and updater replacement use atomic rename.
- Replaced rebooting updater with an independent systemd job using fast-forward Git pull and the same installer, followed by service restart. No releases, forced reset, migrations, or rollback machinery.
- Latest update progress/result is persisted atomically, sent over management, cached in server memory, and displayed in Fleet Management including after reconnect. Detailed command output stays in the systemd journal.
- Added `docs/roverd-installation.md` and updated README instructions.
- Verification: all four committed architecture binaries rebuilt successfully; shell syntax, server syntax, focused UI lint, and diff whitespace checks passed. No installation, apt operation, host reboot/restart, or live server/browser was run on the development machine.
- Required rover checks: fresh bootstrap identity/connectivity; successful update and reconnect-visible status; failure reporting and retry; preservation of settings/custom profiles/data. Hardware/audio checks and final universal-hardware audit remain open.
### Final source cleanup and hardware audit (2026-11-16)
- Audited device paths, ALSA routing and gains, camera defaults, serial discovery, architecture-specific TTS installation, GPIO ownership, host telemetry, installer/build references, and current setup documentation.
- Removed the inverted camera/fixed CSI mode from new defaults and cleared the CSI mode in the V4L2 sample. Preserved the existing AIY/CSI sample and checked-in rover configuration. Physical audio/serial device identifiers remain editable defaults; no automatic hardware guessing was added.
- Pi firmware voltage/throttle probes are optional when `vcgencmd` is absent. Native GPIO remains behind its explicit peripheral switch.
- Inline AIY setup now adds missing settings under `[all]` instead of inheriting the last boot-config section. Existing conditional host settings are documented rather than rewritten.
- Removed obsolete publisher/env-file wording and stale bootstrap status; updated hardware notes with exact existing camera, AIY, PWM, stable serial path, and TTS constraints. Historical stage notes above remain a record of their stage, not current pending work.
- Verification: all four committed architecture binaries rebuilt; actual daemon loaded six profiles and all inline commands passed Bash syntax checks; V4L2 sample validation passed; actual default export confirmed non-inverted video and empty sensor mode; diff whitespace check passed.
- Live installation/update, browser/server saves and permissions, GPIO/serial, camera/audio, independent volume controls, and failure/reconnect behavior remain unverified. Use the deployment checks in the management, installation, media, and hardware documents. No hardware services or background processes were started here.