You started your GDB, typed target remote localhost:1234, and got a refusal — or worse, a silent hang. In PICSimLab, remote GDB debugging only exists for some backends, only after you switch it on inside the simulator, and only with the matching GDB flavour for your chip family. This page sorts all three conditions, backend by backend.

Symptoms

• target remote localhost:1234 (or target extended-remote localhost:1234) fails with “connection refused”.
• The wrong GDB binary connects oddly, errors immediately, or cannot make sense of the target.
• You cannot find any GDB option for your board at all — notably on the uCboard or the gpboard.
• Debugging worked in MPLAB X but the command-line GDB flow does not (or the reverse).

Why it happens

Debug was never enabled in PICSimLab. The shared pattern in the official documentation for every GDB backend is: first open PICSimLab’s configuration window, enable debug and select GDB, and only then connect. With debug off, nothing listens on port 1234 and every connection is refused — the most common cause by far.

Each backend has its own debugger. There is no single “PICSimLab GDB”. Per the official Boards/backend documentation:

So two “failures” are actually correct behaviour: pointing GDB at a uCboard can never work (its remote debug is a telnet console), and the gpboard has no debugging support yet at all. Two port traps complete the picture: the MPLAB X plugin also uses port 1234 (a separate path — running both at once invites a clash), while PICSimLab’s rcontrol interface on port 5000 is not a debug port and GDB cannot talk to it. Finally, the official online version has no debugging support — GDB debugging is a desktop-version feature.

Fix

1. Confirm your backend is a GDB backend. GDB applies to simavr, qemu-stm32 and qemu-esp32 boards only. For PIC boards, use the MPLAB X path instead (see our MPLAB X plugin guide); for the uCboard, use its telnet console; for the gpboard, run without a debugger.
2. Load the board and firmware in PICSimLab first, using the desktop version, with the simulation ready.
3. Enable debug in the configuration window and select GDB (as opposed to any other debug option). This is the step that opens the listener on port 1234.
4. Start the matching GDB with your .elf file as its argument — avr-gdb for AVR boards, arm-none-eabi-gdb (or gdb-multiarch) for the STM32 boards, xtensa-esp32-elf-gdb for the ESP32 boards — then connect with target extended-remote localhost:1234 (the STM32 documentation uses the extended-remote form; the AVR/ESP32 flows use the same localhost:1234 endpoint). Using the .elf (not the .hex) is what gives GDB your symbols.
5. If the connection is still refused: confirm the port in the configuration window is actually 1234 (it can be changed), confirm no firewall is dropping the localhost connection, and close anything else holding port 1234 — most often an MPLAB X plugin session — before retrying.
6. Do not substitute ports. If you find yourself typing port 5000 into GDB, stop: 5000 is rcontrol, the text-command remote control for the simulator itself (start/stop, loadhex, pin inspection). It is a useful tool, but it is not a debug server.

Still stuck?

Cross-check your flow against the MPLAB X plugin guide if your board is a PIC board (that, not GDB, is its debug path), and against a known-good board/firmware combination from the blink tutorial to separate “simulator not running” from “debugger not connecting”. If debug is enabled, the backend and GDB flavour match, and localhost:1234 still refuses on the desktop v0.9.3, report it — backend, board, GDB flavour and the exact GDB error included — on the project’s tracker: github.com/lcgamboa/picsimlab/issues.

PICSimLab v0.9.3 gives Linux users three routes — a .deb package, a Flatpak, and an AppImage — and each fails in its own characteristic way: dependency errors from the .deb, a double-click that does nothing from the AppImage, or an installed program that cannot reach serial devices. This page untangles which route you are on and fixes that route’s problem. (For the clean install sequence itself, see our Ubuntu & Debian installation guide.)

Symptoms

• The .deb refuses to install, ending in unmet-dependency errors.
• The AppImage does not start on double-click — nothing appears at all.
• The Flatpak bundle will not install, or PICSimLab is nowhere to be found afterwards.
• PICSimLab installed and runs, but serial devices (/dev/tnt*) cannot be opened.
• The NOGUI AppImage “does nothing” — no window ever appears.

Why it happens

There are two different .deb files, and they are release-specific. The project publishes one build for Ubuntu 24.04 (PICSimLab_0.9.3_260920_Ubuntu_24.04.5_LTS_amd64.deb) and a separate one for Ubuntu 22.04 (PICSimLab_0.9.3_260920_Ubuntu_22.04.5_LTS_amd64.deb). Installing the 24.04 package on a 22.04 system (or the reverse) is the most common source of dependency errors — the package is being asked to fit a system it was not built for. A second, general package-management point: installing a .deb with a low-level tool alone does not fetch missing dependencies; installing the same file through apt does.

AppImages need the execute permission — and sometimes FUSE. This is general AppImage knowledge, not PICSimLab-specific: a downloaded AppImage is not executable until you set the execute bit, so a double-click silently does nothing. Some systems also lack the FUSE runtime AppImages use to mount themselves, in which case the file is executable but still will not start from the desktop; running it from a terminal shows the actual error message either way.

Serial devices are permission-gated. PICSimLab’s Linux serial support uses tty0tty virtual devices (/dev/tnt2 <=> /dev/tnt3 etc.). Like real serial devices, those files are owned with restricted permissions; if your user account cannot read and write them, the program cannot open the port no matter how correct everything else is.

The NOGUI build has no window by design. PICSimLab_NOGUI-0.9.3_260920_Ubuntu_22.04.5_LTS_x86_64.AppImage is a terminal-only build — per the official release notes it must be used on a terminal together with the remote control interface (rcontrol, default TCP port 5000). Starting it and waiting for a GUI is a category error, not a crash.

Fix

1. Match the .deb to your release. Check your Ubuntu version (lsb_release -a in a terminal — general system knowledge) and download the matching package from our PICSimLab for Linux page: the 24.04 .deb (SHA-256 89510e3d917fa9cb19c8dde5b2facdbd0ee4a50422ba3ba487b201c6f2046fa7) or the 22.04 .deb (SHA-256 1862c3e78e99d427b854083d7ce1ab4a3e86023348150bdb695bc381f72921f1). Verify with sha256sum before installing.
2. Install the .deb through apt so dependencies resolve: sudo apt install ./PICSimLab_0.9.3_260920_Ubuntu_24.04.5_LTS_amd64.deb (adjust the file name to your build). apt pulls the libraries the package needs; a bare dpkg -i does not.
3. On a non-Ubuntu or mismatched system, switch routes instead of fighting dependencies. The Flatpak (picsimlab_Linux_0.9.3_260920.flatpak) installs with flatpak install picsimlab_Linux_0.9.3_260920.flatpak and is the comfortable route off the two supported Ubuntu releases; the AppImage needs no installation at all. The simulator in all three is the same program.
4. Fix the AppImage launch. Run chmod +x PICSimLab-0.9.3_260920_Ubuntu_22.04.5_LTS_x86_64.AppImage, then start it from a terminal (./PICSimLab-0.9.3_260920_Ubuntu_22.04.5_LTS_x86_64.AppImage) so any error is visible. If the terminal points at FUSE, install your distribution’s FUSE package (general AppImage requirement) and retry — or fall back to the Flatpak route.
5. Fix serial device access. After installing tty0tty, make sure your user can read and write the /dev/tnt* devices it creates: check the device permissions, add your account to the group that owns serial devices if needed (on mainstream distributions serial devices are conventionally group-gated), then log out and back in so group changes take effect, and test again. Our virtual serial ports guide covers the pair setup itself.
6. For the NOGUI build, drive it from the terminal. Start the NOGUI AppImage in a terminal and control it through rcontrol (connect to port 5000 with telnet or nc and use its text commands, e.g. to load a .hex and start the simulation). If you wanted a window, install one of the GUI builds instead — there is no Windows or macOS NOGUI build; it exists only as this Linux AppImage.

Still stuck?

Work through the Ubuntu & Debian installation guide route by route, with the file table on the Linux download page open beside it. If the release-matched .deb installed through apt — or the Flatpak — still will not run on v0.9.3, report it with your distribution and release, the route you used, and the terminal error text, on the project’s tracker: github.com/lcgamboa/picsimlab/issues.

