138 lines
4.2 KiB
Markdown
138 lines
4.2 KiB
Markdown
# Agents Guide: Custom Streamdeck
|
|
|
|
This file is a practical onboarding guide for coding agents and contributors working in this repository.
|
|
|
|
## Mission
|
|
|
|
Build and maintain a local-first Streamdeck platform:
|
|
|
|
- Raspberry Pi Pico emits button events over USB serial.
|
|
- FastAPI backend owns state, persistence, action execution, and plugin runtime.
|
|
- React frontend is the configuration UI.
|
|
- Optional Electron overlay displays active profile/folder context.
|
|
|
|
## Tech Stack
|
|
|
|
- Backend: Python, FastAPI, SQLite, pyserial, pynput
|
|
- Frontend: React 19 + TypeScript + Vite
|
|
- Overlay: Electron + TypeScript + Tailwind CLI
|
|
- Device firmware: MicroPython (`pico/main.py`)
|
|
|
|
## Repository Map
|
|
|
|
- `backend/`: API, runtime lifecycle, DB, action engine, serial + plugin services
|
|
- `frontend/`: Vite React app for deck configuration
|
|
- `overlay/`: transparent desktop overlay app
|
|
- `plugins/`: backend plugin modules (`PLUGIN` entrypoint contract)
|
|
- `pico/`: Pico firmware
|
|
- `tests/`: backend and plugin behavior tests
|
|
- `data/`: runtime SQLite data (gitignored)
|
|
|
|
## Fast Start Commands
|
|
|
|
From repo root:
|
|
|
|
```powershell
|
|
python -m pip install -r requirements.txt
|
|
cd frontend; npm install; cd ..
|
|
cd overlay; npm install; cd ..
|
|
```
|
|
|
|
Run backend:
|
|
|
|
```powershell
|
|
python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000
|
|
```
|
|
|
|
Frontend dev mode (separate shell):
|
|
|
|
```powershell
|
|
cd frontend
|
|
npm run dev
|
|
```
|
|
|
|
Frontend production-style build:
|
|
|
|
```powershell
|
|
cd frontend
|
|
npm run build
|
|
```
|
|
|
|
Run tests:
|
|
|
|
```powershell
|
|
pytest
|
|
```
|
|
|
|
Overlay local run:
|
|
|
|
```powershell
|
|
cd overlay
|
|
npm run dev
|
|
```
|
|
|
|
## Runtime Contracts To Respect
|
|
|
|
### Backend Runtime
|
|
|
|
- App entrypoint and route wiring live in `backend/main.py`.
|
|
- `Runtime` owns `db`, websocket manager, plugin manager, action engine, serial service, and app discovery.
|
|
- WebSocket event flow (`/ws`) is part of the product behavior; avoid breaking event names casually.
|
|
|
|
### Database and Layout Rules
|
|
|
|
- SQLite file defaults to `data/streamdeck.sqlite`.
|
|
- First profile/root folder define canonical physical button layout.
|
|
- Physical mapping updates are intentionally restricted to the first profile's root folder.
|
|
- Schema + defaults are managed in `backend/database.py`; preserve migration safety and default seeding.
|
|
|
|
### Action Engine
|
|
|
|
- Action dispatch is centralized in `backend/services/actions.py`.
|
|
- Built-ins include: `noop`, `key_combo`, `chain`, `app_launch`, `folder`, `folder_rotation`, `plugin`.
|
|
- `click_check` mode blocks action execution and is relied on by UI/testing flows.
|
|
|
|
### Plugin System
|
|
|
|
- Plugins load from `plugins/` through `backend/services/plugins.py`.
|
|
- Each plugin exports top-level `PLUGIN`.
|
|
- Expected plugin attributes: `name`, `desc`, `version`, `actions`.
|
|
- Optional hooks: `on_load(ctx)`, `on_event(ctx, event)`, `execute_action(ctx, action_id, config, event)`.
|
|
- Plugin failures should be isolated (disabled plugin, backend stays alive).
|
|
|
|
## Firmware Assumptions
|
|
|
|
- Pico reports JSON lines with fields: `button`, `pin`, `event`, `pressed`.
|
|
- Button indices are 1..10.
|
|
- Wiring order in firmware is authoritative: `28,27,26,22,21,20,18,19,17,16`.
|
|
|
|
## Change Workflow (Recommended)
|
|
|
|
1. Read impacted module(s) and existing tests.
|
|
2. Implement minimal, targeted change.
|
|
3. Add/update tests in `tests/` for behavior changes.
|
|
4. Run `pytest`.
|
|
5. If frontend/overlay touched, run corresponding build command(s).
|
|
6. Summarize user-visible impact and any migration or operational notes.
|
|
|
|
## Guardrails
|
|
|
|
- Keep backend behavior deterministic and explicit; avoid silent fallbacks unless already established.
|
|
- Do not commit runtime/generated directories:
|
|
- `data/`
|
|
- `frontend/dist/`, `frontend/node_modules/`
|
|
- `overlay/dist/`, `overlay/release/`, `overlay/node_modules/`
|
|
- Prefer extending existing action/plugin patterns over introducing parallel frameworks.
|
|
- Preserve local-first behavior: no cloud dependency required for baseline functionality.
|
|
|
|
## High-Value Test Targets
|
|
|
|
When changing core behavior, prioritize tests around:
|
|
|
|
- Pico event parsing (`parse_pico_line`)
|
|
- Profile/folder/button invariants in `Database`
|
|
- Physical layout synchronization and restrictions
|
|
- Action execution paths (`folder`, `folder_rotation`, `plugin`, `chain`)
|
|
- Plugin isolation and HTTP/device integration plugins
|
|
|