Skip to content

Latest commit

 

History

History
237 lines (186 loc) · 5.52 KB

help.md

File metadata and controls

237 lines (186 loc) · 5.52 KB
Raw

pymcuprog - Python MCU programmer

pymcuprog is a Python utility for programming various Microchip MCU devices using Microchip CMSIS-DAP based debuggers

Usage

pymcuprog is used as a command line interface:

pymcuprog [switches] action

Actions (commands)

The only manadatory positional argument specifies the action:

Memory access actions

Read the device ID or signature:

Also functions as a 'connectivity check'

ping

Read memories from a device:

read

Write memories to a device:

NB: Does NOT erase before write!

write

Erase memories on a device:

erase

Read out memories from a device and compare:

verify

Voltage-related actions

Read the actual (sampled) VTG voltage from a kit or debugger:

getvoltage

Read the supply voltage set-point from a kit or debugger:

getsupplyvoltage

Set the supply voltage set-point from a kit or debugger:

Use -l literal to specify voltage

setsupplyvoltage

Read the USB voltage from a kit or debugger:

getusbvoltage

Other misc actions

Reset the application (by entering and leaving programming mode):

reset

Reboot the debugger:

reboot-debugger

Memory types

Memory types may vary depending on the device in question.

Specify the memory type using -m MEMORY or --memory MEMORY

Supported memory types

calibration_row
config_words
eeprom
flash
fuses
icd
internal_sram
lockbits
signatures
user_id
user_row

Optional arguments and switches

Administrative arguments

-h, --help
    show this help message and exit

-V, --version
    Print pymcuprog version number and exit

-R, --release-info
    Print pymcuprog release details and exit

General arguments

-d DEVICE, --device DEVICE
    device to program

-p PACKPATH, --packpath PACKPATH
    path to pack (DFP) to use - mandatory for any action when using a PIC device.
    Packs can be installed usign MPLABX Pack Manager (use Tools->Packs)
    Pack path is displayed in the status bar.
    Packs can be downloaded and unzipped from https://packs.download.microchip.com/

-t TOOL, --tool TOOL
    tool to connect to

-s SERIALNUMBER, --serialnumber SERIALNUMBER
    USB serial number of the unit to use

-v {debug,info,warning,error,critical},
--verbose {debug,info,warning,error,critical}
    Logging verbosity level

-x, --timing
    add timing output

Memory access arguments

-o OFFSET, --offset OFFSET
    memory byte offset to access

-b BYTES, --bytes BYTES
    number of bytes to access

-l LITERAL [LITERAL ...], --literal LITERAL [LITERAL ...]
    literal value(s) to write

-f FILENAME, --filename FILENAME
    file to write / read.

    A specified filename which has .hex extension will be treated as Intel(R) hex
    format; all other file extensions are treated as binary files.

    When writing from a .hex file, the memory segment addresses are read from
    the file, so the OFFSET argument is not allowed.

    When reading to an Intel hex file, only eeprom, flash, fuses, config_words,
    and user_row memories will be written

--verify
    verify content after write (by readback and compare)

Programming interface arguments

-i INTERFACE, --interface INTERFACE
    Programming interface to use

-c CLK, --clk CLK
    clock frequency in Hz (bps) for programming interface.
    (eg: '-c 32768' or '-c 115k' or '-c 1M')

-u UART, --uart UART
    UART to use for serialUPDI tool (when using -t uart)

Special-function UPDI arguments

-H {tool-toggle-power,user-toggle-power,simple-unsafe-pulse},
--high-voltage {tool-toggle-power,user-toggle-power,simple-unsafe-pulse}
    UPDI high-voltage activation mode

-U, --user-row-locked-device
    Writes the User Row on a locked device

-C, --chip-erase-locked-device
    Execute a Chip Erase on a locked device

Examples

Examples of using pymcuprog:

# Ping a device on a kit (checks connectivity by reading its signature):
pymcuprog ping

# Ping a device using Atmel-ICE (standalone debugger requires more information):
pymcuprog ping -t atmelice -d atmega4809 -i updi

# Program memories from a hexfile using PICkit4:
pymcuprog write -t pickit4 -d atmega4809 -i updi -f myfile.hex

# Read 64 bytes of flash from offset 0x80 in flash memory space:
pymcuprog read -m flash -o 0x80 -b 64

# Write literal values 0x01, 0x02 to EEPROM at offset 16 on a kit:
pymcuprog write -m eeprom -o 16 -l 0x01 0x02

# Write fuse byte 1 to 0xE0 on a kit:
pymcuprog write -m fuses -o 1 -l 0xE0

# Erase a device on a kit:
pymcuprog erase

# Erase a locked device on a kit (UPDI only):
pymcuprog erase --chip-erase-locked-device

# Reset a device on a kit (by entering and leaving programming mode):
pymcuprog reset

# Read the actual (sampled) VTG voltage from a kit or debugger:
pymcuprog getvoltage

# Set target supply voltage on a kit (voltage provided by -l literal argument):
pymcuprog setsupplyvoltage -l 3.3

serialUPDI usage

SerialUPDI (also known as 'pyupdi') is implemented as a tool in pymcuprog.

To use it:

  • connect a resistor between a serial port adapter's RX, TX and the UPDI pin as shown in the readme
  • specify uart tool using the switch: '--tool uart'
  • specify which serial port to use using the switch '--uart {serialport}'
  • use the basic actions for accessing memories as shown above

Example:

# Ping a device using serialUPDI:
pymcuprog ping -t uart -u COM42 -d atmega4809

# Erase a device using serialUPDI:
pymcuprog erase -t uart -u COM42 -d atmega4809

# Program memories from a hexfile using serialUPDI:
pymcuprog write -t uart -u COM42 -d atmega4809 -f myfile.hex