@ -41,6 +41,21 @@ Several tools are required for building and debugging Passport.
sudo apt install python3-pip
sudo apt install python3-pip
sudo pip3 install rshell # (this should install rshell in /usr/local/)
sudo pip3 install rshell # (this should install rshell in /usr/local/)
### Using Justfile commands
To use Just for running commands, first follow the instructions here: https://github.com/casey/just#installation to install Just. Note that `Pillow` must be updated to `8.3.1` for all commands to work properly.
Once Just has been installed, the developer can use `just` commands to perform actions such as building, flashing, resetting and even taking screenshots of the displays screen.
Note that all `just` commands must be run from `ports/stm32/` directory.
Here are some of the most common `just` commands and their usages:
just flash {version} - Builds if necessary, signs with a user key and then flashes the device with the firmware binary created under `build-Passport/`
just reset - Resets the device
just screenshot {filename} - Screenshots the device and saves to the desired filename
See the `Justfile` included in our source for the full list of `just` commands.
## Building
## Building
### Open Shell Windows/Tabs
### Open Shell Windows/Tabs
You will need several shell windows or tabs open to interact with the various tools.
You will need several shell windows or tabs open to interact with the various tools.
@ -64,6 +79,10 @@ You should see it building various `.c` files and freezing `.py` files. Once co
GEN build-Passport/firmware.dfu
GEN build-Passport/firmware.dfu
GEN build-Passport/firmware.hex
GEN build-Passport/firmware.hex
If you are using `just` commands, then building the firmware can be done by running the following command:
just build
#### Code Signing
#### Code Signing
In order to load the files onto the device, they need to first be signed by two separate keys.
In order to load the files onto the device, they need to first be signed by two separate keys.
The `cosign` program performs this task, and it needs to be called twice with two separate
The `cosign` program performs this task, and it needs to be called twice with two separate
@ -88,6 +107,12 @@ You can also dump the contents of the firmware header with the following command
If you are using `just` commands, then signing the firmware can be done by running the following command with the desired version:
just sign 1.0.7
It will build the firmware first if necessary.
#### Building the Bootloader
#### Building the Bootloader
To build the bootloader do the following:
To build the bootloader do the following:
@ -145,6 +170,12 @@ These commands do the following:
- Write the firmware to flash at address 0x8000000
- Write the firmware to flash at address 0x8000000
- Reset the MCU and start executing code at address 0x8000000
- Reset the MCU and start executing code at address 0x8000000
If you are using `just` commands, ocd and telnet steps are not required and instead, flashing the firmware can be done using the following command with the desired version number:
just flash 1.0.7
It will build and sign the firmware first if necessary.
### RShell Window
### RShell Window
We use `rshell` to connect to the MicroPython device over USB serial. Open another shell and run:
We use `rshell` to connect to the MicroPython device over USB serial. Open another shell and run: