Trezor Firmware

https://docs.trezor.io/trezor-firmware/
Admin
Trezor Firmware is a monorepo containing various interconnected projects that together form the...
Tokens:93,842
Snippets:1,314
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Basic Trezor Library

Source: https://docs.trezor.io/trezor-firmware/python/trezorlib.html

Install the core trezor library using pip. This is the standard installation method for most users.

```bash
pip3 install trezor
```

--------------------------------

### Install Trezor Library with Ethereum Support

Source: https://docs.trezor.io/trezor-firmware/python/trezorlib.html

Install the trezor library with extra packages needed for Ethereum signing from the command line.

```bash
pip3 install trezor[ethereum]
```

--------------------------------

### Install Trezor Library with All Optional Features

Source: https://docs.trezor.io/trezor-firmware/python/trezorlib.html

Install the trezor library with all common optional features, including Bluetooth, HIDAPI, Ethereum, and Stellar support.

```bash
pip3 install trezor[ble,hidapi,ethereum,stellar]
```

--------------------------------

### Install Dependencies on OpenSUSE

Source: https://docs.trezor.io/trezor-firmware/core/build/emulator.html

Installs the necessary packages for building the Trezor firmware on OpenSUSE systems.

```bash
sudo zypper install scons libSDL2-devel libSDL2_image-devel
```

--------------------------------

### Install Trezor Library with Stellar Support

Source: https://docs.trezor.io/trezor-firmware/python/trezorlib.html

Install the trezor library with additional packages required for Stellar signing from the command line.

```bash
pip3 install trezor[stellar]
```

--------------------------------

### Build Firmware with Debug Console

Source: https://docs.trezor.io/trezor-firmware/print.html

Example of building the firmware with the VCP debug console enabled to output logs.

```bash
make build_firmware TREZOR_MODEL=T3W1 DBG_CONSOLE=VCP

```

--------------------------------

### Example CLI command execution

Source: https://docs.trezor.io/trezor-firmware/developers/hello_world_in_core.html

Demonstrates how to execute the 'say_hello' command via the 'trezorctl' command-line interface, including arguments for name, amount, and display confirmation.

```bash
$ trezorctl helloworld say-hello George -a 3 -d
Please confirm action on your Trezor device.
Hello George!
Hello George!
Hello George!

```

--------------------------------

### Start the Trezor Emulator

Source: https://docs.trezor.io/trezor-firmware/core/build/emulator.html

Launches the Trezor emulator after the firmware has been built.

```bash
./emu.py
```

--------------------------------

### Install Python Dependencies

Source: https://docs.trezor.io/trezor-firmware/print.html

Installs the necessary Python dependencies for the project using uv.

```bash
__
uv sync

```

--------------------------------

### Get Address Example for Passphrase Caching

Source: https://docs.trezor.io/trezor-firmware/common/protocol_v1/passphrase-redesign-migration.html

Use this example to verify that the device prompts for a passphrase when needed and caches it for subsequent requests. This ensures proper session management.

```python
GetAddress(coin_name="Testnet", address_n=[44'/1'/0'/0/0])
```

--------------------------------

### Install Dependencies on Fedora

Source: https://docs.trezor.io/trezor-firmware/core/build/emulator.html

Installs the required packages for building the Trezor firmware on Fedora systems.

```bash
sudo yum install scons SDL2-devel SDL2_image-devel clang-devel
```

--------------------------------

### Install Dependencies on Debian/Ubuntu

Source: https://docs.trezor.io/trezor-firmware/core/build/emulator.html

Installs the necessary packages for building the Trezor firmware on Debian or Ubuntu systems.

```bash
sudo apt-get install scons libsdl2-dev libsdl2-image-dev llvm-dev libclang-dev clang
```

--------------------------------

### Install Project Dependencies with uv

Source: https://docs.trezor.io/trezor-firmware/tests/click-tests.html

Installs project dependencies using the uv package manager. Ensure uv is installed and the virtual environment is activated.

```bash
uv sync
```

--------------------------------

### Install Dependencies on Arch

Source: https://docs.trezor.io/trezor-firmware/core/build/emulator.html

Installs the required packages for building the Trezor firmware on Arch Linux.

```bash
sudo pacman -S scons sdl2 sdl2_image clang-devel
```

--------------------------------

### Install Trezor Library with Bluetooth Support

Source: https://docs.trezor.io/trezor-firmware/python/trezorlib.html

Install the trezor library with additional dependencies for Bluetooth connectivity, required for models like T3W1.

```bash
pip3 install trezor[ble]
```

--------------------------------

