PSLab Bootloader: Building and Flashing the PSLab Firmware Loader

Why the PSLab Needs Its Own USB Firmware Loader

PSLab Bootloader solves a specific bootstrapping problem for the Pocket Science Lab. According to the README, it makes it possible to flash new firmware over USB, whereas a device without the bootloader would require a special programming tool. That division is important for users of the open hardware platform. Once the bootloader is installed, the normal firmware update route does not depend on attaching a separate programmer every time application firmware changes.

The intended audience is therefore split between two groups. Firmware developers need a repeatable way to deploy new PSLab application code. Experiment users and educators need the instrument firmware to remain updateable as the PSLab software stack develops. The wider PSLab platform includes hardware, firmware, a Python library, a desktop application, and an Android app, while this repository covers only the bootloader component.

This is not a general-purpose programmer. The repository is specifically the bootloader for the Pocket Science Lab, and the documented flashing procedure uses a programmer such as the PICkit3 through `flash.mdbscript`. Its USB update role begins after the bootloader itself has been placed on the device.

The C Build Flow Behind the USB Update Path

The repository layout separates the bootloader entry point, generated C sources, the build configuration, and the Microchip CMake toolchain. `src/main.c` is identified as the bootloader entry point, while `src/mcc_generated_files` contains source C files. The root `CMakeLists.txt` drives the build. The `external/cmake-microchip` directory is a Git submodule, which means the build depends on repository-managed toolchain files rather than treating every dependency as a normal source directory.

CMake produces a build directory and invokes the build system through `make`, yielding `pslab-bootloader.hex`. That Intel HEX artifact is the direct build output consumed by the later flashing workflow. For a distribution image that includes both bootloader and firmware, the README describes a separate combination step: build both projects, move `firmware.hex` into the bootloader's `build/` directory, and run `combine_hex.sh`.

The combination script depends on `hexmate`, which the README says is distributed with MPLAB-X. It may instead be invoked through an absolute pathname after editing the script. This separates two operations clearly. `pslab-bootloader.hex` is the bootloader image produced by the CMake build, while the optional combined HEX file packages that image with a separately built firmware image. The README does not document address mapping, signing, version negotiation, rollback, or USB update commands, so those details cannot be assumed.

Building pslab-bootloader.hex with the Documented Toolchain

The build requires the `xc16` compiler and `cmake`. First, clone the repository and initialize its toolchain submodule. The documented initialization and update commands populate `external/cmake-microchip`:

git submodule init
git submodule update

Configure an out-of-tree build with CMake. These commands create `build`, change into it, and generate the build files with the parent repository as the source directory:

mkdir build
cd build
cmake ..

A successful configuration should prepare the Microchip build environment. The README does not state exact compiler versions, CMake minimum versions, or host operating system support for the build, so pinning arbitrary versions here would add information the repository does not establish.

Compile the configured project from the same `build` directory:

make

The expected artifact is `build/pslab-bootloader.hex`. If dependency discovery fails, the first project-specific items to check are whether `xc16` is installed and accessible to CMake and whether the submodule content was actually populated. A bare checkout that skips the submodule commands is not equivalent to the build setup described by the README.

Installing the Bootloader with MPLAB-X and a Programmer

Flashing the bootloader is a different operation from flashing later application firmware over USB. The README specifies a programmer such as the PICkit3 and the `mdb.sh` script distributed with MPLAB-X. On Linux, the documented default location for the script is `/opt/microchip/mplabx/<version>/mplab_platform/bin/mdb.sh`, although the version component will depend on the installed suite.

Before programming, inspect `flash.mdbscript`. The README says it may need modification for the programmer being used and for the location of the firmware HEX. It also names `mdb.sh` as the script used to run that repository file. The documentation does not provide the contents of `flash.mdbscript`, so it does not establish every device selector, address, or voltage setting needed for an arbitrary programmer setup.

Power down the PSLab, connect the programmer to the device's ICSP header, and then power the device through USB. With `mdb.sh` available on your `PATH`, run:

mdb.sh flash.mdbscript

Disconnect the programmer after the operation. This sequence concerns initial bootloader installation or recovery through hardware programming. The repository does not describe the subsequent USB firmware update command, and its flashing section should not be treated as a self-contained guide for end users updating application firmware.

Producing One HEX File for Bootloader and Firmware

PSLab Bootloader also supports a packaging workflow for images that need both the bootloader and firmware. The README does not supply a one-command recipe for this operation because it assumes that the firmware project has already been built separately. The documented order is: build the bootloader, build the firmware, move `firmware.hex` into the bootloader's `build/` directory, and execute `combine_hex.sh`.

The expected file placement can be summarized without adding an invented destination name. At that point, the bootloader build directory contains both its own HEX output and the incoming `firmware.hex` needed by the script.

build/
  pslab-bootloader.hex
  firmware.hex

The script uses `hexmate`, distributed as part of MPLAB-X, so MPLAB-X must still be installed even though the normal CMake bootloader build lists `xc16` and `cmake`. If `hexmate` is not found through `PATH`, the README says to modify `combine_hex.sh` with its full pathname. That is an explicit script change, not a documented environment variable.

The README does not state the output filename, memory layout, merge options, or whether the resulting image is intended for production programming, field flashing, or both. Those details need confirmation from the script or build configuration before treating the combined image as a release artifact.

Maintenance Signals, License Scope, and Adoption Boundaries

The repository is not archived, and its last push was on 2026-08-16. The most recent listed release is version `1.1.1`, dated 2024-12-23. These facts show that repository activity continued after that release, although the release history alone does not establish the scope or compatibility of the newer changes.

The project is licensed under `Apache-2.0`. The license covers this bootloader repository and its stated use, modification, and redistribution terms. It does not automatically settle firmware compatibility, hardware liability, regulatory requirements, or the licensing of every artifact produced by MPLAB-X. Those are separate checks, especially for organizations assembling production images with `hexmate`.

The clearest limitation is the split between USB application firmware updates and programmer-based bootloader installation. PSLab Bootloader is the wrong tool if the device does not already expose the expected PSLab USB bootloader or if the goal is to program an unrelated target. The documented build process also has a narrower platform boundary than a typical portable C utility. It depends on `xc16`, CMake, Microchip toolchain files, and, for programming or HEX combination, MPLAB-X components.

A real alternative for initial or recovery programming is the PICkit3-based MPLAB-X workflow documented here without relying on the PSLab USB loader. The practical difference is access: the PSLab bootloader enables USB-based application firmware updates, while a programmer connects through the ICSP header and writes the bootloader HEX directly. For routine firmware deployment, the bootloader is the relevant component. For first installation or situations where its USB path is unavailable, the programmer workflow remains necessary.

Editorial conclusion

Adopt PSLab Bootloader when firmware work for the Pocket Science Lab must be repeatable through the device's USB update path. Do not treat it as a universal USB flasher or as an alternative to the initial programmer-based installation. Verify first that the required Microchip build tools are available, that the CMake submodule initializes correctly, and that flash.mdbscript matches the programmer, firmware HEX location, and target device.

Frequently asked questions

Official sources

1. fossasia/pslab-bootloader on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases