3 On-Board Debugger

3.1 On-Board Debugger Overview

PIC18F56Q24 Curiosity Nano contains an on-board debugger for programming and debugging. The on-board debugger is a composite USB device consisting of several interfaces:

A debugger that can program and debug the PIC18F56Q24 in MPLAB® X IDE
A virtual serial port (CDC) that is connected to a Universal Asynchronous Receiver/Transmitter (UART) on the PIC18F56Q24 and provides an easy way to communicate with the target application through terminal software
A mass storage device that allows drag-and-drop programming of the PIC18F56Q24
A Data Gateway Interface (DGI) for code instrumentation with logic analyzer channels (debug GPIO) to visualize program flow

The on-board debugger controls a Power and Status LED (marked PS) on the PIC18F56Q24 Curiosity Nano board. The table below shows how the different operation modes control the LED.

Table 3-1. On-Board Debugger LED Control
Operation Mode	Power and Status LED
Boot Loader mode	The LED blinks slowly during power-up
Power-up	The LED is ON
Normal operation	The LED is ON
Programming	Activity indicator: The LED blinks slowly during programming/debugging
Drag-and-drop programming	Success: The LED blinks slowly for 2 sec. Failure: The LED blinks rapidly for 2 sec.
Fault	The LED blinks rapidly if a power fault is detected
Off	The on-board debugger is powered down, the LED is OFF

Info: Slow blinking is approximately 1 Hz, and rapid blinking is about 5 Hz.

3.2 On-Board Debugger Connections

The table below shows the connections between the target and the debugger section. All the connections between the target and the debugger are tri-stated when the debugger is not using the interface. Hence, there are few contaminations of the signals, e.g., the pins can be configured to anything the user wants.

Info: The 12-edge connections closest to the USB connector on Curiosity Nano boards have a standardized pinout. The program/debug pins have different functions depending on the target programming interface.

Table 3-2. On-Board Debugger Connections
Debugger Pin	PIC18F56Q24 Pin		Description
CDC TX	RB4	UART RX	USB CDC TX line
CDC RX	RB5	UART TX	USB CDC RX line
DBG0	RB7	ICSPDAT	Debug data line
DBG1	RB6	ICSPCLK	Debug clock line
DBG2	RF3	SW0/GPIO0	Debug GPIO0/SW0
DBG3	RE3	MCLR	Reset line
ID	—	—	ID line for extensions
NC	—	—	No connect
V_BUS	—	—	V_BUS voltage for external use
VOFF	—	—	Voltage Off input. Disables the target regulator and target voltage when pulled low.
VTG	—	—	Target voltage
GND	—	—	Common ground

Figure 3-1. Curiosity Nano Debugger Pinout

Tip: For the complete PIC18F56Q24 Curiosity Nano pinout, see the PIC18F56Q24 Curiosity Nano Pinout.

3.3 Debugger USB Enumeration

The on-board debugger on the PIC18F56Q24 Curiosity Nano board appears as a Human Interface Device (HID) on the host computer’s USB subsystem. The debugger supports full-featured programming and debugging of the PIC18F56Q24 using MPLAB X IDE.

Remember: Keep the debugger’s firmware up-to-date. Firmware upgrades automatically when using MPLAB X IDE.

3.4 Virtual Serial Port (CDC)

The virtual serial port (CDC) is a general purpose serial bridge between a host PC and a target device.

3.4.1 Overview

The on-board debugger implements a composite USB device with a standard Communications Device Class (CDC) interface, which appears on the host as a virtual serial port. Use the CDC to stream arbitrary data between the host computer and the target in both directions: All characters sent through the virtual serial port on the host computer will be transmitted as UART on the debugger’s CDC TX pin. The UART characters captured on the debugger’s CDC RX pin will be returned to the host computer through the virtual serial port.

Figure 3-2. CDC Connection

Info: The debugger’s CDC TX pin is connected to a UART RX pin on the target for receiving characters from the host computer, as shown in the figure above. Similarly, the debugger’s CDC RX pin is connected to a UART TX pin on the target for transmitting characters to the host computer.

3.4.2 Operating System Support

