python-keepkey

python-keepkey is the official Python library for communicating with a KeepKey device. It is used by firmware CI to drive emulator tests and can also communicate with a physical device. Coverage and transport must be identified in each run. You can also use it to write scripts, automate testing, or build tooling.

Repository: github.com/keepkey/python-keepkey

Installation


pip install keepkey

Or from source:


git clone https://github.com/keepkey/python-keepkey.git
cd python-keepkey
pip install -e .

Quick start


from keepkeylib.transport_hid import HidTransport
from keepkeylib.client import KeepKeyClient
 
# Connect to device
transport = HidTransport(HidTransport.enumerate()[0])
client = KeepKeyClient(transport)
 
# Get device features
features = client.get_features()
print(f"Firmware: {features.major_version}.{features.minor_version}.{features.patch_version}")
print(f"Label: {features.label}")
 
# Get a Bitcoin address
address = client.get_address('Bitcoin', [0x80000000 + 44, 0x80000000, 0x80000000, 0, 0])
print(f"BTC address: {address}")

CI test structure

The firmware CI organizes tests by chain section. Each test file is named test_msg_<operation>.py and lives under tests/ in the python-keepkey repo.

Section	Test file pattern
Core	`test_msg_wipedevice.py`, `test_msg_resetdevice.py`, `test_msg_changepin.py` …
Bitcoin	`test_msg_getaddress.py`, `test_msg_signtx.py`
Ethereum	`test_msg_ethereum_signtx.py`, `test_msg_ethereum_message.py`
THORChain	`test_msg_thorchain_signtx.py`
Solana	`test_msg_solana_getaddress.py`, `test_msg_solana_signtx.py`

Each test follows the same pattern:

Load a known test mnemonic into the device (debug-only operation)
Send the target message
Capture OLED frames (if running against emulator with DEBUG_LINK)
Verify the returned signature/address against the expected value

Running tests locally

Against a real device


cd python-keepkey
pytest tests/test_msg_signtx.py -v

The device must be unlocked. Tests that wipe or reset the device (test_msg_wipedevice.py) will destroy any existing seed — run these only on a test device with no real funds.

Against the emulator

Download the emulator artifact from a CI run or build it yourself:


# From keepkey-firmware repo
./scripts/build/docker/emulator/release.sh
 
# Set transport to emulator
export KEEPKEY_TRANSPORT=emulator
export KEEPKEY_EMULATOR_PATH=/path/to/emu.elf
 
pytest tests/ -v

The emulator supports DEBUG_LINK, which allows tests to inject button presses and capture OLED output programmatically. Selected catalog tests use this capture path. See Test Atlas for scope and limits.

Generating a test report

The CI’s generate-test-report job runs python-keepkey’s report generator against the test results:


python scripts/generate_report.py \
  --firmware-version 7.14.1 \
  --test-results results/ \
  --output keepkey-test-report.pdf

The report includes:

Pass/fail summary by section
Per-test description and OLED captures
Device info (label, firmware version, seed fingerprint)
All chain balances and addresses at time of test

Reports generated by CI are publicly available as artifacts from GitHub Actions .

Key message types

The library wraps the protobuf message protocol. Common messages:

Python method	Protobuf message	What it does
`client.get_features()`	`GetFeatures`	Device info, firmware version, features enabled
`client.get_address(coin, path)`	`GetAddress`	Derive and display an address
`client.ethereum_get_address(path)`	`EthereumGetAddress`	ETH address with EIP-55 checksum
`client.sign_tx(coin, inputs, outputs)`	`SignTx`	Sign a Bitcoin-type transaction
`client.ethereum_sign_tx(...)`	`EthereumSignTx`	Sign an ETH transaction
`client.sign_message(coin, path, msg)`	`SignMessage`	Sign arbitrary message with BTC key
`client.recover_device(...)`	`RecoveryDevice`	Initiate cipher-based seed recovery
`client.wipe_device()`	`WipeDevice`	Erase all keys and settings

Full protocol reference

The protobuf definitions live in device-protocol , pinned by the selected firmware and client. Use matching revisions; a definition alone does not prove that a firmware handler supports the message.


# In keepkey-firmware repo
ls deps/device-protocol/
# messages.proto          - core messages
# messages-bitcoin.proto  - Bitcoin + forks
# messages-ethereum.proto - Ethereum + ERC-20
# messages-cosmos.proto   - Cosmos/THORChain/Maya
# messages-solana.proto   - Solana
# ...

Firmware Overview — build from source, CI pipeline
Supported Chains — what operations each chain supports
Device Display Reference — what the OLED shows for each message type
REST API — higher-level HTTP wrapper (used by the desktop application)