Shell Peripheral Management Guide

Foundations of Peripheral Handling

Why the Shell?

The shell offers fine‑grained, scriptable control over external hardware. Whether you are mount‑ing USB drives, toggling power to hubs, or debugging HID events, the command line lets you automate and reproduce every step for CI pipelines, headless servers, or recovery environments.

Core Utilities Cheat‑Sheet

lsusb – enumerate USB devices
dmesg ‑w – live‑stream kernel messages
udevadm – query & monitor udev events
lshw ‑class disk – detailed hardware tree
udisksctl – modern mounting helper
uhubctl – (when supported) flip USB‑hub power

Detect & Inspect Devices

Real‑time Appearance

# watch udev plug/unplug events
sudo udevadm monitor --udev --property

As soon as you connect a peripheral, udevadm spits out attributes—ID_VENDOR, ID_MODEL, serial numbers, and the dynamically assigned /dev/ node (e.g. /dev/sdb).

One‑shot Inspection

# All info for a block device
sudo udevadm info --query=all --name=/dev/sdb

This prints every key→value pair udev knows. Use filters—grep '^E:'—to focus on environment variables only.

Mounting Removable Storage

Traditional mount

# Identify partition
sudo fdisk -l

# Mount read‑write
sudo mount /dev/sdb1 /mnt/usb

# Unmount when done
sudo umount /mnt/usb

Using udisksctl (non‑root, DBus)

# Safer for desktop sessions
udisksctl mount   -b /dev/sdb1
udisksctl unmount -b /dev/sdb1

DBus authorization means your user keeps permissions and automatically picks an empty mount‑point under /run/media/$USER.

Working with Serial & HID Peripherals

Serial‑over‑USB (CDC‑ACM)

# List all ttyUSB / ttyACM devices
ls -l /dev/ttyACM* /dev/ttyUSB*

# Open a session (115200 baud)
picocom -b 115200 /dev/ttyACM0

HID Debugging

# Monitor raw events (requires root)
sudo evtest            # interactive selection
sudo evtest /dev/input/event13  # specific path

For custom keyboards or gamepads, combine with hid‑tools (pip install hid‑tools) to decode reports.

udev Rules & Hot‑plug Automation

Creating a Rule

# /etc/udev/rules.d/99‑usb‑backup.rules
SUBSYSTEM=="block", \
  ENV{ID_FS_TYPE}=="vfat|ntfs", \
  ACTION=="add", \
  RUN+="/usr/local/bin/backup‑drive.sh %E{DEVNAME}"

Matching on SUBSYSTEM, ENV{}, or interpretations like vendor ID (idVendor) triggers the custom script once the drive appears.

Reload & Debug

sudo udevadm control --reload
sudo udevadm test /sys/block/sdb  # dry‑run rule matching

USB Power Management

Per‑Port Control (uhubctl)

# Cut power on hub 1, port 3
sudo uhubctl -l 1 -p 3 -a off

# Restore power
sudo uhubctl -l 1 -p 3 -a on

Only USB hubs with a per‑port power switching descriptor work. Check uhubctl’s list or your motherboard specs.

Autosuspend Tweaks

Systemd supports /etc/systemd/system/usb‑autosuspend.service to declare power‑save policies. Alternatively, echo auto or on into /sys/bus/usb/devices/1‑1/power/control.

Debugging Workflow

Step‑by‑Step Checklist

Plug device → run dmesg ‑w in another tab.
Query udev → udevadm info --name=/dev/….
Confirm permissions (ls ‑l /dev/…) and group membership.
Mount or open in user‑space tool (ffmpeg, minicom, etc.).
Persist tweaks with udev rules; retest cold‑plug.

Kernel Logs Demystified

Numbers in brackets are seconds since boot. Codes like usb 1‑1: new high‑speed USB device number 4 show the bus/port path (1‑1) and enumeration count. Search for reset high‑speed loops—they hint at power or cable issues.

Security & Best‑Practice

Principle of Least Privilege

Create a dedicated plugdev group for serial or storage access. Set MODE="660", GROUP="plugdev" in udev rules rather than running chmod 777.

Write‑Barrier Off?

External SSDs default to write‑cache. Always flush:

sudo hdparm -W0 /dev/sdb

before sudden power loss scenarios (e.g. robotics).