{"id":7997,"library":"btchip-python","title":"Ledger Nano (Original) Python Library","description":"This library provides Python utilities to communicate with the *original* Ledger Nano hardware wallet over USB HID. It is specific to the first generation of Ledger devices and is largely superseded by `ledger-python` and `ledgerblue` for modern Ledger Nano S, X, and Stax devices. The current version is 0.1.32, with no active development since 2017, indicating an abandoned status.","status":"abandoned","version":"0.1.32","language":"en","source_language":"en","source_url":"https://github.com/LedgerHQ/btchip-python","tags":["hardware wallet","ledger","bitcoin","cryptocurrency","security","abandoned"],"install":[{"cmd":"pip install btchip-python","lang":"bash","label":"Install btchip-python"},{"cmd":"sudo apt-get update && sudo apt-get install -y libusb-1.0-0-dev libudev-dev\npip install hidapi","lang":"bash","label":"Linux: Install hidapi system dependencies (required for btchip-python)"},{"cmd":"brew install libusb\npip install hidapi","lang":"bash","label":"macOS: Install hidapi system dependencies (required for btchip-python)"}],"dependencies":[{"reason":"Required for USB HID communication with the Ledger device.","package":"hidapi","optional":false}],"imports":[{"note":"The communication backend for USB HID.","symbol":"DongleUSB","correct":"from btchip.btchipComm import DongleUSB"},{"note":"The main interface class for sending commands to the device.","symbol":"btchip","correct":"from btchip.btchip import btchip"}],"quickstart":{"code":"from btchip.btchipComm import DongleUSB\nfrom btchip.btchip import btchip\n\n# NOTE: This library is for the *original* Ledger Nano hardware wallet,\n# NOT for Ledger Nano S/X/Stax. For modern devices, use 'ledger-python'.\n#\n# Requires the original Ledger Nano to be connected and proper USB HID\n# permissions (e.g., udev rules on Linux).\n\ndongle = None\ntry:\n    # Initialize the USB dongle communication (timeout in ms)\n    # DongleUSB() without args tries to autodetect original Nano.\n    dongle = DongleUSB(timeout=5000)\n    \n    # Initialize the btchip interface with the dongle\n    interface = btchip(dongle)\n    \n    # Example: Get firmware version\n    firmware_version_response = interface.getFirmwareVersion()\n    # getFirmwareVersion returns a BtchipFirmware object, which __str__ outputs 'VERSION_STRING STATUS_WORD'\n    firmware_version = str(firmware_version_response).split(' ')[0] # Extract only the version string\n    \n    print(f\"Successfully connected to original Ledger Nano.\")\n    print(f\"Device Firmware Version: {firmware_version}\")\n    \nexcept Exception as e:\n    print(f\"Failed to connect to original Ledger Nano: {e}\")\n    print(\"\\nTroubleshooting:\")\n    print(\"- Ensure the original Ledger Nano is connected.\")\n    print(\"- On Linux, ensure appropriate udev rules are in place for Ledger HID devices.\")\n    print(\"- Verify 'hidapi' is correctly installed with its system dependencies.\")\n    print(\"- Remember: This library does NOT work with Ledger Nano S/X/Stax.\")\nfinally:\n    if dongle:\n        dongle.close()\n","lang":"python","description":"Demonstrates connecting to an original Ledger Nano and retrieving its firmware version. This example highlights the specific hardware compatibility and common setup requirements."},"warnings":[{"fix":"For Ledger Nano S/X/Stax, use the actively maintained `ledger-python` library (PyPI: `ledger-app-builder`) or `ledgerblue` for device communication.","message":"This library is designed exclusively for the *original* Ledger Nano hardware wallet. It is NOT compatible with modern Ledger Nano S, Nano X, or Stax devices. Using it with newer devices will result in 'No dongle found' errors or incorrect behavior.","severity":"breaking","affected_versions":"0.1.0 - 0.1.32"},{"fix":"Migrate to `ledger-python` or `ledgerblue` for any new development or maintenance involving Ledger hardware, especially for modern devices.","message":"The `btchip-python` library has been abandoned since its last update in 2017. It receives no further development or security updates. Its functionality is largely superseded by newer Ledger-supported libraries.","severity":"deprecated","affected_versions":"0.1.0 - 0.1.32"},{"fix":"Install `hidapi`'s system dependencies (e.g., `libusb-1.0-0-dev` on Debian/Ubuntu, `hidapi-devel` on Fedora, `libusb` on macOS) before `pip install hidapi`. On Linux, add udev rules for Ledger devices (e.g., `SUBSYSTEM==\"usb\", ATTR{idVendor}==\"2c97\", MODE=\"0660\", GROUP=\"plugdev\", TAG+=\"uaccess\"`).","message":"Successful device communication requires the `hidapi` library and proper system-level USB HID permissions, particularly on Linux (e.g., udev rules). Without these, the library will fail to detect the device.","severity":"gotcha","affected_versions":"0.1.0 - 0.1.32"},{"fix":"Access the string representation and parse it, e.g., `str(firmware_object).split(' ')[0]` to get just the version number.","message":"The `getFirmwareVersion()` method returns a `BtchipFirmware` object, which, when converted to a string, includes both the version and a status word (e.g., '0.1.0 9000'). Extracting only the version number requires parsing.","severity":"gotcha","affected_versions":"0.1.0 - 0.1.32"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed: `pip install btchip-python`. Verify the import statement matches `from btchip.btchipComm import DongleUSB`.","cause":"The `btchip-python` library is not installed, or the import path is incorrect.","error":"ImportError: cannot import name 'DongleUSB' from 'btchip.btchipComm'"},{"fix":"Connect the original Ledger Nano. On Linux, ensure `hidapi` system dependencies are installed and udev rules are correctly configured (refer to Ledger's setup guides for `ledgerblue` or `ledger-python` for applicable udev rule examples). Confirm you are using an *original* Ledger Nano, not a Nano S/X/Stax.","cause":"The original Ledger Nano is not connected, or USB HID permissions are insufficient for your user, or you are trying to use it with a modern Ledger device.","error":"btchip.btchipComm.DongleUSB.DongleNotFoundException: No dongle found"},{"fix":"Ensure `libusb` (and `libudev-dev` on Linux) are installed via your system's package manager, then reinstall `hidapi` (`pip install --no-cache-dir --force-reinstall hidapi`). Confirm udev rules for Ledger devices are correctly applied on Linux and that your user is part of the `plugdev` group.","cause":"Similar to 'No dongle found', this indicates `hidapi` could not access the device, often due to missing `libusb` or insufficient permissions.","error":"hidapi.hid.HIDException: failed to open device"}]}