BUILD.md

Build BitBox02 firmware and bootloader

Dependencies

• HIDAPI
• GNU ARM Embedded Toolchain
• SEGGER J-Link software
  • All packages and versions
    • Newer versions should work, but if not, go to "Older versions" and get version 6.34g
  • OSX package
  • Linux 64bit
  • others
• cmake
• git
• Install the pre-built protobuf python binary
  • Then install the included Python Protocol Buffers runtime library

Reporting issues

For security related issues please see SECURITY.md.

Development environment

Install development environment as a Docker container

The container will contain all tools needed to build the project but it is still necessary to get the J-Link software to flash the bootloader. Run the commands below to build the container and execute a persistent one.

make dockerinit
make dockerdev

If you do not want to build the docker image locally, or are not working on it, it may be more straightforward to pull the image from docker instead of building it. This should be a bit faster and there should not be any issues with make dockerdev expecting specific version of the image.

make dockerpull
make dockerdev

The docker container will not allow you to access the hosts USB devices by default which means that it is necessary to flash the device in a terminal not running in docker.

Note

Current development container is defined in the file .containerversion

The docker container mounts the repo it was launched from, so you can freely edit your fork in your preferred IDE and the changes will be reflected in the docker container.

It is highly recommended you develop using this docker container as not all of local setup is completely up to date with every Operating system.

Install development environment on macOS

Make sure you have Homebrew installed. Install the dependencies with:

brew install hidapi cmake protobuf
brew install automake libtool # for building some code in the external/ folder
brew tap osx-cross/arm
brew install arm-gcc-bin

Simulator

The Multi edition firmware can be built as a simulator for linux-amd64. To build it, run:

make -j simulator

Run it with:

./build-build/bin/simulator

This launches a server simulating the firmware. The send_message tool can connect to it with:

./py/send_message.py --simulator

If you choose to create a wallet by restoring a mnemonic, the simulator will automatically use this mnemonic:

boring mistake dish oyster truth pigeon viable emerge sort crash wire portion cannon couple enact box walk height pull today solid off enable tide

Instructions

Connect the J-Link to the debug pins on the BitBox02 prototype board.

Plug in both the J-Link hardware and the BitBox02 device into USB ports on your computer or a hub connected to your computer.

Build the firmware:

git clone --recurse-submodules https://github.com/BitBoxSwiss/bitbox02-firmware && cd bitbox02-firmware
# or via ssh
git clone --recurse-submodules [email protected]:BitBoxSwiss/bitbox02-firmware.git && cd bitbox02-firmware
make firmware # requires a GNU ARM toolchain for cross-compiling

If you have already cloned the repository without the --recurse-submodules argument, run:

git submodule update --init --recursive

Build the bootloader:

make bootloader

(to create a bootloader for a devdevice or a production device, use make bootloader-devdevice or make bootloader-production respectively).

Load the bootloader by JLink (requires JLinkExe in PATH).

make jlink-flash-bootloader

You need to install the BitBox02 Python Library before you can flash the built firmware.

Load the firmware by the bootloader (requires loading bootloader.bin by JLink, if not already loaded on the device):

make flash-dev-firmware

Load the firmware by JLink:

make jlink-flash-firmware

Build reference documentation (Doxygen)

Dependencies:

brew install graphviz doxygen

Build:

make docs

To view the results, open build/docs/html/index.html in a web browser.

BitBox02 Python library

There is a Python api library in py/bitbox02.

Run pip install -r py/requirements.txt to install the deps (virtualenv recommended).

make -C py/bitbox02 to generate the protobuf files.

To kick off some api calls:

./py/send_message.py

Unit tests

We are using CMocka https://cmocka.org/ for unit tests. To run the tests, the CMocka library needs to be installed on your system.

If you're on a Mac, you can use the brew command to install it:

brew install cmocka

Alternatively, you can get CMocka by cloning the git repository and following these instructions:

git clone git://git.cryptomilk.org/projects/cmocka.git
cd cmocka
mkdir build && cd build
cmake ..
make && sudo make install

By default, the library will be installed into /usr/local/lib64 directory under Linux x86_64. If the library is not on the library path by default, you might need to export the following environment variable:

export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/lib64/

Then you can run the tests by executing

make run-unit-tests # or make -C build-build test

Rust unit tests, if not invoked via make run-rust-unit-tests, must be run with -- --test-threads 1 due to unsafe concurrent access to SafeData, mock_sd() and mock_memory().

Coverage

gcovr or lcov/genhtml can be used to generate HTML coverage reports using the following commands:

make coverage # or make -C build-build coverage

make -C build-build coverage-lcovr

SCCache / CCache

The build systems supports sccache/ccache, you just need to have it available in your path. You can install it into your dev container with the following commands:

docker exec -u 0 -it bitbox02-firmware-dev bash -c 'apt update && apt install -y libssl-dev && CARGO_HOME=/opt/cargo cargo install --locked sccache'