Connected MCU device path determination for macOS and Linux

Latest Release: 0.3.1

 New Version

About dlist

dlist (dee-list) is a macOS/Linux CLI utility that lists MCU boards, such Raspberry Pi Picos. and USB-to-Serial adaptors connected to your computer. It can be used for informational purposes and to pipe a device’s path into other CLI tools, such as serial comms utilities. It is written Swift.

How to Use dlist

Run dlist to get a list of connected MCUs.

If only one board is connected, its path within the /dev/ directory will be provided. On macOS, for example:

$ dlist
/dev/cu.PL2303G-USBtoUART10

The device file path is issued to STDOUT so that it can be passed into other commands. For example:

minicom -D $(dlist) -b 9600

If multiple MCUs are connected, dlist will return a numerical list:

$ dlist
┌───┬───────────────────────────────┬────────────────────────────┬───────────────────────────┐
│   │ Device Path                   │ Device Type                │ Vendor                    │
├───┼───────────────────────────────┼────────────────────────────┼───────────────────────────┤
│ 1 │ /dev/cu.PL2303G-USBtoUART1120 │ USB-Serial Controller      │ Prolific Technology Inc.  │
├───┼───────────────────────────────┼────────────────────────────┼───────────────────────────┤
│ 2 │ /dev/cu.usbmodem11101         │ MCP2221 USB-I2C/UART Combo │ Microchip Technology Inc. │
└───┴───────────────────────────────┴────────────────────────────┴───────────────────────────┘

This list is issued to STDERR, so it’s printed in a terminal but will typically not be passed to another program. This allows you to select which item you then wish to use. For example:

$ minicom -D $(dlist 2) -b 115200

Including a numerical argument causes dlist to issue the specified device (by its index in the list) to subsequent commands through STDOUT.

If there is only one MCU connected and you still specify a value but one that is not 1, this will generate a warning on STERR but will still issue the single device’s path. If there are multiple devices connected, specifying an invalid index number will throw an error.

dlist
/dev/cu.PL2303G-USBtoUART1140

dlist 2
⚠️  2 is out of range (1)
/dev/cu.PL2303G-USBtoUART1140

Options

Including --info or -i as a dlist argument will force it into list mode, however many devices are connected.

$ dlist -i
┌───┬───────────────────────────────┬───────────────────────┬──────────────────────────┐
│   │ Device Path                   │ Device Type           │ Vendor                   │
├───┼───────────────────────────────┼───────────────────────┼──────────────────────────┤
│ 1 │ /dev/cu.PL2303G-USBtoUART1140 │ USB-Serial Controller │ Prolific Technology Inc. │
└───┴───────────────────────────────┴───────────────────────┴──────────────────────────┘

Because the output is intended to be readable by people, it is not suitable for piping into another command. Make sure you don’t include the flag if you’re using dlist to pipe the device path.

Ignorable macOS Devices

macOS adds a number of standard devices to the /dev/cu.* set, none of which can be used for USB-to-serial roles. dlist ignores these. However, macOS may also add other devices which cannot be known at compile time. For example, after I have connected my Beats Solo Pro wireless headphones to my Mac, they can appear in /dev/ as cu.SmittytoneCans based on the name I gave them. I can’t know what your wireless headphones are called, so dlist now reads a list of ignorable devices from ${HOME}/.config/dlist/ignorables. Add the extra devices you want dlist to ignore there, on a one-device-per-line basis.

Install dlist

macOS (Xcode)

IMPORTANT A paid Apple Developer Program membership is required to produce a signed release build that can be notarised.

• Clone this repo
• cd /path/to/repo
• Open the .xcodeproj file
• For signed builds set your team under Signing & Capabilities for the dlist target
• Select Archive from the Product menu
• In the Archives window, select the new build and click Distribute Content
• Follow the sequence, choosing Custom and Build Products, and save the output to the Desktop
• sudo cp /path/to/exported/dlist/binary /usr/local/bin/dlist

macOS (Swift Compiler)

• Clone this repo
• cd /path/to/repo
• swift build -c release

The macOS binary will be located in .build/{architecture}/release/

Linux (Swift Compiler)

• Install pre-requisites: sudo apt update && sudo apt install pkg-config libudev-dev libusb-dev libftdi-dev
• Install Swift
• Clone this repo
• cd /path/to/repo
• swift build -c release

Note On the Raspberry Pi 5, the build process and running dlist will emit swift runtime: unable to protect... disabling backtracing messages. To avoid these, you can add the flag --static-swift-stdlib. The quid pro quo is that it may start up more slowly and will be a much larger build. An alternative approach is to add export SWIFT_BACKTRACE='enable=no' to your shell profile file. This removes the messages, keeps the binary size low, but of course disables Swift’s improved crash reporting.

The Linux binary will be located in .build/{architecture}/release/

Version Management

The source of truth for version information is the Xcode project. If you compile dlist for macOS using the Swift compiler, the file swift.plist will be compiled into the binary to provide version information and to permit subsequent notarisation (after code signing). If you compile under Linux, the file swift_version.swift is used to inject version information into the Linux build process.

The sync-version.sh script is my tool to update the subsidiary files after I have updated the app using Xcode. The current version of the app, in the main branch of the repo, will always contain up-to-date dlist version information with the subsidiary version information files, so you should not need to alter these files yourself. The script is currently macOS only.

Back to the Top

Source Code

You can view Dlist’s source code at GitHub.

Back to the Top

Release Notes

• 0.3.1 13 August 2026
  • Remove script calls from Xcode build Scheme to fix CLI build toolchain errors.
• 0.3.0 13 August 2026
  • Allow macOS binary to be built using the Swift compiler (previously Linux only).
  • Add new version control script to update Linux and macOS Swift compiler builds from Xcode project source of truth.
  • Add missing emoji to No connected devices message.
  • Avoid crash risk by guarding against IORegistryEntryCreateCFProperty() yielding a nil in mac_aliases.swift’s getSerialDevices().
  • Enable macOS builds using the Swift compiler.
  • Revised cross-version version number management script.
  • Remove old, commented-out code.
• 0.2.5 16 July 2026
  • Tabulate --info output.
  • Fix Linux version.
• 0.2.4 1 July 2026
  • Signal errors, warnings, etc. on macOS with emoji.
  • Update to clicore 0.5.0.
• 0.2.3 3 February 2026
  • Fix version number.
  • Update to clicore 0.4.0.
• 0.2.2 13 January 2026
  • Style check and code tidy.
  • New year, new date.
• 0.2.1 15 December 2025
  • Handle ignorable devices on macOS that are prefixed in the list with /dev/.
  • Remove unnecessary Linux build instruction.
  • Fix build warnings on Linux.
  • Update to clicore 0.3.0.
• 0.2.0 22 August 2025
  • Sync project code with my other CLI utilities.
  • Improve build bumping.
• 0.1.5 8 August 2025
  • Initial public release.

Back to the Top

Related Software

• Depot
• Unicoder
• XBeeParser
• word2text
• ASCII

Back to the Top