pk2cmd Usage Guide
Complete guide for using pk2cmd with PICkit2/PICkit3 programmers on macOS.
PICkit2/PICkit3 Hardware Setup
PICkit2 Pinout (6-pin ICSP Connector)
PICkit2 Connector (looking at programmer end):
┌─────────────────┐
│ 1 2 3 4 5 6 │
└─────────────────┘
Pin 1: VPP/MCLR (Programming voltage / Master Clear)
Pin 2: VDD (Target power supply +3.3V or +5V)
Pin 3: VSS (Ground)
Pin 4: PGD (Programming Data)
Pin 5: PGC (Programming Clock)
Pin 6: AUX (Auxiliary / not used for basic programming)
Standard ICSP Connection to Target
Target PIC PICkit2 Pin Wire Color (typical)
──────────── ─────────── ──────────────────
MCLR/VPP ────── 1 Red/Orange
VDD (+3.3V/5V) ────── 2 Red
VSS (Ground) ────── 3 Black
PGD (Data) ────── 4 White/Yellow
PGC (Clock) ────── 5 Brown/Green
Important Connection Notes
1. Power Options:
PICkit Powers Target: Connect Pin 2 (VDD) to target VDD
External Power: Use -W option, connect target VDD to external supply
Voltage Setting: Use -A3.3 or -A5.0 to set voltage
2. MCLR Connection:
Always connect Pin 1 to target MCLR/VPP pin
Some targets may need pull-up resistor (10kΩ) on MCLR
3. Ground Connection:
Pin 3 (VSS) must always be connected to target ground
This provides the reference for all signals
4. Programming Pins:
PGD and PGC are the data and clock lines for programming
These correspond to specific pins on your target PIC (check datasheet)
Getting Started
Check Connected PICkit
# Navigate to pk2cmd directory
cd pk2cmd
# List all connected PICkit devices
./pk2cmd -B. -S
# List devices with firmware versions
./pk2cmd -B. -S#
Expected Output: Unit # Unit type Unit ID OS Firmware 0 PICkit2 2.32.00
List Supported Device Families
# Show all auto-detectable PIC families
./pk2cmd -B. -PF
This shows 20 families including Midrange, PIC18F, PIC24, dsPIC33, PIC32, and EEPROMs.
Target Device Operations
Device Detection and Information
# Auto-detect connected PIC device (any family)
./pk2cmd -B. -P
# Auto-detect within specific family (e.g., PIC18F family #5)
./pk2cmd -B. -PF5
# Show detailed device information (requires connected target)
./pk2cmd -B. -P -I
# Show device ID and silicon revision for specific part
./pk2cmd -B. -PPIC16F877A -I
Power and Voltage Control
# Set VDD voltage
./pk2cmd -B. -P -A3.3 # Set to 3.3V
./pk2cmd -B. -P -A5.0 # Set to 5.0V
# Power target after operations (keeps power on)
./pk2cmd -B. -P -T
# Use external power instead of PICkit power
./pk2cmd -B. -P -W -[Link] -M
# Release MCLR after operations (allows target to run)
./pk2cmd -B. -P -R
Programming Operations
Basic Programming
# Program hex file to auto-detected device
./pk2cmd -B. -P -[Link] -M
# Program specific device type
./pk2cmd -B. -PPIC16F877A -[Link] -M
# Erase device first, then program
./pk2cmd -B. -P -E -[Link] -M
# Program with verification
./pk2cmd -B. -P -[Link] -M -Y
Selective Memory Programming
# Program only program memory
./pk2cmd -B. -P -[Link] -MP
# Program only EEPROM
./pk2cmd -B. -P -[Link] -ME
# Program only configuration memory
./pk2cmd -B. -P -[Link] -MC
# Program only ID memory
./pk2cmd -B. -P -[Link] -MI
# Program multiple regions
./pk2cmd -B. -P -[Link] -MPC # Program + Config
Advanced Programming Options
# Display programming progress
./pk2cmd -B. -P -[Link] -M -J
# Set programming speed (1=fastest, 16=slowest)
./pk2cmd -B. -P -L1 -[Link] -M
# Program with VPP first entry method
./pk2cmd -B. -P -X -[Link] -M
# Preserve EEPROM data when programming
./pk2cmd -B. -P -Z -[Link] -M
Reading Operations
Read Device to File
# Read entire device to hex file
./pk2cmd -B. -P -[Link]
# Read to specific file path
./pk2cmd -B. -P -GF/path/to/[Link]
Read Memory Regions to Screen
# Read program memory range (hex addresses)
./pk2cmd -B. -P -GP0-FF
./pk2cmd -B. -P -GP0-1FF # Larger range
# Read EEPROM range
./pk2cmd -B. -P -GE0-FF
# Read ID memory
./pk2cmd -B. -P -GI
# Read configuration memory
./pk2cmd -B. -P -GC
Device Verification and Testing
Verification Operations
# Blank check device
./pk2cmd -B. -P -C
# Verify device against hex file
./pk2cmd -B. -P -[Link] -Y
# Verify specific memory regions
./pk2cmd -B. -P -[Link] -YP # Program memory only
./pk2cmd -B. -P -[Link] -YE # EEPROM only
./pk2cmd -B. -P -[Link] -YC # Configuration only
File Operations
# Verify hex file checksum
./pk2cmd -B. -[Link] -K
# Display hex file information
./pk2cmd -B. -[Link] -I
Device Erase Operations
# Erase entire device
./pk2cmd -B. -P -E
# Erase then verify blank
./pk2cmd -B. -P -E -C
Typical Programming Workflows
Complete Programming Sequence
# 1. Check PICkit connection and firmware
./pk2cmd -B. -S#
# 2. Auto-detect target device
./pk2cmd -B. -P
# 3. Get detailed device information
./pk2cmd -B. -P -I
# 4. Set appropriate voltage
./pk2cmd -B. -P -A5.0
# 5. Erase device
./pk2cmd -B. -P -E
# 6. Blank check
./pk2cmd -B. -P -C
# 7. Program with verification and progress
./pk2cmd -B. -P -[Link] -M -Y -J
# 8. Power target and release MCLR for execution
./pk2cmd -B. -P -T -R
Quick Programming (One Command)
# Erase, program, verify, power, and release in one command
./pk2cmd -B. -P -E -[Link] -M -Y -T -R
Backup and Restore
# Backup device
./pk2cmd -B. -P -GFbackup_$(date +%Y%m%d).hex
# Restore from backup
./pk2cmd -B. -P -E -Fbackup_20231125.hex -M -Y
Advanced Features
Multiple PICkit Units
# List all connected units
./pk2cmd -B. -S
# Use specific unit by Unit ID (if assigned)
./pk2cmd -B. -SMyPICkit -P
# Assign Unit ID to PICkit
./pk2cmd -B. -NLab1A
Programming Speed Control
# Fastest programming (default)
./pk2cmd -B. -P -L1 -[Link] -M
# Slower for problematic connections
./pk2cmd -B. -P -L8 -[Link] -M
# Slowest for very long cables or noisy environments
./pk2cmd -B. -P -L16 -[Link] -M
Special Device Features
# Program OSCCAL value (for devices that support it)
./pk2cmd -B. -P -U3400 -[Link] -M
# Set I2C address for I2C EEPROMs
./pk2cmd -B. -P -#0x51 -[Link] -M
Help and Information Commands
Getting Help
# General help
./pk2cmd "-?"
# Help for specific options
./pk2cmd -B. "-?M" # Programming help
./pk2cmd -B. "-?G" # Reading help
./pk2cmd -B. "-?P" # Part selection help
./pk2cmd -B. "-?V" # Version information
./pk2cmd -B. "-?E" # Exit codes
# List supported devices
./pk2cmd -B. "-?P"
# Search for specific devices
./pk2cmd -B. "-?PPIC16" # Find PIC16 devices
./pk2cmd -B. "-?PPIC18F" # Find PIC18F devices
Troubleshooting
Common Issues and Solutions
1. "[Link] device file not found" ```bash
Always use -B. for local directory
./pk2cmd -B. -S
Or specify full path if installed system-
wide
pk2cmd -B/usr/local/share/pk2cmd -S ```
2. "Auto-Detect: No known part found"
Check all connections (especially VDD, VSS, MCLR, PGD, PGC)
Verify target has power (either from PICkit or external)
Try slower programming speed: -L8 or -L16
Check if target is in reset or has code preventing programming
3. Programming fails or verification errors
Check VDD voltage setting matches target requirements
Verify all ICSP connections are solid
Try slower programming speed
Check for proper decoupling capacitors on target
Ensure MCLR has proper pull-up resistor if required
4. Target doesn't run after programming
Use -R to release MCLR
Use -T to keep power on
Check configuration bits (oscillator settings, etc.)
Verify VDD is stable and at correct voltage
Connection Verification
# Check PICkit voltages and status
./pk2cmd -B. -P -I
# Test connection with simple operations
./pk2cmd -B. -P # Should detect device
./pk2cmd -B. -P -GI # Read ID memory
./pk2cmd -B. -P -C # Blank check
Device-Specific Notes
PIC16F Series
Typically use 5V programming voltage
Configuration bits control oscillator and other features
Some have OSCCAL calibration value
PIC18F Series
Can use 3.3V or 5V programming
Larger program memory space
Enhanced instruction set
PIC24/dsPIC33 Series
Typically 3.3V devices
May require Programming Executive (PE) - use -Q to disable if needed
16-bit architecture
PIC32 Series
3.3V devices
Separate boot flash and program flash regions
Different programming algorithm
Serial EEPROMs
Use SPI or I2C interface through PICkit
Specify correct protocol in device selection
Some require specific addressing for larger sizes
File Formats
Supported File Types
Intel HEX (.hex): Standard format for program data
Binary (.bin): Raw binary data (for serial EEPROMs)
File Handling
# Import/Export HEX files
./pk2cmd -B. -P -[Link] -M # Import (program)
./pk2cmd -B. -P -[Link] # Export (read)
# Binary files (for EEPROMs)
./pk2cmd -B. -P -[Link] -M # Program binary data
./pk2cmd -B. -P -[Link] # Read to binary file
For build and installation instructions, see BUILD_MACOS.md
For additional help, use: ./pk2cmd "-?" or ./pk2cmd -B. "-?<option>"
