openbitdo/sdk

OpenBitdo SDK

OpenBitdo SDK includes:

• bitdo_proto: protocol/transport/session library
• bitdo_app_core: shared firmware-first workflow and policy layer
• bitdo_tui: Ratatui/Crossterm terminal app
• openbitdo: beginner-first launcher (openbitdo starts guided TUI)

Build

cargo build --workspace

Test

cargo test --workspace --all-targets

Guard

./scripts/cleanroom_guard.sh

Hardware smoke report

./scripts/run_hardware_smoke.sh

TUI app examples (openbitdo)

cargo run -p openbitdo -- --mock

CLI surface

• openbitdo [--mock]: interactive dashboard flow (mouse-primary, minimal keyboard).

Interactive behavior (openbitdo)

• dashboard starts with:
  • searchable device list (left)
  • quick actions (center)
  • persistent event panel (right)
• primary quick actions:
  • Refresh
  • Diagnose
  • Recommended Update
  • Edit Mapping (capability-gated)
  • Settings
  • Quit
• firmware transfer path:
  • preflight generation
  • explicit confirm/cancel action
  • updating progress and final result screen
• mapping editors are draft-first with:
  • apply
  • undo
  • reset
  • restore backup
• recovery lock behavior is preserved when rollback fails.

Headless library API

• headless automation remains available as a Rust API in bitdo_tui:
  • run_headless
  • RunLaunchOptions
  • HeadlessOutputMode
• openbitdo CLI does not expose a headless command surface.

Config schema (v2)

• persisted fields:
  • schema_version
  • advanced_mode
  • report_save_mode
  • device_filter_text
  • dashboard_layout_mode
  • last_panel_focus
• v1 files are read with compatibility defaults and normalized to v2 fields at load time.

Packaging

./scripts/package-linux.sh v0.0.1-rc.2 x86_64
./scripts/package-linux.sh v0.0.1-rc.2 aarch64
./scripts/package-macos.sh v0.0.1-rc.2 arm64 aarch64-apple-darwin

Packaging outputs use:

• openbitdo-<version>-<os>-<arch>.tar.gz
• openbitdo-<version>-<os>-<arch> standalone binary
• .sha256 checksum file for each artifact
• macOS arm64 additionally emits .pkg (unsigned/ad-hoc for RC)

Release Workflow

• CI checks remain in .github/workflows/ci.yml.
• Tag-based release workflow is in .github/workflows/release.yml.
• Release tags must originate from main.
• v0.0.1-rc.2 style tags publish GitHub pre-releases.
• Release notes are sourced from /Users/brooklyn/data/8bitdo/cleanroom/CHANGELOG.md.
• Package-manager publish runs only after release assets are published.

Public RC Gate

• No open GitHub issues with label release-blocker.
• Scope-completeness gate:
  • JP108 RC scope is dedicated mapping only (A/B/K1-K8).
  • Ultimate2 RC scope is expanded mapping for required fields only.
• Clean-tree requirement from /Users/brooklyn/data/8bitdo/cleanroom/RC_CHECKLIST.md must be satisfied before tagging.

Distribution Prep

• Homebrew install path for public RC:
  • brew tap bybrooklyn/openbitdo
  • brew install openbitdo
• Homebrew Core inclusion is not required for v0.0.1-rc.2.
• Homebrew formula scaffold: /Users/brooklyn/data/8bitdo/cleanroom/packaging/homebrew/Formula/openbitdo.rb
• Homebrew tap sync script (disabled by default): /Users/brooklyn/data/8bitdo/cleanroom/packaging/homebrew/sync_tap.sh
• Tap repository: bybrooklyn/homebrew-openbitdo
• AUR package sources:
  • /Users/brooklyn/data/8bitdo/cleanroom/packaging/aur/openbitdo-bin
• AUR package names:
  • openbitdo-bin
• Release metadata renderer:
  • /Users/brooklyn/data/8bitdo/cleanroom/packaging/scripts/render_release_metadata.sh
• AUR publish workflow:
  • /Users/brooklyn/data/8bitdo/cleanroom/.github/workflows/aur-publish.yml
  • gated by AUR_PUBLISH_ENABLED=1
• Homebrew publish path:
  • release.yml renders checksum-pinned formula and runs sync_tap.sh
  • gated by HOMEBREW_PUBLISH_ENABLED=1
• macOS .pkg caveat:
  • unsigned/ad-hoc is accepted for v0.0.1-rc.2
  • notarization required for v0.1.0

CI Gates

• required:
  • guard
  • test
  • tui-smoke-test
  • aur-validate
  • build-macos-arm64