You downloaded the new native macOS build of PICSimLab v0.9.3, dragged it into Applications — and macOS will not open it: a warning dialog, a refusal, or nothing at all. Almost every case is one of two things: Gatekeeper doing its standard job on an internet-downloaded app, or the wrong one of the two .dmg builds for your Mac. Both are quick to fix.

Symptoms

• Double-clicking PICSimLab shows a dialog saying macOS cannot open it or cannot verify it, and the app never starts.
• The app icon appears in Applications but launching it does nothing, or it quits immediately.
• A message suggests the app is damaged and should be moved to the Trash.

Why it happens

Gatekeeper. This is standard macOS behaviour — general Mac knowledge, not a PICSimLab-specific fault: the first time you open an app downloaded from the internet, macOS checks it and, for apps that arrive outside the App Store, asks you to confirm the first open explicitly instead of just double-clicking. A plain double-click can therefore look like a refusal even though the app itself is fine.

The wrong .dmg for your chip. PICSimLab v0.9.3 ships two macOS builds, and they are not interchangeable: PICSimLab_0.9.3_260920_macOS_26.6.1_x86_64.dmg for Intel Macs and PICSimLab_0.9.3_260920_macOS_26.6.2_arm64.dmg for Apple Silicon (M-series) Macs. The arm64 build cannot run on an Intel Mac and vice versa — picking the wrong file produces exactly the “won’t open” symptom with no useful explanation. Both files, with sizes and SHA-256 checksums, are listed on our PICSimLab for macOS page.

An incomplete download. A truncated .dmg (interrupted download, proxy interference) can trigger the harsher “damaged” wording from macOS. That message is macOS’s generic response to a file that fails its integrity checks — re-downloading, not repairing, is the fix.

Fix

1. Check your chip first. Open the Apple menu → About This Mac. An Apple M-series chip means you need the arm64 .dmg; an Intel processor means the x86_64 .dmg. If you installed from the other file, delete that copy and download the correct one from the macOS download page.
2. Verify the checksum before you bypass anything. In Terminal, in your Downloads folder, run shasum -a 256 <file>.dmg and compare it with the value on the download page: 46cae7379b3828d771feefcaeb040f87d02ffbd5bd160dcda6152c8fa14b8b00 for arm64, cb6af4651fe811dab3088667f34f3d0495960ec6b0bb4627f44f73a21386d07b for x86_64. Only proceed past Gatekeeper prompts for a file whose checksum matches — that is what makes the next step safe.
3. Install cleanly. Open the .dmg and drag PICSimLab into your Applications folder, then eject the disk image.
4. Open it the Gatekeeper way: right-click → Open. In Applications, right-click (or Control-click) PICSimLab and choose Open, then confirm in the dialog. This explicit confirmation is the standard first-open path for downloaded apps.
5. Or use Open Anyway. If the app was blocked on a previous attempt, open System Settings → Privacy & Security, scroll to the note about PICSimLab being blocked, and choose Open Anyway, then confirm once more.
6. If macOS insists the app is “damaged”: delete the app and the .dmg, re-download the correct build (step 1), verify the checksum (step 2) and repeat. A verified, complete file does not produce this message; do not go hunting for settings to disable the check instead.

After the first successful open, PICSimLab launches normally from Applications like any other Mac app — the confirmation is a one-time gate, not a per-launch tax. Our macOS installation guide covers the same steps in install order.

Still stuck?

Redo the sequence with the step-by-step macOS installation guide and the file table on the macOS download page. If a checksum-verified build for the correct chip still will not open after the right-click Open on v0.9.3, report it — your Mac chip, the exact dialog text and the macOS version included — on the project’s tracker: github.com/lcgamboa/picsimlab/issues.

Your ESP32 project flashes — or appears to — and then the simulated board will not boot: it loops, stalls, or shows nothing, even though the same firmware runs on a real DevKitC. With PICSimLab’s QEMU-based ESP32 boards there is one documented limitation behind most of these failures, and it is in the build settings, not in your code.

Symptoms

• Flashing with esptool seems to complete, but the ESP32-DevKitC board in PICSimLab never starts the program.
• The firmware boots on real ESP32 hardware but not in the simulator (or the reverse confusion: an old image boots, a newly built one does not).
• Boot problems started right after changing flash settings, switching board definitions, or moving from the Arduino IDE default profile to a custom partition/flash configuration.

