Metadata-Version: 2.4
Name: lr-hwscan
Version: 1.1.0
Summary: Hardware detector CLI for USB serial/debug devices (TriLightSense, STLINK-V3, ESP32, host info).
Author-email: Jonas Estberger <jonas.estberger@lumenradio.com>
License: MIT
Keywords: usb,serial,udev,hardware,detector,TriLightSense,stlink,espressif,jlink
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Operating System Kernels :: Linux
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: black>=25.9.0; extra == "dev"
Requires-Dist: pytest>=8.4.2; extra == "dev"
Requires-Dist: pytest-html; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# 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

```bash
pip install lr-hwscan
```

### Install from source

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

## Usage

### Basic Usage

Run the scanner with JSON output:

```bash
hwscan
```

### Pretty-print JSON Output

For more readable JSON formatting:

```bash
hwscan --pretty
```

### Display Detector Errors

To see any errors encountered during hardware detection:

```bash
hwscan --errors
```

Combined example:

```bash
hwscan --pretty --errors
```

### Save Results to File

Save hardware detection results to a JSON file:

```bash
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:

```bash
# 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:

```json
{
  "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

```bash
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:

```json
{
  "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

```bash
make test
```

### Format Code

```bash
make black
```

### Build Distribution

```bash
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.
