Command Line Reference¶
Complete reference for the IPECMD Wrapper command-line interface.
Synopsis¶
The IPECMD Wrapper features a modern, rich command-line interface powered by Typer, providing enhanced validation, beautiful help output, and improved user experience. The CLI follows the same format as the original IPECMD tool: only the device name and tool are required positional arguments.
Required Positional Arguments¶
The CLI requires exactly two positional arguments, matching the original IPECMD format.
PART¶
Target PIC microcontroller device (positional argument).
Type: TEXT Required: Yes Position: 1st argument
Example:
TOOL¶
Programmer type (positional argument). The tool choice is validated against supported programmers.
Type: Enum (validated choices) Required: Yes Position: 2nd argument
Supported Options:
- PK3 - PICkit 3
- PK4 - PICkit 4
- PK5 - PICkit 5
- ICD3 - MPLAB ICD 3
- ICD4 - MPLAB ICD 4
- ICD5 - MPLAB ICD 5
- ICE4 - MPLAB ICE 4
- RICE - MPLAB REAL ICE
- SNAP - MPLAB SNAP
- PM3 - MPLAB PM3
- PKOB - PICkit On Board
- PKOB4 - PICkit 4 On Board
- J32 - MPLAB J32
Example:
Optional Arguments¶
--file, -F HEXFILE¶
Intel HEX file to program. The file path is validated to ensure it exists.
Type: PATH (automatically validated) Required: No Default: None
Example:
--power, -P VOLTAGE¶
Target power voltage (VDD voltage from tool).
Type: FLOAT Required: No Default: None
Example:
--memory, -M TYPE¶
Program Device memory regions.
Type: TEXT
Options:
- P - Program memory (default)
- E - EEPROM memory
- I - ID memory
- C - Configuration memory
- B - Boot memory
- A - Auxiliary memory
--verify, -Y TYPE¶
Verify Device memory regions after programming.
Type: TEXT
Options:
- P - Verify program memory
- E - Verify EEPROM memory
- I - Verify ID memory
- C - Verify configuration memory
- B - Verify boot memory
- A - Verify auxiliary memory
--erase, -E¶
Erase Flash Device before programming.
Type: Flag (no value required)
--logout, -OL¶
Release from Reset after programming.
Type: Flag (no value required)
--vdd-first, -OD¶
VDD First programming sequence (default is VPP First).
Type: Flag (no value required)
--test-programmer¶
Test programmer detection before programming without actually programming the device.
Type: Flag (no value required)
--ipecmd-version VERSION¶
Specify MPLAB IPE version to use. This option is ignored if --ipecmd-path is provided.
Type: Enum (validated choices)
Supported Versions:
- 5.50
- 6.00
- 6.05
- 6.10
- 6.15
- 6.20
- 6.25
--ipecmd-path PATH¶
Full path to ipecmd.exe. This overrides --ipecmd-version when provided.
Type: TEXT
--version¶
Show version information and exit.
Type: Flag
--help¶
Show help message and exit.
Examples¶
Basic Programming¶
Program a PIC16F876A with firmware.hex using PICkit 3:
Program with Erase and Verify¶
Erase the device, program it, and verify the program memory:
ipecmd-wrapper PIC16F876A PK4 --file firmware.hex --power 5.0 --erase --verify P --ipecmd-version 6.20
Test Programmer Connection¶
Test if the programmer is properly connected without programming:
Program EEPROM Memory¶
Program only EEPROM memory:
Use Custom IPECMD Path¶
Use a custom installation path for ipecmd.exe:
ipecmd-wrapper PIC16F876A PK3 --file firmware.hex --power 5.0 --ipecmd-path "C:\custom\path\ipecmd.exe"
Advanced Programming with Multiple Options¶
Program with erase, verify, and VDD-first sequence:
ipecmd-wrapper PIC18F4550 PK4 --file firmware.hex --power 3.3 --erase --verify P --vdd-first --ipecmd-version 6.25
Minimal Usage (Only Test Programmer)¶
Test programmer connection with minimal arguments:
Rich Help Output¶
The new Typer-based CLI provides beautiful, organized help output. To see all available options with detailed descriptions:
This will display a rich, color-coded help message with: - ✅ Clear separation between required and optional arguments - 🎨 Syntax highlighting and formatting - 📝 Detailed descriptions for each option - 🔍 Validation information for enum choices
Input Validation¶
The CLI provides enhanced validation with clear error messages:
Tool Validation¶
# ✅ Valid tool choice
ipecmd-wrapper PIC16F876A PK4 [OPTIONS]
# ❌ Invalid tool choice (will show available options)
ipecmd-wrapper PIC16F876A INVALID [OPTIONS]
# Error: Invalid value for 'TOOL': 'INVALID' is not one of 'PK3', 'PK4', 'PK5', ...
File Path Validation¶
# ✅ Existing file
ipecmd-wrapper PIC16F876A PK4 --file firmware.hex
# ❌ Non-existent file
ipecmd-wrapper PIC16F876A PK4 --file missing.hex
# Error: Invalid value for '--file' / '-F': Path 'missing.hex' does not exist.
Version Validation¶
# ✅ Valid version
ipecmd-wrapper PIC16F876A PK4 --ipecmd-version 6.20
# ❌ Invalid version
ipecmd-wrapper PIC16F876A PK4 --ipecmd-version 7.0
# Error: Invalid value for '--ipecmd-version': '7.0' is not one of '5.50', '6.00', '6.05', ...
Exit Codes¶
0- Success1- General error2- Command line argument error3- File not found4- IPECMD not found5- Programming failed6- Verification failed7- Programmer not found
Common Device Names¶
PIC10F Series¶
- PIC10F200, PIC10F202, PIC10F204, PIC10F206
- PIC10F220, PIC10F222
PIC12F Series¶
- PIC12F508, PIC12F509, PIC12F510
- PIC12F629, PIC12F675
- PIC12F683, PIC12F685
PIC16F Series¶
- PIC16F84A, PIC16F88
- PIC16F628A, PIC16F648A
- PIC16F876A, PIC16F877A
- PIC16F886, PIC16F887
PIC18F Series¶
- PIC18F2455, PIC18F2550
- PIC18F4455, PIC18F4550
- PIC18F2620, PIC18F4620
- PIC18F46K22, PIC18F47K22
Troubleshooting¶
Device Not Recognized¶
Make sure the device name exactly matches the IPECMD supported devices:
Invalid Programmer¶
Verify the programmer type is supported:
File Not Found¶
Use absolute paths for hex files: