When connecting to a target via a serial port, muforth opens the file muforth/mu/serial-target and expects it to be a symbolic link to a serial port of some kind that is connected to the external target device.

Since most modern machines lack “legacy” RS-232 ports, the serial ports we primarily use are provided by external USB serial adapters. These come in two flavors:

After enumeration, the device will show up in the /dev directory, but the name of the device depends both on the operating system and whether the device uses a class-compliant or chip-specific driver. In order to figure out which serial port device our external target is connected to, we need to do some sleuthing!

In the case of the Launchpad and the HiFive1 – which I use here as examples – we want to connect to the second interface. The first one is the debugger connection; the second connects to the target’s UART.

Once you have found a likely candidate in /dev you’ll need to make a symbolic link so muforth can find the device. I usually do it like this:

  cd muforth/mu
  ln -sf /dev/<something> serial-target

I’ll talk separately about how each OS names these devices.

Linux

On Linux, class-compliant USB serial devices enumerate as /dev/ttyACM devices, while devices with chip-specific drivers enumerate as /dev/ttyUSB devices.

Here is what I get with some of the devices I have on hand:

MSP430FR6989 Launchpad:

  crw-rw---- 1 david serial 166, 0 Apr 11 13:08 /dev/ttyACM0
  crw-rw---- 1 david serial 166, 1 Apr 11 13:08 /dev/ttyACM1

A random Prolific PL2303-based interface:

  crw-rw---- 1 root serial 188, 0 Apr 11 13:06 /dev/ttyUSB0

FTDI FT4232H Mini Module:

  crw-rw---- 1 david serial 188, 0 Apr 11 13:10 /dev/ttyUSB0
  crw-rw---- 1 david serial 188, 1 Apr 11 13:10 /dev/ttyUSB1
  crw-rw---- 1 david serial 188, 2 Apr 11 13:10 /dev/ttyUSB2
  crw-rw---- 1 david serial 188, 3 Apr 11 13:10 /dev/ttyUSB3

HiFive1 (original, which uses an FTDI FT2232):

  crw-rw---- 1 david serial 188, 0 Apr 11 13:19 /dev/ttyUSB0
  crw-rw---- 1 david serial 188, 1 Apr 11 13:19 /dev/ttyUSB1

We can see that all but the Launchpad have chip-specific drivers.

OSX/macOS

OSX (macOS) has a BSD heritage that – unlike Linux – makes a distinction between terminal (or serial) interfaces intended for incoming connections (call-in) and outgoing connections (call-out).

When using a Mac to communicate with target boards via USB serial adapters it is important to use the cu (call-out unit) device, rather than the associated tty (call-in) device.

USB serial devices supported by a chip-specific driver enumerate as /dev/cu.usbserial devices. CDC-ACM class-compliant devices enumerate as /dev/cu.usbmodem devices.

Here is what I get with my devices on hand.

By listing /dev/cu.u* we can skip the Bluetooth devices which would show up if we instead listed /dev/cu.*.

MSP430FR6989 Launchpad:

  $ ls -l /dev/cu.u*
  crw-rw-rw-  1 root  wheel   21,  27 Mar 11 14:47 /dev/cu.usbmodemFA1331
  crw-rw-rw-  1 root  wheel   21,  29 Mar 11 14:47 /dev/cu.usbmodemFA1333

FTDI FT4232H Mini Module:

  $ ls -l /dev/cu.u*
  crw-rw-rw-  1 root  wheel   21,  41 Mar 11 17:44 /dev/cu.usbserial-FT0QE6FS0
  crw-rw-rw-  1 root  wheel   21,  37 Mar 11 17:44 /dev/cu.usbserial-FT0QE6FS1
  crw-rw-rw-  1 root  wheel   21,  39 Mar 11 17:44 /dev/cu.usbserial-FT0QE6FS2
  crw-rw-rw-  1 root  wheel   21,  35 Mar 11 17:44 /dev/cu.usbserial-FT0QE6FS3

HiFive1 (original, which uses an FTDI FT2232):

  $ ls -l /dev/cu.u*
  crw-rw-rw-  1 root  wheel   21,  33 Mar 11 15:19 /dev/cu.usbserial-FA13300
  crw-rw-rw-  1 root  wheel   21,  31 Mar 11 15:19 /dev/cu.usbserial-FA13301

For a while I was having bad luck with the Prolific driver on the Mac. Later I realized that my troubles were not with the driver per se but with using the tty.usbserial device rather than the cu.usbserial device! The Prolific driver works fine. However, I didn’t capture the results on my Mac, and it’s now in storage! So I can’t share them here.

As with Linux, only the Launchpad enumerates as a cu.usbmodem (class-compliant) device.

BSD (all flavors)

All of the BSDs make a distinction between call-in and call-out devices, but make no distinction in the naming of the resulting device based on whether the device has a chip-specific driver or not. So things are slightly simpler. We just want to find the call-out devices and try them!

On FreeBSD and OpenBSD, call-out devices resulting from enumerating a USB serial device show up as /dev/cuaU devices.

On NetBSD, these show up as /dev/dtyU devices. (Why the departure from convention, I wonder?)