GitLocker: The Coding Marketplace

Description:

pydebuggerconfig 3.11.2.44

pydebuggerconfig
pydebuggerconfig is a utility for accessing the configuration information stored inside the PKOB nano on-board debugger,
typically found on Curiosity Nano kits.
Who should use pydebuggerconfig?
Kit designers who are ready to personalize their new kit
Prerequisite knowledge
In order for the PKOB nano on-board debugger to be aware of the properties and capabilities of the board in which
it is mounted, as well as the target device it will operate with, a "board configuration" and "device configuration"
is necessary. This information is stored separately to the PKOB nano firmware, allowing field upgrades to be
performed with identical firmware on all deployed kits without any customization required.
The parameters stored in the configuration include PKOB nano features, program/debug interface capability,
board and manufacturer names and USB serial number as well as device specific parameters required for device
programming through drag and drop.
The configuration information is stored in flash memory and can be modified freely. However, it is recommended
that this information is programmed into the PKOB nano during the kit manufacturing process and not altered
after deployment.
For board specific configuration data there are two identical sections in the configuration memory. One section
is intended for factory settings programmed during production and one for settings that have been changed by the user.
The user section can be reverted to the factory settings by using the pydebuggerconfig utility.
Device and Board XML files
The actual configuration data to be programmed into the PKOB nano debugger's configuration space is stored in XML files,
one file for the data concerning the debugger and kit itself and one file with data concerning the target device.
The board related files are stored in the pydebuggerconfig/board-configs folder and the device specific files
are stored in the pydebuggerconfig/device-configs folder. pydebuggerconfig also supports XML files stored in
other folders by providing the full path to the files.
The specifications for the config XML files are stored in the pydebuggerconfig/config-specification folder.
Each configuration file specifies which specification version to be used by the version registers in the XML file.
These are called CONFIG_FORMAT_MAJOR, CONFIG_FORMAT_MINOR and CONFIG_FORMAT_BUILD for board configuration files and
DEVICE_CONFIG_MAJOR, DEVICE_CONFIG_MINOR and DEVICE_CONFIG_BUILD for device configuration files. The version of
the specification files are given by the file name. Example:
A board config XML file with the following version registers
<register name="CONFIG_FORMAT_MAJOR" value="1"/>
<register name="CONFIG_FORMAT_MINOR" value="5"/>
<register name="CONFIG_FORMAT_BUILD" value="47"/>

will refer to specification files board_config_defines-1.5.47.xml and board_config_defines-1.5.47.xsd
Usage
pydebuggerconfig can be used as a command-line interface or a library
Command-line
for help, use:
pydebuggerconfig --help

Important note on order of command line arguments
It is recommended to put the action next to pydebuggerconfig on the command line. This is in some cases important as
some of the command line arguments takes a list of values and if the action is placed next to such an argument the
action will be interpreted as one of the argument values. Example:
WRONG: pydebuggerconfig -b board-configs/PIC16F18446-CNANO.xml -d device-configs/PIC16F18446-device-blob.xml -p SERNUM write

This will not work as the -p argument takes a list of registers, so write is interpreted as a register to preserve and no
action is found
CORRECT: pydebuggerconfig write -b board-configs/PIC16F18446-CNANO.xml -d device-configs/PIC16F18446-device-blob.xml -p SERNUM

This will work as the action comes first so it is not seen as a part of any of the arguments
Action: read
reads out the config from a board

use -f to read from factory section instead of user section for board config

pydebuggerconfig read

This will read out both board and device config from the kit and print it in a human readable format
Action: write
writes config from board and/or device files

use -b to specify board config XML file
use -d to specify device config XML file
use -f to write to factory section in addition to user section of board config
use -p to preserve the value of one or more registers

To use bundled board and device files the path relative to pydebuggerconfig package is sufficient, i.e. board-configs/<board file> and device-configs/<device file>.
pydebuggerconfig write -b board-configs/ATmega4809-CNANO.xml -d device-configs/ATmega4809-device-blob.xml