### Install Dependencies on macOS

Source: https://docs.trezor.io/trezor-firmware/core/build/emulator.html

Installs the required packages for building the Trezor firmware on macOS using Homebrew.

```bash
brew install scons sdl2 sdl2_image pkg-config llvm
```

--------------------------------

### Install Coverage Tool

Source: https://docs.trezor.io/trezor-firmware/tests/device-tests.html

Install the `coverage.py` tool, which is required for generating HTML or console summary output for code coverage reports.

```bash
__
pip3 install coverage
```

--------------------------------

### Install Trezor Library with HIDAPI Support

Source: https://docs.trezor.io/trezor-firmware/python/trezorlib.html

Install the trezor library with HIDAPI support, necessary for older Trezor One models or firmware versions that are not recognized by default.

```bash
pip3 install trezor[hidapi]
```

--------------------------------

### Setup Development Environment with uv

Source: https://docs.trezor.io/trezor-firmware/python/trezorlib.html

Set up a development environment for trezor-firmware using the 'uv' tool. This allows for live source code testing and immediate effect of changes.

```bash
git clone https://github.com/trezor/trezor-firmware
cd trezor-firmware
git submodule update --init --recursive
uv sync
source .venv/bin/activate
```

--------------------------------

### Run Emulator

Source: https://docs.trezor.io/trezor-firmware/print.html

Starts the Trezor emulator in a separate terminal.

```bash
__
./core/emu.py

```

--------------------------------

### Initialize a New Session

Source: https://docs.trezor.io/trezor-firmware/common/protocol_v1/sessions.html

Starts a new session by calling Initialize with no arguments. The response contains the new session ID.

```protobuf
Initialize()
--------->          Features(..., session_id=AAAA)
                       <---------
```

--------------------------------

### Start JLinkGDBServer for STM32F427VI

Source: https://docs.trezor.io/trezor-firmware/core/embed_debug/index.html

Use this command to start the JLink GDB server for a specific device and interface. Adjust speed as needed.

```bash
JLinkGDBServerCLExe -select USB -device STM32F427VI -endian little -if SWD -speed 4000 -LocalhostOnly

```

--------------------------------

### Run trezorctl command

Source: https://docs.trezor.io/trezor-firmware/print.html

Example of using the trezorctl command-line tool to interact with a Trezor device. This command sends a 'say-hello' request with specified parameters and displays the confirmation and output.

```bash
$ trezorctl helloworld say-hello George -a 3 -d
Please confirm action on your Trezor device.
Hello George!
Hello George!
Hello George!
```

--------------------------------

### Deferred Import of trezor.ui

Source: https://docs.trezor.io/trezor-firmware/core/misc/fragmentation.html

This example demonstrates deferring the import of `trezor.ui` until the `draw_foo` function is actually called. This helps manage image size by only loading dependencies when needed.

```python
def draw_foo():
    import trezor.ui

    trezor.ui.display.draw_text("Foo")

```

--------------------------------

### Install Rust Target Architectures

Source: https://docs.trezor.io/trezor-firmware/core/build/embedded.html

Install the appropriate Rust target architectures for Trezor devices using rustup. 'thumbv7em-none-eabihf' is for Trezor T, and 'thumbv7m-none-eabi' is for Trezor T1.

```bash
rustup target add thumbv7em-none-eabihf  # for TT
ustup target add thumbv7m-none-eabi     # for T1
```

--------------------------------

### Build Firmware with Debug Console

Source: https://docs.trezor.io/trezor-firmware/core/misc/logging.html

Example of building Trezor firmware with the VCP (Virtual COM Port) debug console enabled for logging output.

```bash
make build_firmware TREZOR_MODEL=T3W1 DBG_CONSOLE=VCP
```

--------------------------------

### Start OpenOCD for STM32F4x

Source: https://docs.trezor.io/trezor-firmware/core/embed_debug/index.html

Launch OpenOCD with specific interface and target configurations. It's recommended to use the latest version from git.

```bash
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg

```

--------------------------------

### Run Emulator with Temporary Profile

Source: https://docs.trezor.io/trezor-firmware/core/emulator/index.html

Start the emulator with a temporary profile that is automatically erased upon exit. This is ideal for isolated testing scenarios.

```bash
./emu.py -t / --temporary-profile
```

--------------------------------

### Set up Development Environment

Source: https://docs.trezor.io/trezor-firmware/tests/upgrade-tests.html

Activate the development environment using nix-shell and uv sync, then source the virtual environment. This is the initial step before proceeding with other tasks.