On Windows® machines, the CDC will enumerate as Curiosity Virtual COM Port and appear in the Ports section of the Windows Device Manager. The COM port number can also be found there.

Info: On older Windows systems, the CDC requires a USB driver. The MPLAB X IDE installation include this driver.

On Linux® machines, the CDC will enumerate and appear as /dev/ttyACM#.

Info: tty* devices belong to the “dialout” group in Linux, so it may be necessary to become a member of that group to have permission to access the CDC.

On Mac® machines, the CDC will enumerate and appear as /dev/tty.usbmodem#. Depending on the terminal program used, it will appear in the available list of modems as usbmodem#.

Info: For all operating systems, use a terminal emulator that supports DTR signaling. See 3.4.4 Signaling.

3.4.3 Limitations

Not all UART features are implemented in the on-board debugger CDC. The constraints are outlined here:

Baud rate: Must be in the range of 1200 bps to 500 kbps. Any baud rate outside this range will be set to the closest limit without warning. Baud rate can be changed on-the-fly.
Character format: Only 8-bit characters are supported.
Parity: Can be odd, even, or none.
Hardware flow control: Not supported.
Stop bits: One or two bits are supported.

3.4.4 Signaling

During USB enumeration, the host OS will start both the communication and data pipes of the CDC interface. At this point, it is possible to set and read back the baud rate and other UART parameters of the CDC, but data sending and receiving will not be enabled.

The terminal must assert the DTR signal when it connects to the host. As this is a virtual control signal implemented on the USB interface, it is not physically present on the board. Asserting the DTR signal from the host will indicate to the on-board debugger that a CDC session is active. The debugger will enable its level shifters (if available) and start the CDC data send and receive mechanisms.

Deasserting DTR in debugger firmware version 1.20 or earlier has the following behavior:

Debugger UART receiver is disabled, and no further data will be transferred to the host computer
Debugger UART transmitter will continue to send queued data ready for transfer, but no new data is accepted from the host computer
Level shifters (if available) are not disabled, and the debugger CDC TX line remains driven

Deasserting DTR in debugger firmware version 1.21 or later has the following behavior:

Debugger UART receiver is disabled, and no further data will be transferred to the host computer
Debugger UART transmitter will continue to send queued data ready for transfer, but no new data is accepted from the host computer
Once the ongoing transmission is complete, level shifters (if available) are disabled, and the debugger CDC TX line will become high-impedance

Remember: Set up the terminal emulator to assert the DTR signal. Without the signal, the on-board debugger will not send or receive data through its UART.

Tip: The on-board debugger’s CDC TX pin will not be driven until the CDC interface is enabled by the host computer. Also, there are no external pull-up resistors on the CDC lines connecting the debugger and the target, meaning the lines are floating during power-up. The target device may enable the internal pull-up resistor on the pin connected to the debugger’s CDC TX pin to avoid glitches resulting in unpredictable behavior like framing errors.

3.4.5 Advanced Use

CDC Override Mode

In ordinary operation, the on-board debugger is a true UART bridge between the host and the device. However, in certain use cases, the on-board debugger can override the basic Operating mode and use the CDC TX and RX pins for other purposes.

Dropping a text file into the on-board debugger’s mass storage drive can be used to send characters out of the debugger’s CDC TX pin. The filename and extension are trivial, but the text file will start with the characters:

CMD:SEND_UART=

Debugger firmware version 1.20 or earlier has the following limitations:

The maximum message length is 50 characters – all remaining data in the frame are ignored
The default baud rate used in this mode is 9600 bps, but if the CDC is already active or configured, the previously used baud rate still applies

Debugger firmware version 1.21 and later has the following limitations/features:

The maximum message length will vary depending on the MSC/SCSI layer timeouts on the host computer and/or operating system. A single SCSI frame of 512 bytes (498 characters of payload) is ensured, and files up to 4 KB will work on most systems. The transfer will complete on the first NULL character encountered in the file.
The baud rate used is always 9600 bps for the default command:
```
CMD:SEND_UART=
```
Do not use the CDC Override mode simultaneously with data transfer over the CDC/terminal. If a CDC terminal session is active when receiving a file via the CDC Override mode, it will be suspended for the duration of the operation and resumed once complete.
Additional commands are supported with explicit baud rates:
```
CMD:SEND_9600=
```
```
CMD:SEND_115200=
```
```
CMD:SEND_460800=
```

