9 Debugger Configuration

The Nano Debugger uses a portion of its internal non-volatile memory to store information about the hardware it interacts with. This content is typically programmed during manufacturing but can also be modified by end users. This configuration is preserved when debugger firmware is updated, and is thus an important mechanism to prevent specific customizations from being made in the firmware itself.

Debugger configuration includes two parts:

Board configuration describes the board on which the Nano Debugger is mounted and is mandatory
Device configuration describes the device that is permanently mounted to a kit and is optional

Tip: If no device configuration is needed, a dummy configuration is used. This indicates to the Nano Debugger that drag-and-drop programming is not available.

9.1 Board Configuration

The board configuration (or board-config) of the Nano Debugger resides in a section of non-volatile memory. The board configuration format is specified in XML, with various offsets in this section allocated to different fields and bits. The API to the host computer is simply a block read/write operation with no knowledge of the format. The meaning of the fields is defined by the Python files (for the host computer) and header files (for the Nano Debugger) generated from the configuration XML itself. New fields can be added without changing the API by allocating unused space in the XML and regenerating the Python and header files. The XML schema uses semantic versioning (semver) for compatability.

Table 9-1. Board Configuration 1.14
Register	Size	Description	What its for/Default Value
DEVNAME	Up to 32 ASCII characters	Device name	Specify the exact device name here if a device is permanently mounted on the board. If the target device is not mounted on the board this field must be blank.
KITNAME	Up to 60 ASCII characters	Kit name	Give your kit a nice name here
MNFRNAME	Up to 60 ASCII characters	Manufacturer name	Specify who you are as a vendor
SERNUM	20 characters	USB serial number	A specific USB serial number can be set here. It is recommended to use exactly 20 upper-case alphanumeric characters and no spaces. Setting the "automatic serial number" bit will override this at enumeration time, but the original value will remain in the configuration in flash memory.
REDIRECT	4 characters	Redirect ID	See note below
DATE	8 digits	Manufacturing date	Optionally specify the manufacturing date of the kit in format YYYYMMDD
INSTANCE	1 byte	Content revision	This is a simple version field, and can be incremented for each change made to the configuration
TARGET_DEBUG_INTERFACES	4 bytes	Set of programing and debugging interfaces supported	Set the bits in this bitfield to indicate which physical interface(s) are supported in this implementation. Relevant bits are: Bit 1: SWD for ARM devices Bit 8: UPDI for AVR devices Bit 10: SWO for ARM devices Bit 11: ICSP for PIC and dsPIC® devices
TARGET_DEBUG_FEATURES	1 byte	Set of programming and debugging features implemented	Set the bits in this bitfield to enable individual features: Relevant bits are: Bit 0: SINGLE_DEVICE - set this bit if the device is permanently mounted to the board Bit 1: PROG_ENABLED - set this bit to enable programming Bit 2: DEBUG_ENABLED - set this bit to enable debugging Bit 3: FUSE_CONFIG_PROTECTION - set this bit to enable protection of fuses and configuration bytes. A set of protection masks must be provided in the device configuration for this to work. Bit 4: AUTO_SERIAL_NUMBER - set this bit to automatically generate a USB serial number
DGI_INTERFACES	4 bytes	Set of DGI interfaces supported	Set the bits in this bitfield to indicate to the debugger which DGI interfaces are connected. Relevant bits are: Bit 0: GPIO
DGI_GPIO_MAP	1 byte	Map of DGI GPIO channels	Set the bits in this bitfield to indicate to the debugger which DGI GPIO lines are connected. Relevant bits are: Bit 0: DGI_GPIO0 Bit 1: DGI_GPIO1
ANALOG_FEATURES	4 bytes	Analog features	Set the bits in this bitfield to indicate to the debugger which analog implementation is present on the board. Relevant bits are: Bit 0: TVS - the debugger can control the target voltage Bit 1: TVR - the debugger can measure the target voltage Bit 2: LVC - level shifters are present between debugger and the target
VMIN	1 byte	Minimum voltage	For adjustable-voltage boards, specify the minimum voltage in deciVolts
VMAX	1 byte	Maximum voltage	For adjustable-voltage boards, specify the maximum voltage in deciVolts
VTG	1 byte	Default voltage	For adjustable-voltage boards, specify the default voltage in deciVolts
VREG	1 byte	Voltage regulator	Specify the voltage regulation circuit implemented Values are: 0x00 - not adjustable 0x01 - adjustable regulator configuration 1 controlled by the Nano Debugger
ID_CHANNELS	1 byte	ID channels	Specify which ID channels are implemented Bit 0: ID channel 1
CONFIG_FORMAT_MAJOR CONFIG_FORMAT_MINOR CONFIG_FORMAT_BUILD	4 bytes	The version of the configuration specification being used. If new fields are added, this version is updated and this document will also be updated.	(latest)
HARDWARE_MOD	1 byte	Specify hardware modifications which affect the firmware	0x00
USB_ENUMERATION	1 byte	USB enumeration	0x03
MSD_SETTINGS	1 byte	Mass storage content settings	0x00
CLICK_ME_TYPE	1 byte	Click-me type configuration	0xFF
I2C_ADDR_0, I2C_ADDR_1	1 byte	I2C address, alternative I2C address	0x00
LABS	1 byte	Activate experimental firmware features	0x00
KEY1_TYPE	1 byte	Key type: 0: None 1: 48-bit MAC 2: 64-bit MAC 3: UUID 4: UID 5: PUBKEY	IoT kits
KEY2_TYPE	1 byte	Key type: 0: None 1: 48-bit MAC 2: 64-bit MAC 4: UID	IoT kits
KEY3_TYPE	1 byte		IoT kits
KEY4_TYPE	1 byte		IoT kits
KEY1_LEN	1 byte	Up to 64 bytes	Length of content of KEY1
KEY2_LEN	1 byte	Up to 32 bytes	Length of content of KEY2
KEY3_LEN	1 byte	Up to 16 bytes	Length of content of KEY3
KEY4_LEN	1 byte	Up to 16 bytes	Length of content of KEY4
KEY1	64 bytes	Key 1 value	-
KEY2	32 bytes	Key 2 value	-
KEY3	16 bytes	Key 3 value	-
KEY4	16 bytes	Key 4 value	-

