From 307f7058614c1431723f14214b0b2adabd0d88dd Mon Sep 17 00:00:00 2001 From: will-v-pi <108662275+will-v-pi@users.noreply.github.com> Date: Thu, 19 Sep 2024 09:59:31 +0100 Subject: [PATCH 1/6] Add note about pico-sdk-tools to README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 6b4cdbe1..8eefec14 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ ## Building +> If you don't need to build picotool yourself, you can find pre-built binaries for Windows, macOS, and Linux in the [pico-sdk-tools](https://github.com/raspberrypi/pico-sdk-tools/releases) repository + You need to set PICO_SDK_PATH in the environment, or pass it to cmake with `-DPICO_SDK_PATH=/path/to/pico-sdk`. To use features such as signing or hashing, you will need to make sure the mbedtls submodule in the SDK is checked out - this can be done by running this from your SDK directory. ```console From ce1e6b992e062736ba6f670de0ea2684e70afd00 Mon Sep 17 00:00:00 2001 From: William Vinnicombe Date: Wed, 2 Apr 2025 14:22:46 +0100 Subject: [PATCH 2/6] Separate out BUILDING.md Move build & install instructions into separate file, liked from the main readme --- BUILDING.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 106 +++------------------------------------------------- 2 files changed, 105 insertions(+), 100 deletions(-) create mode 100644 BUILDING.md diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 00000000..0834203d --- /dev/null +++ b/BUILDING.md @@ -0,0 +1,99 @@ +## Building + +You need to set PICO_SDK_PATH in the environment, or pass it to cmake with `-DPICO_SDK_PATH=/path/to/pico-sdk`. To use features such as signing or hashing, you will need to make sure the mbedtls submodule in the SDK is checked out - this can be done by running this from your SDK directory. + +```console +git submodule update --init lib/mbedtls +``` + +You also need to install `libusb-1.0` if you want to use the USB functionality. + +### Linux / macOS + +Use your favorite package tool to install dependencies. For example, on Ubuntu: + +```console +sudo apt install build-essential pkg-config libusb-1.0-0-dev cmake +``` + +> If libusb-1.0-0-dev is not installed, picotool still builds, but it omits all options that deal with managing a pico via USB (load, save, erase, verify, reboot). Builds that do not include USB support can be recognized because these commands also do not appear in the help command. The build output message 'libUSB is not found - no USB support will be built' also appears in the build logs. + +Then simply build like a normal CMake project: + +```console +mkdir build +cd build +cmake .. +make +``` + +On Linux you can add udev rules in order to run picotool without sudo: + +```console +sudo cp udev/99-picotool.rules /etc/udev/rules.d/ +``` + +### Windows + +##### For Windows without MinGW + +Download libUSB from here https://libusb.info/ + +set LIBUSB_ROOT environment variable to the install directory. +```console +mkdir build +cd build +cmake -G "NMake Makefiles" .. +nmake +``` + +##### For Windows with MinGW in WSL + +Download libUSB from here https://libusb.info/ + +set LIBUSB_ROOT environment variable to the install directory. + +```console +mkdir build +cd build +cmake .. +make +``` + +##### For Windows with MinGW in MSYS2: + +No need to download libusb separately or set `LIBUSB_ROOT`. + +```console +pacman -S $MINGW_PACKAGE_PREFIX-{toolchain,cmake,libusb} +mkdir build +cd build +cmake .. -DCMAKE_INSTALL_PREFIX=$MINGW_PREFIX +cmake --build . +``` + +## Installing (so the Pico SDK can find it) + +The Raspberry Pi Pico SDK ([pico-sdk](https://github.com/raspberrypi/pico-sdk)) version 2.0.0 and above uses `picotool` to do the ELF-to-UF2 conversion previously handled by the `elf2uf2` tool in the SDK. The SDK also uses `picotool` to hash and sign binaries. + +Whilst the SDK can download picotool on its own per project, if you have multiple projects or build configurations, it is preferable to install a single copy of `picotool` locally. This can be done most simply with `make install` or `cmake --install .`, using `sudo` if required; the SDK will use this installed version by default. + +> On some Linux systems, the `~/.local` prefix may be used for an install without `sudo`; from your build directory simply run +> ```console +> cmake -DCMAKE_INSTALL_PREFIX=~/.local .. +> make install +> ``` +> This will only work if `~/.local/bin` is included in your `PATH` + +### Custom Path Installation (eg if you can't use `sudo`) + +Alternatively, you can install to a custom path via: + +```console +cmake -DCMAKE_INSTALL_PREFIX=$MY_INSTALL_DIR -DPICOTOOL_FLAT_INSTALL=1 .. +make install +``` + +In order for the SDK to find `picotool` in this custom folder, you will usually need to set the `picotool_DIR` variable in your project. This can be achieved either by setting the `picotool_DIR` environment variable to `$MY_INSTALL_DIR/picotool`, by passing `-Dpicotool_DIR=$MY_INSTALL_DIR/picotool` to your `cmake` command, or by adding `set(picotool_DIR $MY_INSTALL_DIR/picotool)` to your CMakeLists.txt file. + +> See the [find_package documentation](https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure) for more details diff --git a/README.md b/README.md index 8eefec14..e2cff54a 100644 --- a/README.md +++ b/README.md @@ -1,103 +1,3 @@ -## Building - -> If you don't need to build picotool yourself, you can find pre-built binaries for Windows, macOS, and Linux in the [pico-sdk-tools](https://github.com/raspberrypi/pico-sdk-tools/releases) repository - -You need to set PICO_SDK_PATH in the environment, or pass it to cmake with `-DPICO_SDK_PATH=/path/to/pico-sdk`. To use features such as signing or hashing, you will need to make sure the mbedtls submodule in the SDK is checked out - this can be done by running this from your SDK directory. - -```console -git submodule update --init lib/mbedtls -``` - -You also need to install `libusb-1.0`. - -### Linux / macOS - -Use your favorite package tool to install dependencies. For example, on Ubuntu: - -```console -sudo apt install build-essential pkg-config libusb-1.0-0-dev cmake -``` - -> If libusb-1.0-0-dev is not installed, picotool still builds, but it omits all options that deal with managing a pico via USB (load, save, erase, verify, reboot). Builds that do not include USB support can be recognized because these commands also do not appear in the help command. The build output message 'libUSB is not found - no USB support will be built' also appears in the build logs. - -Then simply build like a normal CMake project: - -```console -mkdir build -cd build -cmake .. -make -``` - -On Linux you can add udev rules in order to run picotool without sudo: - -```console -sudo cp udev/99-picotool.rules /etc/udev/rules.d/ -``` - -### Windows - -##### For Windows without MinGW - -Download libUSB from here https://libusb.info/ - -set LIBUSB_ROOT environment variable to the install directory. -```console -mkdir build -cd build -cmake -G "NMake Makefiles" .. -nmake -``` - -##### For Windows with MinGW in WSL - -Download libUSB from here https://libusb.info/ - -set LIBUSB_ROOT environment variable to the install directory. - -```console -mkdir build -cd build -cmake .. -make -``` - -##### For Windows with MinGW in MSYS2: - -No need to download libusb separately or set `LIBUSB_ROOT`. - -```console -pacman -S $MINGW_PACKAGE_PREFIX-{toolchain,cmake,libusb} -mkdir build -cd build -cmake .. -DCMAKE_INSTALL_PREFIX=$MINGW_PREFIX -cmake --build . -``` - -## Usage by the Raspberry Pi Pico SDK - -The Raspberry Pi Pico SDK ([pico-sdk](https://github.com/raspberrypi/pico-sdk)) version 2.0.0 and above uses `picotool` to do the ELF-to-UF2 conversion previously handled by the `elf2uf2` tool in the SDK. The SDK also uses `picotool` to hash and sign binaries. - -Whilst the SDK can download picotool on its own per project, if you have multiple projects or build configurations, it is preferable to install a single copy of `picotool` locally. This can be done most simply with `make install` or `cmake --install .`, using `sudo` if required; the SDK will use this installed version by default. - -> On some Linux systems, the `~/.local` prefix may be used for an install without `sudo`; from your build directory simply run -> ```console -> cmake -DCMAKE_INSTALL_PREFIX=~/.local .. -> make install -> ``` -> This will only work if `~/.local/bin` is included in your `PATH` - -Alternatively, you can install to a custom path via: - -```console -cmake -DCMAKE_INSTALL_PREFIX=$MY_INSTALL_DIR -DPICOTOOL_FLAT_INSTALL=1 .. -make install -``` - -In order for the SDK to find `picotool` in this custom folder, you will usually need to set the `picotool_DIR` variable in your project. This can be achieved either by setting the `picotool_DIR` environment variable to `$MY_INSTALL_DIR/picotool`, by passing `-Dpicotool_DIR=$MY_INSTALL_DIR/picotool` to your `cmake` command, or by adding `set(picotool_DIR $MY_INSTALL_DIR/picotool)` to your CMakeLists.txt file. - -> See the [find_package documentation](https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure) for more details - ## Overview `picotool` is a tool for working with RP2040/RP2350 binaries, and interacting with RP2040/RP2350 devices when they are in BOOTSEL mode. (As of version 1.1 of `picotool` it is also possible to interact with devices that are not in BOOTSEL mode, but are using USB stdio support from the Raspberry Pi Pico SDK by using the `-f` argument of `picotool`). @@ -157,6 +57,12 @@ Use "picotool help " for more info Note commands that aren't acting on files require a device in BOOTSEL mode to be connected. +## Building & Installing + +If you don't want to build picotool yourself, you can find pre-built executables for Windows, macOS, and Linux in the [pico-sdk-tools](https://github.com/raspberrypi/pico-sdk-tools/releases) repository. Assuming you've unzipped that directory to `$PICOTOOL_LOC` (with the actual picotool executable at `$PICOTOOL_LOC/picotool/picotool`), you can point the Pico SDK at this binary by setting the `picotool_DIR` environment variable to `$PICOTOOL_LOC/picotool`, or by passing `-Dpicotool_DIR=$PICOTOOL_LOC/picotool` to your `cmake` command or setting it in your `CMakeLists.txt` file. + +If you do wish to build picotool yourself, then see [Building](BUILDING.md#building) for build instructions. For the Pico SDK to find your picotool you will need to install it, the simplest way being to run `cmake --install .` - see [Installing](BUILDING.md#installing-so-the-pico-sdk-can-find-it) for more details and alternatives. **You cannot just copy the binary into your `PATH`, else the Pico SDK will not be able to locate it.** + ## info There is _Binary Information_ support in the SDK which allows for easily storing compact information that `picotool` From e033a4316cc81c496dc6dc25e10b777f37255537 Mon Sep 17 00:00:00 2001 From: William Vinnicombe Date: Wed, 2 Apr 2025 14:30:32 +0100 Subject: [PATCH 3/6] Remove references to `picotool sign` Fixes #218 --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e2cff54a..56f437ae 100644 --- a/README.md +++ b/README.md @@ -576,7 +576,7 @@ OPTIONS: ## encrypt -`encrypt` allows you to encrypt and sign a binary for use on the RP2350. By default, it will sign the encrypted binary, but that can be configured similarly to `picotool sign`. +`encrypt` allows you to encrypt and sign a binary for use on the RP2350. By default, it will sign the encrypted binary, but that can be configured similarly to `picotool seal`. The encrypted binary will have the following structure: @@ -850,10 +850,10 @@ These commands will set/get specific rows of OTP. By default, they will write/re ### load -This command allows loading of a range of OTP rows onto the device. The source can be a binary file, or a JSON file such as the one output by `picotool sign`. The schema for this JSON file is [here](json/schemas/otp-schema.json) +This command allows loading of a range of OTP rows onto the device. The source can be a binary file, or a JSON file such as the one output by `picotool seal`. The schema for this JSON file is [here](json/schemas/otp-schema.json) For example, if you wish to sign a binary and then test secure boot with it, you can run the following set of commands: ```text -$ picotool sign hello_world.elf hello_world.signed.elf private.pem otp.json +$ picotool seal --sign hello_world.elf hello_world.signed.elf private.pem otp.json $ picotool load hello_world.signed.elf $ picotool otp load otp.json $ picotool reboot From 1e709e64d009542ada9f81b4abeda0390fe24ba7 Mon Sep 17 00:00:00 2001 From: William Vinnicombe Date: Wed, 2 Apr 2025 14:59:08 +0100 Subject: [PATCH 4/6] Review fixups Move no-libusb bit Capital S `$PICOTOOL_LOC` -> `$EXTRACT_LOCATION` unzipped that directory -> extracted that archive --- BUILDING.md | 8 ++++---- README.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 0834203d..89c2771c 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -8,6 +8,8 @@ git submodule update --init lib/mbedtls You also need to install `libusb-1.0` if you want to use the USB functionality. +> If libusb-1.0 is not installed, picotool still builds, but it omits all options that deal with managing a pico via USB (load, save, erase, verify, reboot). Builds that do not include USB support can be recognized because these commands also do not appear in the help command. The build output message 'libUSB is not found - no USB support will be built' also appears in the build logs. + ### Linux / macOS Use your favorite package tool to install dependencies. For example, on Ubuntu: @@ -16,8 +18,6 @@ Use your favorite package tool to install dependencies. For example, on Ubuntu: sudo apt install build-essential pkg-config libusb-1.0-0-dev cmake ``` -> If libusb-1.0-0-dev is not installed, picotool still builds, but it omits all options that deal with managing a pico via USB (load, save, erase, verify, reboot). Builds that do not include USB support can be recognized because these commands also do not appear in the help command. The build output message 'libUSB is not found - no USB support will be built' also appears in the build logs. - Then simply build like a normal CMake project: ```console @@ -39,7 +39,7 @@ sudo cp udev/99-picotool.rules /etc/udev/rules.d/ Download libUSB from here https://libusb.info/ -set LIBUSB_ROOT environment variable to the install directory. +Set LIBUSB_ROOT environment variable to the install directory. ```console mkdir build cd build @@ -51,7 +51,7 @@ nmake Download libUSB from here https://libusb.info/ -set LIBUSB_ROOT environment variable to the install directory. +Set LIBUSB_ROOT environment variable to the install directory. ```console mkdir build diff --git a/README.md b/README.md index 56f437ae..8b999e84 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ Note commands that aren't acting on files require a device in BOOTSEL mode to be ## Building & Installing -If you don't want to build picotool yourself, you can find pre-built executables for Windows, macOS, and Linux in the [pico-sdk-tools](https://github.com/raspberrypi/pico-sdk-tools/releases) repository. Assuming you've unzipped that directory to `$PICOTOOL_LOC` (with the actual picotool executable at `$PICOTOOL_LOC/picotool/picotool`), you can point the Pico SDK at this binary by setting the `picotool_DIR` environment variable to `$PICOTOOL_LOC/picotool`, or by passing `-Dpicotool_DIR=$PICOTOOL_LOC/picotool` to your `cmake` command or setting it in your `CMakeLists.txt` file. +If you don't want to build picotool yourself, you can find pre-built executables for Windows, macOS, and Linux in the [pico-sdk-tools](https://github.com/raspberrypi/pico-sdk-tools/releases) repository. Assuming you've extracted that archive to `$EXTRACT_LOCATION` (with the actual picotool executable at `$EXTRACT_LOCATION/picotool/picotool`), you can point the Pico SDK at this binary by setting the `picotool_DIR` environment variable to `$EXTRACT_LOCATION/picotool`, or by passing `-Dpicotool_DIR=$EXTRACT_LOCATION/picotool` to your `cmake` command or setting it in your `CMakeLists.txt` file. If you do wish to build picotool yourself, then see [Building](BUILDING.md#building) for build instructions. For the Pico SDK to find your picotool you will need to install it, the simplest way being to run `cmake --install .` - see [Installing](BUILDING.md#installing-so-the-pico-sdk-can-find-it) for more details and alternatives. **You cannot just copy the binary into your `PATH`, else the Pico SDK will not be able to locate it.** From d705b9d39294a2a44e01bb48a0b07779aad98a51 Mon Sep 17 00:00:00 2001 From: William Vinnicombe Date: Wed, 2 Apr 2025 16:42:27 +0100 Subject: [PATCH 5/6] Review fixup because these commands also do not appear in the help command. -> because these commands won't appear in the output of the help command. --- BUILDING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BUILDING.md b/BUILDING.md index 89c2771c..b71d9da8 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -8,7 +8,7 @@ git submodule update --init lib/mbedtls You also need to install `libusb-1.0` if you want to use the USB functionality. -> If libusb-1.0 is not installed, picotool still builds, but it omits all options that deal with managing a pico via USB (load, save, erase, verify, reboot). Builds that do not include USB support can be recognized because these commands also do not appear in the help command. The build output message 'libUSB is not found - no USB support will be built' also appears in the build logs. +> If libusb-1.0 is not installed, picotool still builds, but it omits all options that deal with managing a pico via USB (load, save, erase, verify, reboot). Builds that do not include USB support can be recognized because these commands won't appear in the output of the help command. The build output message 'libUSB is not found - no USB support will be built' also appears in the build logs. ### Linux / macOS From 295306d483088a89b31f3b0d3b0047ea885b8523 Mon Sep 17 00:00:00 2001 From: will-v-pi <108662275+will-v-pi@users.noreply.github.com> Date: Wed, 2 Apr 2025 17:52:22 +0100 Subject: [PATCH 6/6] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8b999e84..b594878a 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ Note commands that aren't acting on files require a device in BOOTSEL mode to be ## Building & Installing -If you don't want to build picotool yourself, you can find pre-built executables for Windows, macOS, and Linux in the [pico-sdk-tools](https://github.com/raspberrypi/pico-sdk-tools/releases) repository. Assuming you've extracted that archive to `$EXTRACT_LOCATION` (with the actual picotool executable at `$EXTRACT_LOCATION/picotool/picotool`), you can point the Pico SDK at this binary by setting the `picotool_DIR` environment variable to `$EXTRACT_LOCATION/picotool`, or by passing `-Dpicotool_DIR=$EXTRACT_LOCATION/picotool` to your `cmake` command or setting it in your `CMakeLists.txt` file. +If you don't want to build picotool yourself, you can find pre-built executables for Windows, macOS, and Linux in the [pico-sdk-tools](https://github.com/raspberrypi/pico-sdk-tools/releases) repository. Assuming you've extracted that archive to `` (with the actual picotool executable at `/picotool/picotool`), you can point the Pico SDK at this binary by setting the `picotool_DIR` environment variable to `/picotool`, or by passing `-Dpicotool_DIR=/picotool` to your `cmake` command or setting it in your `CMakeLists.txt` file. If you do wish to build picotool yourself, then see [Building](BUILDING.md#building) for build instructions. For the Pico SDK to find your picotool you will need to install it, the simplest way being to run `cmake --install .` - see [Installing](BUILDING.md#installing-so-the-pico-sdk-can-find-it) for more details and alternatives. **You cannot just copy the binary into your `PATH`, else the Pico SDK will not be able to locate it.**