Why it happens

PICSimLab’s ESP32 boards — only two exist, the ESP32-DevKitC and the ESP32-C3-DevKitC-02 — run on the qemu-esp32 backend. The official documentation carries an explicit warning for this backend, worth quoting in full: “Qemu ESP32 don’t support the QIO and QOUT flash modes, use only DIO or DOUT flash modes.” An image built for QIO or QOUT flash access asks the emulated flash to behave in a way QEMU does not implement, so the bootloader cannot read the application correctly and the board never reaches your code. On real hardware the same image is perfectly fine, which is exactly why this failure is so confusing.

The second part of the picture is the flashing path itself. Per the official documentation, you flash PICSimLab’s ESP32-DevKitC as if it were a real ESP32 board, using the Arduino IDE or the ESP-IDF esptool.py over the serial connection. That means the desktop serial prerequisite applies here too: the simulated serial port reaches your tools through a virtual null-modem pair (com0com on Windows, tty0tty on Linux, format 8N1) — if that path is broken, flashing fails before flash modes even matter. All files and builds are listed on our Download page.

Fix

1. Set the flash mode to DIO (or DOUT). In the Arduino IDE, choose the DIO flash mode in the board settings for your ESP32 target; in ESP-IDF, set the flash mode to DIO or DOUT in the project configuration (menuconfig → serial flasher config). Do not use QIO or QOUT for any image you intend to run in PICSimLab.
2. Rebuild completely after changing the mode. A flash-mode change only takes effect in a fresh build. Clean and rebuild the project so the bootloader and application image are regenerated with the new mode — flashing only the application partition from a QIO build keeps the broken combination alive.
3. Select the matching board in PICSimLab. Use ESP32-DevKitC for classic ESP32 firmware and ESP32-C3-DevKitC-02 for ESP32-C3 firmware; the two are different chips (the C3 is a RISC-V part) and their images are not interchangeable.
4. Flash over the serial path, esptool-style. With the virtual serial pair in place (PICSimLab on one end, your flashing tool pointed at the other end), flash the rebuilt image with the Arduino IDE upload or the IDF/esptool.py flow, exactly as you would for a real board. If the port itself will not connect, fix that first with our virtual serial ports guide.
5. Start the simulation and watch the boot. Reset the board after flashing completes. A DIO/DOUT image should now run through the bootloader into your application.
6. Sanity-check with a minimal program. If a full project still will not boot, flash the smallest blink-style example built with DIO mode. If the minimal image boots, the remaining problem is inside the full project’s configuration (partition or flash settings are the first suspects); if even the minimal DIO image fails, re-check steps 3–4.

Still stuck?

For what the two QEMU ESP32 boards do and do not cover, see the ESP32-DevKitC board page. Confirm your toolchain basics against the Download page (PICSimLab itself) and the serial path in the virtual serial ports guide, and re-read the worked serial example in the PIC16F877A UART tutorial — the pair/8N1 discipline is identical. If a clean DIO build flashed over a verified serial path still will not boot on the correct ESP32 board in v0.9.3, report it — board, flash mode, and the esptool output included — on the project’s tracker: github.com/lcgamboa/picsimlab/issues.

You installed PICSimLab, opened your project in MPLAB X, started a debug session — and MPLAB X cannot connect to the simulator. The PICSimLab plugin talks to MPLAB X over a plain TCP socket, which makes this failure pleasantly mechanical: it is almost always the plugin not being installed, the port numbers disagreeing, or a firewall quietly dropping a localhost connection. (If the plugin is not set up at all yet, start with our MPLAB X plugin installation guide and come back here if the connection still fails.)

Symptoms

• MPLAB X reports it cannot connect to the PICSimLab tool, or the debug session fails immediately at connect time.
• The PICSimLab tool does not appear in MPLAB X at all.
• The connection worked before and stopped after a PICSimLab or MPLAB X update, or after moving the project to another PC.

Why it happens

Per the official documentation, the plugin file com-picsim-picsimlab.nbm lets MPLAB X debug and program PICSimLab (PICs and AVRs) by connecting through a TCP socket using port 1234 — or another port defined in the configuration window — and the documentation adds explicitly that you have to allow the access in the firewall. Three failure modes follow directly from that design:

