Integrating Hardware with systemd and udev

Documenting a simple system for process management in the context of integrating hardware into a linux environment in the face of multiple devices and hot-plugging.

This whole exercise is prompted by a low grade annoyance I've had for years with how to manage a kind of internet of things configuration of devices on edge computers. I'll skip all the gory details and instead focus on some high level context and goals.

That's it! I expect you're thinking "that doesn't sound so hard" and you are right! It was the idea that this shouldn't be so hard that made so many convoluted solutions so painful.

Instead of getting too into the weeds of any particular piece of hardware or protocol I'm going grab some Arduino Uno R3 devices I have lying around and crib an example from the Arduino IDE. I'll perform an analog read of a pin (A0), here with nothing attached to it, and write it out to a 9600 baud serial line with a newline terminator. The board is in fact totally empty so the pin is reading a floating voltage that will drift around. This is sufficiently interesting and requires no real explaining, you get to use your imagination for what it would look like to decode a real protocol with actual useful information in it.

Plugging in one of these boards to my laptop produces a bit of chatter that can be seen in dmesg:

that ttyACM0 is the character device node that becomes available on connect, you can find it under the device tree (/dev/ttyACM0). You can also find the device under the sys file system with the data that it carries from the device itself. Getting at that is a little circuitous because of the symlinking involved in the sys tree but can be seen with the actual location here:

Part of that indirection becomes obvious when you start to plug in more devices. The second device plugged in would be named ttyACM1 but the destination depends on the physical USB port used. On my laptop 1-3 is the furthest port on the left hand side for example.

So let's contrive a program that should read device information out when it is plugged in, you might imagine this is for monitoring or some kind of inventory tracking. After it has been plugged in the device will be doing work and producing data to be read off the serial communication line. I will, of course, be using TCL for this because it is simply delightful how easy it is to read a serial device compared to something like Python unless you use a third-party package like pyserial:

#!/usr/bin/env tclsh

set port     [lindex $argv 0]
set baudrate 9600

proc sysfs_attr {path attr} {
    set f [file join $path $attr]
    if {![file readable $f]} { return "" }
    set fd [open $f r]
    set val [string trim [read $fd]]
    close $fd
    return $val
}

proc print_device_info {device_name} {
    set tty_device [file join /sys/class/tty $device_name device]
    set resolved [exec readlink -f $tty_device]
    set usb_path [file dirname $resolved]

    puts "--- device: /dev/$device_name ---"
    foreach attr {idVendor idProduct manufacturer serial} {
	set val [sysfs_attr $usb_path $attr]
	if {$val ne ""} { puts "  $attr: $val" }
    }
    puts "---"
}

set device_name [file tail $port]
print_device_info $device_name


set fd [open $port r+]
fconfigure $fd \
    -mode     "$baudrate,n,8,1" \
    -handshake none             \
    -buffering line             \
    -translation auto           \
    -blocking  0

proc readLine {fd} {
    if {[eof $fd]} {
	puts stderr "serial port closed."
	close $fd
	exit 0
    }
    set line [gets $fd]
    if {$line ne ""} { puts $line }
}

fileevent $fd readable [list readLine $fd]
puts "listening on $port at $baudrate baud..."
vwait forever

With that saved someplace plausible and marked executable it is possible to test it out with one of these junk-data-generators plugged in:

So far, so easy. Now to integrate it into the process management system I want to hook the plug-in event using udev. The idea is that I want to act only when one of these specific devices is plugged in because there's little guarantee what else might be running or temporarily attached to the machine. The way udev works this is quite easy with a rule definition based on those attributes enumerated above:

Of course you may question whether that information is really available or how I know what to call it. It's a simple thing to query it out with udevadm:

The rule specifies ENV{SYSTEMD_WANTS}="arduino-monitor@%k.service" which is a nifty integration into the service management of systemd. The %k is a template or parameter to be substituted with a value from the device that matched the rule, specifically it will be what is (confusingly) referred to as the "kernel name" for the device, in this example "ttyACM0". Additionally, the "TAGS" will cause systemd to create a .device for this matched device, which pretty much supplies everything needed to tie together the process management. Writing a service file that binds to that device file looks like this:

A slight systemd quirk is the substitution of / values with hyphens (which I've dealt with before) that turns dev/ttyACM0 into dev-ttyACM0 when naming systemd things like devices and mounts.

Final Test

With the service file added and the udev rule loaded (

udevadm
  control --reload-rules

) things pretty much just work to launch the process on plug in:

I didn't do a great job differentiating the log lines so you have to squint to see that I'm logging two different services (seen in the process IDs) and they're both producing data at once. Unplugging one of them looks like this:

Plugging in the device launches the service and unplugging the device shuts it down cleanly. I won't belabor the point but unplugging and replugging a bunch more times but you can trust that I've done it dozens of time in writing this and delighted in watching it all just work.