PICSimLab and the strange business of emulating a whole development board

A board emulator, not a chip simulator

PICSimLab is described as a realtime emulator of development boards, with MPLABX and avr-gdb debugger integration. The word board is the whole point, and it is what separates this project from the simulators it is built on.

A chip simulator takes the instruction set of a microcontroller and executes it. A board emulator also has the parts wired to the chip: the LEDs, the push buttons, the displays, the serial lines, the ethernet shield, the USB port. PICSimLab models those as spare parts that can be connected to the board, with the documentation holding the complete list.

The scale of that list is what makes the project useful for teaching and for hardware-less development. Some parts are trivial, like example LEDs and push buttons for simple outputs and inputs. Others are considerably more involved, such as the w5500 ethernet shield for internet connectivity, and the ili9340 colour graphic display with touchscreen. If a course needs a student to drive a graphical display with touch input, emulating the board means the student writes the same firmware they would write on the desk, and the same peripheral driver works on the real thing later.

The supported device families are listed in the project topics and in the simulator list, and they span the whole embedded hobbyist range: PIC16 and PIC18, AVR, STM32, ESP32 including the esp32c3, and Arduino boards built on those cores.

The repository is GPL-2.0 licensed and not archived, with the last push on 2026-10-12. The homepage points at the repository itself, and there is a published documentation site with separate user and developer sections, an examples index, an online version of the simulator, a changelog and a TODO list.

Six simulators under one board model

PICSimLab does not implement the microcontrollers itself. It supports microcontrollers from a set of existing simulation projects, and the list is the clearest way to understand what the tool can and cannot do.

For PIC there is picsim, the author's own project. For AVR there is simavr, and the project links both the original by buserror and a modified version used by PICSimLab. For the 8051, STM8 and Z80 there is ucsim, again linking the original and a modified copy. For STM32 there is qemu-stm32, and for ESP32 there is qemu-esp32, both from the upstream projects with PICSimLab specific forks linked for the STM32 case.

Then there is gpsim, also listed among the supported microcontroller sources.

This architecture has an important consequence for how you debug a problem, and the project is explicit about it. The simulation consists of three parts: the microcontroller program, the microcontroller simulation made by picsim and simavr, and the simulation of boards and parts. When something goes wrong you need to work out which layer is at fault, and the project gives you a procedure for it.

For each layer there is a suggested action. The most common problem is an error in the microcontroller program, and before creating an issue you should test your code on a real circuit, even partially, to make sure the problem is not there. Errors in the microcontroller simulation can be detected using code debugging, and any instruction execution or peripheral behaviour outside the expected should be reported in the project of the simulator used, whether that is picsim or simavr. If neither of the first two is the cause, the problem is probably in PICSimLab itself, and a good practice is to send a source code together with a PICSimLab workspace, a .pzw file, with the issue.

That .pzw file convention is worth remembering. A workspace file makes a bug report reproducible, which is the difference between a report that gets fixed and one that stalls.

No code editor, on purpose

The most unusual decision in the project is a missing feature. As the purpose of PICSimLab is to emulate real hardware it does not have any source code editing support.

The reasoning is stated directly: for code editing and debugging the same tools used for a real board should be used with PICSimLab, such as MPLABX, Arduino IDE, or VSCode with PlatformIO.

This is a coherent position rather than an omission. The moment the simulator contains its own editor, the firmware you debug in it is no longer the firmware you will flash, and the debugger integration that the project advertises becomes a fiction. By keeping the editor outside, the same project file, the same toolchain and the same debug configuration are used for the simulated board and the physical one.

The debugger integration is what makes that workable. MPLABX and avr-gdb attach to the simulator, so you can single step, set breakpoints and inspect variables inside the emulated chip, using the workflow you would use on the bench. The emulated board behaves like the real board as far as the debugger is concerned.

The trade-off is obvious. If you want a single self-contained application in which you type code, compile it and watch it run on a simulated board, this is not it, and a general purpose simulator with its own toolchain integration would serve better. If you already write firmware in MPLABX, Arduino IDE or PlatformIO and want to try it without the hardware, the arrangement is exactly right.

The Code Project Wizard generates projects for the right toolchain

If the simulator does not edit code, something has to set up the project that the external IDE will open. That is what the Code Project Wizard is for, and it is described as letting you quickly create pre-configured code templates for both writing and debugging a wide range of boards.

The generated project depends on the chip family, and the mapping is explicit. For boards based on the PIC16F and PIC18F microcontrollers, the wizard generates projects that use MPLAB X. For boards based on AVR, STM32 and ESP32, the wizard generates projects that use VSCode with PlatformIO.

That split follows the same logic as the no-editor decision. A PIC developer gets a project that MPLAB X can open directly, with the device and configuration already set. An AVR, STM32 or ESP32 developer gets a PlatformIO project, which is the ecosystem those cores are normally developed in. The wizard is doing the part of the work that the simulator refuses to do, and doing it per vendor.

The board list is documented separately, and the spare parts list is documented too, so the two things you need to check before starting a project are both available: whether the board you have in mind is emulated, and whether the peripheral you want to use is modelled.

There is also an online version of the simulator, linked from the documentation, and an examples index, so the fastest way to judge the project is to open a worked example rather than to build a firmware project from nothing.

