UCOM(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 UCOM(4) — the USB tty glow-up 💖

okay bestie, sit down, hydrate, and let me tell you about ucom, the USB tty support driver from the Kernel Interfaces Manual. she's the reason your lil USB modem can act like a real terminal and honestly? iconic. ✨

🌸 NAME 🌸

ucom — USB tty support 🫶

🎀 SYNOPSIS 🎀

so to get this driver baked into your kernel, you drop this line in your kernel configuration file:

device ucom

or, if you'd rather load her as a module at boot time (slay, flexible queen), put this in loader.conf(5):

ucom_load="YES"

✨ DESCRIPTION ✨

The ucom driver attaches to USB modems, serial ports, and honestly any other device that needs to look like a tty. she shows behavior like a tty(4), no cap. which means all your normal little programs — think tip(1) or ppp(8) — can just. use the device. no drama. 💅

💜 SYSCTL VARIABLES 💜

these babies are available both as sysctl(8) variables and loader(8) tunables. double threat energy:

  • hw.usb.ucom.debug — debug output level, where 0 means debugging is disabled and bigger values crank up the debug message verbosity. default is 0. (lowkey quiet by default, respect.)
  • hw.usb.ucom.device_mode_console — when set to 1, the ucom driver marks terminals as console devices while operating in device mode. default is 1.
  • hw.usb.ucom.pps_mode — enables and configures PPS capture mode, as described down below 👇

⏱️ Pulse Per Second (PPS) Timing Interface ⏱️

The ucom driver can capture PPS timing info as defined in RFC 2783. the API lives on the tty device and you get to it via ioctl(2). to use the PPS capture feature with ntpd(8), just symlink the tty device to /dev/pps0. periodt.

The hw.usb.ucom.pps_mode sysctl configures the PPS capture mode. you can set it in loader.conf(5) or sysctl.conf(5). the capture modes available are:

  • 0 — capture disabled (default).
  • 1 — capture pulses on the CTS line.
  • 2 — capture pulses on the DCD line.

🦋 FILES 🦋

  • /dev/ttyU* — for callin ports
  • /dev/ttyU*.init
  • /dev/ttyU*.lock — corresponding callin initial-state and lock-state devices
  • /dev/cuaU* — for callout ports
  • /dev/cuaU*.init
  • /dev/cuaU*.lock — corresponding callout initial-state and lock-state devices

🌈 SEE ALSO 🌈

tty(4), uark(4), ubsa(4), ubser(4), uchcom(4), ucycom(4), ufoma(4), uftdi(4), uhso(4), uipaq(4), umcs(4), umct(4), umodem(4), umoscom(4), uplcom(4), usb(4), uslcom(4), uvisor(4), uvscom(4)

like, the whole USB serial friend group. squad goals fr fr. 🫶

📜 HISTORY 📜

The ucom driver was adopted from NetBSD in March of 2002. this manual page was adopted from NetBSD by Tom Rhodes <trhodes@FreeBSD.org> in **April 2002`. (shoutout to Tom, a real one 👑)

💀 BUGS 💀

prior to FreeBSD 6.0, ucom created /dev/ucom? rather than the uniform device names created today. so if you're running some ancient script from the before-times, you must adjust it accordingly. no shortcuts, bestie. 😭

tl;dr: plug in a USB modem, get a tty, run tip(1) or ppp(8), maybe symlink /dev/pps0 if you're feeling fancy. that's the whole vibe. you got this 💖✨

— cute lil sign-off from the Debian crew, page dated April 25, 2018 🎀 mwah, go touch some serial ports 🦋

📦 where this page comes from