Note: The REDIRECT_ID field is used to populate the URL on the USB Mass Storage disk, redirecting via kits.microchip.com to a product-specific web page. Contact Microchip support or edbg@microchip.com if you want to customize a Nano Debugger for your product.

9.2 Device Configuration

The device configuration of the Nano Debugger provides information about the device that is permanently connected to the debugger. Its main function is to support drag-and-drop programming, which needs to be self-contained (no IDE is involved). The device configuration can be empty (unprogrammed), but it is recommended to program a null or dummy device configuration in cases where drag-and-drop programming is not supported (e.g., ARM target devices) or when a target device is not mounted (e.g., a standalone debugger scenario).

Device configuration has only a single instance, and is not intended to be modified by the user.

The images in the Nano Debugger firmware zip include the null device configuration.

The pydebuggerconfig tool available on pypi.org can be used to write or replace the device config on a Nano Debugger.

Device Configuration - Advanced Information

Important: This information is for reference only. The device configuration is not intended to be user-serviced.

The device configuration is a 3 kB section in non-volatile memory on the Nano Debugger that is preserved during debugger upgrades.

Table 9-2. Header Structure
Offset	Type	Field	Description
0	uint8	major version	Major version of device-specific configuration specification
1	uint8	minor version	Minor version
2	uint16	build number	Build number of specification
4	uint16	content length	Number of bytes of actual content (after header)
6	uint16	content checksum	Checksum over content (not currently validated)
8	uint8	instance	Version of this config instance. Sequentially increasing.
9	7 bytes	reserved	For future use

Table 9-3. Version 1 Encoding
Offset	Type	Field	Description
16	uint8 (enum)	programming interface type	0x00: None 0x01: AVR UPDI by EDBG API 0x02: reserved 0x03: PIC by GEN4 binary code 0x04: PIC by GEN4 primitives 0x05-0xFF: reserved
17	uint8 (enum)	device sub-variant	For PIC devices: 0x00: PIC16 0x01: PIC18 0x02: PIC24/dsPIC 0x03-0xFF: reserved
18	14 bytes	reserved	For future use

After these headers, a lookup table of relative offsets of binary objects (BLOB) is encoded

Table 9-4. BLOB Table Encoding
Offset	Type	Field	Description
32	uint8	'L'	List token
33	uint8	size	Number of items
34	uint16	offset	Offset of item 1
...	...	...	...
34+2n	uint16	offset	Offset of item n

Each BLOB is encoded

Table 9-5. BLOB Header Encoding
Offset	Type	Field	Description
0	uint8	Structure type	'S': binary object from GEN4 script 'D': device context (as used for AVR)
1	uint8	ID	eg: script ID
2	uint16	size	data length in bytes
...		data	binary data

Table 9-6. GEN4 Script Binary Types
ID	Function
0	Binary code for enter programming mode
1	Binary code for get device ID
2	Binary code for erase chip
3	Binary code for program flash memory
4	Binary code for program config words
5	Binary code for exit programming mode
6	Binary code for read flash memory

Device Context (parametric device data)

The Device Context for AVR devices is described in the Embedded Debugger-Based Tools Protocol User's Guide and in pymcuprog.

