FreeBSD USB Serial Adapter Operations: Identify Drivers, Ports, and Settings

USB-to-serial adapters expose a UART-like device through the USB bus. On FreeBSD, supported USB serial drivers commonly connect through ucom(4), which presents a tty-style interface to terminal programs. The workflow differs from an onboard UART console: a USB adapter usually appears as ttyU or cuaU, while the motherboard serial driver commonly uses ttyu or cuau. Picking the wrong node, speed, flow control, or adapter chipset can produce silence that looks like a remote-device failure.

This guide covers host-side identification and operation of a USB serial port. It does not guarantee compatibility with every USB-to-UART bridge, cable, level voltage, or target device. Verify electrical signaling and pinout independently. RS-232 voltage levels, TTL UART levels, and RS-485 are not interchangeable.

Identify the adapter before opening a port

Start with a baseline, connect one adapter, and inspect the USB and kernel views:

usbconfig list
dmesg | tail -100
kldstat
devinfo -rv
ls -l /dev/ttyU* /dev/cuaU*

The shell glob may match no device and report an error; that is useful evidence when recorded with the other output. Repeat after unplugging and reconnecting only when no terminal session is using the port. Record the vendor, product, serial identifier if available, USB bus and address, driver attachment, and created device nodes.

Common driver families include uftdi(4) for supported FTDI devices, uplcom(4) for supported Prolific adapters, umodem(4) for USB CDC ACM modems and serial interfaces, and other chipset-specific drivers. The vendor name printed on a plastic case does not identify the internal bridge reliably. Compare the USB vendor/product IDs and the driver manual’s supported-device list. Some counterfeit or clone adapters identify differently or behave differently from the chipset they imitate.

The ucom driver is often loaded automatically through devmatch when the USB device is recognized. If no port appears, do not begin by creating a device node manually. Check whether the USB bus sees the device, whether the driver attached, and whether kernel logs show firmware or probe errors. Device nodes are provided by the driver; manually fabricated nodes do not make a nonfunctional driver work.

For an adapter whose manual documents runtime loading, load only the relevant driver and check again:

kldload uftdi
kldstat
dmesg | tail -50

Replace uftdi with the driver that matches the detected hardware. Do not load every serial module as a guessing strategy. A module name and exact rc.conf persistence should be verified against the manual for the installed FreeBSD release.

Choose the correct character device

ucom(4) exposes call-in tty nodes and call-out cua nodes. For a typical single-port adapter, examples are /dev/ttyU0 and /dev/cuaU0. Multiport adapters may expose additional unit suffixes. Use the actual node created by the system, and verify its ownership and permissions before granting an application access.

Call-out nodes are generally suitable for initiating an outbound terminal session to a device. A call-in node is associated with terminal login behavior and carrier handling. Do not configure getty on a call-out interface simply because a program can open it. Conversely, if the USB serial device is intended as a login console, use the documented call-in/getty path and carefully consider physical access and authentication.

To inventory permissions and current users of the port:

ls -l /dev/cuaU0 /dev/ttyU0
fstat /dev/cuaU0

fstat can show processes with a file open. Use it, process inspection, and the terminal application’s own status to determine whether a session owns the device. Before closing a production terminal session, confirm the remote system’s impact.

With multiple adapters, unit numbers can change when devices are attached in a different order. Do not persist a critical management script that assumes cuaU0 always maps to a specific rack device unless you have verified a stable identification mechanism. Keep a mapping of adapter serial IDs or USB port locations to the resulting nodes and test after reboot and replug.

Set serial parameters deliberately

The adapter’s UART parameters must match the target: baud rate, data bits, parity, stop bits, and flow control. Common console settings such as 115200 8N1 are not universal. Consult the target product’s official console documentation and ensure that its pinout and voltage standard match the adapter.

For a controlled test, open the call-out device with cu:

cu -l /dev/cuaU0 -s 115200

Check cu(1) locally for the exact escape sequence to leave the session. Do not simply kill the terminal from a remote automation system if it may leave a lock or flow-control state behind. Set software or hardware flow control only when the remote endpoint supports the same convention and the cable has the required signals. A three-wire cable typically cannot carry RTS/CTS, and enabling it at only one end may make the session appear frozen.

When a terminal tool allows a profile, save the settings in that tool rather than layering several competing serial configuration systems. If using stty, consult stty(1) and first ensure no active process owns the port. A settings probe can itself open or alter terminal state. Keep a record of the prior configuration so a test can be reversed.

Echo is a frequent source of misdiagnosis. Some targets echo received characters and others do not. Local terminal echo can create duplicate characters even when the wire is working correctly. Test with a known prompt, a short harmless command, and both ends’ logging. Avoid sending configuration or firmware commands until the line discipline and target identity are confirmed.

Diagnose silence and corrupted output by layer

If the adapter is absent from usbconfig output, investigate the physical USB path, hub, cable, power, and port before changing tty settings. If the device is visible on USB but no ucom port appears, inspect the driver attachment messages and match the USB IDs to a supported driver. If a device node exists but cannot be opened, inspect permissions, active process ownership, device flags, and the terminal program’s chosen path.

If the port opens but prints nothing, verify the target is powered, the adapter is connected to the correct UART header, TX and RX are crossed as required, ground is common, and logic voltage is compatible. Check that the selected baud rate and framing match the endpoint. Hardware serial can be electrically damaged by connecting incompatible RS-232 and TTL levels; software retries will not correct the electrical mismatch.

If output is garbled, reduce the diagnosis to baud and framing, then check clock tolerance, cable length, flow control, and noise. Verify that both endpoints use the same speed and that the target’s bootloader does not change baud during startup. Capture a repeatable boot log and compare the point where characters become invalid.

If the connection stalls after initial output, inspect RTS/CTS or XON/XOFF settings, device buffers, terminal lock behavior, and competing process ownership. Some target consoles stop transmitting when flow-control input is not asserted. Do not bridge pins or force modem-control lines without an adapter schematic and a controlled test.

Persistent loading and service use

If devmatch does not load a required supported module automatically, the driver manual may document adding the module name to kld_list in /etc/rc.conf. For example:

sysrc kld_list+="uftdi"

Before using that command, inspect the existing kld_list and confirm that the syntax preserves all current entries. Runtime kldload is temporary; a persistent setting should be changed through rc.conf tooling and verified after a controlled reboot. Do not set loader.conf variables copied from unrelated drivers.

For a service such as a console server or monitoring daemon, configure it to open the intended cua node with a bounded reconnect policy. Ensure that only one process owns the adapter at a time unless the specific software supports multiplexing. A regular UNIX tty is not a broadcast console server. If several operators need access, use a controlled console-management service instead of sharing the raw device path.

If this is a host console or a safety-critical management port, test service restart, host reboot, adapter disconnect, reconnect, and target reboot. Confirm that a USB port renumber does not redirect the service to a different device. Keep an independent access route before changing rules or service startup order.

Record a trustworthy operational baseline

Save the FreeBSD release, kernel version, USB adapter chipset and ID, driver module, interface path, serial profile, terminal program, remote target firmware, cable type, and test result. Record exact time and capture a short sample of normal boot output. For field systems, keep spare adapters that have been tested with the same host release rather than assuming all visually similar adapters are equivalent.

Acceptance means that the correct adapter is recognized consistently, the expected device node is used, a test session is stable at the target’s documented settings, and the tested recovery path works after a disconnect and reboot. A successful cu launch alone does not prove electrical compatibility, persistent enumeration, or reliable console operation.

Related:

Sources: