5 Virtual Serial Port (CDC)
The virtual serial port (CDC) is a general purpose serial bridge between a host PC and a target device.
5.1 Overview
The Nano 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.
5.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#.
5.3 Limitations
Not all UART features are implemented in the Nano 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. The 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.
5.4 Signaling
During USB enumeration, the host OS will start 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 sending and receiving data 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 Nano 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.
- The debugger UART receiver is disabled, and no more data will be transferred to the host computer
- The 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
- The debugger UART receiver is disabled, and no further data will be transferred to the host computer
- The debugger UART transmitter will continue to send queued data that are ready for transfer, but no new data will be 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
5.5 Advanced Use
CDC Override Mode
In ordinary operation, the Nano Debugger is a UART bridge between the host and the device. However, in certain use cases, the Nano 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 be completed 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 Nano Debugger buffers frames but not bytes. A maximum of four 64-byte frames can be active at any time. The Nano 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 Nano 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) 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, the user must ensure that the CDC data pipe is continuously read, or alternatively reduce the incoming data rate.
Sending Break Characters
The host can send a UART break character to the device using the CDC, which can be usable 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 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.
- A break must NOT be sent simultaneously with the use of CDC Override mode (drag-and-drop). Both these functions are temporary states and must be used independently.
- Sending a break will cause any data 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. In this case, it is the responsibility of the terminal application or user to release the break state.