The USB Equipment Commander is a lightweight daemon that is able to run commands based on the USB equipment connected to a computer. It makes it easily possible to run scripts and programs when specific USB devices are being connected or disconnected.

"Why, there's udev for that?!" you might say. Sure, but udev rules come with all sorts of limitations, making it very cumbersome to run especially Wayland-related commands. Often times, rules that trigger user-specific scripts and tools are hacky at best, given the constrains imposed by udev.

The daemon can be fully configured using a toml file.

Examples include disabling the internal keyboard when you connect an external keyboard to your laptop, triggering a script that runs a backup on an external hard drive as soon as it's being connected, opening a LUKS encrypted device when a USB stick containing a key was inserted, activate a profile-script when your network (via NetworkManager) changes, and much more.

go build .

Check out the example config and create a similar config under any of the usual configuration paths (/etc/usbec.toml, $XDG_CONFIG_HOME/usbec.toml, ./usbec.toml).

usbec

When usbec is started from the Sway configuration via exec it gets no signal when Sway exits so it keeps running after you log out. Logging back in again starts a second instance that runs every action twice. Therefore it is important to run usbec with the --exit-with-sway flag that binds it to the Sway session:

exec usbec --exit-with-sway

usbec then connects to the IPC socket in SWAYSOCK, subscribes to Sway's shutdown event, and exits when the event arrives or the socket closes, which also covers Sway crashing. When SWAYSOCK isn't set or the subscription fails, usbec prints an error and exits with status 1.

In recent versions usbec can also run commands when NetworkManager's state changes... which.. I guess.. makes it usbnetec? Anyway, each [[Networks]] entry is a rule with a list of events, optional filters and the commands to run. The example config contains one that shows a notification. usbec only connects to NetworkManager when at least one rule is configured.

Note: Durations are strings such as "2s" or "500ms". usbec exits with an error at startup when a rule has an unknown key or event, a duplicate ID or no commands.

usbec reads NetworkManager's state after change signals and compares it with the previous read, so events describe the difference between two reads. This, in turn, means that e.g. connections that are already up when usbec starts don't produce connection-up, and a rule with RunOnStartup = true runs once after the first read instead, with the event initial-state, which can't be listed in Events.

NetworkManager creates a new active connection for every activation, so reconnecting to the same network produces connection-up again. A connection counts as down as soon as it starts deactivating. Addresses are compared together with their prefix length and the gateway to avoid DHCP renewals from producing events.

Types, Interfaces and Connections limit a rule to certain connections. The values within one filter are alternatives and all filters that are set have to match the same connection. If a filter is empty it matches everything.

Types uses NetworkManager's connection types, such as 802-3-ethernet, 802-11-wireless, vpn, wireguard or bluetooth.

Connections matches the name or UUID that nmcli connection show lists.

Commands inherit usbec's environment together with the variables below. Arguments are passed without a shell, so a command that needs a variable in an argument has to run through sh -c, as the example config does.