• The .nbm is not installed (or a stale one from a different PICSimLab release is): MPLAB X then has no PICSimLab tool to connect with.
• The ports disagree: the port in PICSimLab’s configuration window and the port the MPLAB X side expects must be identical. Change one and not the other and the connection is refused, even though both programs are running.
• The firewall blocks it: a localhost TCP connection is still a TCP connection; a strict firewall profile can drop it silently, especially on first use or on a work-managed PC.

One naming trap: PICSimLab’s remote control interface (rcontrol) uses port 5000 by default — a different feature for controlling the simulator with text commands. Do not enter 5000 where the plugin expects its debug port; the plugin port is 1234 unless you changed it in the configuration window.

Fix

1. Confirm the .nbm is installed, from the matching release. In MPLAB X, open Tools → Plugins and check the Downloaded/Installed lists for the PICSimLab plugin. If it is missing, install com-picsim-picsimlab.nbm from the same PICSimLab release you run (for v0.9.3 the file is 27,091 bytes) following our plugin guide, then restart MPLAB X.
2. Start PICSimLab first, with a board loaded. The plugin connects to a running simulator. Launch PICSimLab, select your board and load the firmware before starting the MPLAB X debug session.
3. Make the ports match. Open PICSimLab’s configuration window and note the plugin/debug port (default 1234). Confirm the MPLAB X side is set to the same number. If you changed the port at some point, change it in both places or reset both to 1234.
4. Allow the connection in the firewall. Accept the firewall prompt if one appears when the first connection is attempted; if no prompt appears and the connection still fails, add an allow rule for PICSimLab / TCP port 1234 for the local network. Both programs run on the same PC — never forward this port on your router.
5. Rule out a port clash. Only one listener can own port 1234 at a time. Close anything else that may be holding it — most commonly a leftover GDB debug session, which uses the same default port in PICSimLab (see our GDB connection guide on this site) — then retry.
6. Retry the debug session with PICSimLab running and idle (not mid-reset), and confirm MPLAB X now connects, programs the simulated device and halts at your first breakpoint.

Still stuck?

Redo the setup from scratch with the MPLAB X plugin guide, then try the connection pattern on a known-good project such as the PIC18F4550 first project. If a matching-plugin, matching-port, firewall-allowed setup still refuses to connect on v0.9.3, report it — MPLAB X version, PICSimLab version and the exact error text included — on the project’s tracker: github.com/lcgamboa/picsimlab/issues.

Your simulated UART is silent: the terminal window shows nothing, or shows garbage, or the port will not open at all. In PICSimLab this is rarely a firmware bug. The desktop simulator’s serial port does not connect to a real COM port by itself — it needs a piece of operating-system setup first, and three settings after that. This page covers all of them.

Symptoms

• The serial terminal stays empty even though the program is running and should be transmitting.
• Received text is garbled or framed wrong.
• Your terminal program cannot open the port, or PICSimLab cannot open its end.
• Serial works with PICSimLab’s built-in virtual terminal but not with your external terminal program (or the other way round).

Why it happens

The virtual port pair is missing. Per the official documentation, desktop serial simulation in PICSimLab requires a NULL-MODEM virtual serial port pair: on Windows that pair is created by com0com, on Linux by tty0tty (which creates linked devices such as /dev/tnt2 <=> /dev/tnt3). PICSimLab opens one end of the pair and your terminal opens the other. Without the pair installed, there is simply nothing for either side to connect to — this is the single most common cause.

Both programs are on the same end. A pair only works when the two programs sit on opposite ends. Two programs on the same end hear nothing (and usually one of them fails to open the port at all, because a port end can only be opened once).

Format or baud mismatch. The link format is 8N1 (8 data bits, no parity, 1 stop bit), and the baud rate in the terminal must equal the baud rate the firmware was written for. A wrong baud rate is the classic cause of garbled text.

