pydebuggerupgrade 3.7.1.60

Description:

pydebuggerupgrade 3.7.1.60

pydebuggerupgrade
pydebuggerupgrade is a combined Command Line Interface and library utility for upgrading firmware on Microchip debuggers with DFU based bootloaders.
These tools are currently supported:

PKOB nano (nEDBG): Embedded debugger found on kits

Usage
pydebuggerupgrade can be used as a command-line interface or a library
Command-line usage
for help, use:
pydebuggerupgrade --help

Upgrade using local firmware artifact
pydebuggerupgrade supports firmware artifact zip files and hex files
Example: Upgrade PKOB nano (nEDBG) with zip
pydebuggerupgrade -t nedbg nedbg_fw-1.13.458.zip

Example: Upgrade PKOB nano (nEDBG) with hex
pydebuggerupgrade -t nedbg nedbg.hex

Upgrade using pack server
pydebuggerupgrade is capable of fetching firmware artifacts from the Microchip pack server (https://packs.download.microchip.com)
Example: Upgrade PKOB nano (nEDBG) with firmware from the latest released pack
pydebuggerupgrade -t nedbg latest

Example: Upgrade PKOB nano (nEDBG) with firmware from a specific pack version
Note: This version indicates the pack version and not the firmware version inside it
pydebuggerupgrade -t nedbg 1.0.33

Report firmware versions
The -r/--report option makes pydebuggerupgrade only report firmware versions and not do any upgrade. Both the version of the currently loaded firmware and the version of the upgrade candidate is reported
Example: Report versions using latest release from pack server
pydebuggerupgrade -t nedbg -r latest

Command-line switches
Many of these switches are optional, and many parameters are automatically set when using a Curiosity Nano 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. Substring matching on end of USB serial number is supported.
-v LEVEL for selecting logging verbosity ('debug', 'info', 'warning', 'error', 'critical')
-T TIMEOUT to configure the timeout in seconds when attempting to connect to tool
-a to upgrade all tools matching tool type and USB serial number
-b to upgrade all tools matching the tool type that are already in boot mode before doing the upgrade of the tool with the specified USB serial number
-r to report (i.e. no upgrade) version of upgrade candidate and version of currently loaded firmware
-f to force upgrade or downgrade (no version checking)
-V to print pydebuggerupgrade version number and exit
-m to use Microchip internal artifact server

Library
pydebuggerupgrade can be used as a library using its "backend API". For example:
# Print the pydebuggerupgrade version
from pydebuggerupgrade.version import VERSION as pydebuggerupgrade_version
print("pydebuggerupgrade version {}".format(pydebuggerupgrade_version))

# Print the backend API version
print("pydebuggerupgrade backend API version: {}".format(backend.get_api_version()))

# Instantiate backend
from pydebuggerupgrade.backend import Backend
backend = Backend()

# Choose from one of these:

# Upgrade to latest published pack
backend.upgrade_from_source(source="latest")

# Upgrade with a specific zip
backend.upgrade_from_source(source="nedbg_fw.zip", tool_name="nedbg")

# Upgrade with a specific hex file
backend.upgrade_from_source(source="nedbg.hex")


Linux systems
Create udev rules for the debuggers in HID mode as well as DFU mode:
Example udev rules file
Store in /etc/udev/rules.d

# PKOB nano (nEDBG) - debugger on Curiosity Nano
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2175", MODE="0666"
# PKOB nano (nEDBG) in DFU mode - bootloader of debugger on Curiosity Nano
SUBSYSTEM=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2fc0", MODE="0666"

Note that udev rules are required for both DFU (boot) mode and normal debugger (application) mode. These rules are detailed in the pyedbglib package: https://pypi.org/project/pyedbglib
Dependencies
pydebuggerupgrade depends on pyedbglib for its transport protocol. pyedbglib requires a USB transport library like libusb. See pyedbglib package for more information.
pydebuggerupgrade depend on pyusb for the USB communication with the DFU bootloader of the debugger.
Versioning
pydebuggerupgrade version can be determined using the CLI:
pydebuggerupgrade -V

or using the library:
from pydebuggerupgrade.version import VERSION as pydebuggerupgrade_version
print("pydebuggerupgrade version {}".format(pydebuggerupgrade_version))

In addition, the CLI-backend API is versioned for convenience:
from pydebuggerupgrade.backend import Backend
backend = Backend()
print("pydebuggerupgrade backend API version: {}".format(backend.get_api_version()))