```bash
nix-shell
uv sync
source .venv/bin/activate
```

--------------------------------

### Set Runtime Log Filter (trezorctl)

Source: https://docs.trezor.io/trezor-firmware/core/misc/logging.html

Configures the runtime log filter using the trezorctl command-line tool. This example keeps error messages from all modules and enables all messages for modules starting with 'session'.

```bash
trezorctl debug set-log-filter -- +1*+session*
```

--------------------------------

### Set Runtime Log Filter (prodtest)

Source: https://docs.trezor.io/trezor-firmware/core/misc/logging.html

Configures the runtime log filter within the prodtest environment using the 'log-filter' command. This example keeps error messages from all modules and enables all messages for modules starting with 'session'.

```bash
log-filter +1*+session
```

--------------------------------

### Build Firmware Components

Source: https://docs.trezor.io/trezor-firmware/core/build/embedded.html

Use make commands to build the vendor dependencies, boardloader, bootloader, and the main firmware.

```bash
make vendor build_boardloader build_bootloader build_firmware
```

--------------------------------

### Initialize Two Sessions and Resume First

Source: https://docs.trezor.io/trezor-firmware/print.html

Illustrates the process of initiating two separate sessions and then resuming the first one. This highlights the ability to manage multiple sessions and return to a previous state.

```protobuf
__
Initialize()
--------->          Features(..., session_id=AAAA)
                       <---------
    ---<now in session AAAA>---
Request
--------->          Response
                       <---------

```

--------------------------------

### Session Initialization and Feature Discovery

Source: https://docs.trezor.io/trezor-firmware/print.html

Demonstrates the initial communication flow where the device is initialized and features are discovered, establishing a session.

```protobuf
Initialize()
--------->          Features(..., session_id=BBBB)
                       <---------
    ---<now in session BBBB>---
Request
--------->          Response
                       <---------
```

```protobuf
Initialize(session_id=AAAA)
--------->          Features(..., session_id=AAAA)
                       <---------
    ---<now in session AAAA>---
Request
--------->          Response
                       <---------
```

--------------------------------

### Building and running Trezor emulator

Source: https://docs.trezor.io/trezor-firmware/developers/hello_world_in_core.html

Commands to build the Trezor emulator image and run it on a Unix-like system. This is necessary to test the new 'Hello World' functionality.

```bash
cd core
make build_unix
./emu.py

```

--------------------------------

### Build Firmware with SystemView Enabled

Source: https://docs.trezor.io/trezor-firmware/core/systemview/index.html

Build the embedded firmware with SystemView enabled. Adjust PYOPT and BITCOIN_ONLY as needed. V=1 and VERBOSE=1 provide detailed output.

```bash
V=1 VERBOSE=1 PYOPT=0 BITCOIN_ONLY=1 SYSTEM_VIEW=1 make build_embed
```

--------------------------------

### Running Trezor Core Unit Tests

Source: https://docs.trezor.io/trezor-firmware/print.html

These commands demonstrate how to build the Unix port and execute all unit tests or a specific test file from the `core/` directory.

```bash
make test
make test TESTOPTS=test_apps.bitcoin.address.py
```

--------------------------------

### Device Test for Hello World Workflow

Source: https://docs.trezor.io/trezor-firmware/developers/hello_world_in_core.html

This device test integrates with `trezorlib` to test the complete Hello World workflow, including sending requests and asserting responses. It uses pytest with parameterization to test multiple input vectors.

```python
import pytest

from trezorlib import hello_world
from trezorlib.debuglink import SessionDebugWrapper as Session

VECTORS = (  # name, amount, show_display
    ("George", 2, True),
    ("John", 3, False),
    ("Hannah", None, False),
)


@pytest.mark.models("core")
@pytest.mark.parametrize("name, amount, show_display", VECTORS)
def test_hello_world(
    session: Session, name: str, amount: int | None, show_display: bool
):
    greeting_text = hello_world.say_hello(
        session, name=name, amount=amount, show_display=show_display
    )
    greeting_lines = greeting_text.strip().splitlines()

    assert len(greeting_lines) == amount or 1
    assert all(name in line for line in greeting_lines)

```

--------------------------------

### Run Emulator with SLIP-0014 Seed

Source: https://docs.trezor.io/trezor-firmware/core/emulator/index.html

Initialize the emulator using the 'all all all' seed defined in SLIP-14. This can be done using the --slip0014 flag or its shorthand -s.

```bash
./emu.py --slip0014
```

```bash
./emu.py -s
```

--------------------------------

### Spawn and Await an Asynchronous Task