IO UART vs IO Virtual term confusion. PICSimLab has two different serial-related spare parts. The IO UART part (in the Others category of Modules → Spare parts) bridges the microcontroller’s UART to a serial port — this is the one that needs the virtual pair above. The IO Virtual term part (in the Virtual category) is a terminal that lives entirely inside the simulation: it needs no operating-system port at all, but it also cannot talk to external programs. Expecting the external path from the virtual terminal — or a virtual-pair setup from the built-in terminal — produces exactly the “nothing arrives” symptom. Note also that the official online version has no serial communication support at all (only the IO Vterm), so an external-terminal setup can never work there; use the desktop version.

Fix

1. Install the pair driver. Windows: install com0com and create a dedicated pair (for example COM10/COM11). Linux: install tty0tty and note the pair it creates (for example /dev/tnt2 <=> /dev/tnt3). Our virtual serial ports guide walks through both setups.
2. Put the programs on opposite ends. Configure PICSimLab’s serial port to one end (say COM10 or /dev/tnt2) and open the other end (COM11 or /dev/tnt3) in your terminal.
3. Match the settings. Set the terminal to 8N1 and the exact baud rate your firmware uses. If text arrives garbled, the baud rate is wrong — this symptom is diagnostic, not random.
4. Make sure the firmware really transmits. The simulation must be running, the loaded .hex must actually initialise and use the UART, and the UART pins must reach the serial connection on the selected board. A minimal known-good reference is our PIC16F877A UART tutorial, which runs at 9600 8N1.
5. On Linux, check device permissions. If opening /dev/tnt* fails with a permission error, your user account is not allowed to read/write those device files. Fix the tty device permissions or group membership for your account first (logging out and back in after a group change), then retry — this is a general Linux serial-device rule, not a PICSimLab setting.
6. Or simplify: use the virtual terminal. If you only need to see what the firmware sends, add the IO Virtual term spare part instead of the IO UART part and skip the OS-level setup entirely.

Still stuck?

Re-check the setup end-to-end against the virtual serial ports guide and the worked example in the PIC16F877A UART tutorial. If a correct pair at matching 8N1 settings still passes nothing with the tutorial firmware on the desktop version, report it — operating system, pair driver, board and baud rate included — on the project’s tracker: github.com/lcgamboa/picsimlab/issues.

The firmware loads, you press run — and the board just sits there. No blinking, no output, no reaction to buttons. A dead-looking simulation in PICSimLab is usually one of four things: the simulation is not actually running, the board is held in reset or mis-clocked, the selected microcontroller does not match the firmware, or a saved workspace (.pzw) is restoring a broken configuration. Work through them in order.

Symptoms

• The simulation window opens and the board is drawn, but nothing ever changes.
• A program that visibly worked yesterday does nothing today, with no code changes.
• Code runs, but absurdly slowly — a one-second blink takes many seconds.
• Inputs (buttons, spare parts) have no effect at all.

Why it happens

The simulation is stopped or the board is in reset. PICSimLab can sit in a stopped state with the board fully drawn; a board held in reset executes nothing, just like real hardware.

Clock mismatch. PICSimLab boards have a configured crystal/clock, and PIC firmware is normally built with a matching assumption (in XC8, the _XTAL_FREQ value used for delay calculations). If the code assumes 20 MHz but the board is configured for a much lower clock, delays stretch by the same factor and a lively program can look frozen. The mismatch does not stop the CPU — it makes everything happen in slow motion.

Wrong microcontroller selected. If the selected board is set to a different MCU than the one the .hex was compiled for, the loaded firmware does not correspond to the simulated chip and the board stays inert (see also our guide on .hex files not loading — searching this site for “hex file not loading” finds it).

A corrupted or mismatched workspace. A .pzw workspace file saves the board, its configuration and the loaded setup. If that file was saved from a different board setup, or was damaged, reopening it can faithfully restore a configuration in which nothing works — the file loads fine, the setup it describes does not.

Fix

