hwscan

A Python CLI tool that detects attached hardware devices on Linux systems. It scans for connected USB devices, storage devices, and host system information, outputting results in JSON format.

Features

Supported Hardware Detection:

• TriLightSense (FTDI devices)
• STLINK-V3 (ST-Link debuggers with attached storage)
• ESP32 (C5 WROOM variant)
• Arduino Leonardo
• JLink (Segger JLink debuggers)
• UART to DMX converters
• Host System Info (hostname, model name, system UUID)

Installation

Prerequisites

• Python 3.8 or higher
• Linux operating system (uses sysfs for device detection)

Install from PyPI

pip install lumenradio-hwscan

Install from source

git clone <repository-url>
cd lumenradio-hwscan
pip install -e ".[dev]"

Usage

Basic Usage

Run the scanner with JSON output:

hwscan

Pretty-print JSON Output

For more readable JSON formatting:

hwscan --pretty

Display Detector Errors

To see any errors encountered during hardware detection:

hwscan --errors

Combined example:

hwscan --pretty --errors

Save Results to File

Save hardware detection results to a JSON file:

hwscan --output hardware.json

Smart Merging: If the file already exists, the tool intelligently merges new detection results with existing data. This preserves any custom fields you've added (like name for device mapping) while updating detected information:

# First run - creates the file
hwscan --output hardware.json

# Later, if device configuration changes, custom fields are preserved
hwscan --output hardware.json

Example: If your hardware.json contains custom mapping data:

{
  "3C:DC:75:84:F9:7C": {
    "name": "spi-bridge-timo",
    "type": "esp32-c5-wroom",
    "tty": "/dev/ttyACM0"
  }
}

And the tty changes to /dev/ttyACM1, running hwscan --output hardware.json will update the tty while preserving the name field.

Show Version

hwscan --version

Output Format

The tool outputs a JSON object where each key is a unique hardware identifier and the value contains device information.

Example output:

{
  "trilightsense_0": {
    "vendor": "FTDI",
    "product": "TriLightSense",
    "serial": "FTDI123456",
    "port": "/dev/ttyUSB0"
  },
  "stlink_0": {
    "vendor": "STMicroelectronics",
    "product": "STLINK-V3",
    "serial": "STL12345678",
    "port": "/dev/ttyACM0"
  },
  "host_system": {
    "hostname": "workstation-01",
    "model": "Dell Inc.",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Use Cases

• Hardware Inventory: Automatically detect and catalog connected devices in labs or production environments
• CI/CD Pipelines: Verify required hardware is available before running CI tests
• Device Management: Track connected debugging and serial devices
• System Integration: Generate hardware resource definitions for automated test systems

Development

Run Tests

make test

Format Code

make black

Build Distribution

make build

Requirements

Runtime Dependencies:

• requests >= 2.32
• typer >= 0.12
• rich >= 13.7
• pydantic >= 2.8

Development Dependencies:

• black >= 25.9.0
• pytest >= 8.4.2
• pytest-html
• pytest-cov
• build >= 1.2.1
• twine >= 5.1.1

License

MIT License - See LICENSE file for details

Support

This tool is intended for internal LumenRadio use. For issues or feature requests, please contact the development team.