Added chatterbox connections
This commit is contained in:
Jeff Luke committed
1 parent
41ef12f954
commit
e58ceeb192
58 files changed
+8931
-8
No files matched your search
@@ -0,0 +1,183 @@
|
||||
# Glitch / Odin integration lab
|
||||
|
||||
A separate experiment for **Glitch: the Dark Machine**, hosted in the Glitch repository. Odin stays untouched. This is a first vertical slice, not a migrated room or a deployment release.
|
||||
|
||||
## Whole-room simulation
|
||||
|
||||
The supplied Glitch GDD now has an isolated multi-cabinet room simulation with puzzles, boss, cells, calibration, launch and Teddy captions. Run `py -3 lab.py start-room` and open http://127.0.0.1:18777/?room=1 after building. See [the full walkthrough and test coverage](ROOM_SIMULATION.md). It uses separate ports and never sends GPIO outputs. Chatterbox Teddy speech and a phone-accessible LAN demo are available: run `py -3 lab.py start-room --speech --lan` on the configured GPU host. See [voice prerequisites and the optional Piper fallback](ROOM_SIMULATION.md#hear-teddy-with-chatterbox). Enable audio in the Teddy tab on each listening device; see the walkthrough for setup and timing.
|
||||
|
||||
## Status
|
||||
|
||||
The Rust controller, simulated cabinet, and real Godot sidecar build successfully. Rust tests, Flutter analysis/widget test, Python launcher tests, a headless HTTP/NATS/Godot lifecycle test, and the real Pac-Man score-completion adapter test have passed locally.
|
||||
|
||||
Physical RFID/Pi testing is still pending. The existing simulator remains the default. The new explicit Godot mode is a source-only lab, excluded from production exports. The Godot score test reports existing Pac-Man resource-retention warnings at shutdown; its assertions pass.
|
||||
|
||||
## Relationship to Odin
|
||||
|
||||
Reference: sibling Odin repository, commit `eecb42c2364d915bc79ea99b16a7dad8f71baf1b`.
|
||||
|
||||
The reference uses Rust/async-nats for control, MessagePack for prop messages, and JSON for game/Flutter messages. This lab follows that separation. It is newly written, with no dependency on or modifications to Odin, no copied production credentials, and no Odin puzzle rules.
|
||||
|
||||
The Flutter screen is a small Glitch-specific starting point, **not a fork of the full Odin UI yet**. We should establish the transport and message contract before migrating its room layout, services, routing, and puzzle controls. Escape Gallery is the app identity; Glitch is the current room.
|
||||
|
||||
```text
|
||||
Flutter web GM (127.0.0.1:18767)
|
||||
| HTTP JSON / polling
|
||||
Rust controller/gateway (127.0.0.1:18766)
|
||||
| NATS request/reply, named-field MessagePack
|
||||
Local NATS (127.0.0.1:14222)
|
||||
|
|
||||
Rust simulated cabinet_01
|
||||
```
|
||||
|
||||
The HTTP browser gateway is experimental. It avoids assuming the existing Odin Dart NATS client works in browsers. The owner may prefer a supported NATS WebSocket client or a different gateway.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install these on the development computer, then open a new terminal:
|
||||
|
||||
1. [Rust stable](https://www.rust-lang.org/tools/install), including the native compiler/linker required by its installer. This project uses edition 2024.
|
||||
2. [Flutter stable](https://docs.flutter.dev/install), with Dart 3.9.2 or newer within Dart 3.x. Run `flutter doctor`.
|
||||
3. [NATS Server](https://docs.nats.io/running-a-nats-service/introduction/installation), with `nats-server` on PATH.
|
||||
4. Python 3.10 or newer.
|
||||
|
||||
No Docker, Starfish, Pi login, room tokens, or existing production server are required for desktop tests. Dependency fetching needs internet access on the build computer. Commit Cargo.lock and gm/pubspec.lock after the first successful dependency resolution to pin the tested versions.
|
||||
|
||||
## Build and start on Windows
|
||||
|
||||
From the Glitch repository root:
|
||||
|
||||
```powershell
|
||||
cd labs/glitch_odin
|
||||
py -3 lab.py preflight
|
||||
py -3 lab.py build
|
||||
py -3 lab.py start
|
||||
```
|
||||
|
||||
Run each command separately and stop if it reports an error. Build runs Rust tests, compiles the two-role Rust executable, resolves Flutter dependencies, runs analysis and widget tests, and builds the browser app. It does not export or change Godot.
|
||||
|
||||
Keep the startup terminal open. When it prints READY, visit **http://127.0.0.1:18767** on this same computer. Ctrl+C stops only the child processes created by this launcher. An occupied port causes startup to fail instead of terminating another service.
|
||||
|
||||
On Linux/macOS, use `python3` in place of `py -3`.
|
||||
|
||||
## First acceptance test
|
||||
|
||||
1. Confirm the amber simulated-cabinet banner and **POWERED OFF / Waiting for operator**.
|
||||
2. Click **Power on**. The phase becomes booting for four seconds.
|
||||
3. Wait for ready. Credits must still be zero.
|
||||
4. Click **Simulate RFID scan**. Credits become one.
|
||||
5. Click **Simulate player Start**. Credits return to zero and phase becomes playing.
|
||||
6. Click **Simulate win**. Phase becomes won.
|
||||
7. Click **Reset test** to return to powered off.
|
||||
|
||||
In another terminal, run the automated test while the lab is running:
|
||||
|
||||
```powershell
|
||||
cd labs/glitch_odin
|
||||
py -3 lab.py smoke
|
||||
```
|
||||
|
||||
This test resets the simulated cabinet, exercises the actual HTTP/NATS/MessagePack path, verifies boot gating, credit gating, duplicate scan handling, stale-session rejection, and expiry, then leaves the cabinet powered off. Do not interact with the GM controls during this test.
|
||||
|
||||
To check unavailable-state behavior, run the three backend components manually in separate terminals instead of using the supervisor:
|
||||
|
||||
```powershell
|
||||
nats-server -c nats.conf
|
||||
.\target\debug\glitch-odin-lab.exe cabinet
|
||||
.\target\debug\glitch-odin-lab.exe controller
|
||||
py -3 -m http.server 18767 --bind 127.0.0.1 --directory gm/build/web
|
||||
```
|
||||
|
||||
Stop the cabinet process. The UI should show disconnected and disable controls after the next poll/timeout. Restart it: a new session begins powered off. No previous command should be replayed automatically.
|
||||
|
||||
## Contract and limits
|
||||
|
||||
- Subject: `escape_gallery.glitch.lab.v1.cabinet_01.request`.
|
||||
- Commands: snapshot, power_on, scan, start, win, reset.
|
||||
- Mutations require an ID, matching cabinet-process session, and expiry within 30 seconds.
|
||||
- Replies contain acceptance, duplicate status, a message, and the current cabinet snapshot.
|
||||
- MessagePack uses named fields. **This is not wire-compatible with Odin's generated tuple messages.**
|
||||
- The simulator remembers the last 256 commands in memory. It is not a persistent command journal.
|
||||
- Reset clears simulated game state but keeps the process session and replay cache. Restart creates a new session.
|
||||
- Ready state advances when queried after the boot deadline; the simulator has no rendering loop.
|
||||
- HTTP 200 can contain a rejected command: clients must inspect `accepted`.
|
||||
- No responder/timeouts produce HTTP 503. An unconfirmed delivery is never treated as success or automatically retried.
|
||||
- There is no room autopilot, next-cabinet sequencing, authentication, durable recovery, or generated Odin schema yet. The opt-in Godot sidecar is experimental.
|
||||
- All listeners are loopback only. The unauthenticated test gateway is deliberately unsuitable for LAN deployment.
|
||||
- BCM23 remains an LED. I2C button integration is still pending hardware identification.
|
||||
|
||||
## What we need next
|
||||
|
||||
1. Owner confirmation of the current Odin branch and permission/strategy for sharing its framework crates.
|
||||
2. Generator source, canonical schema, subjects, command acknowledgements, and state/session semantics.
|
||||
3. Choose the browser transport and verify the target Flutter build on laptops and iPads.
|
||||
4. Replace the experimental sidecar boundary with the agreed generated contract and, if desired, a Rust GDExtension. Only one controller may own a cabinet.
|
||||
5. Run the same acceptance flow on a disconnected test cabinet, then connect the known RFID driver. Keep the I2C board disabled until identified.
|
||||
6. Add room autopilot and multi-cabinet sequencing, then migrate the useful Odin GM room views.
|
||||
7. Integrate Starfish deployment/SSH management after runtime communication works.
|
||||
|
||||
The current Python controller, Godot exports, Pi services, and deployment guide remain the working deployment path until these gates pass.
|
||||
|
||||
## Development checks
|
||||
|
||||
```powershell
|
||||
py -3 -m unittest discover -s . -p test_runner.py -v
|
||||
cargo test
|
||||
cd gm
|
||||
flutter analyze
|
||||
flutter test
|
||||
```
|
||||
|
||||
Build products are ignored locally. The lab has a Godot import ignore marker and is excluded from game exports.
|
||||
|
||||
## Real Godot cabinet test (desktop)
|
||||
|
||||
Stop the running simulator with Ctrl+C first. From this lab folder:
|
||||
|
||||
```powershell
|
||||
py -3 lab.py build
|
||||
py -3 lab.py start-godot
|
||||
```
|
||||
|
||||
The launcher starts the local NATS broker, JSON controller, Rust Godot sidecar, a separate real Pac-Man scene, and the Flutter web server. Open http://127.0.0.1:18767. It should explicitly say REAL GODOT CABINET.
|
||||
|
||||
1. Power on from the GM screen.
|
||||
2. Watch the actual four-second boot and character intro in Godot.
|
||||
3. Click Simulate RFID scan. This desktop fixture is explicitly enabled by the launcher; it enters the game's normal RFID admission path.
|
||||
4. Press your mapped player Start in Godot, or Start game in the GM screen.
|
||||
5. Play to 500 points. The GM phase should become won. Simulate win is disabled for real Godot.
|
||||
6. Reset test returns the cabinet to powered off.
|
||||
|
||||
Set GLITCH_LAB_GODOT to the absolute executable path if the repository's Windows Godot executable is unavailable. The lab scene is tests/odin_lab/cabinet.tscn; it refuses to run without --glitch-lab. It does not load the managed production cabinet connection or invoke room reward mappings.
|
||||
|
||||
The sidecar talks only to 127.0.0.1:18768 using one newline-delimited JSON command/reply per TCP connection. The current Rust layer owns NATS and MessagePack. This is **not a GDExtension yet**.
|
||||
|
||||
### Automated checks
|
||||
|
||||
Stop the interactive lab before running these:
|
||||
|
||||
```powershell
|
||||
py -3 godot_smoke.py
|
||||
```
|
||||
|
||||
This starts and stops its own headless Godot, broker, sidecar and controller. It tests the real transport, injected scan admission, Start, reset, offline 503, and a new process session after restart. No physical devices are used. The original lab.py smoke intentionally refuses real Godot.
|
||||
|
||||
From the repository root, the score-completion test exercises Pac-Man's actual score objective:
|
||||
|
||||
```powershell
|
||||
.\Godot_v4.7.2-stable_win64_console.exe --headless --path . --script res://tests/odin_lab/check_adapter.gd -- --glitch-lab --lab-inject-rfid
|
||||
```
|
||||
|
||||
### Physical RFID: next bench test, not a deployment change
|
||||
|
||||
The lab can read the existing local GPIO bridge when Godot is started with --gpio=real instead of --lab-inject-rfid. These options cannot be combined. Leave BCM23 as an LED; I2C buttons remain unimplemented. No output command is exposed by the lab.
|
||||
|
||||
For that bench test, manually run NATS, the controller, the sidecar (binary argument godot, not cabinet), and Godot on the **same test host**. Start the known RFID-only bridge configuration separately. Godot arguments are:
|
||||
|
||||
```text
|
||||
--path <project-root> res://tests/odin_lab/cabinet.tscn -- --glitch-lab --gpio=real --lab-rfid-device=cab1_rfid1
|
||||
```
|
||||
|
||||
Use the device ID actually configured on that reader. Without --lab-inject-rfid, the GM scan button is disabled: a fresh physical card scan is required after boot. This initial test accepts any nonempty card UID, matching the existing test policy. A Pi needs its own Rust build, source project/assets and a compatible Godot executable; the Windows binary is not portable to it. This path has not been physically verified yet. Do not run another cabinet/Godot owner or another reader driver on the same hardware.
|
||||
|
||||
See [Odin message audit](ODIN_MESSAGES.md) for reusable system/timer/lifecycle definitions and the new Glitch-specific messages still needed.
|
||||
Reference in new issue
Block a user