1. Start the simulation and pulse reset. Make sure the simulation is in the running state, then reset the board once and watch for the program’s start-up behaviour (most example programs blink or initialise outputs immediately).
2. Verify board + MCU against the firmware. The selected board and microcontroller must be exactly the chip the .hex was built for. After any board change, load the .hex again.
3. Check the clock. Compare the board’s configured crystal frequency with the frequency your code was built for (for XC8 projects, the _XTAL_FREQ define). Align them — either set the board clock to the value the code expects, or rebuild the code with the board’s frequency — and re-test: correct timing returning is the confirmation.
4. Recover from a bad workspace. Close PICSimLab, reopen it without loading your .pzw file, select the board and microcontroller manually, load the .hex fresh, and re-add any spare parts (or reload the parts configuration, .pcf, if you saved one). If the simulation now runs, the old workspace was the problem: save a new workspace from this working setup and discard the old file.
5. Prove the setup with a minimal program. Run the PIC16F877A blink tutorial on McLab2 or PICGenios, and if you need to see whether the CPU is toggling pins at all, probe a pin with the built-in oscilloscope as shown in Using the PICSimLab Oscilloscope. A clean square wave there means the simulation is running and the issue is in your program’s logic, not the simulator state.

Still stuck?

The blink tutorial and the oscilloscope walkthrough give you a known-good baseline to compare against. If a fresh manual setup (no .pzw) with matching board, MCU and clock still will not run the official-style blink example on v0.9.3, report it — board, MCU, clock setting and version included — on the project’s tracker: github.com/lcgamboa/picsimlab/issues.

You built your firmware, opened PICSimLab, loaded the .hex file — and nothing happened. Either the load itself fails, or the file appears to load but the board behaves as if no program is there. This page works through the causes in the order they actually occur, from a board/firmware mismatch down to a stale build file.

Symptoms

• Loading the .hex file produces no visible change: no code runs, outputs stay idle.
• The simulation runs, but the board behaves like it still holds an older program — or no program at all.
• A .hex file that worked before stops working after you switched to a different board in PICSimLab.
• The file loads on one board (for example McLab2) but not on another board you tried.

Why it happens

PICSimLab does not run “a hex file” in the abstract — it runs firmware compiled for the specific microcontroller selected on the currently selected board. A .hex built for a PIC18F4550 cannot run on a board configured for a PIC16F877A, and an AVR .hex built for an Arduino Uno (ATmega328P) cannot run on a PIC board. When the firmware and the selected board/MCU do not match, the load either fails outright or produces a simulation that does nothing meaningful.

The other common causes are mundane: the .hex on disk is stale because the last build in your IDE actually failed, the file is empty or truncated because the build was interrupted, or you changed the board after loading the file — switching boards resets the simulation state, so the previously loaded firmware is no longer in place.

Fix

1. Confirm the board and MCU match the firmware. Check which board is selected in PICSimLab and which microcontroller it is set to, then check what chip your project was compiled for. For example, the McLab2 and PICGenios boards support the PIC16F777, PIC16F877A, PIC18F452, PIC18F4520, PIC18F4550 and PIC18F4620; if your chip is not selectable on the current board, pick a board that supports it (the generic Breadboard covers many additional PIC and AVR parts).
2. Rebuild and confirm the build really succeeded. In MPLAB X, the Arduino IDE or VS Code with PlatformIO, fix any build errors first, then note the exact output path of the fresh .hex file. A failed build often leaves yesterday’s file in place, which makes a fixed program look “still broken”.
3. Check the file itself. The .hex should be a non-trivial text file (an empty or near-empty file is a failed export, not firmware). If in doubt, move or copy it to a short, simple folder path and load it from there, so a moved project folder or a stale network path cannot confuse the load.
4. Load in the right order: board first, then file. Select the board and microcontroller first, then load the .hex file. If you loaded the file and then switched boards, simply load the file again on the new board.
5. Run and reset. After loading, make sure the simulation is actually running, and pulse reset once — some programs only show activity after a clean reset, exactly as on real hardware.
6. Isolate with a known-good program. Load a minimal blink program built for exactly the selected chip (our PIC16F877A LED blink tutorial is built for the McLab2/PICGenios pair). If the blink program loads and runs, PICSimLab and the board selection are fine and the problem is inside your original project’s build; if even the blink program does nothing, re-check steps 1–3.

Still stuck?

Revisit the basics in order: the first-project blink tutorial shows the exact board-then-load sequence, and the Windows installation guide (with the platform pages under Download) rules out a damaged installation. If a correctly built .hex for a supported chip still will not load on a fresh PICSimLab v0.9.3 install, report it — with your board, MCU and PICSimLab version — on the project’s tracker: github.com/lcgamboa/picsimlab/issues.