usb_cdc – USB CDC Serial streams

The usb_cdc module allows access to USB CDC (serial) communications.

On Windows, each Serial is visible as a separate COM port. The ports will often be assigned consecutively, console first, but this is not always true.

On Linux, the ports are typically /dev/ttyACM0 and /dev/ttyACM1. The console port will usually be first.

On MacOS, the ports are typically /dev/cu.usbmodem<something>. The something varies based on the USB bus and port used. The console port will usually be first.

usb_cdc.console :Optional[Serial]
The console Serial object is used for the REPL, and for sys.stdin and sys.stdout.

console is None if disabled.

However, note that sys.stdin and sys.stdout are text-based streams, and the console object is a binary stream. You do not normally need to write to console unless you want to write binary data. :Optional[Serial]

A Serial object that can be used to send and receive binary data to and from the host. Note that data is disabled by default. data is None if disabled.


Do not present any USB CDC device to the host. Can be called in, before USB is connected. Equivalent to usb_cdc.enable(console=False, data=False).

usb_cdc.enable(*, console: bool = True, data: bool = False)None

Enable or disable each CDC device. Can be called in, before USB is connected.

  • bool (data) – Enable or disable the console USB serial device. True to enable; False to disable. Enabled by default.

  • bool – Enable or disable the data USB serial device. True to enable; False to disable. Disabled by default.

If you enable too many devices at once, you will run out of USB endpoints. The number of available endpoints varies by microcontroller. CircuitPython will go into safe mode after running to inform you if not enough endpoints are available.

class usb_cdc.Serial

Receives cdc commands over USB

You cannot create an instance of usb_cdc.Serial. The available instances are in the usb_cdc.serials tuple.

connected :bool

True if this Serial is connected to a host. (read-only)


The host is considered to be connected if it is asserting DTR (Data Terminal Ready). Most terminal programs and pyserial assert DTR when opening a serial connection. However, the C# SerialPort API does not. You must set SerialPort.DtrEnable.

in_waiting :int

Returns the number of bytes waiting to be read on the USB serial input. (read-only)

out_waiting :int

Returns the number of bytes waiting to be written on the USB serial output. (read-only)

timeout :Optional[float]

The initial value of timeout is None. If None, wait indefinitely to satisfy the conditions of a read operation. If 0, do not wait. If > 0, wait only timeout seconds.

write_timeout :Optional[float]

The initial value of write_timeout is None. If None, wait indefinitely to finish writing all the bytes passed to write().If 0, do not wait. If > 0, wait only write_timeout seconds.

read(self, size: int = 1)bytes

Read at most size bytes. If size exceeds the internal buffer size only the bytes in the buffer will be read. If timeout is > 0 or None, and fewer than size bytes are available, keep waiting until the timeout expires or size bytes are available.


Data read

Return type


readinto(self, buf: _typing.WriteableBuffer)int

Read bytes into the buf. If nbytes is specified then read at most that many bytes, subject to timeout. Otherwise, read at most len(buf) bytes.


number of bytes read and stored into buf

Return type


readline(self, size: int = - 1)Optional[bytes]

Read a line ending in a newline character (“\n”), including the newline. Return everything readable if no newline is found and timeout is 0. Return None in case of error.

This is a binary stream: the newline character “\n” cannot be changed. If the host computer transmits “\r” it will also be included as part of the line.


size (int) – maximum number of characters to read. -1 means as many as possible.


the line read

Return type

bytes or None


Read multiple lines as a list, using readline().


If timeout is None, readlines() will never return, because there is no way to indicate end of stream.


a list of the line read

Return type


write(self, buf: _typing.ReadableBuffer)int

Write as many bytes as possible from the buffer of bytes.


the number of bytes written

Return type



Force out any unwritten bytes, waiting until they are written.


Clears any unread bytes.


Clears any unwritten bytes.