mirror of
https://github.com/bybrooklyn/openbitdo.git
synced 2026-03-19 04:12:56 -04:00
Bootstrap OpenBitdo clean-room SDK and reliability milestone
This commit is contained in:
18
spec/command_matrix.csv
Normal file
18
spec/command_matrix.csv
Normal file
@@ -0,0 +1,18 @@
|
||||
command_id,safety_class,confidence,experimental_default,report_id,request_len,request_hex,expected_response,notes
|
||||
GetPid,SafeRead,confirmed,false,0x81,64,8105c100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02;byte1=0x05;byte4=0xC1,"Primary PID detection request"
|
||||
GetReportRevision,SafeRead,confirmed,false,0x81,64,81040001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02;byte1=0x04;byte5=0x01,"RR read preflight"
|
||||
GetMode,SafeRead,confirmed,false,0x81,64,81040501000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02;byte1=0x05,"Mode read"
|
||||
GetModeAlt,SafeRead,confirmed,false,0x81,64,81050800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02;byte1=0x05,"Alternate mode read"
|
||||
GetControllerVersion,SafeRead,confirmed,false,0x81,64,81042101000006000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02;byte1=0x22,"Controller version"
|
||||
GetSuperButton,SafeRead,inferred,true,0x81,64,81052100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02;byte1=0x05,"Super button capability"
|
||||
SetModeDInput,SafeWrite,confirmed,false,0x81,64,81050051020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02,"Mode write to DInput"
|
||||
Idle,SafeRead,confirmed,false,0x81,64,81040001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02,"Idle check"
|
||||
Version,SafeRead,confirmed,false,0x81,64,81042101000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte1=0x22,"Version check"
|
||||
ReadProfile,SafeRead,inferred,true,0x81,64,81060001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02,"Profile slot read (sanitized)"
|
||||
WriteProfile,SafeWrite,inferred,true,0x81,64,81070001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02,"Profile slot write (sanitized)"
|
||||
EnterBootloaderA,UnsafeBoot,confirmed,false,0x81,6,050050010000,none,"Boot stage A"
|
||||
EnterBootloaderB,UnsafeBoot,confirmed,false,0x81,6,005100000000,none,"Boot stage B"
|
||||
EnterBootloaderC,UnsafeBoot,confirmed,false,0x81,5,0050000000,none,"Boot stage C"
|
||||
ExitBootloader,UnsafeBoot,inferred,true,0x81,6,050051010000,none,"Boot exit (sanitized inferred)"
|
||||
FirmwareChunk,UnsafeFirmware,inferred,true,0x81,64,81100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02,"Firmware chunk transfer"
|
||||
FirmwareCommit,UnsafeFirmware,inferred,true,0x81,64,81110000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,byte0=0x02,"Firmware commit"
|
||||
|
60
spec/pid_matrix.csv
Normal file
60
spec/pid_matrix.csv
Normal file
@@ -0,0 +1,60 @@
|
||||
pid_name,pid_decimal,pid_hex,vid_decimal,vid_hex,support_level,protocol_family,notes
|
||||
PID_None,0,0x0,11720,0x2dc8,detect-only,Unknown,Sentinel value
|
||||
PID_IDLE,12553,0x3109,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_SN30Plus,24578,0x6002,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_USB_Ultimate,12544,0x3100,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_USB_Ultimate2,12549,0x3105,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_USB_UltimateClasses,12548,0x3104,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Xcloud,8448,0x2100,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Xcloud2,8449,0x2101,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_ArcadeStick,36890,0x901a,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Pro2,24579,0x6003,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Pro2_CY,24582,0x6006,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Pro2_OLD,24579,0x6003,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Pro2_Wired,12304,0x3010,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Ultimate_PC,12305,0x3011,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Ultimate2_4,12306,0x3012,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Ultimate2_4RR,12307,0x3013,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_UltimateBT,24583,0x6007,11720,0x2dc8,full,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_UltimateBTRR,12550,0x3106,11720,0x2dc8,full,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_JP,20992,0x5200,11720,0x2dc8,detect-only,JpHandshake,Baseline from sanitized dirty-room analysis
|
||||
PID_JPUSB,20993,0x5201,11720,0x2dc8,detect-only,JpHandshake,Baseline from sanitized dirty-room analysis
|
||||
PID_NUMPAD,20995,0x5203,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_NUMPADRR,20996,0x5204,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_QINGCHUN2,12554,0x310a,11720,0x2dc8,full,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_QINGCHUN2RR,12316,0x301c,11720,0x2dc8,full,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_Xinput,12555,0x310b,11720,0x2dc8,detect-only,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_Pro3,24585,0x6009,11720,0x2dc8,full,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_Pro3USB,24586,0x600a,11720,0x2dc8,full,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_Pro3DOCK,24589,0x600d,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_108JP,21001,0x5209,11720,0x2dc8,detect-only,JpHandshake,Baseline from sanitized dirty-room analysis
|
||||
PID_108JPUSB,21002,0x520a,11720,0x2dc8,detect-only,JpHandshake,Baseline from sanitized dirty-room analysis
|
||||
PID_XBOXJP,8232,0x2028,11720,0x2dc8,detect-only,JpHandshake,Baseline from sanitized dirty-room analysis
|
||||
PID_XBOXJPUSB,8238,0x202e,11720,0x2dc8,detect-only,JpHandshake,Baseline from sanitized dirty-room analysis
|
||||
PID_NGCDIY,22352,0x5750,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_NGCRR,36906,0x902a,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Ultimate2,24594,0x6012,11720,0x2dc8,full,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_Ultimate2RR,24595,0x6013,11720,0x2dc8,full,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_UltimateBT2,24591,0x600f,11720,0x2dc8,full,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_UltimateBT2RR,24593,0x6011,11720,0x2dc8,full,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_Mouse,20997,0x5205,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_MouseRR,20998,0x5206,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_SaturnRR,36907,0x902b,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_UltimateBT2C,12314,0x301a,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Lashen,12318,0x301e,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_HitBox,24587,0x600b,11720,0x2dc8,full,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_HitBoxRR,24588,0x600c,11720,0x2dc8,full,DInput,Baseline from sanitized dirty-room analysis
|
||||
PID_N64BT,12313,0x3019,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_N64,12292,0x3004,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_N64RR,36904,0x9028,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_XBOXUK,12326,0x3026,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_XBOXUKUSB,12327,0x3027,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_LashenX,8203,0x200b,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_68JP,8250,0x203a,11720,0x2dc8,detect-only,JpHandshake,Baseline from sanitized dirty-room analysis
|
||||
PID_68JPUSB,8265,0x2049,11720,0x2dc8,detect-only,JpHandshake,Baseline from sanitized dirty-room analysis
|
||||
PID_N64JoySticks,12321,0x3021,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_DoubleSuper,8254,0x203e,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Cube2RR,8278,0x2056,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_Cube2,8249,0x2039,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
PID_ASLGJP,8282,0x205a,11720,0x2dc8,detect-only,JpHandshake,Baseline from sanitized dirty-room analysis
|
||||
PID_ASLGMouse,20997,0x5205,11720,0x2dc8,detect-only,Standard64,Baseline from sanitized dirty-room analysis
|
||||
|
42
spec/protocol_spec.md
Normal file
42
spec/protocol_spec.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# 8BitDo Clean-Room Protocol Specification (Sanitized)
|
||||
|
||||
## 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.
|
||||
|
||||
## 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
|
||||
|
||||
## 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
|
||||
|
||||
## 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
|
||||
|
||||
## Device Support Levels
|
||||
- `full`: command execution permitted for safe and unsafe operations (with user gates)
|
||||
- `detect-only`: identification allowed; unsupported operations return `UnsupportedForPid`
|
||||
|
||||
## Required Runtime Gating
|
||||
Unsafe commands execute only when both conditions are true:
|
||||
1. `--unsafe`
|
||||
2. `--i-understand-brick-risk`
|
||||
|
||||
## 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.
|
||||
52
spec/requirements.yaml
Normal file
52
spec/requirements.yaml
Normal file
@@ -0,0 +1,52 @@
|
||||
metadata:
|
||||
version: 1
|
||||
owner: cleanroom-sdk
|
||||
status: draft
|
||||
requirements:
|
||||
- id: REQ-PROT-001
|
||||
title: CommandFrame model
|
||||
description: SDK shall expose CommandFrame with command id, payload, report id, and expected response metadata.
|
||||
acceptance: Unit tests validate frame creation for all CommandId values.
|
||||
- id: REQ-PROT-002
|
||||
title: Response validation
|
||||
description: SDK shall validate responses using command-specific byte signatures.
|
||||
acceptance: Parser rejection tests fail malformed responses and accept matching responses.
|
||||
- id: REQ-PROT-003
|
||||
title: Deterministic retries
|
||||
description: SDK shall retry reads on timeout/malformed responses using configured retry count.
|
||||
acceptance: Retry tests cover delayed and partial responses.
|
||||
- id: REQ-PROT-004
|
||||
title: Report width support
|
||||
description: SDK shall support both 64-byte reports and variable-length boot/firmware frames.
|
||||
acceptance: Encode/decode tests cover Report64 and variable report wrappers.
|
||||
|
||||
- id: REQ-PID-001
|
||||
title: PID registry completeness
|
||||
description: SDK shall include all PIDs present in sanitized pid_matrix.csv.
|
||||
acceptance: pid registry coverage test count equals pid_matrix.csv row count.
|
||||
- id: REQ-PID-002
|
||||
title: Support-level gating
|
||||
description: detect-only devices shall reject unsupported operations with UnsupportedForPid.
|
||||
acceptance: Capability gating tests verify rejection for unsafe operations on detect-only PIDs.
|
||||
|
||||
- id: REQ-SAFE-001
|
||||
title: Unsafe command dual confirmation
|
||||
description: Unsafe commands shall require both unsafe and brick-risk acknowledgement flags.
|
||||
acceptance: Boot safety tests verify command denial without both flags.
|
||||
- id: REQ-SAFE-002
|
||||
title: Experimental command policy
|
||||
description: Inferred commands shall require experimental mode.
|
||||
acceptance: Inferred-command tests verify denial without experimental flag.
|
||||
|
||||
- id: REQ-TEST-001
|
||||
title: Golden profile fixture
|
||||
description: SDK shall parse and serialize profile blobs compatible with golden binary fixture.
|
||||
acceptance: Profile serialization test round-trips fixture payload.
|
||||
- id: REQ-TEST-002
|
||||
title: CLI structured output
|
||||
description: CLI shall provide JSON output for automation.
|
||||
acceptance: CLI tests assert stable JSON keys and command responses.
|
||||
- id: REQ-TEST-003
|
||||
title: Clean-room guard
|
||||
description: CI shall fail if cleanroom/sdk references forbidden dirty-room locations or tokens.
|
||||
acceptance: cleanroom guard script is executed in CI and by integration test.
|
||||
Reference in New Issue
Block a user