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

68
process/add_device_guide.md Normal file
View File

@@ -0,0 +1,68 @@
# Add Device Support (Hardcoded Path)
This guide keeps device support simple and explicit: everything is added directly in Rust code.
## 1) Add/verify PID in hardcoded registry
File:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/crates/bitdo_proto/src/pid_registry_table.rs`
Add a `PidRegistryRow` with:
- `name`
- `pid`
- `support_level`
- `support_tier`
- `protocol_family`
## 2) Update capability policy
File:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/crates/bitdo_proto/src/registry.rs`
Update `default_capability_for(...)` and support-tier PID lists so capability flags match evidence.
## 3) Add/verify command declarations
File:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/crates/bitdo_proto/src/command_registry_table.rs`
Add/verify command rows:
- `id`
- `safety_class`
- `confidence`
- `experimental_default`
- `report_id`
- `request`
- `expected_response`
- `applies_to`
- `operation_group`
## 4) Confirm runtime policy
Runtime policy is derived in code (not scripts):
- `confirmed` -> enabled by default
- inferred `SafeRead` -> experimental-gated
- inferred `SafeWrite`/unsafe -> blocked until confirmed
File:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/crates/bitdo_proto/src/registry.rs`
## 5) Update candidate gating allowlists
File:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/crates/bitdo_proto/src/session.rs`
Update `is_command_allowed_for_candidate_pid(...)` so detect/diag behavior for the new PID is explicit.
## 6) Keep spec artifacts in sync
Files:
- `/Users/brooklyn/data/8bitdo/cleanroom/spec/pid_matrix.csv`
- `/Users/brooklyn/data/8bitdo/cleanroom/spec/command_matrix.csv`
- `/Users/brooklyn/data/8bitdo/cleanroom/spec/evidence_index.csv`
- `/Users/brooklyn/data/8bitdo/cleanroom/spec/dossiers/...`
## 7) Add tests
- Extend candidate gating tests:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/tests/candidate_readonly_gating.rs`
- Extend runtime policy tests:
- `/Users/brooklyn/data/8bitdo/cleanroom/sdk/tests/runtime_policy.rs`
## 8) Validation
From `/Users/brooklyn/data/8bitdo/cleanroom/sdk`:
- `cargo test --workspace --all-targets`
- `./scripts/cleanroom_guard.sh`

17
process/commenting_standard.md Normal file
View File

@@ -0,0 +1,17 @@
# OpenBitdo Commenting Standard
This project prefers concise, high-context comments.
## Required Comment Zones
- Command gating order and rationale (`bitdo_proto::session`).
- Support-tier decisions and promotion boundaries (`candidate-readonly` vs `full`).
- Unsafe/firmware blocking rules and brick-risk protections.
- Retry/fallback behavior where multiple command paths exist.
- State-machine transitions in TUI/app-core flows when transitions are non-obvious.
## Avoid
- Trivial comments that restate code syntax.
- Comment blocks that drift from behavior and are not maintained.
## Rule of Thumb
If someone adding a new device could misread a policy or safety boundary, comment it.

30
process/community_evidence_intake.md Normal file
View File

@@ -0,0 +1,30 @@
# Community Evidence Intake
## Purpose
Collect hardware and protocol evidence from the community in a clean-room-safe format.
## Submission Requirements
Every report must include:
- Device name
- VID/PID (`0xVVVV:0xPPPP`)
- Firmware version shown by official software/device
- Operation attempted
- Sanitized request/response shape description
- Reproducibility notes (steps, OS, transport mode)
## Prohibited Content
- Raw copied decompiled code.
- Vendor source snippets.
- Binary dumps with proprietary content not required for protocol structure.
## Acceptance Levels
- `intake`: report received, unverified.
- `triaged`: mapped to a PID/operation group and requirement IDs.
- `accepted`: converted into sanitized dossier/spec updates.
## Maintainer Processing
1. Validate report format.
2. Cross-reference PID with `spec/pid_matrix.csv`.
3. Create/update `spec/dossiers/<pid_hex>/*.toml`.
4. Update `spec/evidence_index.csv` and command/pid matrices.
5. Keep device as `candidate-readonly` until full 3-signal promotion gate is met.

33
process/device_name_sources.md Normal file
View File

