mirror of
https://github.com/trezor/trezor-firmware.git
synced 2024-12-24 07:18:09 +00:00
docs: update emulator documentation
This commit is contained in:
matejcik
parent
85f2e18828
commit
d28caf990e
@ -59,7 +59,7 @@ pipenv run make build_unix
|
||||
Now you can start the emulator:
|
||||
|
||||
```sh
|
||||
./emu.sh
|
||||
./emu.py
|
||||
```
|
||||
|
||||
The emulator has a number of interesting features all documented in the [Emulator](../emulator/index.md) section.
|
||||
|
||||
@ -11,73 +11,112 @@ Emulator significantly speeds up development and has several features to help yo
|
||||
## How to run
|
||||
|
||||
1. [build](../build/emulator.md) the emulator
|
||||
2. run `emu.sh`
|
||||
2. run `emu.py` inside the pipenv environment:
|
||||
- either enter `pipenv shell` first, and then use `./emu.py`
|
||||
- or always use `pipenv run ./emu.py`
|
||||
3. to use [bridge](https://github.com/trezor/trezord-go) with the emulator support, start it with `trezord -e 21324`
|
||||
|
||||
Now you can use the emulator the same way as you use the device, for example you can visit our Wallet (https://wallet.trezor.io), use our Python CLI tool (`trezorctl`) etc. Simply click to emulate screen touches.
|
||||
|
||||
## Features
|
||||
|
||||
### Debug mode
|
||||
Run `./emu.py --help` to see all supported command line options and shortcuts. The
|
||||
sections below only list long option names and most notable features.
|
||||
|
||||
To allow debug link (to run tests), see exceptions and log output, run emulator with `PYOPT=0 ./emu.sh`. To properly distinguish the debug mode from production there is a tiny red square in the top right corner. The debug mode is obviously disabled on production firmwares.
|
||||
### Debug and production mode
|
||||
|
||||
By default the emulator runs in debug mode. Debuglink is available (on port 21325 by
|
||||
default), exceptions and log output goes to console. To indicate debug mode, there is a
|
||||
red square in the upper right corner of Trezor screen.
|
||||
|
||||
|
||||
|
||||
To enable production mode, run `./emu.py --production`, or set environment variable `PYOPT=1`.
|
||||
|
||||
### Initialize with mnemonic words
|
||||
|
||||
If the debug mode is enabled, you can load the device with any recovery seed directly from the console. This feature is otherwise disabled. To enter seed use `trezorctl`:
|
||||
In debug mode, the emulator can be pre-configured with a mnemonic phrase.
|
||||
|
||||
To use a specific mnemonic phrase:
|
||||
|
||||
```sh
|
||||
trezorctl -m "your mnemonic words"
|
||||
./emu.py --mnemonic "such deposit very security much theme..."
|
||||
```
|
||||
|
||||
or to use the "all all all" seed defined in [SLIP-14](https://github.com/satoshilabs/slips/blob/master/slip-0014.md):
|
||||
When using Shamir shares, repeat the `--mnemonic` option:
|
||||
|
||||
```sh
|
||||
trezorctl -s
|
||||
./emu.py --mnemonic "your first share" --mnemonic "your second share" ...
|
||||
```
|
||||
|
||||
Shamir Backup is also supported:
|
||||
To use the "all all all" seed defined in [SLIP-14](https://github.com/satoshilabs/slips/blob/master/slip-0014.md):
|
||||
|
||||
```sh
|
||||
trezorctl -m "share 1 words" -m "share 2 words"
|
||||
./emu.py --slip0014
|
||||
```
|
||||
|
||||
### Storage and Profiles
|
||||
|
||||
Internal Trezor's storage is emulated and stored in the `/var/tmp/trezor.flash` file on default. Deleting this file is similar to calling _wipe device_. You can also find `/var/tmp/trezor.sdcard` for SD card and `/var/tmp/trezor.log`, which contains the communication log, the same as is in the emulator's stdout.
|
||||
Internal Trezor's storage is emulated and stored in the `/var/tmp/trezor.flash` file on
|
||||
default. Deleting this file is similar to calling _wipe device_. You can also find
|
||||
`/var/tmp/trezor.sdcard` for SD card and `/var/tmp/trezor.log`, which contains the
|
||||
communication log, the same as is in the emulator's stdout.
|
||||
|
||||
To run emulator with different files set the environment variable **TREZOR_PROFILE** like so:
|
||||
You can specify a different location for the storage and log files via the `-p` /
|
||||
`--profile` option:
|
||||
|
||||
```sh
|
||||
TREZOR_PROFILE=foobar ./emu.sh
|
||||
./emu.py -p foobar
|
||||
```
|
||||
|
||||
This will create a profile directory in your home ``` ~/.trezoremu/foobar``` containing emulator run files. Alternatively you can set a full path like so:
|
||||
This will create a profile directory in your home `~/.trezoremu/foobar` containing
|
||||
emulator run files. Alternatively you can set a full path like so:
|
||||
|
||||
```sh
|
||||
TREZOR_PROFILE=/var/tmp/foobar ./emu.sh
|
||||
./emu.py -p /var/tmp/foobar
|
||||
```
|
||||
|
||||
You can also set a full profile path to `TREZOR_PROFILE_DIR` environment variable.
|
||||
|
||||
Specifying `-t` / `--temporary-profile` will start the emulator in a clean temporary
|
||||
profile that will be erased when the emulator stops. This is useful, e.g., for tests.
|
||||
|
||||
### Running subcommands with the emulator
|
||||
|
||||
In scripts, it is often necessary to start the emulator, run a commmand while it is
|
||||
available, and then stop it. The following command runs the device test suite using the
|
||||
emulator:
|
||||
|
||||
```sh
|
||||
./emu.py --command pytest ../tests/device_tests
|
||||
```
|
||||
|
||||
### Profiling support
|
||||
|
||||
Run `./emu.py --profiling`, or set environment variable `TREZOR_PROFILING=1`, to run the
|
||||
emulator with a profiling wrapper that generates statistics of executed lines.
|
||||
|
||||
### Memory statistics
|
||||
|
||||
Run `./emu.py --log-memory`, or set environment variable `TREZOR_LOG_MEMORY=1`, to dump
|
||||
memory usage information after each workflow task is finished.
|
||||
|
||||
### Run in gdb
|
||||
|
||||
Running `emu.sh` with `-d` runs emulator inside gdb/lldb.
|
||||
Running `./emu.py --debugger` runs emulator inside gdb/lldb.
|
||||
|
||||
### Watch for file changes
|
||||
|
||||
Running `emu.sh` with `-r` watches for file changes and reloads the emulator if any occur. Note that this does not do rebuild, i.e. this works for MicroPython code (which is interpreted) but if you make C changes, you need to rebuild your self.
|
||||
Running `./emu.py --watch` watches for file changes and reloads the emulator if any
|
||||
occur. Note that this does not do rebuild, i.e. this works for MicroPython code (which
|
||||
is interpreted) but if you make C changes, you need to rebuild yourself.
|
||||
|
||||
### Print screen
|
||||
|
||||
Press `p` on your keyboard to capture emulator's screen. You will find a png screenshot in the `src` directory.
|
||||
Press `p` on your keyboard to capture emulator's screen. You will find a png screenshot
|
||||
in the `src` directory.
|
||||
|
||||
### Environment Variables
|
||||
### Disable animation
|
||||
|
||||
#### Memory statistics
|
||||
|
||||
If ```TREZOR_LOG_MEMORY=1``` is set, the emulator prints memory usage information after each workflow task is finished.
|
||||
|
||||
#### Disable animations
|
||||
|
||||
```TREZOR_DISABLE_ANIMATION=1``` disables fading and other animations, which speeds up the UI workflows significantly (useful for tests). This is also requirement for UI integration tests.
|
||||
Run `./emu.py --disable-animation`, or set environment variable
|
||||
`TREZOR_DISABLE_ANIMATION=1` to disable all animations.
|
||||
|
||||
@ -25,10 +25,9 @@ environment:
|
||||
pipenv shell
|
||||
```
|
||||
|
||||
If you want to test against the emulator, run it in a separate terminal from the `core`
|
||||
subdirectory:
|
||||
If you want to test against the emulator, run it in a separate terminal:
|
||||
```sh
|
||||
PYOPT=0 ./emu.sh
|
||||
./core/emu.py
|
||||
```
|
||||
|
||||
Now you can run the test suite with `pytest` from the root directory:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user