It can be puzzling when your BitBox02 doesn't connect to your computer, but don't worry! This guide provides clear, step-by-step solutions to get you back on track.

Start with these quick checks

Often, a simple fix is all you need. Let's cover the basics first:

• Remove the screen protector: If you still have the protective sticker on your BitBox02 screen, please remove it.
• Check device orientation: Ensure your BitBox02 is connected with its display facing upward. The BitBox logo should be on the same side as the screen.
• Use a direct USB connection: Plug your BitBox02 directly into a USB port on your computer.¹ Avoid using USB hubs, docking stations, or extension cables initially, as these can sometimes cause issues.
• Extension cable (if used): If you're using the USB-C extension cable that came with your BitBox02, make sure the small logo on the cable aligns with the BitBox02 display.
• Try different USB ports: Sometimes, a specific USB port can be faulty or have compatibility issues. Try connecting your BitBox02 to another USB port on your computer.
• Test on another device: If possible, try connecting your BitBox02 to a different computer or an Android smartphone (using the BitBoxApp for Android). This helps determine if the issue lies with the BitBox02 itself or your computer's setup.

See if your operating system detects the BitBox02

Even if the BitBoxApp doesn’t see your BitBox02, your computer's operating system might still recognize it. Here’s how to check:

macOS:

1. Open Terminal (you can find it using Spotlight search: Cmd + Space, then type "Terminal").
2. Copy and paste the following command, then press Enter:

ioreg -p IOUSB -l -w 0 | grep "BitBox"

3. If your BitBox02 is detected, you'll see an entry containing "BitBox" or "BitBox02".

Windows:

1. Open Device Manager (search for it in the Windows search bar).
2. Expand the Universal Serial Bus controllers section.
3. Look for entries named USB Composite Device.
4. Right-click on each USB Composite Device, select Properties, go to the Details tab, and choose Hardware Ids from the Property dropdown menu.
5. If the Hardware Ids include VID_03EB and PID_2403, your BitBox02 is detected by Windows.²

Linux:

1. Open a Terminal.
2. Run the command:

lsusb

3. Look for an entry containing "BitBox" or "03eb:2403".

Fix USB permissions on Linux

If your BitBox02 isn't detected on Linux, or if it's detected by lsusb but not by the BitBoxApp, you might need to adjust USB permissions.

The recommended way is to download and run the udev rules script from the official Shift Crypto GitHub repository. 

Alternatively, you can manually add the udev rules:

1. Open a Terminal.
2. Execute the following commands one by one:

printf "SUBSYSTEM==\"usb\", TAG+=\"uaccess\", TAG+=\"udev-acl\", SYMLINK+=\"bitbox02_%%n\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2403\"\n" | sudo tee /etc/udev/rules.d/53-hid-bitbox02.rules > /dev/null
printf "KERNEL==\"hidraw*\", SUBSYSTEM==\"hidraw\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2403\", TAG+=\"uaccess\", TAG+=\"udev-acl\", SYMLINK+=\"bitbox02_%%n\"\n" | sudo tee /etc/udev/rules.d/54-hid-bitbox02.rules > /dev/null
sudo udevadm control --reload
sudo udevadm trigger

3. If issues persist, add your user to the plugdev group (replace $USER with your actual username if the variable doesn't expand correctly, though it usually does):

sudo usermod -aG plugdev $USER

4. After applying these changes, unplug your BitBox02 and plug it back in. A system reboot might also be necessary for all changes to take effect.

Additional troubleshooting steps

If the problem continues, try these further solutions:

• Update conflicting software: Some applications, like Citrix Workspace, can interfere with USB device recognition. Check for updates for such software and install them.
• Check USB drivers (Windows): Outdated or corrupted USB drivers can cause problems on Windows.³ You can typically update these through the Device Manager (right-click the USB controller or device and select "Update driver").
• Temporarily disable security software: Antivirus or firewall programs can sometimes block new USB devices.⁴ Try temporarily disabling them to see if your BitBox02 connects. Remember to re-enable your security software afterward.

Still having trouble? Contact support

If you've worked through all these steps and your BitBox02 still won't connect, please reach out to BitBox Support.

To help them assist you quickly, please provide:

• The model of your computer and its operating system version.
• The version of the BitBoxApp you are using.
• A detailed description of the problem.
• The troubleshooting steps you’ve already tried and their results (e.g., whether the OS detects the device).

We're here to help you get your BitBox02 working smoothly!