@@ -0,0 +1,33 @@
# Device Name Sources
This index lists sanitized naming sources used to build `/Users/brooklyn/data/8bitdo/cleanroom/spec/device_name_catalog.md`.
## Primary dirty-room references
- `DR-1`: Decompiled PID constants table (`VIDPID`) in `/Users/brooklyn/data/8bitdo/decompiled_dll/8BitDo_Ultimate_Software_V2.decompiled.cs` around line 194289.
- `DR-2`: Decompiled device name resolver (`getName()`) in `/Users/brooklyn/data/8bitdo/decompiled_dll/8BitDo_Ultimate_Software_V2.decompiled.cs` around line 12249.
- `DR-3`: Decompiled language map (`LanguageTools`) in `/Users/brooklyn/data/8bitdo/decompiled_dll/8BitDo_Ultimate_Software_V2.decompiled.cs` around line 206277.
## Official 8BitDo web cross-check references
- `WEB-1`: [8BitDo product catalog](https://www.8bitdo.com/#Products)
- `WEB-2`: [Ultimate 2 Wireless Controller](https://www.8bitdo.com/ultimate-2-wireless-controller/)
- `WEB-3`: [Ultimate 2 Bluetooth Controller](https://www.8bitdo.com/ultimate-2-bluetooth-controller/)
- `WEB-4`: [Ultimate 2C Wireless Controller](https://www.8bitdo.com/ultimate-2c-wireless-controller/)
- `WEB-5`: [Ultimate 2C Bluetooth Controller](https://www.8bitdo.com/ultimate-2c-bluetooth-controller/)
- `WEB-6`: [Pro 2 Bluetooth Controller](https://www.8bitdo.com/pro2/)
- `WEB-7`: [Retro 108 Mechanical Keyboard](https://www.8bitdo.com/retro-108-mechanical-keyboard/)
- `WEB-8`: [Retro 87 Mechanical Keyboard - Xbox Edition](https://www.8bitdo.com/retro-87-mechanical-keyboard-xbox/)
- `WEB-9`: [Retro R8 Mouse - Xbox Edition](https://www.8bitdo.com/retro-r8-mouse-xbox/)
- `WEB-10`: [Arcade Controller](https://www.8bitdo.com/arcade-controller/)
- `WEB-11`: [64 Bluetooth Controller](https://www.8bitdo.com/64-controller/)
- `WEB-12`: [Retro Mechanical Keyboard N Edition](https://www.8bitdo.com/retro-mechanical-keyboard/)
## Confidence policy
- `high`: direct match in `DR-2/DR-3` and/or product page exact-name match.
- `medium`: strong inferred match from product family naming with at least one source anchor.
- `low`: internal fallback name because no confident public marketing name was found.
## Low-confidence naming convention
- Canonical wording for low-confidence rows is:
- `Unconfirmed Internal Device (PID_*)`
- `Unconfirmed Variant Name (PID_*)`
- `Unconfirmed Interface Name (PID_*)`

60
process/dirtyroom_collection_playbook.md Normal file
View File

@@ -0,0 +1,60 @@
# Dirty-Room Collection Playbook (Decompiler-First Expansion)
## Goal
Create sanitized, requirement-linked evidence that expands device detect/diagnostics support without contaminating clean-room implementation.
## Scope of This Wave
- Evidence source: decompiler/static-only.
- Target: Wave 2 +12 popularity cohort (plus previously tracked candidate-readonly set).
- Promotion policy: no new `full` promotions in this wave.
- Output artifacts: `spec/dossiers/**`, `spec/evidence_index.csv`, updated `spec/*.csv`, updated `requirements.yaml`.
## Allowed Dirty-Room Inputs
- `/Users/brooklyn/data/8bitdo/decompiled_dll/8BitDo_Ultimate_Software_V2.decompiled.cs`
- `/Users/brooklyn/data/8bitdo/decompiled/*.cs`
- `/Users/brooklyn/data/8bitdo/decompiled_autoupdate/*.cs`
- Existing dirty-room transcript files under `/Users/brooklyn/data/8bitdo/`
## Required Sanitization Rules
- Do not copy raw vendor/decompiled code snippets into clean artifacts.
- Record only sanitized structure-level findings:
- command intent
- request/response byte-shape
- validator expectations
- gating/policy notes
- Use requirement IDs only (`REQ-DR-*`, `REQ-PROM-*`, `REQ-COMM-*`, `REQ-GH-*`).
## Dossier Workflow
1. Pick PID and operation group.
2. Collect static evidence anchors (class/function names and behavior summaries).
3. Derive sanitized command mapping and validation expectations.
4. Write TOML dossier in `spec/dossiers/<pid_hex>/<operation_group>.toml`.
5. Link dossier ID into `spec/command_matrix.csv` (`dossier_id` column).
6. Update `spec/evidence_index.csv`.
7. Ensure each Wave 2 PID has all three required dossier files:
- `core_diag.toml`
- `mode_or_profile_read.toml`
- `firmware_preflight.toml`
## Authoring Approach (No Helper Scripts)
- Dossiers and matrix updates are maintained directly in repository source files.
- `spec/evidence_index.csv` is updated manually with deterministic ordering.
- Validation is performed through normal repository review plus workspace tests.
## Confidence Rules
- `confirmed`: requires static + runtime + hardware confirmation (not achievable in this wave).
- `inferred`: static-only or partial confidence.
- For this wave, new entries should remain `inferred` unless already confirmed historically.
## Promotion Gate
A device can move from `candidate-readonly` to `full` only when all three are true:
1. static evidence complete
2. runtime trace evidence complete
3. hardware read/write/readback complete
## Review Checklist
- Dossier contains required fields from schema.
- Requirement linkage is explicit.
- No raw decompiled text/snippets are present.
- `support_tier` remains `candidate-readonly` for new no-hardware devices.
- Runtime and hardware placeholders are populated with concrete promotion evidence tasks.

56
process/dirtyroom_dossier_schema.md Normal file
View File

@@ -0,0 +1,56 @@
# Dirty-Room Dossier Schema
Each dossier file is TOML and must include these fields.
## Required Fields
- `dossier_id`: stable identifier, e.g. `DOS-5200-CORE`.
- `pid_hex`: target PID in hex (`0xNNNN`).
- `operation_group`: logical grouping (`CoreDiag`, `ModeProfileRead`, `FirmwarePreflight`, etc).
- `command_id`: array of command IDs scoped by this dossier.
- `request_shape`: sanitized request structure summary.
- `response_shape`: sanitized response structure summary.
- `validator_rules`: array of response validation constraints.
- `retry_behavior`: retry and timeout behavior summary.
- `failure_signatures`: array of known failure signatures.
- `evidence_source`: `static` for this wave.
- `confidence`: `inferred` or `confirmed`.
- `requirement_ids`: array of linked requirement IDs.
- `state_machine`: table with `pre_state`, `action`, `post_state`, and `invalid_transitions`.
- `runtime_placeholder`: table with `required` and `evidence_needed`.
- `hardware_placeholder`: table with `required` and `evidence_needed`.
## Optional Fields
- `class_family`: static class-family grouping hints.
- `notes`: additional sanitized context.
## Example
```toml
dossier_id = "DOS-5200-CORE"
pid_hex = "0x5200"
operation_group = "CoreDiag"
command_id = ["GetPid", "GetReportRevision", "GetControllerVersion", "Version", "Idle"]
request_shape = "64-byte HID report, command byte in report[1], PID-specific gating outside payload"
response_shape = "short status header plus optional payload bytes"
validator_rules = ["byte0 == 0x02", "response length >= 4"]
retry_behavior = "retry up to configured max attempts on timeout/malformed response"
failure_signatures = ["timeout", "malformed response", "unsupported command for pid"]
evidence_source = "static"
confidence = "inferred"
requirement_ids = ["REQ-DR-001", "REQ-PROM-001", "REQ-PID-002"]
class_family = "JP/Handshake path"
notes = "candidate-readonly in this wave"
[state_machine]
pre_state = "DeviceConnected"
action = "Run core diagnostics reads"
post_state = "DeviceIdentified"
invalid_transitions = ["NoDevice", "TransportClosed", "BootloaderOnly"]
[runtime_placeholder]
required = true
evidence_needed = ["runtime request/response captures", "error signature examples"]
[hardware_placeholder]
required = true
evidence_needed = ["physical read validation", "repeatability checks"]
```

50
process/dirtyroom_evidence_backlog.md Normal file
View File

@@ -0,0 +1,50 @@
# Dirty-Room Evidence Backlog
## Purpose
Track future dirty-room evidence work for protocol expansion in a structured way, so new functionality can be translated into sanitized clean-room specs without contaminating implementation code.
## Clean-Room Boundaries
- Dirty-room analysis may use approved evidence sources.
- Clean implementation must consume only sanitized artifacts in `spec/` and approved harness data.
- No raw dirty-room snippets, copied code, or direct decompiled fragments may be carried into clean implementation files.
## Prioritized Backlog
1. Wave-2 candidate-readonly expansion (decompiler-first):
- Popularity +12 PIDs:
- `0x3100`, `0x3105`, `0x2100`, `0x2101`, `0x901a`, `0x6006`
- `0x5203`, `0x5204`, `0x301a`, `0x9028`, `0x3026`, `0x3027`
- Deliverable posture: detect/diag-only (`candidate-readonly`), no firmware transfer/write promotion.
2. Wave-1 candidate-readonly follow-through:
- Primary 14 PIDs:
- `0x6002`, `0x6003`, `0x3010`, `0x3011`, `0x3012`, `0x3013`
- `0x5200`, `0x5201`, `0x203a`, `0x2049`, `0x2028`, `0x202e`
- `0x3004`, `0x3019`
- Stretch PIDs:
- `0x3021`, `0x2039`, `0x2056`, `0x5205`, `0x5206`
- Deliverable posture: stay candidate-readonly until runtime and hardware evidence is accepted.
3. JP108 deeper mapping coverage:
- Expand dedicated key mapping confirmation beyond the current A/B/K1-K8 baseline.
- Confirm feature and voice command behavior with stronger request/response confidence.
4. Ultimate2 advanced paths:
- Expand confidence for advanced slot/config interactions and additional profile behaviors.
- Confirm edge cases for mode transitions and per-slot persistence.
5. Firmware trace confidence:
- Increase confidence for bootloader enter/chunk/commit/exit behavior across supported target variants.
- Capture and sanitize additional failure and recovery traces.
## Required Sanitized Outputs
- Update `spec/protocol_spec.md` for any newly confirmed operation groups or behavior rules.
- Update `spec/requirements.yaml` with new stable requirement IDs.
- Update `spec/command_matrix.csv` and `spec/pid_matrix.csv` as evidence confidence changes.
- Add or refresh sanitized harness fixtures under `harness/golden/` for replay and regression tests.
## Review Checklist Before Clean Implementation
- Sanitized evidence is traceable to requirement IDs.
- Command confidence levels are explicit (`confirmed` vs `inferred`).
- PID capability changes are reflected in matrices.
- No raw-source text is present in clean implementation artifacts.

6
process/release_scope_gate.toml Normal file
View File

@@ -0,0 +1,6 @@
[rc_scope]
# Set to true once full 108-key mapping coverage is implemented and validated.
jp108_full_keyboard_mapping = false
# Set to true once expanded Ultimate2 mapping coverage is implemented and validated.
ultimate2_expanded_mapping = false

23
process/wave1_baseline.md Normal file
View File

@@ -0,0 +1,23 @@
# Wave 1 Baseline Snapshot
Generated: 2026-02-28
## Hardware Access Baseline
- Available hardware lines: JP108 + Ultimate2.
- Exact attached PID variants: pending local identify run on connected hardware.
- Temporary lab fixture defaults remain:
- JP108: `0x5209`
- Ultimate2: `0x6012`
## Required Next Verification Step
Run identify flow with connected hardware and confirm fixture PIDs:
1. `cargo test --workspace --test hardware_smoke -- --ignored --exact hardware_smoke_detect_devices`
2. `./scripts/run_hardware_smoke.sh` with `BITDO_REQUIRED_SUITE=108jp`
3. `./scripts/run_hardware_smoke.sh` with `BITDO_REQUIRED_SUITE=ultimate2`
If detected variants differ, update `harness/lab/device_lab.yaml` fixture PIDs immediately.
## Support Baseline
- Existing `full` paths: JP108/Ultimate2 and previously confirmed families.
- New expansion wave devices remain `candidate-readonly` (detect/diag only).
- No new firmware/write enablement for no-hardware targets.

23
process/wave1_results.md Normal file
View File

@@ -0,0 +1,23 @@
# Wave 1 Results (Template)
Generated: 2026-02-28
## Summary
- Primary target PIDs processed: 14
- Stretch target PIDs processed: TBD
- New `full` promotions: 0 (expected in decompiler-only wave)
## Deliverables
- Dossiers created: `spec/dossiers/**`
- Evidence index updated: `spec/evidence_index.csv`
- Matrices updated: `spec/pid_matrix.csv`, `spec/command_matrix.csv`
- Requirements updated: `spec/requirements.yaml`
## Validation
- `cargo test --workspace --all-targets`: pending
- `./scripts/cleanroom_guard.sh`: pending
- Detect/diag targeted tests: pending
## Follow-Up
- Collect runtime traces for candidate-readonly devices.
- Run hardware confirmation on each candidate before promotion to `full`.

32
process/wave2_baseline.md Normal file
View File

@@ -0,0 +1,32 @@
# Wave 2 Baseline (Frozen)
## Snapshot Date
- 2026-03-01
## Pre-Wave Counts (Frozen)
- `spec/pid_matrix.csv` rows: 59
- Support tier counts (pre-wave):
- `full`: 14
- `candidate-readonly`: 15
- `detect-only`: 30
- `spec/command_matrix.csv` rows (pre-wave): 37
## Hardware Reality (Current)
- Available fixtures: JP108 line and Ultimate2 line only.
- Non-owned devices must remain `candidate-readonly` until strict promotion signals are complete.
## Required Checks Baseline
Branch protection for `main` must require:
- `guard`
- `aur-validate`
- `tui-smoke-test`
- `build-macos-arm64`
- `test`
- `hardware-108jp`
- `hardware-ultimate2`
## Promotion Policy
Promotion from `candidate-readonly` to `full` requires all 3 signals:
1. static dossier evidence,
2. runtime sanitized traces,
3. hardware read/write/readback confirmation.

22
process/wave2_pid_scorecard.md Normal file
View File

@@ -0,0 +1,22 @@
# Wave 2 PID Scorecard
Legend:
- Static: dossier + matrix linkage complete.
- Runtime: sanitized runtime traces accepted.
- Hardware: read/write/readback confirmed on owned fixture.
- Gate: promotion blocker status.
| PID | Device | Tier | Static | Runtime | Hardware | Gate |
|---|---|---|---|---|---|---|
| `0x3100` | PID_USB_Ultimate | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x3105` | PID_USB_Ultimate2 | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x2100` | PID_Xcloud | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x2101` | PID_Xcloud2 | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x901a` | PID_ArcadeStick | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x6006` | PID_Pro2_CY | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x5203` | PID_NUMPAD | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x5204` | PID_NUMPADRR | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x301a` | PID_UltimateBT2C | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x9028` | PID_N64RR | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x3026` | PID_XBOXUK | candidate-readonly | yes | no | no | blocked/no_runtime |
| `0x3027` | PID_XBOXUKUSB | candidate-readonly | yes | no | no | blocked/no_runtime |

23
process/wave2_results.md Normal file
View File

@@ -0,0 +1,23 @@
# Wave 2 Results
## Scope
- Expansion cohort: 12 additional popularity-first PIDs.
- Evidence mode: static/decompiler-only.
- Support result: all 12 moved to `candidate-readonly` with detect/diag-only behavior.
## Delivered
1. Manual, source-controlled dossier and matrix updates (no script-generated artifacts).
2. Wave 2 dossier set (`core_diag`, `mode_or_profile_read`, `firmware_preflight`) for each of 12 PIDs.
3. `pid_matrix.csv` updated with Wave 2 candidate-readonly tiering.
4. `command_matrix.csv` updated with Wave 2 dossier-linked rows and explicit promotion gates.
5. `evidence_index.csv` updated from current candidate-readonly set.
6. Governance verification completed for variables, labels, and required checks.
## Deferred
- Runtime trace evidence for Wave 2 cohort.
- Hardware read/write/readback confirmation for Wave 2 cohort.
- Any promotion to `full` for Wave 2 cohort.
## Exit Status
- Wave 2 static-only deliverables: complete.
- Promotion status: blocked pending runtime + hardware signals.

38
process/wave2_runtime_intake.md Normal file
View File

@@ -0,0 +1,38 @@
# Wave 2 Runtime/Hardware Intake (Prepared, Deferred)
## Purpose
Define exactly what sanitized runtime/hardware evidence is needed to move Wave 2 devices beyond static-only dossiers.
## Required Submission Data
Every submission must include:
1. VID/PID in hex.
2. Firmware version.
3. Operation attempted.
4. Sanitized request structure.
5. Sanitized response structure.
6. Reproducibility notes (OS, transport, retries, success/failure rate).
## Sanitization Rules
Allowed content:
- byte-layout summaries,
- command/response shape descriptions,
- validation predicates,
- timing/retry observations.
Forbidden content:
- raw decompiled code snippets,
- copied vendor constants blocks,
- copied source fragments from official binaries/tools.
## Evidence Acceptance Checklist
1. VID/PID and firmware fields are present.
2. Request/response structure is sanitized and technically complete.
3. Failure signatures are mapped to stable categories (`timeout`, `malformed`, `unsupported`, `invalid_signature`).
4. Repro steps are clear enough for independent rerun.
5. No forbidden raw-source content appears.
## Promotion Readiness Mapping
A PID is promotion-eligible only when all are true:
1. Static dossiers complete.
2. Runtime traces accepted from at least 2 independent runs.
3. Hardware read/write/readback validation passes on owned fixture(s).