mirror of
https://github.com/bybrooklyn/openbitdo.git
synced 2026-03-19 04:12:56 -04:00
94 lines
2.0 KiB
Markdown
94 lines
2.0 KiB
Markdown
# OpenBitdo Protocol Overview
|
|
|
|
This document summarizes the sanitized protocol model used by the clean-room runtime.
|
|
|
|
## Wire Model
|
|
|
|
- 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`
|
|
- `JpHandshake`
|
|
- `DInput`
|
|
- `DS4Boot`
|
|
- `Unknown`
|
|
|
|
## Safety Classes
|
|
|
|
- `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`
|
|
- `JP108Dedicated`
|
|
- `Ultimate2Core`
|
|
- `Firmware`
|
|
- `CoreDiag`
|
|
- `ModeProfileRead`
|
|
- `FirmwarePreflight`
|
|
|
|
## Support Model
|
|
|
|
### Support Levels
|
|
|
|
- `full`
|
|
- `detect-only`
|
|
|
|
### Support Tiers
|
|
|
|
- `full`: normal read, write, and gated unsafe paths
|
|
- `candidate-readonly`: safe-read diagnostics only
|
|
- `detect-only`: identify-only posture
|
|
|
|
## Candidate Read-Only Policy
|
|
|
|
Read-only candidates may:
|
|
|
|
- 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
|