# Troubleshooting

## The controller is not listed

1. Confirm the controller is powered on and in an active input mode. An
   8BitDo device shown by `lsusb` as **8BitDo IDLE** is not yet an evdev
   controller and cannot produce input events.
2. Connect it over USB or pair it through a supported receiver/Bluetooth mode.
3. Check kernel discovery with `ls -l /dev/input/event*` and `evtest`.
4. Reopen the app or switch Simulation Mode off in Settings.

The app only reads Linux evdev capability metadata. It does not send
undocumented commands or update controller firmware.

## Permission denied for input or virtual controller

Install the local udev rule:

```bash
bash scripts/setup-linux.sh
```

Then log out and back in so your new `8bitdo` group membership takes effect.
Settings → Diagnostics reports whether `/dev/uinput` is writable.

## Duplicate or missing game input

Do not enable live remapping until the virtual controller pipeline is active
and the physical input device is safely grabbed. Until then, keep remapping
disabled to retain direct physical-controller input.

## No battery or firmware details

Those details are optional Linux input properties and may not be exposed by
every controller mode. This application never queries undocumented 8BitDo
protocols to obtain them.

## App will not build

Install development dependencies:

```bash
bash scripts/dev-deps.sh
npm install
npm run tauri dev
```