openbitdo/spec/protocol_spec.md

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