usb_cdc – USB CDC Serial streams — Adafruit CircuitPython 1 documentation (original) (raw)

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.

Available on these boards

usb_cdc.console_: Serial | None_

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.

usb_cdc.data_: Serial | None_

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.

usb_cdc.disable() → None

Do not present any USB CDC device to the host. Can be called in boot.py, 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 boot.py, before USB is connected.

Parameters:

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 boot.py 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.

read(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 size is not specified or is -1, read as many bytes as possible, until the timeout expires. If timeout is > 0 or None, and fewer than size bytes are available, keep waiting until the timeout expires or size bytes are available.

If no bytes are read, return b''. This is unlike, say, busio.UART.read(), which would return None.

Returns:

Data read

Return type:

bytes

readinto(buf: circuitpython_typing.WriteableBuffer) → int

Read bytes into the buf. Read at most len(buf) bytes. If timeoutis > 0 or None, keep waiting until the timeout expires or len(buf)bytes are available.

Returns:

number of bytes read and stored into buf

Return type:

int

readline(size: int = -1) → bytes | None

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.

Parameters:

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

Returns:

the line read

Return type:

bytes or None

readlines() → List[bytes | None]

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

Warning

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

Returns:

a list of the line read

Return type:

list

write(buf: circuitpython_typing.ReadableBuffer) → int

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

Returns:

the number of bytes written

Return type:

int

flush() → None

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

connected_: bool_

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

Note

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)

reset_input_buffer() → None

Clears any unread bytes.

reset_output_buffer() → None

Clears any unwritten bytes.

timeout_: float | None_

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_: float | None_

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.