Initial release of 8BitDo Control Center

Provide a Linux desktop controller configuration app with evdev input, uinput remapping, profiles, calibration, and reconnect recovery. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-21 12:18:10 -07:00
commit 6507f5f8b3
121 changed files with 15415 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,115 @@
+# 8BitDo Control Center
+
+A desktop configuration utility for 8BitDo Ultimate controllers on Linux. It reads the
+physical controller through **evdev**, runs input through a configurable transform
+pipeline (calibration, deadzones, response curves, remapping), and outputs a remapped
+virtual controller through **uinput** — without depending on any proprietary 8BitDo
+software or undocumented USB/firmware protocols.
+
+Built with [Tauri 2](https://tauri.app), React + TypeScript, Tailwind CSS, and Rust.
+
+> **Status:** Device discovery and read-only evdev input observation are implemented.
+> The virtual-controller output pipeline remains opt-in work in progress; until it is
+> enabled, the app never changes physical controller output.
+
+## Features (current)
+
+- Dark, light, and high-contrast themes
+- Profile management: create, rename, duplicate, delete, reset, import, export —
+  persisted as versioned JSON under `~/.config/8bitdo-control-center/profiles/`
+- Five built-in profiles (Default, FPS, Racing, Platformer, Custom)
+- Reusable, generic SVG controller diagram (front + rear views, clickable hotspots)
+- Button remapping (button/key/mouse/disabled, with turbo/toggle/hold/long-press/
+  double-tap modes)
+- Analog stick tuning: inner/outer/anti-deadzone, radial/axial mode, sensitivity,
+  inversion, circularity correction, smoothing, response curve presets, with a live
+  raw-vs-processed preview and a draggable pad to simulate input
+- Trigger tuning: deadzone, max activation, sensitivity, hair-trigger, digital mode,
+  inversion, response curve, with a live preview
+- Motion page (gyro + vibration controls, hidden when unsupported)
+- Input tester: live button/stick/trigger/gyro readout, poll rate estimate, and a
+  scrollable raw event log, drivable via a simulated controller
+- Device information page
+- Linux evdev discovery/capability probing and live raw input event streaming for
+  detected physical gamepads, with a simulated fallback for development
+- Explicit **Apply / Revert / Save Profile** controls with unsaved-changes warnings
+
+## Getting started (Linux Mint / Ubuntu-based)
+
+### Prerequisites
+
+```bash
+# Rust toolchain
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# Tauri Linux system dependencies
+sudo apt update
+sudo apt install -y libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1-dev \
+  libsoup-3.0-dev libgtk-3-dev librsvg2-dev libudev-dev \
+  libayatana-appindicator3-dev libssl-dev build-essential curl wget file pkg-config
+```
+
+Node.js 20+ and npm are also required.
+
+### Run in development
+
+```bash
+npm install
+npm run tauri dev
+```
+
+### Build a release bundle
+
+```bash
+npm run tauri build
+```
+
+## Project structure
+
+```
+src/                        React + TypeScript frontend
+├── components/
+│   ├── layout/              Sidebar, TopBar, AppLayout, PageShell
+│   ├── controller/           Generic SVG controller diagram + hotspots
+│   ├── inputs/                Slider, Toggle, Select, TextField, SimulatedStickPad
+│   ├── feedback/               Toasts, confirm dialog, unsaved-changes bar
+│   ├── visualizations/          Stick/trigger preview, event log
+│   └── common/                   Panel, Button, Badge, StatusDot
+├── pages/                     One component per sidebar destination
+├── hooks/                      useTheme, useController, useProfileInit, ...
+├── services/                    Tauri command wrappers + the mock controller backend
+├── stores/                       Zustand stores (controller, profile, settings, ui)
+├── types/                         Mirrors of the Rust profile/controller structs
+├── utils/                         Deadzone/curve math shared by every preview
+└── constants/                     Canonical control IDs, nav items
+
+src-tauri/                  Rust backend (Tauri 2)
+├── src/
+│   ├── commands/            Tauri command handlers (profiles, system)
+│   ├── profile_schema.rs     Versioned profile data model + migration
+│   ├── profile_manager.rs     Disk-backed profile CRUD
+│   └── default_profiles.rs     Built-in profile templates
+```
+
+## Roadmap
+
+1. **Phase 1 — Shell & scaffolding** *(current)* — app shell, theming, profile
+   management, controller visualization, and a simulated controller backend so every
+   page is usable before real hardware is wired up.
+2. **Phase 2 — Real device visibility** — `device_detection`/`evdev_reader`, capability
+   probing, live Device Information + Input Tester pages.
+3. **Phase 3 — Core remap pipeline** — `uinput_writer`, the real `input_transform`
+   deadzone/sensitivity pipeline, and Apply/Revert/Save wired to the live pipeline.
+4. **Phase 4 — Profiles in depth** — shortcut-combo/process-based profile switching,
+   the calibration wizard, and the custom curve point editor.
+5. **Phase 5 — Advanced mapping & polish** — macros, shift layers, motion/vibration
+   against real hardware, diagnostics/support bundle, udev rules + setup script,
+   packaging, and the full Rust test suite.
+
+## Permissions
+
+The app never needs to run as root. A later phase adds a `udev` rule and setup script
+that grant a dedicated group access to the controller's `evdev` nodes and `/dev/uinput`.
+
+See [Troubleshooting](docs/TROUBLESHOOTING.md) and the detailed
+[development roadmap](docs/ROADMAP.md) for permissions and hardware-mode guidance.