Action: replace
replaces the value of one or more registers in config

use -r to specify which registers to update

pydebuggerconfig replace -r SERNUM=MCHP0000111122223333 KITNAME="My new kit"

Action: show
to print the content of config xml files in a human readable format

use -b to specify board config XML file
use -d to specify device config XML file

pydebuggerconfig show -b board-configs/ATmega4809-CNANO.xml -d device-configs/ATmega4809-device-blob.xml

Action: verify
to compare the content of config XML files with the config on a kit

use -b to specify board config XML file
use -d to specify device config XML file

To use bundled board and device files the path relative to pydebuggerconfig package is sufficient, i.e. board-configs/<board file> and device-configs/<device file>.
pydebuggerconfig verify -b board-configs/ATmega4809-CNANO.xml -d device-configs/ATmega4809-device-blob.xml

Action: restore
to restore board config to factory settings
pydebuggerconfig restore

This will copy the board config on the kit from the factory section to the user section
Action: version-update
to update the version of the board config in a kit
pydebuggerconfig version-update

This will update the version registers in the board config to the latest available spec version to allow new
registers to be supported. It depends on back-compatibility, i.e. minor version updates only. Note that this command
will not change the actual config settings.
Action: generate-hex
to generate a hex file from config xml files

use -b to specify board config XML file
use -d to specify device config XML file

pydebuggerconfig generate-hex -b board-configs/ATmega4809-CNANO.xml -d device-configs/ATmega4809-device-blob.xml

This will generate an Intel-hex file with the XML files contents. This file can then be programmed directly into the debugger.
This feature is most useful when making pre-programmed debuggers.
Action: list
to list all board-configurations and device-configurations which are bundled with the package
pydebuggerconfig list

This will show the contents of the config folders which are bundled with the package.
Command-line switches
Many of these switches are optional, and some only apply to certain actions. See the action details above.

-b BOARD to specify board XML file. Some actions require at least either a board XML file or a device XML file but
not necessarily both. Can be either an absolute path or a path relative to pydebuggerconfig folder,
i.e. board-configs/ATmega4809-CNANO.xml.
-d DEVICE to specify device XML file. Some actions require at least either a device XML file or a board XML file but
not necessarily both. Can be either an absolute path or a path relative to pydebuggerconfig folder,
i.e. device-configs/ATmega4809-device-blob.xml.
-s SERIALNUMBER to specify the USB serial number of the kit/debugger to connect to when reading and writing config data.
This is not the USB serial number to program into the config, it is the serial number of the debugger before any config
has been written. Sub-string matching on end of serial number is supported. If this argument is omitted or set to an
empty string pydebuggerconfig will connect to any PKOB nano debugger connected to the host if there is only one connected.
If there are more than one matching debugger connected, pydebuggerconfig will just terminate with an error message.
-S CONFIG_SERIALNUMBER to specify the USB serial number to program to the kit. The serial number should be 20 ASCII characters.
This option makes it possible to program a custom serial number to a kit while fetching the rest of the config parameters
from a board config XML file. Without this option the serial number will be fetched from the board config XML file
(usually set to "FFFFFFFFFFFFFFFFFFFF"). Note that the new serial number will not latch (be used) until the debugger
is rebooted.
-p PRESERVE [PRESERVE ...] to specify registers that should not be updated when writing config data to the kit. These registers
will keep their current values even if new values are given in the provided config XML files.
-r REGISTER [REGISTER ...] to specify register values to replace. Only used with replace action.
-f to access factory board config section. For read it means read factory board config while for write it means
write both factory and user board config. There is no factory section for device config.
-v to enable verbose output.
-vv to enable debug output.
-V to print pydebuggerconfig version number and exit.
-R to print pydebuggerconfig release details and exit.

