Package: pymcuprog
pymcuprog - Python MCU programmerpymcuprog is a utility for programming various Microchip MCU devices using Microchip CMSIS-DAP based debuggersOverviewpymcuprog is available:install using pip from pypi:https://pypi.org/project/pymcuprogbrowse source code on github:https://github.com/microchip-pic-avr-tools/pymcuprogread API documentation on github:https://microchip-pic-avr-tools.github.io/pymcuprogUsagepymcuprog can be used as a command-line interface or a libraryCommand-line programmingfor help, use:pymcuprog--helpAction: pingchecks connectivity by reading the device identityExample:pymcuprogpingAction: eraseerases device memoriesuse -m to erase only a specified memory region (if available)Example: chip erase the devicepymcuprogeraseAction: writewrites device memoriesuse -f for writing from a file, oruse -l for writing literal valuesuse -m to specify memory type for literal writinguse -o to specify offset for literal writingExample: writes the content of an Intel(R) hex file to the appropriate memory areas on the devicepymcuprogwrite-fapp.hexNote: memory is not erased automatically before writing!Example: erases memories and then writes an Intel hex file:pymcuprogwrite-fapp.hex--eraseExample: erases memories, writes an Intel hex file and then verifies the content:pymcuprogwrite-fapp.hex--erase--verifyAction: readreads device memoriesuse -m to specify memory typeuse -o to specify offset to read fromuse -b to specify number of bytes to readuse -f to read to a fileExample: reads 64 bytes of flash memory from offset 0x1000pymcuprogread-mflash-o0x1000-b64Action: resetresets the target deviceExample:pymcuprogresetCommand-line board utilitiesAction: getvoltagereads the actual target operating voltageExample:pymcuproggetvoltageAction: getsupplyvoltagereads the supply voltage (set-point)Example:pymcuproggetsupplyvoltageAction: getusbvoltagereads the USB voltage (Vbus)Example:pymcuproggetusbvoltageAction: setsupplyvoltagesets the target supply voltageuse -l to specify a literal supply voltage valueExample: sets the target supply voltage on a Curiosity Nano kit to 3.3Vpymcuprogsetsupplyvoltage-l3.3Action: reboot-debuggerreboots the debuggerExample: reboots a Curiosity Nano kitpymcuprogreboot-debuggerCommand-line switchesMany of these switches are optional, and many parameters are automatically set when using a Curiosity Nano or Xplained Pro kit.-t TOOL to select which tool to use.  Optional if only one is connected.-s SERIALNUMBER to select which tool instance to use.  Optional if only one is connected.-d DEVICE to specify the device to program.  Optional when using a kit.-i INTERFACE to specify the target communication interface.  Optional.-p PACKPATH to specify the path to the DFP for PIC devices*-c CLK to specify the programming interface clock speed.  Optional.--verify to verify after programming-u UART to use native host serial port UART for UPDI instead of a USB-based tool.-H MODE to select UPDI high-voltage entry mode ('tool-toggle-power', 'user-toggle-power', 'simple-unsafe-pulse')-U to write user row values when the device is locked (UPDI only)-C to erase and unlock a locked device (UPDI only)-v LEVEL for selecting logging verbosity ('debug', 'info', 'warning', 'error', 'critical')*Notes regarding PACKPATH argumentWhile pymcuprog itself contains sufficient information to program AVR devices (with UPDI interface), it is unable to program a PIC device without access to programming scripts for that device.  These scripts are deployed in Device Family Packs (DFP) onhttps://packs.download.microchip.comand are only provided for PIC devices mounted on Curiosity Nano boards or other boards with the PKOB nano (nEDBG) debugger.  To use pymcuprog with PIC devices, you will either need to download a DFP for the PIC in question, or have MPLAB X v5.25 or later installed.  In either case the path to the particular device in the scripts folder inside the DFP must be passed into pymcuprog using the -p PACKPATH argument.  Remember to use "" if the path itself contains spaces.Example: Ping the device on a PIC16F15244 Curiosity Nanopymcuprogping-p"c:\Program Files (x86)\Microchip\MPLABX\v5.40\packs\Microchip\PIC16F1xxxx_DFP\1.4.119\scripts\pic16f15244"Serial port UPDI (pyupdi)The AVR UPDI interface implements a UART protocol, which means that it can be used by simply connecting TX and RX pins of a serial port together with the UPDI pin; with a series resistor (eg: 1k) between TX and UPDI to handle contention.  (This configuration is also known as "pyupdi".)  Be sure to connect a common ground, and use a TTL serial adapter running at the same voltage as the AVR device.Vcc                     Vcc
                        +-+                     +-+
                         |                       |
 +---------------------+ |                       | +--------------------+
 | Serial port         +-+                       +-+  AVR device        |
 |                     |      +----------+         |                    |
 |                  TX +------+   1k     +---------+ UPDI               |
 |                     |      +----------+    |    |                    |
 |                     |                      |    |                    |
 |                  RX +----------------------+    |                    |
 |                     |                           |                    |
 |                     +--+                     +--+                    |
 +---------------------+  |                     |  +--------------------+
                         +-+                   +-+
                         GND                   GNDpymcuprog includes this implementation as an alternative to USB/EDBG-based tools.  To connect via a serial port, use the "uart" tool type with the UART switch in addition.Example: checks connectivity by reading the device identitypymcuprogping-davr128da48-tuart-ucom35When using serial port UPDI it is optional to use:--clk BAUD to specify the baud rate (defaults to 115200)--uart-timeout TIMEOUT to specify the uart read timeout (defaults to 1.0s)Increasing the baud rate can decrease programming time.  Decreasing the timeout can decrease the initial connection latency when UPDI is disabled and does not respond.  These parameters can be tweaked to suit the serial port adapter in use.Librarypymcuprog can be used as a library using its backend API.  For example:# pymcuprog uses the Python logging moduleimportlogginglogging.basicConfig(format="%(levelname)s:%(message)s",level=logging.WARNING)# Configure the sessionfrompymcuprog.backendimportSessionConfigsessionconfig=SessionConfig("atmega4808")# Instantiate USB transport (only 1 tool connected)frompymcuprog.toolconnectionimportToolUsbHidConnectiontransport=ToolUsbHidConnection()# Instantiate backendfrompymcuprog.backendimportBackendbackend=Backend()# Connect to tool using transportbackend.connect_to_tool(transport)# Start the sessionbackend.start_session(sessionconfig)# Read the target device_iddevice_id=backend.read_device_id()print("Device ID is{0:06X}".format(int.from_bytes(device_id,byteorder="little")))LoggingThis package uses the Python logging module for publishing log messages to library users.