Source: https://docs.trezor.io/trezor-firmware/core/src/event-loop.html

Use `loop.spawn` to start a background task asynchronously and `await` its result later. The task starts execution immediately upon spawning.

```python
task = loop.spawn(some_background_task())
await do_something_here()
result = await task
```

--------------------------------

### Protobuf Binary Encoding Example

Source: https://docs.trezor.io/trezor-firmware/common/bitcoin-signing.html

This example illustrates the binary representation of Protobuf fields, specifically for a nested structure. It shows how repeated fields are encoded as a sequence of the same field ID and demonstrates the mapping of field IDs and types (e.g., NESTED, int) to their encoded values.

```protobuf
FIELD 1 (type NESTED):
    FIELD 2 (type NESTED):
        FIELD 1 (type int): 0x8000002c
        FIELD 1 (type int): 0x80000000
        FIELD 1 (type int): 0x80000000
        FIELD 1 (type int): 0
        FIELD 1 (type int): 0
        FIELD 8 (type int): 1234567

```

--------------------------------

### loop.spawn

Source: https://docs.trezor.io/trezor-firmware/core/src/event-loop.html

Starts a task asynchronously and returns an object to manage its result and shutdown.

```APIDOC
## loop.spawn(task)

### Description
Start the task asynchronously. Return an object that allows the caller to await its result, or shut the task down.
Unlike other syscalls, `loop.spawn` starts the task at instantiation time. `await`ing the same `loop.spawn` instance a second time will immediately return the result of the original run.
If the task is cancelled (usually by calling `task.close()`), the awaiter receives a `loop.TaskClosed` exception. It is also possible to register a synchronous finalizer callback via `task.set_finalizer`.

### Parameters
#### Path Parameters
- **task** - Required - The task to start asynchronously.
```

--------------------------------

### Build and Flash Firmware for DISC1

Source: https://docs.trezor.io/trezor-firmware/print.html

Use this command to build firmware images and flash them to the DISC1 board using ST-Link. Ensure the `TREZOR_MODEL` is set to `DISC1`.

```bash
make build_boardloader build_bootloader build_firmware TREZOR_MODEL=DISC1
make flash
```

--------------------------------

### Update Rust and Cargo

Source: https://docs.trezor.io/trezor-firmware/core/build/emulator.html

Ensures that the nightly version of Rust and Cargo are installed and up-to-date using rustup.

```bash
rustup default nightly
rustup update
```

--------------------------------

### Run Emulator with Shamir Shares

Source: https://docs.trezor.io/trezor-firmware/core/emulator/index.html

Configure the emulator using Shamir's Secret Sharing by providing multiple mnemonic shares. Each share is passed with a separate --mnemonic flag.

```bash
./emu.py --mnemonic "your first share" --mnemonic "your second share" ...
```

--------------------------------

### Run UI Tests (Emulator)

Source: https://docs.trezor.io/trezor-firmware/tests/ui-tests.html

Runs UI tests against the emulator. Requires the development environment to be installed and activated.

```bash
source .venv/bin/activate
```

```bash
./core/emu.py -a
```

```bash
pytest tests/device_tests --ui=test
```

--------------------------------

### Run Trezor Emulator

Source: https://docs.trezor.io/trezor-firmware/tests/click-tests.html

Starts the Trezor emulator in a separate terminal. This is required for running click tests against the emulator.

```bash
./core/emu.py
```

--------------------------------

### Run UI Tests (Core)

Source: https://docs.trezor.io/trezor-firmware/tests/ui-tests.html

Runs core UI tests, likely for initial setup or basic verification.

```bash
uv run make -C core test_emu_ui
```

--------------------------------

### Log Error Message in C

Source: https://docs.trezor.io/trezor-firmware/core/misc/logging.html

Example of logging an error message with parameters using the LOG_ERR macro in C code.

```c
LOG_ERR("operation failed (errcode=%d)", errcode);

```

--------------------------------

### Get Address Handler Function

Source: https://docs.trezor.io/trezor-firmware/core/src/apps.html

The asynchronous function that handles the `GetAddress` message within the Bitcoin app. Located in `apps.bitcoin.get_address.py`.

```python
async def get_address(msg: GetAddress, keychain: Keychain, coin: CoinInfo) -> Address:
    # ...



```

--------------------------------

### Erase Emulator Storage

Source: https://docs.trezor.io/trezor-firmware/core/emulator/index.html

Start the emulator with the --erase flag to delete existing storage files before initialization. This is equivalent to wiping the device.

```bash
./emu.py -e / --erase
```
Tokens:
Raw