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: prepare v0.0.1-rc.4

Browse Source
This commit is contained in:
Brooklyn Halmstad
2026-03-07 15:51:21 -05:00
parent 86875075fc
commit da09094d3e
52 changed files with 1076 additions and 1234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
spec/alias_index.md
View File

@@ -1,9 +1,8 @@
# Alias Index
OpenBitdo uses a strict no-duplicate PID model in runtime and canonical spec tables.
These legacy names are preserved here as aliases only.
OpenBitdo keeps one canonical row per PID. Historical duplicate names are tracked here as aliases only.
| Alias PID Name | Canonical PID Name | PID (hex) | Note |
| --- | --- | --- | --- |
| `PID_Pro2_OLD` | `PID_Pro2` | `0x6003` | Legacy constant alias in 8BitDo source; runtime/spec use only `PID_Pro2`. |
| `PID_ASLGMouse` | `PID_Mouse` | `0x5205` | Alias constant maps to the same PID as `PID_Mouse`; runtime/spec use only `PID_Mouse`. |
| `PID_Pro2_OLD` | `PID_Pro2` | `0x6003` | Historical constant alias; runtime and specs use `PID_Pro2`. |
| `PID_ASLGMouse` | `PID_Mouse` | `0x5205` | Historical alias for the same canonical mouse PID. |

17
spec/device_name_catalog.md
View File

@@ -1,7 +1,14 @@
# Device Name Catalog
This catalog is the sanitized naming source of truth for OpenBitdo runtime/docs.
Canonical rows are unique by PID (no duplicates in this table).
This catalog is the canonical PID-to-name reference for OpenBitdo.
Use it when you need a stable display name for runtime UI, docs, packaging copy, or evidence review.
## How To Use This Catalog
- Match devices by `pid_hex` first.
- Treat `display_name_en` as the preferred user-facing label.
- Keep aliases out of new canonical rows; add them to the `aliases` column and the alias index instead.
- When confidence is low or the source is `internal-fallback`, treat the name as provisional until better evidence is collected.
| canonical_pid_name | pid_hex | display_name_en | protocol_family | name_source | source_confidence | aliases |
| --- | --- | --- | --- | --- | --- | --- |
@@ -64,5 +71,7 @@ Canonical rows are unique by PID (no duplicates in this table).
| PID_ASLGJP | 0x205a | Riviera Keyboard | JpHandshake | vendor-language-map | high | |
## Notes
- Name-source references are indexed in `/Users/brooklyn/data/8bitdo/cleanroom/process/device_name_sources.md`.
- Alias names are documented in `/Users/brooklyn/data/8bitdo/cleanroom/spec/alias_index.md` and intentionally excluded from canonical PID rows.
- Canonical rows are unique by PID. Do not duplicate a PID to reflect a marketing alias.
- Name-source evidence is indexed in `/Users/brooklyn/data/8bitdo/cleanroom/process/device_name_sources.md`.
- Alias names live in `/Users/brooklyn/data/8bitdo/cleanroom/spec/alias_index.md` and stay out of the primary PID rows unless they become the canonical public name.

153
spec/protocol_spec.md
View File

@@ -1,98 +1,93 @@
# 8BitDo Clean-Room Protocol Specification (Sanitized)
# OpenBitdo Protocol Overview
## Scope
This document defines a sanitized command and transport contract for a clean-room Rust implementation.
It is intentionally independent from reverse-engineered source code details and uses stable requirement IDs.
This document summarizes the sanitized protocol model used by the clean-room runtime.
## Wire Model
- Transport: HID-like reports
- Primary report width: 64 bytes (`Standard64`, `DInput`, `JpHandshake` families)
- Variable-length reports: allowed for boot/firmware phases
- Byte order: little-endian for multi-byte numeric fields
- HID-like command transport
- primary 64-byte reports for `Standard64`, `DInput`, and `JpHandshake`
- variable-length reports only where firmware or boot phases require them
- little-endian multi-byte numbers
## Protocol Families
- `Standard64`: standard 64-byte command and response flow
- `JpHandshake`: alternate handshake and version probing workflow
- `DInput`: command family used for mode and runtime profile operations
- `DS4Boot`: reserved boot mode for DS4-style update path
- `Unknown`: fallback for unknown devices
- `Standard64`
- `JpHandshake`
- `DInput`
- `DS4Boot`
- `Unknown`
## Safety Classes
- `SafeRead`: read-only operations
- `SafeWrite`: runtime settings/profile writes
- `UnsafeBoot`: bootloader transitions with brick risk
- `UnsafeFirmware`: firmware transfer/commit operations with brick risk
## Response Validation Contract
- Responses are validated per command against byte-pattern expectations from `command_matrix.csv`
- Validation outcomes: `Ok`, `Invalid`, `Malformed`
- Retry policy applies on `Malformed` or timeout responses
- `SafeRead`: diagnostics and metadata reads
- `SafeWrite`: profile, setting, or mapping writes
- `UnsafeBoot`: bootloader transitions
- `UnsafeFirmware`: firmware transfer and commit operations
## Response Validation
- every command validates against the registry table
- outcomes are `Ok`, `Invalid`, or `Malformed`
- retry logic applies on timeout or malformed data according to session policy
## 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.
- `Core`
- `JP108Dedicated`
- `Ultimate2Core`
- `Firmware`
- `CoreDiag`
- `ModeProfileRead`
- `FirmwarePreflight`
## 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.
## Support Model
## 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.
### Support Levels
## Device Support Levels
- `full`: command execution permitted for safe and unsafe operations (with user gates)
- `detect-only`: identification allowed; unsupported operations return `UnsupportedForPid`
- `full`
- `detect-only`
## 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.
### Support Tiers
## 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
- `full`: normal read, write, and gated unsafe paths
- `candidate-readonly`: safe-read diagnostics only
- `detect-only`: identify-only posture
## 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.
## Candidate Read-Only Policy
## Required Runtime Gating
Unsafe commands execute only when both conditions are true:
1. `--unsafe`
2. `--i-understand-brick-risk`
Read-only candidates may:
## Clean-Room Requirements Linkage
Implementation and tests must trace to IDs in `requirements.yaml`.
All public APIs and behavior are governed by `REQ-PROT-*`, `REQ-PID-*`, `REQ-SAFE-*`, and `REQ-TEST-*` IDs.
- identify themselves
- run allowed safe-read diagnostics
- perform family-appropriate read-only metadata checks
Read-only candidates may not:
- write mappings or profiles
- enter unsafe boot paths
- transfer firmware
Promotion to full support requires:
1. static evidence
2. runtime evidence
3. hardware evidence
## Feature Scopes
### JP108
- supported targets: `0x5209`, `0x520a`
- current mapping scope: `A`, `B`, `K1`-`K8`
### Ultimate 2
- supported targets: `0x6012`, `0x6013`
- current scope: mode, slot, slot config, core button map, and required analog handling
## Runtime Safety Rule
Unsafe commands are only allowed when the runtime has both:
1. unsafe mode enabled
2. explicit brick-risk acknowledgment