How to Load a .hex or .bin File into PICSimLab

PICSimLab does not run source code. It runs compiled firmware — the .hex file (or, on some paths, a .bin file) that your compiler produced. Loading sounds trivial, and it is, provided one rule is respected: the board and microcontroller selected in PICSimLab must match the chip the firmware was built for. Most “it loads but does nothing” reports trace back to that single mismatch.

Where the file comes from

  • PIC (PIC16F / PIC18F): build the project in MPLAB X with the XC8 compiler; the build output folder contains the .hex. See the MPLAB X + XC8 workflow.
  • AVR, STM32, ESP32: the Code Project Wizard generates VSCode + PlatformIO projects for these boards; PlatformIO builds produce the firmware file to load. The command-line helper picsimlab_tool can also upload a file directly — its documented form is picsimlab_tool file [.hex or .bin] — and it integrates with PlatformIO. See the PlatformIO / Arduino IDE workflow.
  • Online version: files are loaded by drag and drop or the Load button in the browser, as .hex, .pzw (workspace) or .pcf (spare-parts configuration). See PICSimLab Online.

The loading order that works

  1. Select the board first. Pick the board your project targets (for example McLab2 for a PIC16F877A project).
  2. Select the exact microcontroller. Set the chip to the one the firmware was compiled for — PIC16F877A firmware on a PIC18F4550 selection is a mismatch even though both sit on the same board list.
  3. Load the file. Use the load/open control to point PICSimLab at the freshly built .hex (or .bin where that is the build output). If you rebuilt after a code change, reload — the simulator keeps running the old file until you do.
  4. Run. Start the simulation and check for the expected behaviour: an LED state change, output on a spare part, characters in the terminal.

Three checks before you blame the simulator

  • Did the build actually succeed? A failed compile can leave a stale .hex from an earlier, different project in the output folder. Rebuild cleanly and confirm the file’s timestamp is new.
  • Is the clock consistent? If your code uses delays based on a clock define such as _XTAL_FREQ, it must match the clock configured for the board in PICSimLab, or everything runs at the wrong speed.
  • Are you loading the right file type? A .pzw is a saved workspace and a .pcf is a spare-parts configuration — neither is firmware. The firmware itself is the .hex / .bin.

Still stuck — the file will not load, or loads with no visible effect? Work through the dedicated troubleshooting guide: PICSimLab hex file not loading. If the file loads and the board is selected correctly but the simulation itself will not run, see simulation not running instead. And if you have not run anything yet, start with the first simulation walkthrough, which uses a built-in example so the firmware side is known-good.

Similar Posts