Skip to content

Latest commit

 

History

History
180 lines (128 loc) · 5.06 KB

usage.md

File metadata and controls

180 lines (128 loc) · 5.06 KB

Usage

Basic usage

./speculos.py apps/btc.elf

The Nano S is the default model; the Nano X and Blue can be specified on the command-line:

./speculos.py --model nanox apps/nanox#btc#1.2#57272a0f.elf
./speculos.py --model blue --sdk 1.5 apps/blue#btc#1.5#00000000.elf

The last SDK version is automatically selected. However, a specific version be specified if the target app is not build against the last version of the SDK, thanks to the -k/--sdk argument. For instance, to launch an app built against the SDK 1.5 on the Nano S:

./speculos.py --sdk 1.5 --model nanos apps/btc.elf

Supported SDK values for the -k/--sdk argument are:

Nano S Nano X Blue
SDK 1.5, 1.6 1.2 1.5, blue-2.2.5

For more options, pass the -h or --help flag.

Keyboard control

  • The keyboard left and right arrow keys are used instead of the Nano buttons. The down arrow can also be used as a more convenient shortcut.
  • The Q key exits the application.

Display

Several display options are available through the --display parameter:

  • qt: default, requires a X server
  • headless: nothing is displayed
  • text: the UI is displayed in the console (handy on Windows)

These options can be used along --vnc-port which spawns a VNC server on the specified port. macOS users should also add --vnc-password <password> if using the built-in VNC client because unauthenticated sessions doesn't seem to be supported (issue #34).

Docker

A docker image is available on Docker Hub.

Run

From the root of the speculos project

docker run -it -v "$(pwd)"/apps:/speculos/apps \
-p 1234:1234 -p 40000:40000 -p 41000:41000 -p 42000:42000 \
ledgerhq/speculos --model nanos ./apps/btc.elf --sdk 1.6 --seed "secret" --display headless \
--apdu-port 40000 --vnc-port 41000 --button-port 42000

Debug

docker run -it -v "$(pwd)"/apps:/speculos/apps -p 1234:1234 -p 40000:40000 -p 41000:41000 -p 42000:42000 --entrypoint /bin/bash ledgerhq/speculos

docker-compose setup

docker-compose up [-d]

Default configuration is nanos / 1.6 / btc.elf / seed "secret"

Edit docker-compose.yml to configure port forwarding and environment variables that fit your needs.

Build

The following command-line can be used to create a docker image based on a local build:

docker build ./ -t speculos

Replace ledgerhq/speculos with speculos in the sections above to use this image.

Bitcoin Testnet app

Launch the Bitcoin Testnet app, which requires the Bitcoin app:

./speculos.py ./apps/btc-test.elf -l Bitcoin:./apps/btc.elf

Debug

Debug an app thanks to gdb:

./speculos.py -d apps/btc.elf &
./tools/debug.sh apps/btc.elf

Semihosting features can be used as an additional debug mechanism.

Clients

Clients can communicate with the emulated device using APDUs, as usual. Speculos embbeds a TCP server (listening on 127.0.0.1:9999) to forward APDUs to the target app.

ledgerctl (ledgerwallet)

ledgerwallet is a library to control Ledger devices, also available through the command ledgerctl (it can be installed thanks to pip:

pip3 install ledgerwallet

If the environment variables LEDGER_PROXY_ADDRESS and LEDGER_PROXY_PORT are set, the library tries to use the device emulated by Speculos. For instance, the following command-line sends the APDU e0 c4 00 00 00 (Bitcoin app APDU to get the version):

$ echo 'e0c4000000' | LEDGER_PROXY_ADDRESS=127.0.0.1 LEDGER_PROXY_PORT=9999 ledgerctl send -
13:37:35.096:apdu: > e0c4000000
13:37:35.099:apdu: < 1b3001030e0100039000
1b3001030e0100039000

blue-loader-python (ledgerblue)

Most clients relies on the blue-loader-python Python library which supports Speculos since release 0.1.24. This library can be installed through pip using the following command-line:

pip3 install ledgerblue

The usage is similar to ledgerctl:

$ ./speculos.py ./apps/btc.elf &
$ echo 'e0c4000000' | LEDGER_PROXY_ADDRESS=127.0.0.1 LEDGER_PROXY_PORT=9999 python3 -m ledgerblue.runScript --apdu
=> b'e0c4000000'
<= b'1b30010308010003'9000
<= Clear bytearray(b'\x1b0\x01\x03\x08\x01\x00\x03')

btchip-python

Use btchip-python without a real device:

PYTHONPATH=$(pwd) LEDGER_PROXY_ADDRESS=127.0.0.1 LEDGER_PROXY_PORT=9999 python tests/testMultisigArmory.py

Note: btchip-python relies on its own library to communicate with devices (physical or emulated) instead of ledgerblue to transmit APDUs.

ledger-live-common

./tools/ledger-live-http-proxy.py &
DEBUG_COMM_HTTP_PROXY=http://127.0.0.1:9998 ledger-live getAddress -c btc --path "m/49'/0'/0'/0/0" --derivationMode segwit