USB-Level Framing Considerations

Sending data from the host to the CDC can be done byte-wise or in blocks, chunked into 64-byte USB frames. Each frame will be queued for transfer to the debugger’s CDC TX pin. Sending a small amount of data per frame can be inefficient, particularly at low baud rates, as the on-board debugger buffers frames but not bytes. A maximum of four 64-byte frames can be active at any time. The on-board debugger will throttle the incoming frames accordingly. Sending full 64-byte frames containing data is the most efficient method.

When receiving data on the debugger’s CDC RX pin, the on-board debugger will queue up the incoming bytes into 64-byte frames, which are sent to the USB queue for transmission to the host when they are full. Incomplete frames are also pushed to the USB queue at approximately 100 ms intervals, triggered by USB start-of-frame tokens. Up to eight 64-byte frames can be active at any time.

An overrun will occur if the host (or the software running on it) fails to receive data fast enough. When this happens, the last-filled buffer frame recycles instead of being sent to the USB queue, and a complete data frame will be lost. To prevent this occurrence, the user will ensure that the CDC data pipe is continuously read, or the incoming data rate will be reduced.

Sending Break Characters

The host can send a UART break character to the device using the CDC, which can be useable for resetting a receiver state-machine or signaling an exception condition from the host to the application running on the device.

A break character is defined as a sequence of at least 11 zero bits transmitted from the host to the device.

Not all UART receivers have support for detecting a break, but a correctly-formed break character usually triggers a framing error on the receiver.

Sending a break character using the debugger's CDC has the following limitations:

Sending a break must NOT be done simultaneously, as using the CDC Override mode (drag-and-drop). Both these functions are temporary states and must be used independently.
Sending a break will cause the data currently being sent to be lost. Be sure to wait a sufficient amount of time to allow all characters in the transmission buffer to be sent (see above section) before sending the break, which is also in line with expected break character usage: For example, reset a receiver state-machine after a timeout occurs waiting for returning data to the host.
The CDC specification allows for debugger-timed breaks of up to 65534 ms in duration to be requested. For simplicity, the debugger will limit the break duration to a maximum of 11 bit-durations at its minimum supported baud rate.
The CDC specification allows for indefinite host-timed breaks. It is the responsibility of the terminal application/user to release the break state in this case.

Note: Sending break characters is available in debugger firmware version 1.24 and later.

3.5 Mass Storage Device

The on-board debugger includes a simple Mass Storage Device implementation, which is accessible for read/write operations via the host operating system to which it is connected.

It provides:

Read access to basic text and HTML files for detailed kit information and support
Write access for programming Intel® HEX formatted files into the target device’s memory
Write access for simple text files for utility purposes

3.5.1 Mass Storage Device Implementation

The on-board debugger implements a highly optimized variant of the FAT12 file system with several limitations, partly due to the nature of FAT12 itself and optimizations made to fulfill its purpose for its embedded application.

The Curiosity Nano USB device is USB Chapter 9-compliant as a mass storage device but does not, in any way, fulfill the expectations of a general purpose mass storage device. This behavior is intentional.

When using the Windows operating system, the on-board debugger enumerates as a Curiosity Nano USB Device found in the disk drives section of the device manager. The CURIOSITY drive appears in the file manager and claims the following available drive letter in the system.

The CURIOSITY drive contains approximately one MB of free space and does not reflect the target device’s Flash size. When programming an Intel HEX file, the binary data are encoded in ASCII with metadata providing a vast overhead, so 1 MB is a trivially chosen value for disk size.

It is not possible to format the CURIOSITY drive. The filename may appear in the disk directory listing when programming a file to the target, which is merely the operating system’s view of the directory that, in reality, has not been updated. It is not possible to read out the file contents. Removing and replugging the board will return the file system to its original state, but the target will still contain the previously programmed application.

Copy a text file starting with “CMD:ERASE” onto the disk to erase the target device.

By default, the CURIOSITY drive contains several read-only files for generating icons as well as reporting status and linking to further information:

