Why is my robot arm not detected as a serial port?

Two different failures look identical in the client

The client tells you it cannot find the arm in both of the following situations, and they have nothing in common. In the first, the operating system has no serial device for your adapter, so there is nothing for the client to open. In the second, the port exists and the client opens it, but no servo answers on the bus. The output of ay-robots devices distinguishes them in one line, which is why it is the first thing to run rather than the thing you try after reinstalling.

ay-robots devices

# Case 1: the port itself is missing
# SERIAL PORTS
#   (none)
# CAMERAS
#   0  FaceTime HD Camera   1280x720

# Case 2: the port is there, the bus is not
# SERIAL PORTS
#   /dev/ttyACM0   unknown  (0 servos responding)

Everything below is about case 1. If you are in case 2, the port is proof that your cable carries data and that your permissions are fine, and the search moves to the arm: power first, then the first cable out of the controller, then the chain itself.

What the device is called on your system

The name depends on the chip in your adapter, not on which arm you own. An arm that uses a native USB microcontroller enumerates as a CDC ACM device, one that uses a separate USB-to-serial chip enumerates through that chip’s driver. Knowing which name to look for saves you from concluding that nothing appeared when something did.

Work through it in this order

1. 1
   Run the device scan and read it literally

   An empty serial section means the operating system has nothing. A named port with zero servos means you are in case 2 and the rest of this page does not apply to you.

   bash

   ay-robots devices

2. 2
   Stop worrying about arm power for a moment

   The USB-to-serial adapter draws its power from the USB port, so the serial device shows up whether or not the servo supply is plugged in. That is useful: it means a missing port is never explained by the arm being switched off. Powering the arm changes the servo count, not the port list.

3. 3
   Swap the USB cable for one you have moved files over

   This is the single most productive minute in this whole list. Cables that came with a phone charger, a battery pack or a lamp are frequently wired for power only, and they will light up an adapter that never enumerates.

4. 4
   Plug directly into the machine

   Skip hubs, docks and USB-C dongles for the duration of the test. A dock that works for a keyboard can still fail to pass a serial adapter through cleanly, and eliminating it costs nothing.

5. 5
   On Linux, check the group before anything else

   A device node that exists but is not readable by you looks exactly like a device that does not exist. The next section covers this in full.

   bash

   ls -l /dev/ttyUSB0 /dev/ttyACM0

6. 6
   On macOS, replug and answer the accessory prompt

   Recent macOS versions ask whether to allow a newly connected USB accessory. If that prompt was dismissed, or appeared behind another window, the device stays blocked and silent. Unplug, plug back in, and answer it.

7. 7
   On Windows, look in Device Manager rather than at the client

   If an unknown device appears when you plug the arm in and disappears when you unplug it, the machine sees the hardware and the serial driver did not bind. Install the driver for your adapter chip, then rescan. If nothing appears or disappears at all, go back to the cable.

8. 8
   Restart the client last, not first

   If the CLI lists the port and the client does not, you are looking at a stale scan. Quit the client fully and reopen it so it enumerates again. Reinstalling before you have checked the cable is how people spend an evening on a two euro problem.

   bash

   ay-robots status

The Linux dialout group, in full

On most distributions serial device nodes are owned by root and by a group called dialout, with no permissions for anyone else. Your user is not in that group by default. The result is that the file is right there in /dev and your process cannot open it, which surfaces as a permission error in a log you may not be reading, or as an empty list.

# Who owns the node
ls -l /dev/ttyUSB0
# crw-rw---- 1 root dialout 188, 0 Aug  9 14:02 /dev/ttyUSB0

# Are you in that group
groups
# users adm cdrom sudo

# Add yourself once
sudo usermod -aG dialout $USER

# Log out and log back in, then confirm
groups
# users adm cdrom sudo dialout

The step people skip is the login. Running the usermod command and then immediately retrying in the same terminal changes nothing, because your current session still carries the old group set. Log out and back in, or start a new session, and check with groups before you conclude the fix did not work. Some desktop environments keep a session alive after what looks like a logout, in which case a reboot is the reliable way to get a clean session even though it is not strictly required by the group change itself.

The cable that carries power but no data

A USB cable needs four conductors to move data and two to move power. Plenty of cables in circulation only have the two. There is no marking that tells you which one you are holding, the connector looks identical, and the adapter on the far end may well have a power LED that comes on and convinces you the link is good.

Test the cable rather than reasoning about it. Plug a USB stick or a phone through the same cable into the same port. If the machine mounts the stick, the cable moves data and you can rule it out. On Linux you can watch enumeration directly while you plug the arm in, which also tells you the device name without guessing.

# Linux: watch the kernel as you plug the arm in
sudo dmesg -w
# [ 1284.552] usb 1-3: new full-speed USB device number 8 using xhci_hcd
# [ 1284.712] cdc_acm 1-3:1.0: ttyACM0: USB ACM device

# Linux: the device tree, useful for spotting which controller a port hangs off
lsusb -t

# macOS: list what is there before and after plugging in
ls /dev/cu.*

If dmesg prints nothing at all when you plug in, the machine did not see an electrical connection: cable, port, or adapter. If it prints a line about a device that fails to initialize, you have a driver or power question instead. Either way you now know which half of the problem you are in, which is worth more than any amount of reinstalling.

Symptom to cause, at a glance

If you want to check the rest of the stack while you wait

A missing port is local to your machine, so nothing about your account, your pairing or the platform is implicated. If you would like to confirm that for yourself, /live drives a real SO-100 in the browser with no signup and no local hardware. It uses none of your USB stack, so it working proves the far side is fine and keeps the search where it belongs. The client itself, if you need to reinstall or move to another machine, is on /download, and the full first-time setup path including calibration is on /learn/so-100-getting-started.

Frequently asked questions