Skip to main content

Program Microchip MCUs with a PICkit 5

A standalone project can program Microchip microcontrollers through a PICkit 5 plugged into an external USB port of the AT1000. The project runs Microchip's command-line programmer, ipecmd:

ipecmd -TPPK5 -P32MX250F128D -M -Ffirmware.hex

ipecmd is part of MPLAB IPE, which Microchip does not allow us to distribute. You produce MPLAB IPE once on a PC and copy it into your project. After that, the project programs targets with no computer attached.

For a complete project that programs a target and shows the result on the AT1000 screen, follow the tutorial Program and test a PIC in a standalone project.

Requirements​

  • A PICkit 5 connected to an external USB port of the AT1000.
  • A standalone project.
  • Once, to produce MPLAB IPE: an x86-64 Linux PC with Docker or Podman. Microchip's installer exists for x86-64 Linux only.
Projects created before PICkit 5 support do not have ipecmd

A project keeps the software it was created with. Updating the AT1000 firmware or restarting the project does not add ipecmd. To use a PICkit 5 in such a project, create it again from its code: see Projects created without USB support.

Overview​

  1. Produce MPLAB IPE on your PC.
  2. Copy it into your project.
  3. Run ipecmd from the project's terminal or from your application.

Step 1: Produce MPLAB IPE on your PC​

Download install-mplab.sh and make it executable:

curl -fLO https://www.ikalogic.com/downloads/at1000/install-mplab.sh
chmod +x install-mplab.sh

Run it with the device families you program:

./install-mplab.sh --families 32bit           # PIC32 / SAM
./install-mplab.sh --families 8bit,16bit      # PIC10/12/16/18, PIC24, dsPIC
./install-mplab.sh --families 8bit --version 6.30 --output mplab.tar
OptionDescription
--familiesRequired. Device families to include, comma-separated: 8bit (PIC10, PIC12, PIC16, PIC18), 16bit (PIC24, dsPIC), 32bit (PIC32, SAM), other.
--versionMPLAB version. Default: 6.35.
--outputOutput file. Default: mplab-ipe-v<version>.tar.

The script downloads Microchip's installer (1.2 GB) into the current folder, or reuses it if it is already there. It then runs the installer in a temporary container, with MPLAB IPE only and the families you chose. Nothing is installed on the PC, and the script does not need root.

note

The installer runs unattended and accepts Microchip's license agreement on your behalf.

The output is large: about 9.3 GB for 32bit, mostly device and programmer support packs. Before copying it to the AT1000, keep only the packs you need.

Other ways to produce the file:

  • From a PC with MPLAB X installed, archive its install folder: 
    tar -C / -cf mplab-ipe-v6.35.tar opt/microchip/mplabx/v6.35
  • Run Microchip's installer yourself with --mode unattended --ide 0 --ipe 1 --8bitmcu 0|1 --16bitmcu 0|1 --32bitmcu 0|1 --othermcu 0|1, then archive /opt/microchip/mplabx/v<version> as above.

Keep only the packs you need​

MPLAB IPE includes support packs for every programmer and every device of the families you chose. ipecmd needs only the PICkit 5 pack, PICkit5_TP, and the pack for your device. Removing the others makes the file several times smaller and the copy much faster. For example, a 32bit install trimmed to the PIC32MX devices drops from 9.3 GB to 1.2 GB.

  1. Find the pack that supports your device. Replace PIC32MX250F128D with your part number: 
    tar -tf mplab-ipe-v6.35.tar | grep '/edc/PIC32MX250F128D.PIC'
    The folder after packs/Microchip/ is the pack name, here PIC32MX_DFP: 
    opt/microchip/mplabx/v6.35/packs/Microchip/PIC32MX_DFP/1.7.380/edc/PIC32MX250F128D.PIC
  2. Extract the install into a working folder, then delete every pack except PICkit5_TP and yours. This needs as much free space again as the .tar file: 
    mkdir mplab
    tar -C mplab -xf mplab-ipe-v6.35.tar
    find mplab/opt/microchip/mplabx/v6.35/packs/Microchip -mindepth 1 -maxdepth 1 \
        ! -name PICkit5_TP ! -name PIC32MX_DFP -exec rm -rf {} +
    To keep several device packs, add one ! -name <pack> per pack.
  3. Create a compressed archive of the trimmed install: 
    tar -C mplab -czf mplab-ipe-v6.35-pic32mx.tar.gz opt/microchip/mplabx/v6.35

To program a device from another pack later, copy a new archive that includes it into the project.

Step 2: Copy it into your project​

  1. In AT1000-Interface, run the project in Development mode and set up SSH access: see Connect to the project over SSH.
  2. From the folder that holds the archive, run the following command, replacing <serial-number> with your device's serial number: 
    ssh -p 2222 dev@AT1032S-<serial-number>.local 'sudo tar -C / -xzf -' < mplab-ipe-v6.35-pic32mx.tar.gz
    For an uncompressed .tar file, use -xf instead of -xzf.

