Flashing PSLab firmware with a programmer will overwrite the bootloader

What the device is, and why the firmware is one layer of a stack

The Pocket Science Lab is a USB device that presents itself as an array of test and measurement instruments. The README lists an oscilloscope, a waveform generator, a frequency counter, programmable voltage and current sources, and a logic analyzer, plus UART, I2C and SPI buses through which external devices can be connected and controlled.

That bus list is the part that matters for anyone deciding whether the hardware fits a lab. It is not a single purpose instrument; it is a device with a mixed signal front end and three serial buses exposed, so a class can attach a sensor, an external device or both.

This repository is only the firmware layer of a five part open stack, all under FOSSASIA and all open source: the hardware designs in pslab-hardware, the bootloader in pslab-bootloader, this firmware, the Python library in pslab-python, and the desktop or mobile application in pslab-app. That structure explains a lot about what follows, especially the bootloader warnings: the firmware and the bootloader are separate artefacts with separate flashing procedures.

The firmware targets hardware version 5 and version 6, stated in the first paragraph, and the primary language is C. The licence is Apache-2.0 with a `LICENSE` file at the root, and the default branch is `main`.

Hardware is sold through the FOSSASIA shop and a list of resellers on the PSLab website, and the project points at a Gitter chat channel and a PSLab mailing list on Google Groups for support.

Building needs a Microchip compiler that is not in any package manager

The build is CMake, and it needs two tools the README names: the xc16 compiler and cmake.

The first step after cloning is the toolchain submodule, because the Microchip toolchain is not vendored:

git submodule init
git submodule update

That populates `external/cmake-microchip`, which is the CMake glue for the vendor toolchain. Then the ordinary out of source build:

mkdir build
cd build
cmake ..
make

The artifact is `pslab-firmware.hex` in the `build` directory, which is the file every flashing method then consumes.

Hardware version 5 is selected with a CMake define rather than a branch:

cmake -DLEGACY_HARDWARE=true ..

That single flag is what makes one codebase target two board revisions, and it is also a trap: build without it and you have firmware for the wrong board.

Where xc16 comes from is the part that will cost you an hour. The `Dockerfile` in this repository answers it directly. It starts from `ubuntu:22.04`, installs cmake, make, git and wget, then downloads the Microchip installer directly:

RUN wget -qO- https://ww1.microchip.com/downloads/aemDocuments/documents/DEV/ProductDocuments/SoftwareTools/xc16-v2.10-full-install-linux64-installer.run \
    -O /tmp/xc16-installer.run && \
    chmod +x /tmp/xc16-installer.run && \
    /tmp/xc16-installer.run --mode unattended --prefix /opt/microchip/xc16/v2.10 --netservername "" && \
    rm /tmp/xc16-installer.run

So the toolchain is a vendor `.run` installer from Microchip, pinned to v2.10, installed unattended into `/opt/microchip/xc16/v2.10` with the licence server name blanked. It is not in apt and it is not a Python package. That is why the repository also ships a `.devcontainer/`: opening the project in VS Code, GitHub Codespaces or any other container aware editor offers a Reopen in Container action, and the container is stated to contain everything needed to build, run and test the project. For anyone without a Microchip account or a Linux box with the toolchain, the dev container is the practical path.

There is also a `Dockerfile` step that predates the dev container, so you can build the image yourself if you prefer not to use VS Code.

Two flashing routes, and one of them destroys the bootloader

The README documents a USB route and a programmer route, and then warns hard about the second one. That warning is the most valuable content in the document.

The USB route requires the bootloader to already be installed. Flashing uses mcbootflash, which can be installed standalone or comes as a dependency of pslab-python. The sequence on a version 6 board is: press and hold the BOOT button, press RESET, wait for the Status LED to blink, release BOOT, then run:

mcbootflash --port <portname> -b 460800 firmware.hex

The baud rate and the port name are both explicit, so this is a command you can copy and adjust rather than infer.

The programmer route is where the warning sits. Flashing only the firmware HEX with a programmer will OVERWRITE the bootloader, and the README's advice is that if you cannot flash over USB you should create a combined HEX file containing both the bootloader and the firmware and flash that instead, with instructions in the bootloader repository. That is a recoverable mistake only if you knew about it first, which is why the warning is a blockquote.

The programmer route also needs Microchip's MPLAB-X tooling. `mdb.sh` is part of that suite and sits at `/opt/microchip/mplabx/<version>/mplab_platform/bin/mdb.sh` by default on Linux. The repository ships `flash.mdbscript` in its root, and the README warns that you may need to edit that script depending on which programmer you have and where your HEX lives. That is an admission the script is not universal.

The physical sequence for the programmer route is short: disconnect power, connect the programmer to the ICSP header, power the device from USB, run `mdb.sh flash.mdbscript`, disconnect the programmer. Powering from USB while the programmer is attached is the part that looks wrong and is correct.

The v5 has no BOOT button, so you short two pins with a paper clip

There is a hardware difference between the two supported revisions that has a software consequence, and the README handles it as its own section.

The PSLab v5 lacks the BOOT button used to enter bootloader mode on the v6. The pin wired to that button on the v6 is present on the v5, so entering bootloader mode is possible by bridging pins.

The procedure is specific enough to follow without a schematic. With the USB port at the top left of the board, the fifth pin on the left side of the MCU is the BOOT pin counted from the top, and immediately below it, sixth from the top, is a conveniently located GND pin. The repository ships a diagram at `docs/images/bootloader_v5.png` showing both.

Bridge those two pins by touching both at once with a small piece of metal such as the tip of a jump wire or a paper clip, then reset or power cycle. The v5 also lacks a RESET button, so the soft reset goes through the Python library:

import pslab
pslab.ScienceLab().reset()

The pins must be bridged at the moment of the reset, not before it. If you did it correctly the SYSTEM LED starts blinking, which is the indicator of bootloader mode.

There is a precondition note that is easy to miss: the PSLab v5 does not come with the bootloader preinstalled, so these steps do nothing until you have installed the bootloader as described in the bootloader repository. Combined with the earlier warning that programming overwrites the bootloader, the v5 story is a specific order of operations. Install the bootloader first, use USB flashing from then on, and never reach for the programmer on a v5 unless you are deliberately writing a combined HEX.

The whole stack is on an Apache-2.0 footing, with a `LICENSE` file, a `CHANGELOG.md`, `flash.mdbscript`, `.clang-format` and `.clang-tidy` at the root, and a `docs/` directory. The repository is not archived, and the last push was on 2026-08-28. The visible release history is inconsistent, with 3.0.4 in January 2025, 3.1.0 in February 2025 and then 2.0.1 in August 2025, so read the CHANGELOG rather than trusting the tag numbers to order the history.

Editorial conclusion

Adopt this firmware only if you have PSLab hardware, since it targets specific board revisions rather than general microcontrollers and supports version 5 and version 6 with a compile time switch for the older board. Do not flash the pure firmware HEX with an ICSP programmer unless you intend to lose the bootloader, and prefer the combined HEX described in the bootloader repository. Verify first which hardware revision you have, whether the bootloader is already installed, and that the xc16 compiler version in the Dockerfile, v2.10, matches what your build environment provides.

Frequently asked questions

Official sources

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