AUTORUN.ICO – icon file for the Microchip logo
AUTORUN.INF – system file required for Windows Explorer to show the icon file
KIT-INFO.HTM – redirect to the development board website
KIT-INFO.TXT – a text file containing details about the board’s debugger firmware version, board name, USB serial number, device, and drag-and-drop support
STATUS.TXT – a text file containing the programming status of the board

Info: The on-board debugger dynamically updates STATUS.TXT. The contents may not reflect the correct status as the OS may cache it.

3.5.2 Special Commands

Several utility commands are supported by copying text files to the mass storage disk. The filename or extension is irrelevant – the command handler reacts to content only.

Table 3-3. Special File Commands
Command Content	Description
`CMD:ERASE`	Executes a chip erase of the target
`CMD:SEND_UART=`	Sends a string of characters to the CDC UART. See “CDC Override Mode.”
`CMD:SEND_9600=` `CMD:SEND_115200=` `CMD:SEND_460800=`	Sends a string of characters to the CDC UART at the specified baud rate. Note that only the baud rates explicitly specified here are supported. See “CDC Override Mode.” (Debugger firmware v1.25.6 or newer.)
`CMD:RESET`	Resets the target device by entering Programming mode and exiting Programming mode immediately afterward. The exact timing can vary according to the programming interface of the target device. (Debugger firmware v1.25.6 or newer.)
`CMD:POWERTOGGLE`	Powers down the target and restores it after a 100 ms delay. If external power is provided, this has no effect. (Debugger firmware v1.25.6 or newer.)
`CMD:0V`	Powers down the target device by disabling the target supply regulator. If external power is provided, this has no effect. (Debugger firmware v1.25.6 or newer.)
`CMD:1V8`	Sets the target voltage to 1.8V. If external power is provided, this has no effect. (Debugger firmware v1.25.6 or newer.)
`CMD:3V3`	Sets the target voltage to 3.3V. If providing external power, this has no effect. (Debugger firmware v1.25.6 or newer.)

Info: The content sent to the mass storage emulated disk triggers the commands listed here and provides no feedback in the case of either success or failure.

3.6 Data Gateway Interface (DGI)

Data Gateway Interface (DGI) is a USB interface transporting raw and timestamped data between on-board debuggers and host computer-based visualization tools. MPLAB Data Visualizer is used on the host computer to display any debug GPIO data. It is available as a plug-in for MPLAB X IDE or a stand-alone application that can be used in parallel withMPLAB® X IDE.

Although DGI encompasses several physical data interfaces, the PIC18F56Q24 Curiosity Nano implementation includes logic analyzer channels:

One debug GPIO channel (also known as DGI GPIO)

3.6.1 Debug GPIO

Debug GPIO channels are timestamped digital signal lines connecting the target application to a host computer visualization application. They are typically used to plot low-frequency events on a time axis, such as when given Application state transitions occur.

The figure below shows the monitoring of the Digital state of a mechanical switch connected to a debug GPIO in the MPLAB Data Visualizer.

Figure 3-3. Monitoring Debug GPIO with MPLAB Data Visualizer

Debug GPIO channels are timestamped, so the resolution of DGI GPIO events is determined by the resolution of the DGI Timestamp module.

Important: Although signal bursts of higher frequency can be captured, the frequency range of signals for which debug GPIO can be used is up to about 2 kHz. Attempting to capture signals above this frequency will result in data saturation and overflow, which may cause the DGI session to be aborted.

3.6.2 Timestamping

When captured by the debugger, DGI sources are timestamped. The timestamp counter implemented in the Curiosity Nano debugger increments at a 2 MHz frequency, providing a timestamp resolution of a half microsecond.

3.7 Device Configuration Protection

The on-board debugger on the PIC18F56Q24 Curiosity Nano has a protection mechanism intended to prevent the MCU from being rendered 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 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 mechanism depend on the device. Check the data sheet for further information.

The protection mechanism can be disabled for users wanting to have the complete experience of given features that require irreversible changes. Doing this will result in permanent changes.

The pydebuggerconfig package distributed on pypi.org 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

Then 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 that the new value is set, repeat the process from step 1 and then toggle 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 altered kit configuration settings that have changed since manufacturing, which is done 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 that may have been made to its configuration.