MPLAB X Plugin Cannot Connect to PICSimLab? Port 1234 Checks

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.

Similar Posts