A basic configuration can be used (see example), but for best results a more thorough configuration is recommended in order to control the verbosity of output from dependencies in the stack which also use logging.
See logging.yaml which is included in the package (although only used for CLI)Dependenciespymcuprog depends on pyedbglib for its transport protocol.
pyedbglib requires a USB transport library like libusb.  See pyedbglib package for more information.Versioningpymcuprog version can be determined using the CLI:pymcuprog-Vor using the library:frompymcuprogimport__version__aspymcuprog_versionprint("pymcuprog version{}".format(pymcuprog_version))In addition, the CLI-backend API is versioned for convenience:frompymcuprog.backendimportBackendbackend=Backend()print("pymcuprog backend API version:{}".format(backend.get_api_version()))Supported devices and toolspymcuprog is primarily intended for use with PKOB nano (nEDBG) debuggers which are found on Curiosity Nano kits and other development boards.  This means that it is continuously tested with a selection of AVR devices with UPDI interface as well as a selection of PIC devices.  However since the protocol is compatible between all EDBG-based debuggers (pyedbglib) it is possible to use pymcuprog with a wide range of debuggers and devices, although not all device families/interfaces have been implemented.Debuggers / Toolspymcuprog supports:PKOB nano (nEDBG) - on-board debugger on Curiosity NanoMPLAB PICkit 4 In-Circuit Debugger (when in 'AVR mode')MPLAB Snap In-Circuit Debugger (when in 'AVR mode')Atmel-ICEPower DebuggerEDBG - on-board debugger on Xplained Pro/UltramEDBG - on-board debugger on Xplained Mini/NanoJTAGICE3 (firmware version 3.0 or newer)Although not all functionality is provided on all debuggers/boards.  See device support section below.Devicespymcuprog supports:All UPDI devices, whether mounted on kits or standalonePIC devices mounted on Curiosity Nano kits, or similar board with PKOB nano (nEDBG) debuggerOther devices (eg ATmega328P, ATsamd21e18a) may be partially supported for experimental purposesNotes for Linux® systemsThis package uses pyedbglib and other libraries for USB transport and some udev rules are required.  For details see the pyedbglib package:https://pypi.org/project/pyedbglibChangelog[3.16] - November 2023AddedDSG-6057 Added support for BOOT_ROW memtypeDSG-6631 Added serialupdi support for P:4 and P:5DSG-6213 Added AVR EBChangedDSG-5887 Refactor serialupdi NVM variantsDSG-6210 Made serialupdi logging more conciseDSG-6533 Help tweaksFixedDSG-5817 Improved error handling with SAM devicesDSG-6409 Error return code when --verify failsDSG-6590 Corrected AVR Ex to use 24-bit addressing for serialupdi[3.14] - October 2022AddedDSG-5158 github-28 Added CLI switch for serial port read timeoutDSG-5421 Added support for AVR DU and additional AVR DD devicesChangedDSG-5418 Added Python 3.10 metadata tagDSG-5543 Removed Python 3.6 metadata tagDSG-5417 Removed distutils usageFixedDSG-5157 github-29 Fixed return value on errorDSG-4836 Corrected flash offset compensation for avrdebugger[3.13] - May 2022AddedDSG-3936 Fixed AVR ISP implementation and added commands (beta)DSG-4172 github-10 Disable ACK response signature on serialUPDI block write (speed-up)DSG-3951 github-8 Added --erase argument to erase device before write with single executionDSG-3972 CLI help additionsDSG-3997 Added debugwire_disable() to Avr8ProtocolFixedDSG-3945, DSG-3938 Unable to write fuse byte 0 on Curiosity Nano ATtiny kitsDSG-4488 github-19 Return bytearray (not list) from serialUPDI readDSG-4594 SAMD21 performance improvement (SAM-IoT provisioning)DSG-4540 Fixed SAMD21 non-word-oriented read failureDSG-3941 Improved feedback on verification failureDSG-3944 Removed timeout warning for serialUPDI with a locked deviceDSG-4419 Corrected AVR high voltage UPDI device dataDSG-3993 github-9 Corrected AVR signature sizes to make additional data available[3.10] - October 2021AddedDSG-2702 Add serialupdi backend for AVR EADSG-3633 github-3 Add missing AVR-DB devicesDSG-3635 github-4 Add missing ATtiny devicesDSG-3662 Add ascii-art for serialUPDIDSG-3804 Add py39 metadata to packageDSG-3943 github-7 Add CLI documentationFixedDSG-2859 github-1 serialUPDI write user_row on locked device failsDSG-3538 github-2 Unable to write fuses on ATmega4809 using serialUPDIDSG-3817 SAM D21 user row programming failsDSG-3952 Incorrect size of FUSES on Dx, Ex devices[3.9] - April 2021AddedDSG-2920 Raise exception if device ID does not matchDSG-2918 SerialUPDI: error recovery if non-ascii characters are read in SIBDSG-2861 Valid memory types are listed if an invalid one is specifiedFixedDSG-3238 PIC16 eeprom displays incorrect addressDSG-3239 PIC16 eeprom verification does not workDSG-2925 UPDI device revision not correctly parsed/displayedDSG-2860 SerialUPDI: chip erase does not work on locked deviceDSG-2857 SerialUPDI: crash when writing lockbitsDSG-2855 Verify action fails if hex file contains eeprom contentDSG-2854 User row excluded when reading to hex fileDSG-2850 UPDI device model fix (sram)ChangedDSG-2862 Improved exception handlingDSG-3203 Improved exception handlingDSG-3178 Cosmetic changes for publication[3.7.4] - December 2020AddedDSG-1492 Added verify functionDSG-2039 Added all UPDI devicesDSG-2279 Added error codesDSG-1550 Flash-only eraseFixedDSG-2470 No feedback when multiple kits are connectedDSG-2014 Error when reading using -m and -o but no -bDSG-2738 Padding to page size when writing user row on locked deviceChangedDSG-2234 Logging using logging moduleDSG-2034 prevent read using -b with no -m specifiedDSG-2009 prevent writing from hexfile with memory type specifiedDSG-2012 prevent writing from hexfile with offset specifiedDSG-2458 documentation changesDSG-2041 documentation changesDSG-2042 documentation changesDSG-2043 documentation changesDSG-2011 documentation changes[3.1.3] - June 2020First public release to PyPi