Find the serial port
A USB serial adapter shows up as two files in /dev. List them before and after you plug it in, and the new name is your port:
ls /dev/cu.*/dev/cu.Bluetooth-Incoming-Port
/dev/cu.debug-console
/dev/cu.usbserial-1420Typical names are cu.usbserial-XXXX for FTDI and Prolific adapters and cu.usbmodemXXXX for boards that act as a USB modem, such as many microcontroller boards. The number changes with the USB port you use.
Each port also has a /dev/tty.* twin. Use the cu one. The tty device is for incoming calls and waits for a carrier signal that a console cable rarely sends, so the session can hang with no output.
If no new port appears, check that macOS sees the adapter at all:
ioreg -p IOUSBIf it is listed there but has no port, the chip needs a driver from its maker. If it is not listed, try another cable: some USB cables only carry power.
Connect with screen
screen ships with macOS and is the quickest serial terminal. Give it the port and the speed:
screen /dev/cu.usbserial-1420 9600The screen goes blank. That is normal: a console prints nothing until you send something, so press Enter and the prompt appears. You can add line settings after the speed, in stty style, separated by commas:
screen /dev/cu.usbserial-1420 115200,cs8,-ixon,-ixoffHere cs8 means 8 data bits, and -ixon,-ixoff turn software flow control off.
To exit screen, press Ctrl-A, then K, then Y. Ctrl-A then D only detaches: the session keeps running and holds the port. To find and close a detached session:
screen -ls
screen -r
screen -X -S 98339 quitTo keep a copy of everything the device prints, start screen with -L. It writes a file named screenlog.0 in the current folder.
Connect with cu
cu is the other built-in tool. On a Mac it needs sudo, because it writes a lock file in /var/spool/uucp. Without it, cu stops with Line in use even when the port is free. We hit exactly this in our test.
sudo cu -l /dev/cu.usbserial-1420 -s 9600To leave cu, type ~. at the start of a line, that is Enter, then tilde, then dot. If you are connected to the Mac over SSH, ssh catches the same sequence first, so type ~~. instead. The SSH escape sequences guide explains why.
Speed, parity and flow control
Both ends must use the same settings, or you get garbage or nothing. The usual notation is speed plus 8N1: 8 data bits, no parity, 1 stop bit.
| Device | Common setting |
|---|---|
| Switches, routers, firewalls | 9600 8N1, no flow control |
| Raspberry Pi, most Linux boards | 115200 8N1, no flow control |
| Microcontroller boards | Whatever the firmware sets, often 115200 or 9600 |
| Old modems and some industrial gear | May use 7E1 (7 data bits, even parity) or RTS/CTS |
Signs of a wrong setting: random symbols mean the speed is wrong; text with a few wrong characters points to parity or data bits; output that stops after a screenful points to flow control. To see what the port is set to right now:
stty -f /dev/cu.usbserial-1420For a Raspberry Pi, the serial console must also be turned on in the system first. The Raspberry Pi SSH guide covers the network route once the console has done its job.
Common problems
Resource busyorLine in use. Another program holds the port, often a detached screen. Find it withlsof /dev/cu.usbserial-1420and close it, or runscreen -ls.- A blank screen. Press Enter. If still nothing, check the speed, then whether you need a null modem (crossed) cable or a rollover console cable for that device.
- Lines that step down like a staircase, or no new line at all. The device expects CR and LF differently. Many consoles want only CR when you press Enter.
- Arrow keys or full screen menus look wrong. Set
TERMon the device to match, see unknown terminal type.
screen or a dedicated serial terminal
screen and cu are enough for a quick look. A dedicated serial terminal for Mac helps when you go back to the same devices often: it remembers the port and line settings per device, lists ports for you and survives a cable that comes out. Either way, once the device is on the network, switch to SSH for daily work.
Questions
Should I use /dev/tty.usbserial or /dev/cu.usbserial on a Mac?
Use /dev/cu. The tty device waits for a carrier signal that most console cables never send, so screen can sit there with no output. The cu device opens at once.
How do I exit screen on a serial port?
Press Ctrl-A, then K, and answer Y. Closing the Terminal window instead can leave screen running in the background and holding the port, which then reports Resource busy.
Why does my serial console show garbage characters?
The speed is wrong. Close the session and try the other common speeds, 9600 and 115200 first, then 19200, 38400 and 57600.
Does a Mac need a driver for a USB serial adapter?
Recent macOS versions include drivers for the common chips. If the adapter appears in ioreg -p IOUSB but no /dev/cu. port appears, install the driver from the chip maker.
Sources
- screen(1), GNU Screen manual
- cu(1), Taylor UUCP manual
- stty(1), FreeBSD manual
- Raspberry Pi documentation, UART configuration