3 On-Board Debugger
Features and interfaces of the on-board debugger for programming and debugging.
3.1 On-Board Debugger Overview
- 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.
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 |
|
Fault | The LED blinks rapidly if a power fault is detected |
Off | The on-board debugger is powered down, the LED is OFF |
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.
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 |
VBUS | — | — | VBUS voltage for external use |
VOFF | — | — | Voltage Off input. Disables the target regulator and target voltage when pulled low. |
VTG | — | — | Target voltage |
GND | — | — | Common ground |
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.
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.
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.
On Linux® machines, the CDC will enumerate and appear as /dev/ttyACM#
.
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#
.
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.
- 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
- 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
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.
CMD:SEND_UART=
- 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
- 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 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.
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.
- 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 logoAUTORUN.INF
– system file required for Windows Explorer to show the icon fileKIT-INFO.HTM
– redirect to the development board websiteKIT-INFO.TXT
– a text file containing details about the board’s debugger firmware version, board name, USB serial number, device, and drag-and-drop supportSTATUS.TXT
– a text file containing the programming status of the board
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.
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.” |
|
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.) |
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.
- 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.
Debug GPIO channels are timestamped, so the resolution of DGI GPIO events is determined by the resolution of the DGI Timestamp module.
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 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
pydebuggerconfig read
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
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
pydebuggerconfig restore