Building from source has four documented paths

Release executables are published for Linux, macOS and Windows on the GitHub releases page, and there is a separate tag for the latest code build that is explicitly labelled unstable, carrying the unreleased features listed in an automatically generated changelog. If you need a specific binary that is not available, the project says to contact the author.

Building from source is the alternative, and the documentation covers four cases.

On Debian Linux and derivatives, the native build is a clone, a dependency install script and a build and install script:

git clone --depth=1 https://github.com/lcgamboa/picsimlab.git
cd picsimlab
bscripts/install_deps.sh
bscripts/build_all_and_install.sh

Recompiling afterwards is a plain parallel make:

make -j$(nproc)

Cross compiling for Windows from Linux or WSL has its own script, build_w64.sh for 64-bit targets and build_w32.sh for 32-bit, each followed by a recompile command that selects a different makefile with the FILE variable:

make FILE=Makefile.cross -j$(nproc) 

The macOS path was contributed by a contributor named @valentingorelov and uses a different pair of scripts, one to build and install and one to produce the application bundle and disk image:

git clone --depth=1 https://github.com/lcgamboa/picsimlab.git
cd picsimlab
bscripts/build_all_and_install_macos.sh
bscripts/make_macos_bundle_and_dmg.sh

The root Makefile shows how the pieces fit together. It dispatches to a set of subdirectories, and the subdirectory list names the tools that ship with the simulator:

FILE=Makefile


SUBDIRS= src tools/espmsim tools/srtank tools/PinViewer tools/picsimlab_tool

Those tool names hint at the surrounding toolchain, with an ESP32 simulator tool, a logic analyser tool, a pin viewer and the main application.

The distribution warning is worth taking seriously

The repository description and the documentation both carry the same warning: the official distribution of the PICSimLab simulator binaries is available on github.com and SourceForge.net, and readers should be cautious of unofficial sites, such as picsimlab.com, which do not disclose the owner.

It is unusual to see a project warn against its own name in this way, and the reason is worth stating plainly. A simulator is a binary you download and run that runs with wide access to your filesystem, often to flash or inspect a microcontroller, and a project that ships a working build on GitHub and SourceForge has no way to control what an unrelated domain does with a lookalike build. The warning is a supply chain notice rather than a technical one, and the practical rule is simple: take the binaries from the GitHub releases or from SourceForge, and treat any other site as unverified regardless of how official it looks.

The rest of the project information follows the same pattern of pointing at primary sources. The documentation site carries the stable documentation, the development documentation is separate, and the changelog and TODO list live in the repository. The library and project list in the documentation is explicitly all free software, which matters for an educational tool: wxwidgets for the graphical interface, lxrad as a graphic library, lunasvg for SVG support, and the family of modified simulators described above, with the original upstream projects and the modified versions PICSimLab uses both linked.

The licence is GPL-2.0, with the COPYING file in the repository root. For a teaching tool distributed with source, that is the expected arrangement, and for anyone who wants to modify and redistribute it the copyleft terms are the terms to read.

Where PICSimLab is the wrong tool

The first wrong case is firmware development rather than firmware testing. If your goal is to write and debug a program for a chip you do not have, a simulator that is designed around an external IDE is a step sideways. You still need the vendor toolchain, and you have added a layer between you and the hardware. For a student learning a new chip, that layer is often the point, because the same code then runs on a real board. For a professional with a board on the desk, it is not.

The second wrong case is a peripheral that is not modelled. The list of spare parts is extensive but finite, and the risk is that a project depends on a specific part, or on a timing behaviour of a part, that the simulation approximates rather than reproduces. The consequence is a firmware that passes in simulation and fails on the bench, which is worse than not having a simulator at all. This is why the project's own troubleshooting guidance starts by testing on a real circuit, even partially.

The third is a project that needs timing fidelity, power measurement or anything else physical. A realtime emulator runs the processor fast enough to feel live, but it models a board, not a power rail, not a signal integrity problem, and not a peripheral bus at its real edge cases.

The realistic alternative is to use the vendor's own simulator, or a bare-metal emulator, or QEMU's machine models directly. The difference in approach is instructive. A vendor simulator is coupled to one chip family and one toolchain, and it is the most faithful to that silicon. A board emulator such as PICSimLab is broader, wrapping several simulator cores behind a common peripheral model so that a course can use the same environment for PIC, AVR, STM32 and ESP32 without students learning four different tools. The breadth is bought at the cost of fidelity, since each wrapped core is only as good as its own model of that chip, and the peripherals are PICSimLab's approximation rather than the manufacturer's.

For a teaching lab, that trade is usually the right one. For a firmware engineer with the hardware in hand, it usually is not.

Editorial conclusion

PICSimLab fits an embedded student or developer who wants to run a firmware project against a simulated board, with a debugger attached, without owning the hardware. It is the wrong tool if you need to write firmware inside it, because the project states that it has no source code editing support by design, and it is the wrong tool for a peripheral that the simulation does not model. Before you rely on it, check the spare parts list in the documentation for the peripheral you need, build from source only if the release binaries do not cover your platform, and get your binaries from the GitHub releases or SourceForge, since the project explicitly warns about unofficial sites.

Frequently asked questions

Official sources

1. lcgamboa/picsimlab on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases