udev for the win

So I have an Arduino Uno now and some parts to begin working on my alarm clock project but I'm still new to Arduino and need to get comfortable with programming it. So first thing I do is fire up the standard Arduino GUI programming tool ("IDE" in the argot of those that like such tools).

And I'm ready to Ackchyually it.

Being added to the dialout group is a pretty good fix. But it's not the only way to do that, so "need" is a strong word. The advantage of being in the dialout group is it works pretty generally and without any extra tooling. The disadvantage is group membership is inherited from login, and I don't want to log out and log in again. A logout is as good as a reboot, and usually it is the reboot that forces the logout. These days I try to limit it those to once a month or less, depending on important kernel updates. It's been less than two weeks now, way too soon for that much disruption.

So here follows an alternative route with udev rules.

First I need to identify the device to apply those rules. I'll start with watching what's going on in /var/log/syslog when I plug the device in:

Nov  7 19:49:59 slate-asus kernel: [947954.307562] usb 1-3: new full-speed USB device number 8 using xhci_hcd
Nov  7 19:49:59 slate-asus kernel: [947954.458285] usb 1-3: New USB device found, idVendor=2341, idProduct=0043
Nov  7 19:49:59 slate-asus kernel: [947954.458291] usb 1-3: New USB device strings: Mfr=1, Product=2, SerialNumber=220
Nov  7 19:49:59 slate-asus kernel: [947954.458294] usb 1-3: Manufacturer: Arduino (www.arduino.cc)
Nov  7 19:49:59 slate-asus kernel: [947954.458296] usb 1-3: SerialNumber: 8593731353731234A012
Nov  7 19:49:59 slate-asus mtp-probe: checking bus 1, device 8: "/sys/devices/pci0000:00/0000:00:15.0/usb1/1-3"
Nov  7 19:49:59 slate-asus mtp-probe: bus: 1, device: 8 was not an MTP device
Nov  7 19:49:59 slate-asus kernel: [947954.532024] cdc_acm 1-3:1.0: ttyACM0: USB ACM device

That's all I really need there, but there's other ways to get that information. If you are not used to reading that log, here's the general format of what it is showing:

• Nov 7 19:49:59 date and time in system default timezone (US Pacific for me).
• slate-asus computer name. I uniquely name all my computers, and this one doesn't have an obvious model name on it, so color - maker.
• kernel: / mtp-probe: the name of the component creating the message. Messages from the kernel include the uptime in seconds, eg [947954.532024], which is one week, three days, twenty-three hours, nineteen minutes and a bit over fourteen seconds. Way too soon to reboot.
• checking bus 1, device 8: "/sys/devices/pci0000:00/0000:00:15.0/usb1/1-3 This message from the media transport protocol probe has one way to identify the device.
• cdc_acm 1-3:1.0: ttyACM0: USB ACM device This contains the other way. cdc: communications device class; acm: abstract control model. Essentially this is a modem-like serial device on USB (the "universial serial bus"). And modem-like is why the group is dialout.

Another way to find the device name is look in the /dev/ directory and find the new file that was created when plugging the device in (here, /dev/ttyACM0) and have the udev system tell us what it is with the udevadm info -a -n /dev/ttyACM0 command (verbose output partially removed):

# udevadm info -a -n /dev/ttyACM0
Udevadm info starts with the device specified by the devpath and then
walks up the chain of parent devices. It prints for every device
found, all possible attributes in the udev rules key format.
A rule to match, can be composed by the attributes of the device
and the attributes from one single parent device.

  looking at device '/devices/pci0000:00/0000:00:15.0/usb1/1-3/1-3:1.0/tty/ttyACM0':
    KERNEL=="ttyACM0"
    SUBSYSTEM=="tty"
    DRIVER==""

  looking at parent device '/devices/pci0000:00/0000:00:15.0/usb1/1-3/1-3:1.0':
[...]
  looking at parent device '/devices/pci0000:00/0000:00:15.0/usb1/1-3':
[...]
  looking at parent device '/devices/pci0000:00/0000:00:15.0/usb1':
[...]
  looking at parent device '/devices/pci0000:00/0000:00:15.0':
    KERNELS=="0000:00:15.0"
    SUBSYSTEMS=="pci"
    DRIVERS=="xhci_hcd"
    ATTRS{broken_parity_status}=="0"
    ATTRS{class}=="0x0c0330"
    ATTRS{consistent_dma_mask_bits}=="64"
    ATTRS{d3cold_allowed}=="1"
    ATTRS{dbc}=="disabled"
    ATTRS{device}=="0x5aa8"
    ATTRS{dma_mask_bits}=="64"
    ATTRS{driver_override}=="(null)"
    ATTRS{enable}=="1"
    ATTRS{irq}=="123"
    ATTRS{local_cpulist}=="0-1"
    ATTRS{local_cpus}=="3"
    ATTRS{msi_bus}=="1"
    ATTRS{numa_node}=="-1"
    ATTRS{revision}=="0x0b"
    ATTRS{subsystem_device}=="0x201f"
    ATTRS{subsystem_vendor}=="0x1043"
    ATTRS{vendor}=="0x8086"

  looking at parent device '/devices/pci0000:00':
[...]

We'd get the same relevant information from the other identifier using the udevadm info -a /sys/devices/pci0000:00/0000:00:15.0 command. Every single thing in that list of device info can be used as a key for trigging a udev script. The ATTRS{subsystem_device} or ATTRS{subsystem_vendor} is a good choice for being relatively specific to plugging in an Uno and getting a device.

So now we know what to use as a trigger, let's use that to run a script. In /etc/udev/rules.d/ live *.rules files for what to do for devices. On my system the highest numbered existing rule is 70-snap.snapd.rules, so I'll pick a two digit number higher than that and create my new rules file.

$ cat /etc/udev/rules.d/80-arduino.rules
ATTRS{subsystem_device}=="0x201f", ACTION=="add", RUN+="/usr/local/bin/plugin uno"
$

Each line is a rule. This one says when the subsystem_device attribute is 0x201f and the action happening is an add, then add to the list of things to be run /usr/local/bin/plugin uno. The argument isn't really needed for udev, because there are enough environment variables to use for context, but could be handy for hand running it. I (or you) could match on more than one attribute by just adding them to the list: ATTRS{subsystem_vendor}=="0x1043", ATTRS{subsystem_device}=="0x201f", ...

With the rule in place, we need to reload the udev configuration in order to have the rule take effect. This is much easier than a reboot.

# udevadm control --reload
#

A note on prompts: in my copies of terminal output, a prompt of $ means that it is a command to be run as a regular user, and a prompt of # means it requires superuser privileges. I usually use a superuser shell, but sudo in front of the command is the common way these days.

Now we have a rule to run something when the device is plugged in, we should figure out what to run. A stub script is very helpful here:

$ cat /usr/local/bin/plugin
#!/bin/sh

log=/var/log/plugin-udev.log
exec >> "$log" 2>&1     # "exec" changes stdout, etc, while running

env
$

Plug the Uno in, and then look at the plugin-udev.log file.

$ cat /var/log/plugin-udev.log
ID_BUS=usb
DEVNAME=/dev/ttyACM0
ACTION=add
ID_VENDOR_FROM_DATABASE=Arduino SA
ID_PCI_INTERFACE_FROM_DATABASE=XHCI
ID_SERIAL_SHORT=8593731353731234A012
ID_USB_DRIVER=cdc_acm
ID_USB_CLASS_FROM_DATABASE=Communications
DEVPATH=/devices/pci0000:00/0000:00:15.0/usb1/1-2/1-2.1/1-2.1:1.0/tty/ttyACM0
ID_MODEL_ENC=0043
ID_USB_INTERFACES=:020201:0a0000:
ID_MODEL=0043
SUBSYSTEM=tty
ID_MODEL_ID=0043
MINOR=0
ID_MODEL_FROM_DATABASE=Uno R3 (CDC ACM)
ID_PATH=pci-0000:00:15.0-usb-0:2.1:1.0
ID_MM_CANDIDATE=1
ID_VENDOR_ENC=Arduino\x20\x28www.arduino.cc\x29
[...]

There's a lot in there, so I could use ID_MODEL_FROM_DATABASE or ID_MODEL_FROM_DATABASE instead of uno as an argument, but I'm going to stick with that method to flag what to do. But I will have DEVNAME tell me what to act on. Next version of the plugin script:

#!/bin/sh

what="$1"

# device to try for "uno" if $DEVNAME is not set
uno_dev=/dev/ttyACM0

log=/var/log/plugin-udev.log 
if [ ! -w "$log" ] ; then
  echo "$0: Intended to be run as root from udev scripts."
  exit
fi

exec 3>&1               # create 3 as copy of stdout
exec >> "$log" 2>&1     # make orig stdout/stderr logfile

now=$(date +%Y/%m/%dT%H:%M:%S)

case "$1" in
  uno) device=${DEVNAME:-$uno_dev} 
       if [ -c "$device" ] ; then
         echo "$now - chowning $device now"
         chown username "$device"
       else
         echo "$now - can't find $device"
       fi
       ;;
  ?*) echo "$now - unrecognized plugin event: $1"
      echo        "unrecognized plugin event: $1" >&3
       ;;
  *)  echo "$now - need a udev event, eg 'uno'"
      echo        "need a udev event, eg 'uno'" >&3
       ;;
esac

I juggle stdout/stderr a bit here. First I open file descriptor 3 as a copy of stdout, then I change stdout and stderr to go to the logfile. This means anything normally sent to stdout or stderr will go in the log, and I can capture output and errors there, but because if I want to print to the original stdout (probably a terminal), I need to do it explicitly through file descriptor 3. Any program I run, will use the logfile for output but I can also print to the terminal. I use that for the unexpected usage cases. If someone with privileges runs /usr/local/bin/plugin that gets logged in the logfile and gets a message on the terminal. (Someone without privileges probably gets stopped when I check if the logfile is writable with [ -w "$log" ].)

So, let's try it out. Plug in the USB cable from the Arduino and:

$ ls -l /dev/ttyA*     
crw-rw---- 1 username dialout 166, 0 Nov  8 13:39 /dev/ttyACM0
$ groups
username adm cdrom sudo dip plugdev lpadmin sambashare docker rvm
$ tail -1 /var/log/plugin-udev.log
2020/11/07T21:51:46 - chowning /dev/ttyACM0 now
$

Presto, the device "belongs" to me, I can write to it without being in group dialout.

People often use udev rules for dealing with permissions related to thumbdrives, and there are a bunch of tutorials on doing that sort of thing, but udev is more useful and I wanted to show that.