bybrooklyn/openbitdo
1
0
Fork 0
mirror of https://github.com/bybrooklyn/openbitdo.git synced 2026-03-19 04:12:56 -04:00
Code Issues Packages Projects Releases Wiki Activity

release prep: rc.1 baseline and gating updates

Browse Source
This commit is contained in:
Brooklyn Halmstad
2026-03-02 15:54:55 -05:00
parent 97a42c8802
commit f43b2b24b6
168 changed files with 14708 additions and 982 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
spec/protocol_spec.md
View File

@@ -28,10 +28,66 @@ It is intentionally independent from reverse-engineered source code details and
- Validation outcomes: `Ok`, `Invalid`, `Malformed`
- Retry policy applies on `Malformed` or timeout responses
## Operation Groups
- `Core`: generic identify/mode/profile/boot/fallback commands
- `JP108Dedicated`: 108-key dedicated-button mapping + feature/voice operations
- `Ultimate2Core`: Ultimate2 mode/slot/core-map operations
- `Firmware`: device-scoped firmware enter/chunk/commit/exit operations
- `CoreDiag`: decompiler-first detect/diagnostic command subset for candidate-readonly PIDs
- `ModeProfileRead`: decompiler-first read-only mode/profile snapshot group for candidate-readonly PIDs
- `FirmwarePreflight`: decompiler-first firmware readiness metadata reads (no transfer enablement)
## JP108 Dedicated Support
- Supported targets: `0x5209` (`PID_108JP`), `0x520a` (`PID_108JPUSB`)
- First milestone mapping scope: `A`, `B`, `K1`-`K8`
- Additional controls in this group:
- feature flags read/write
- voice setting read/write
- Full 111-key matrix remap is explicitly out of scope for this milestone.
## Ultimate2 Core Support
- Supported targets: `0x6012` (`PID_Ultimate2`), `0x6013` (`PID_Ultimate2RR`)
- First milestone editable scope:
- current mode read/set
- current slot read
- slot config read/write
- core button map read/write
- Advanced subsystems (theme/sixaxis/deep macro editing) are intentionally hidden in this milestone.
## PID-Aware Command Gating
- Command availability is gated by:
1. safety class and runtime unsafe acknowledgements
2. capability flags
3. explicit PID allowlist from `command_matrix.csv:applies_to`
- `applies_to="*"` means globally available within existing safety/capability constraints.
## Device Support Levels
- `full`: command execution permitted for safe and unsafe operations (with user gates)
- `detect-only`: identification allowed; unsupported operations return `UnsupportedForPid`
## Support Tiers
- `full`: read/write/unsafe operations available according to existing safety gates.
- `candidate-readonly`: detect/diag safe reads are allowed per PID allowlist; safe writes and unsafe flows are blocked.
- `detect-only`: identify-only posture for unsupported or unknown PIDs.
## Candidate Read-Only Wave Policy
- Wave-1 and Wave-2 expansion PIDs are classified as `candidate-readonly`.
- Command policy for this tier:
- allow: detect/diag safe-read subset.
- allow: read-only mode/profile snapshot reads when family-appropriate.
- allow: firmware metadata/preflight reads only.
- deny: all safe-write operations.
- deny: all unsafe boot/firmware operations.
- Promotion from `candidate-readonly` to `full` requires 3-signal evidence:
1. static dossier coverage
2. runtime trace evidence
3. hardware read/write/readback confirmation
## Dossier Linkage
- Per-PID operation evidence is tracked in `spec/dossiers/**`.
- `command_matrix.csv:dossier_id` links command rows to sanitized dossier artifacts.
- `evidence_index.csv` maps PID to class-family anchors and operation groups.
## Required Runtime Gating
Unsafe commands execute only when both conditions are true:
1. `--unsafe`