Metadata-Version: 2.4
Name: bussdcc-hardware
Version: 0.16.1
Summary: Provides hardware device integrations for bussdcc.
Author-email: "Joshua B. Bussdieker" <jbussdieker@gmail.com>
Maintainer-email: "Joshua B. Bussdieker" <jbussdieker@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jbussdieker/bussdcc-hardware
Project-URL: Documentation, https://github.com/jbussdieker/bussdcc-hardware/blob/main/README.md
Project-URL: Repository, https://github.com/jbussdieker/bussdcc-hardware
Project-URL: Issues, https://github.com/jbussdieker/bussdcc-hardware/issues
Project-URL: Changelog, https://github.com/jbussdieker/bussdcc-hardware/blob/main/CHANGELOG.md
Keywords: hardware
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bussdcc~=0.37.0
Provides-Extra: dev
Requires-Dist: mypy~=1.19.1; extra == "dev"
Requires-Dist: types.RPi.GPIO~=0.7.0; extra == "dev"
Provides-Extra: nau7802
Requires-Dist: nau7802[i2c]~=0.6.0; extra == "nau7802"
Provides-Extra: pump
Requires-Dist: RPi.GPIO~=0.7.1; extra == "pump"
Provides-Extra: usb-camera
Requires-Dist: opencv-python-headless~=4.13.0.92; extra == "usb-camera"
Dynamic: license-file

# BussDCC Hardware

**bussdcc-hardware** provides hardware device integrations for `bussdcc`.

It includes drivers for common buses and devices and exposes them through the BussDCC device system so they can be managed, monitored, and orchestrated by the runtime.

# Architecture

Hardware in BussDCC is modeled using **devices attached to buses**.

```
Runtime
  ├── Bus Devices
  │     ├── I2C Bus
  │     └── 1-Wire Bus
  │
  └── Hardware Devices
        ├── Sensors
        ├── ADCs
        ├── Cameras
        └── Actuators
```

Each hardware component is represented as a **BussDCC Device** with a managed lifecycle:

```
connect → operate → disconnect
```

The runtime handles:

* device initialization
* dependency ordering
* failure detection
* online/offline status

# Features

## Bus Drivers

Hardware buses are modeled as devices themselves.

Currently supported:

### I²C

```
bussdcc_hardware.bus.i2c
```

Features:

* bus discovery
* device address scanning
* register bus interface

### 1-Wire

```
bussdcc_hardware.bus.w1
```

Features:

* device discovery
* filesystem-based device access

## Hardware Devices

### NAU7802 Load Cell ADC

High precision load cell amplifier.

```
bussdcc_hardware.device.nau7802
```

Features:

* dual channel support
* calibration parameters
* automatic channel switching
* failure detection

### DS18B20 Temperature Sensor

1-Wire temperature sensor.

```
bussdcc_hardware.device.ds18b20
```

Features:

* filesystem-based reading
* automatic offline detection

### USB Camera

OpenCV-based camera integration.

```
bussdcc_hardware.device.usb_camera
```

Features:

* configurable resolution and FPS
* exposure control
* focus control
* white balance control
* automatic failure recovery

### GPIO Pump

Simple actuator using Raspberry Pi GPIO.

```
bussdcc_hardware.device.pump
```

Features:

* on/off control
* safe shutdown

# Device Configuration

All devices use **typed dataclass configurations**.

Example:

```python
from bussdcc_hardware.device.nau7802 import NAU7802Config

config = NAU7802Config(
    bus_id="i2c0",
    addr=0x2A,
)
```

Configuration metadata includes UI hints:

* labels
* groups
* ranges
* control types

This allows configuration systems or web interfaces to automatically generate forms.

Example metadata:

```
{
  "label": "Frame Width",
  "group": "Video",
  "ui": "number",
  "min": 160,
  "max": 3840
}
```

# Device Discovery

Hardware integrations are registered using **Python entry points**.

```
bussdcc.bus
bussdcc.device
```

The registry loads available devices automatically:

```python
from bussdcc_hardware.registry import registry

registry.buses
registry.devices
```

Unavailable drivers (missing optional dependencies) are detected and reported.

# Optional Dependencies

Some hardware drivers require additional libraries.

Install them using extras:

```
pip install bussdcc-hardware[nau7802]
pip install bussdcc-hardware[pump]
pip install bussdcc-hardware[usb_camera]
```

# Example

Example hardware configuration:

```python
runtime.add_device(
    "i2c0",
    "i2c",
    {
        "bus": 1
    }
)

runtime.add_device(
    "scale_adc",
    "nau7802",
    {
        "bus_id": "i2c0",
        "addr": 0x2A
    }
)
```

The runtime ensures buses are initialized before devices that depend on them.

# Design Goals

### Hardware as first-class devices

Buses and sensors are modeled the same way as any other BussDCC device.

### Runtime-managed lifecycle

Devices automatically:

* connect
* report failures
* recover when possible

### Strong typing

All configurations are statically typed dataclasses.

### Composable integrations

Hardware modules can be distributed as independent packages and discovered through entry points.

# Installation

```
pip install bussdcc-hardware
```

Optional drivers:

```
pip install bussdcc-hardware[nau7802]
pip install bussdcc-hardware[pump]
pip install bussdcc-hardware[usb_camera]
```

# Related Projects

* **bussdcc** — cybernetic runtime kernel
* **bussdcc-framework** — runtime utilities and web interface

# License

MIT License