The command prints nothing until the copy finishes. A 1.2 GB archive takes a few minutes over a wired network. Connect your PC to the network with a cable if you can: over Wi-Fi the copy can take much longer.

If the copy stops making progress or ends with Broken pipe, run the same command again: it overwrites the partly copied files. If it stops again, replace AT1032S-<serial-number>.local with the AT1000's IP address. It is the Host value in the device settings, without the :port part.

You do this once per project: the project keeps MPLAB IPE when it stops, restarts or changes mode.

Export code does not include MPLAB IPE

MPLAB IPE is installed outside /workspace, so Export code does not save it. After you create a project with Import code, copy MPLAB IPE into it again.

If the project holds several MPLAB versions, ipecmd uses the newest one. To choose another, set MPLAB_INSTALL to its folder, for example MPLAB_INSTALL=/opt/microchip/mplabx/v6.30.

Step 3: Run ipecmd​

Open a terminal in the project (over SSH, or in VS Code with Open in VS Code) and check that the PICkit 5 is detected:

ipecmd -T

The output lists the connected programmers with their serial numbers:

Available Tool List
-------------------
1  PICkit 5 S.No : 020026702RYN021240

ipecmd also prints a few log lines starting with a date, such as [2026-10-29 19:50:39.180] [info] … LibUSBAccess version …. They are informational. ipecmd -T exits with code 50 even when it lists a programmer: read its output, not its exit code.

Then work with the target. Replace 32MX250F128D with your device's part number:

ipecmd -TPPK5 -P32MX250F128D -I                   # identify the target
ipecmd -TPPK5 -P32MX250F128D -GFbackup.hex        # read the target into a file
ipecmd -TPPK5 -P32MX250F128D -M -Ffirmware.hex    # program, then verify

A successful programming run ends with:

Programming/Verify complete
 Program Report
2026-10-29, 19:51:35
Device Type:PIC32MX250F128D
Program Succeeded.
Operation Succeeded

ipecmd -? lists every option. The most common ones:

OptionDescription
-TList the connected programmers.
-TPPK5Use the PICkit 5.
-TS<serial>Use the programmer with this serial number, for example -TS020026702RYN021240, when several are connected.
-P<part>Target part number, without the PIC prefix, for example -P32MX250F128D or -P16F18446.
-IRead and display the target's device ID.
-F<file>HEX file to program or verify.
-MProgram the whole device from the -F file, then verify it.
-YVerify the device against the -F file.
-EErase the device.
-CCheck that the device is blank.
-GF<file>Read the device into a HEX file.
-OLRelease the target from reset when the operation ends, so its firmware starts running. Without it, the target stays in reset.

Relative file paths are resolved in the current folder. MPLAB writes its log, MPLABXLog.xml, to ~/.mplab_ipe/dev/v<version>/.

Each ipecmd call takes about 5 to 16 seconds, including the programmer start-up: about 5 s for -T, 12 s for -I, and 13 to 15 s to program, verify or read a PIC32MX250F128D. Include this time in your test-time budget.

Check the output, not only the exit code

ipecmd can exit with code 0 when an operation did not run. For example, it prints Connection Failed. and exits with 0 when the target is not powered. In your application, check the output for the expected success message, such as Program Succeeded.

Troubleshooting​

Output or exit codeCauseWhat to do
Connection Failed. (exit code 0)The programmer cannot reach the target, usually because the target has no power.Check the target's power and the programming connections.
No Tools Connected. (exit code 50)The PICkit 5 is not detected. If the output also shows Access denied (insufficient permissions), the project cannot open it.Check the USB cable and port. For Access denied, update the AT1000 firmware, then contact Ikalogic support if the error persists. ipecmd -T also exits with 50 when it lists a programmer: check its output.
Hex File could not be read. (exit code 15)The -F file does not exist, or is not a HEX file.Check the file name. Relative paths start from the current folder.
Could not find device:PIC… (exit code 36)The part number is wrong, or its device pack is not installed.Check the -P part number. If you trimmed the packs, copy an archive that includes the pack for this device.
Exit code 127, no MPLAB IPE install foundNo MPLAB IPE install was found in the project.Copy MPLAB IPE into the project (Step 2), or correct MPLAB_INSTALL.
Exit code 125, with [usbbridge] ERROR: …The USB access layer failed.Run the command again with MCHP_BRIDGE_DEBUG=1 set, and send the output to Ikalogic support.

Other USB devices​

ipecmd opens only Microchip (vendor ID 0x04D8) and Atmel (0x03EB) USB devices. Other devices on the AT1000, such as a J-Link or an FTDI adapter, are never opened. Detecting programmers does not open any device.

A device under test that uses the Microchip or Atmel vendor ID, such as an MCP2221 or an AVR with USB, can be seen by ipecmd.

MPLAB's automatic detection of Microchip development boards (Curiosity, Xplained, Microstick) is turned off, because it can stop ipecmd from responding when such a board is connected. Programming with -P does not need it. To turn it back on, set IPECMD_KIT_PROBE=1.