Library
pydebuggerconfig can be used as a library using its "backend API". For example:
# Instantiate backend (if more than one kit is connected a serial number must be provided as parameter to the Backend constructor)
from pydebuggerconfig.backend import Backend
pb = Backend()

# Write board configuration data to a kit, preserving KITNAME and setting custom USB serial number
board_config_string = pb.write_board_config("board-configs/ATmega4809-CNANO.xml", serial_number="MYSERIALNUMBER012345", preserve=['KITNAME'])
print("Written board config to kit:")
print(board_config_string)

# Write device configuration data to a kit
device_config_string = pb.write_device_config("device-configs/ATmega4809-device-blob.xml)
print("Written device config to kit:")
print(device_config_string)

# Update the name and serial number of a kit
registers = {'KITNAME': 'My new kitname', 'SERNUM': 'MYNEWSERIAL012345678'}
pb.replace(registers)

# Read out and print board configuration data from a kit
board_config_string = pb.read_board_config_as_string("board-configs/ATmega4809-CNANO.xml")
print("Board config from kit:")
print(board_config_string)

# Read out and print device configuration data from a kit
device_config_string = pb.read_device_config_as_string()
print("Device config from kit:")
print(device_config_string)

# Print the pydebuggerconfig package version
from pydebuggerconfig import __version__ as pydebuggerconfig_version
print("pydebuggerconfig version {}".format(pydebuggerconfig_version))

# In addition, the CLI-backend API is versioned for convenience
print("pydebuggerconfig backend API version: {}".format(pb.get_api_version()))

Dependencies
pydebuggerconfig depends on pyedbglib for its transport protocol. pyedbglib requires a USB transport library like libusb.
See pyedbglib package for more information.
Supported tools
pydebuggerconfig only supports PKOB nano (nEDBG) debuggers. These are typically found on Curiosity Nano kits.
Linux systems
This 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/pyedbglib
Changelog
[3.11] - March 2024
Added

DSG-3022 Update documentation to describe how to use bundled configuration files
DSG-5755 Add CLI catch-all exception handler to pydebuggerconfig
DSG-5884 SAM-IoT Wx board configuration
DSG-6060 Extend CONFIG to cater for immutable boot and boot row memtype
DSG-6139 EBV-IoT Mirochip ATECC608 Secure Shield board configuration
DSG-6144 List all available configurations through the CLI
DSG-6510 Prepare pydebuggerconfig for new build commands

Changed

DSG-6990 Refactor pydebuggerconfig id_extension_tool backend to make it usable as a library

Fixed

DSG-2253 Pydebuggerconfig crashes when a single digit hex value is used for an ENUM register
DSG-4169 PIC24FJ128GA705 device config is broken
DSG-4725 Pydebuggerupgrade requirements ambiguity for python 2.7
DSG-6852 Config words fail to write
DSG-6991 Pydebuggerconfig id_extension_tool does not check 16-bit overflow

[3.9] - December 2021
Added

DSG-2503 Added support for PIC18F16Q40 and PIC18F16Q41 Curiosity Nano boards
DSG-5421 Added support for AVR DU and additional AVR DD devices
DSG-3804 Added Python 3.9 support

Changed

DSG-5418 Added Python 3.10 metadata tag
DSG-5543 Removed Python 3.6 metadata tag
DSG-5417 Removed distutils usage

Fixed

DSG-2200 Handle missing exact specification version
DSG-2230 Naming consistency audit
DSG-2310 Clarification: -fa switch is "ALSO factory section" (not JUST factory section)
DSG-2423 Python package zip artifact is missing pypi.md file
DSG-2459 Python package broken on Py 2.7
DSG-2576 Fix short form switches
DSG-3061 Fuse protection not enabled on AVR EA Curiostiy Nano
DSG-3104 Crash while replacing KEY2
DSG-3111 Package version in Python wheel metadata does not match wheel version for wheels from non-master branches
DSG-4328 Fixed -s confusion

[3.5] - October 2020

First public release to PyPi