mirror of
https://github.com/legop3/MultiRoombaRover.git
synced 2026-11-16 19:52:17 -05:00
move from /pi to /rover because it isnt just pi anymore.
new json config stuff and ui
This commit is contained in:
@@ -0,0 +1,51 @@
|
||||
# Rover hardware configuration notes
|
||||
|
||||
This document records hardware-specific requirements while the roverd rework is in progress. The existing installer still contains machine-specific setup; the universal bootstrap and media profiles are not implemented yet. Final profile names and JSON examples will be added when those interfaces exist.
|
||||
|
||||
## 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. This design is agreed but not yet implemented.
|
||||
|
||||
## Existing AIY Voice HAT setup
|
||||
|
||||
These facts come from the repository's existing installer/configuration, not a live hardware check:
|
||||
|
||||
- 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.
|
||||
|
||||
## Remaining implementation work
|
||||
|
||||
- [ ] Add AIY capture/playback profiles alongside generic selectable ALSA device profiles.
|
||||
- [ ] Make TTS, horn, forwarded audio, and mixer routing use configured devices consistently.
|
||||
- [ ] Generate ALSA routing from the shared input/output configuration, including distinct input/output cards, logical profile devices, format conversion, and independent playback volume controls.
|
||||
- [ ] Audit fixed card numbers, named PCM assumptions, capture formats, camera orientation/sensor defaults, serial device defaults, and architecture-specific TTS assets.
|
||||
- [ ] Keep required one-time host boot changes visible; distinguish a hardware-overlay reboot from ordinary roverd update/restart behavior.
|
||||
- [ ] 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.
|
||||
+26
-36
@@ -359,43 +359,33 @@ An ESP32 that supplies all three roles describes:
|
||||
}
|
||||
```
|
||||
|
||||
The ESP32 description owns the calibration for hardware attached to that ESP32. Rover YAML does not repeat the ESP32 pin numbers or servo calibration.
|
||||
The ESP32 description owns the calibration for hardware attached to that ESP32. Rover configuration does not repeat the ESP32 pin numbers or servo calibration.
|
||||
|
||||
### Optional backend-selection rule
|
||||
### Peripheral role selection
|
||||
|
||||
`roverd` resolves each built-in role once during startup:
|
||||
Roverd resolves each built-in role once during startup across Firmata peripherals and the optional internal Pi GPIO peripheral. Exactly one provider enables a role; no providers leave it disabled. Multiple providers report a conflict identifying the devices and leave only that role unavailable. Native GPIO has no priority over external peripherals.
|
||||
|
||||
1. If that native Pi GPIO feature is enabled in rover YAML, use the native Pi implementation.
|
||||
2. Otherwise, if exactly one discovered ESP32 declares the role, use its Firmata implementation.
|
||||
3. Otherwise, leave the built-in feature disabled.
|
||||
All native settings live under `piGpio`, whose parent switch defaults to disabled:
|
||||
|
||||
Native configuration deliberately wins. A Pi rover can attach an ESP32 for unrelated generic controls without unexpectedly moving its existing camera servo, headlight, or laser to the ESP32. To deliberately use the ESP32 for one of those features, disable only that native feature in rover YAML.
|
||||
|
||||
Any rover configuration that should use the ESP32 for these roles keeps the corresponding native GPIO features disabled:
|
||||
|
||||
```yaml
|
||||
cameraServo:
|
||||
enabled: false
|
||||
|
||||
headlight:
|
||||
enabled: false
|
||||
|
||||
laser:
|
||||
enabled: false
|
||||
```json
|
||||
{
|
||||
"piGpio": {
|
||||
"enabled": false,
|
||||
"cameraServo": { "enabled": false },
|
||||
"headlight": { "enabled": true, "gpioPin": 22, "activeLow": true },
|
||||
"laser": { "enabled": false },
|
||||
"brc": { "enabled": true, "gpioPin": 4, "pulseEvery": "1m", "pulseWidth": "1s" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
An attached ESP32 can then fill any or all of those roles automatically at the next `roverd` start. This works identically on Raspberry Pi and laptop rover hosts; no USB path or backend name is added to YAML.
|
||||
This is a layout excerpt, not a complete configuration file. Use the JSON sample or `-print-default-config` for all required fields.
|
||||
|
||||
Conflict behavior is fixed and simple:
|
||||
|
||||
- Native feature enabled and ESP32 declares the same role: use native and log that the ESP32 role was ignored.
|
||||
- Native feature disabled and one ESP32 declares the role: use that ESP32.
|
||||
- Native feature disabled and no ESP32 declares the role: disable the feature.
|
||||
- Native feature disabled and multiple ESP32s declare the same role: fail startup with a duplicate-role error rather than choosing by USB enumeration order.
|
||||
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.
|
||||
|
||||
### Shared controller interfaces
|
||||
|
||||
The current `WSClient` directly owns concrete `*CameraServo` and `*GPIOToggle` values. Supporting either physical backend cleanly requires it to depend on the behavior it uses instead of a platform-specific concrete type.
|
||||
`WSClient` uses controller interfaces shared by the internal GPIO and external Firmata providers.
|
||||
|
||||
The intended interfaces are:
|
||||
|
||||
@@ -433,7 +423,7 @@ ToggleController
|
||||
|
||||
### Effective hello metadata
|
||||
|
||||
The current hello is built from `c.cfg.CameraServo`, `c.cfg.Headlight`, and `c.cfg.Laser`. That cannot remain the source of truth because an ESP32 role may enable a feature whose native YAML entry is disabled.
|
||||
Hello uses the selected controllers’ effective configuration, since external roles are independent of saved native GPIO settings.
|
||||
|
||||
After startup resolution, the selected controller supplies the effective public configuration. `sendHello()` advertises that effective configuration:
|
||||
|
||||
@@ -794,7 +784,7 @@ Use `esp32-s3-devkitc-1` and the matching `/dev/ttyACM*` device for a
|
||||
native-USB ESP32-S3.
|
||||
|
||||
```bash
|
||||
cd pi/roverd
|
||||
cd rover/roverd
|
||||
go run ./cmd/peripheral-probe -port /dev/ttyUSB0
|
||||
```
|
||||
## Connection lifecycle
|
||||
@@ -813,8 +803,8 @@ Peripheral discovery happens exactly once per `roverd` process. The currently im
|
||||
8. Validates every advertised standard-output pin against Firmata capabilities.
|
||||
9. Configures generic digital, PWM, and servo pin modes once.
|
||||
10. Assigns process-local IDs such as `firmata-0` and `firmata-1` in discovery order.
|
||||
11. Resolves `cameraServo`, `headlight`, and `laser` against the native configuration.
|
||||
12. Rejects duplicate ESP32 providers only when the corresponding native role is disabled and Firmata selection would otherwise be ambiguous.
|
||||
11. Registers the internal Pi GPIO peripheral if enabled and resolves camera-servo, headlight, and laser roles across providers.
|
||||
12. Reports duplicate role providers and leaves conflicting roles unavailable.
|
||||
13. Constructs the selected native or Firmata controllers and fixed generic inventory.
|
||||
14. Constructs `WSClient` with those controllers and that inventory.
|
||||
15. Connects to the server and includes the effective built-in configuration and renderable inventory in the normal rover hello.
|
||||
@@ -1144,7 +1134,7 @@ repository reference firmware. The package manifest, README, and examples are
|
||||
self-contained so the same directory can be published directly to the
|
||||
PlatformIO Registry as `legop3/RoverPeripheral`.
|
||||
|
||||
### `pi/roverd`
|
||||
### `rover/roverd`
|
||||
|
||||
`PeripheralManager` is responsible for:
|
||||
|
||||
@@ -1164,9 +1154,9 @@ Only renderable control metadata leaves `roverd`. Firmata pin numbers, output ma
|
||||
|
||||
The manager should remain independent of the existing Roomba Open Interface serial adapter. A peripheral serial connection is not the Roomba base serial connection and must not be routed through `SerialAdapter`.
|
||||
|
||||
The transport foundation is a focused Firmata parser/client in `pi/roverd/firmata.go`. It operates on `io.ReadWriteCloser`, which keeps byte-stream behavior testable without hardware and lets discovery pass either `/dev/ttyUSB*` or `/dev/ttyACM*` ports into the same client. `pi/roverd/cmd/peripheral-probe` remains the direct hardware diagnostic entry point, while `PeripheralManager` now connects the same client to automatic daemon startup discovery.
|
||||
The transport foundation is a focused Firmata parser/client in `rover/roverd/firmata.go`. It operates on `io.ReadWriteCloser`, which keeps byte-stream behavior testable without hardware and lets discovery pass either `/dev/ttyUSB*` or `/dev/ttyACM*` ports into the same client. `rover/roverd/cmd/peripheral-probe` remains the direct hardware diagnostic entry point, while `PeripheralManager` now connects the same client to automatic daemon startup discovery.
|
||||
|
||||
`WSClient` now depends on shared camera-servo and toggle controller interfaces rather than platform-selected concrete types. The startup resolver uses the same native-first rule in the ARM Pi and amd64 laptop binaries. Firmata camera movement retains the established limits, home position, nudging, inversion, pulse calibration, raw-pulse policy, and movement-rate behavior; Firmata toggles retain logical state and polarity conversion.
|
||||
`WSClient` now depends on shared camera-servo and toggle controller interfaces rather than platform-selected concrete types. The startup resolver uses the same unique-provider rule in every architecture binary. Firmata camera movement retains the established limits, home position, nudging, inversion, pulse calibration, raw-pulse policy, and movement-rate behavior; Firmata toggles retain logical state and polarity conversion.
|
||||
|
||||
### Server
|
||||
|
||||
@@ -1247,8 +1237,8 @@ The completed system should be verified with a real ESP32 and rover Linux comput
|
||||
- Confirm camera angle limits, home position, nudge amount, inversion, pulse calibration, and rate limiting match the declared ESP32 configuration.
|
||||
- Confirm headlight and laser toggle state events remain identical to the native Pi path.
|
||||
- Confirm existing laser restrictions still apply with the Firmata backend.
|
||||
- Enable a native role and declare the same ESP32 role; confirm native wins and the ignored role is logged.
|
||||
- Disable native and declare the same role from two ESP32s; confirm startup fails with a clear duplicate-role error.
|
||||
- Enable Pi GPIO and a native role also declared by an ESP32; confirm the conflict lists both providers and leaves that role unavailable.
|
||||
- Declare the same role from two ESP32s; confirm a clear conflict and that unrelated roles remain available.
|
||||
- Confirm a Pi rover can use native built-in controls and generic ESP32 controls simultaneously.
|
||||
- Repeat ESP32 role selection on both the ARM Pi binary and amd64 laptop binary and confirm their commands and advertised configurations match.
|
||||
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
# 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`: existing control commands, acknowledgements, sensors, and operational toggle state. The planned full `roverState` replacement is not implemented yet.
|
||||
- `/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 in hello are currently empty. YAML media profiles are the next media implementation stage, not installed catalogs hidden elsewhere.
|
||||
|
||||
## 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 remain 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
|
||||
|
||||
Browser/live verification of the configuration page, shared `roverState`, YAML media catalogs/child supervision, universal ALSA routing, standalone bootstrap, and replacement update workflow remain pending. The current updater and systemd media supervisor have moved transport but retain their existing implementations until those stages.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,266 @@
|
||||
# Roverd rework plan and implementation tracker
|
||||
|
||||
Status: implementation authorized on 2026-11-16; repository/build, internal GPIO, and JSON/management backend implemented; live management verification and remaining stages 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.
|
||||
- [ ] 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.
|
||||
- [ ] 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).
|
||||
- [ ] Implement full-object `roverState` and consolidate server/UI operational-state consumers.
|
||||
- [ ] Add bundled YAML catalogs and one custom YAML profile per media category.
|
||||
- [ ] Preserve AIY HAT as an explicit profile and expose ordinary audio-device selection on every architecture, including TTS/horn/mixer paths.
|
||||
- [ ] Generate ALSA routing from shared input/output selections; connect microphone, TTS, horn, forwarded audio, and independent volume controls to the resulting logical devices.
|
||||
- [ ] Document exact configuration for the existing AIY rover and audit other machine-specific assumptions.
|
||||
- [ ] Implement command environments, persistent working directories, and setup on each daemon startup.
|
||||
- [ ] Replace media systemd management with child-process supervision and continuous bounded output forwarding.
|
||||
- [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).
|
||||
- [ ] Add profile editing/selection, media output/status, reboot, and update UI.
|
||||
- [ ] Implement standalone bootstrap with only name/address input and automatic OS architecture selection.
|
||||
- [ ] Implement shared checkout installation and self-update with reconnect-visible results.
|
||||
- [ ] Remove obsolete services, configuration files, scripts, build distinctions, and documentation.
|
||||
- [ ] Update user/contributor documentation, including profile variables, setup expectations, building, installation, and updates.
|
||||
- [ ] Perform focused available verification and record results below.
|
||||
- [ ] Record deployment/hardware checks still required; do not claim those verified locally.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user