Table 9-7. Device Context for AVR devices
Offset	Size	Description
0x00	uint16	Base address for Program Flash memory
0x02	uint8	Flash page bytes
0x03	uint8	EEPROM page bytes
0x04	uint16	Address of NVMCTRL module
0x06	uint16	Address of OCD module
0x08	uint16	reserved
0x0A	uint16	reserved
0x0C	uint16	reserved
0x0E	uint16	reserved
0x10	uint16	Maximum frequency of PDI pin
0x12	uint32	Flash size in bytes
0x16	uint16	EEPROM size in bytes
0x18	uint16	User Row size in bytes
0x1A	uint8	Fuse memory size in bytes
0x1B	uint8	Offset of SYSCFG0 or PINCFG fuse within fuse area
0x1C	uint8	AND mask to apply to SYSCFG/PINCFG value when writing
0x1D	uint8	OR mask to apply to SYSCFG/PINCFG value when writing
0x1E	uint8	AND mask to apply to SYSCFG/PINCFG value after erase
0x1F	uint8	OR mask to apply to SYSCFG/PINCFG value after erase
0x20	uint16	Base address of EEPROM memory
0x22	uint16	Base address of User Row memory
0x24	uint16	Base address of Signature Row memory
0x26	uint16	Base address of Fuse memory
0x28	uint16	Base addrses of Lockbits memory
0x2A	uint16	Device ID
0x2C	uint8	MSB of base address of Program Flash memory (extends offset 0x00)
0x2D	uint8	MSB of flash page size in bytes (extends offset 0x02)
0x2E	uint8	Addressing mode of UPDI: 0x00: use 16-bit addressing 0x01: use 24-bit addressing
0x2F	uint8	High-voltage implementation
0x30	uint16	Base address of Boot Row
0x32	uint16	Boot Row size in bytes
0x34	uint16	Fuse protection mask. One bit per fuse byte (from LSB): 0: write allowed 1: protected

The Device Context for PIC devices is described here:

Table 9-8. Device Context for PIC Devices
Offset	Size	Description
0x00	uint32	Base address for PFM (Program Flash Memory)
0x04	uint32	Base address for EEPROM memory
0x08	uint32	Base address for User Row memory
0x0C	uint32	Base address for Configuration memory
0x10	uint32	Flash size in bytes
0x14	uint16	EEPROM size in bytes
0x16	uint16	User Row size in bytes
0x18	uint16	Configuration memory size in bytes
0x1A	uint16	Flash write block size in bytes
0x1C	uint16	EEPROM write block size in bytes
0x1E	uint8	User Row write block size in bytes
0x1F	uint8	Configuration memory write block size in bytes
0x20	uint16	Device ID
0x22	uint32	Configuration memory protection mask. One bit per configuration location (from LSB): 0: write allowed 1: protected

9.3 Modifying the Debugger Configuration

The board configuration and device configuration can be changed by the end user using the pydebuggerconfig utility.

For more general information about using pydebuggerconfig, see the information on pypi.org.

Use-Case: Altering the Configuration for Device Protection

When used in conjunction with AVR devices that are permanently mounted to a kit, the Nano Debugger includes a protection mechanism intended to prevent the MCU from becoming unrecoverable, especially when using drag-and-drop programming. Disabling the programming and debugging interface or permanently locking memories are features of some MCUs that are not conducive to evaluation on a development kit platform.

The protection mechanism works by intercepting write operations to the relevant fuses or configuration bits and conditionally masking the addresses and values written.

Info: The protection mechanism is intended to prevent making accidental irreversible changes. Users intentionally making irreversible changes do so at their own risk.

Info: The available feature-set and corresponding prevention mechanisms depend on the device. Check the data sheet for further information.

The protection mechanism can be disabled for users who want to have the full experience of features that require irreversible changes. Doing so will result in permanent changes.

pydebuggerconfig can be used to tweak many aspects of the debugger, including configuration protection. This procedure requires the installation of a recent release of Python 3 and the pydebuggerconfig package in that environment.

Step 1: Current Status

Determine whether protection is currently enabled by executing:

pydebuggerconfig read

Next, check for the section:

Register TARGET_DEBUG_FEATURES:   0x0F (15)  # Program/debug features
            bit 0, SINGLE_DEVICE: 1 # Single-device
            bit 1, PROG_ENABLED: 1 # Programming
            bit 2, DEBUG_ENABLED: 1 # Debug
            bit 3, FUSE_PROTECTION: 1 # Fuse protection

A FUSE_PROTECTION value of '1' indicates that protection is in place.

Step 2: Modifying the Protection Setting

Calculate the desired setting for TARGET_DEBUG_FEATURES by setting FUSE_PROTECTION to '0'. Replace the current value in the TARGET_DEBUG_FEATURES register by executing, for example:

pydebuggerconfig replace -r TARGET_DEBUG_FEATURES=0x07

To verify the new value, repeat the process from step 1 and then toggle the power on the kit. All protection mechanisms are now disabled.

Step 3: Restoring Protection

Protection can be re-enabled either by repeating step 2 with the initial value or using the factory-restore function by executing:

pydebuggerconfig restore

Important: The restore function will only restore any kit configuration settings that have been altered since manufacturing, by restoring a copy of the kit configuration settings stored internally on the debugger. This operation does not affect the MCU and will not undo any irreversible changes made to its configuration.