Skip to content

Commit 9bfb5ac

Browse files
committed
docs(coral-tpu): update README with ai-edge-litert, dynamic models, and watchdog
- Replaced references to PyCoral framework with ai-edge-litert - Documented the new dynamic model download behavior at deploy-time (no longer tracked in git) - Added a section on Resilience & Auto-Recovery covering the TPU Watchdog's hang (10s invoke timeout) and stall (30-frame silent drop) detection logic - Refined Linux/macOS Python documentation since the constraint has been lifted to 3.9-3.13
1 parent d2623c7 commit 9bfb5ac

File tree

1 file changed

+15
-5
lines changed
  • skills/detection/yolo-detection-2026-coral-tpu

1 file changed

+15
-5
lines changed

skills/detection/yolo-detection-2026-coral-tpu/README.md

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,9 @@ flowchart TD
1616
1717
subgraph Native_Process[Python Virtual Env]
1818
D[detect.py Script]
19-
E(PyCoral Framework)
19+
E(ai-edge-litert)
2020
F[yolo26n_edgetpu.tflite]
21+
W[TPU Watchdog]
2122
end
2223
2324
subgraph Hardware
@@ -28,26 +29,35 @@ flowchart TD
2829
Aegis -->|stdin JSONL 'frame' event| Native_Process
2930
D -.->|Loads| F
3031
C -.->|Reads JPEG| D
32+
D <-->|Monitors| W
3133
D -->|Hands off tensors| E
3234
E <==>|USB 3.0 Inferencing| G
3335
Native_Process -->|stdout JSONL 'detections'| Aegis
36+
Native_Process -.->|stdout JSONL 'tpu_error'| Aegis
3437
```
3538

3639
### Flow Breakdown
3740

3841
1. **Deployment Phase**:
39-
The `deploy.sh` script executes during installation, hooking directly into your OS's package manager. It provisions essential C-libraries (`libusb`), native Google driver binaries (`libedgetpu`), and creates an isolated `python3 -m venv` sandbox securely.
42+
The OS-specific deployment scripts (`deploy-linux.sh`, `deploy-macos.sh`, `deploy.bat`) provision essential C-libraries (`libusb`), native Google driver binaries (`libedgetpu`), and create an isolated `python3 -m venv` sandbox securely.
43+
* **Dynamic Models:** Instead of tracking massive raw binary files in git, the deployment script dynamically downloads the `.tflite` compiled models directly from Google's master Edge TPU repository using `curl` / `Invoke-WebRequest`.
4044
2. **Inference Loop**:
4145
- The host system (Aegis-AI) continuously records frames and saves a snapshot to `/tmp/aegis_detection/` memory cache.
4246
- Using standard input (`stdin`), Aegis-AI sends a brief JSON control sequence instructing the Python watcher script (`detect.py`) to process the frame.
4347
- The Edge TPU fetches the tensor, performs native hardware execution using `libusb`, and instantly evaluates bounding box predictions without triggering CPU payload spikes.
4448
- Results are streamed synchronously over standard output (`stdout`) to Aegis-AI.
4549

50+
## Resilience & Auto-Recovery
51+
52+
The integration features a native **TPU Health Watchdog** built directly into `detect.py`:
53+
* **Hang Detection**: If the USB connection fails and the `ai-edge-litert` delegate locks up, the invocation thread will hard-timeout after 10 seconds. The skill emits a `invoke_timeout` error and exits, prompting Aegis-AI to autonomously restart the sidecar process.
54+
* **Stall Detection**: If the TPU thermally throttles and begins silently returning zero objects for 30 consecutive frames (despite functioning perfectly seconds prior), the watchdog emits a `stall` telemetry event back to Aegis-AI.
55+
4656
## Platform Differences
4757

48-
* **Linux**: Inherits Python dependencies explicitly from system-level tools via `apt-get` (due to Debian/Ubuntu `externally-managed-environment` guards). Uses the official Coral `apt` repositories.
49-
* **macOS (Apple Silicon)**: Uses the `feranick/libedgetpu` community fork to allow Edge TPU execution on ARM64 chips without relying on Rosetta 2.
50-
* **Windows**: Relies entirely on PowerShell bootstrapping and UAC elevation to quietly execute Google's `install.bat`.
58+
* **Linux**: Inherits Python dependencies securely and provisions Google's `libedgetpu1-max` driver via `apt-get` on Debian/Ubuntu systems. Uses `ai-edge-litert` to support modern Python (3.9 - 3.13) without requiring legacy `pycoral` or `pyenv` locking.
59+
* **macOS**: Fully supports Apple Silicon natively. Uses the `feranick/libedgetpu` community fork to allow Edge TPU execution on ARM64 chips without relying on Rosetta 2.
60+
* **Windows**: Relies on PowerShell bootstrapping and transparent UAC elevation logs to quietly execute Google's `install.bat`. Fallbacks to community wheels gracefully.
5161

5262
## Configuration Options
5363

0 commit comments

Comments
 (0)