MPLAB X Plugin for PICSimLab: Install the .nbm Plugin and Debug over TCP

PICSimLab has no built-in source code editor — by design, you write and build firmware with the same tools you would use for a real board. For PIC projects that tool is usually MPLAB X, and PICSimLab ships a small plugin that makes MPLAB X treat the simulator like a hardware debug tool. This guide covers installing the plugin, connecting it, and the one network setting that trips people up. It assumes PICSimLab itself is already installed (see the Windows installation guide or the platform pages).

What the plugin does

The plugin file is com-picsim-picsimlab.nbm (27,091 bytes in v0.9.3, SHA-256 72c47991bca337b55bafe83e85d7562a5419115cb8e3446bcce681d260a4fd46). Per the official documentation, once it is installed in MPLAB X it lets MPLAB X debug and program PICSimLab — for PICs and AVRs — much as it would with a real board connected. The plugin connects to PICSimLab through a TCP socket on port 1234 (or another port defined in the configuration window).

Download the plugin here: com-picsim-picsimlab.nbm (official GitHub release file for v0.9.3).

Step 1: Install the .nbm in MPLAB X

  1. Download com-picsim-picsimlab.nbm using the link above.
  2. In MPLAB X, open the Plugins window (Tools → Plugins), go to the Downloaded tab, and choose Add Plugins.
  3. Select the downloaded .nbm file and complete the installation, restarting MPLAB X if it asks.

Step 2: Prepare PICSimLab

  1. Start PICSimLab and load the board and firmware you want to debug.
  2. Open PICSimLab’s configuration for the MPLAB X connection and confirm the port — the default is 1234. If you change it, the MPLAB X side must use the same port.
  3. Leave PICSimLab running while you work in MPLAB X; the plugin connects to the running simulator.

Step 3: Allow the connection through the firewall

The official documentation calls this out explicitly: because the plugin talks to PICSimLab over a TCP socket, you have to allow the access in the firewall. On Windows, if a firewall prompt appears when the connection is first made, allow it for your local network; if no prompt appears and the connection fails, add an allow rule for PICSimLab / port 1234 in your firewall settings. Both programs normally run on the same PC, so this is a localhost connection — you are not exposing the port to the internet, and you should not forward it on your router.

Step 4: Debug from MPLAB X

With the plugin installed and PICSimLab running, select the PICSimLab tool in your MPLAB X project and start a debug session as you would with a hardware tool: MPLAB X connects over TCP, programs the simulated device, and lets you run, halt and inspect your code while PICSimLab shows the board reacting. If the connection is refused, check the three usual causes: PICSimLab is not running, the port numbers differ between the two programs, or the firewall blocked the connection.

Good to know

  • The same 1234 port also appears in PICSimLab’s GDB workflows for other backends (avr-gdb, arm-gdb, esp32-gdb). The MPLAB X plugin is a separate path for PIC and AVR work inside MPLAB X — do not confuse the two when following a tutorial.
  • The plugin file is versioned with PICSimLab itself: when you update PICSimLab, download the .nbm from the same release (the link above always points at the v0.9.3 file from our Download page).

Related guides

Similar Posts