Metadata-Version: 2.4
Name: bme688
Version: 0.1.0
Summary: A typed, register-accurate Python driver for the Bosch BME688 environmental sensor.
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/bme688
Project-URL: Documentation, https://github.com/jbussdieker/bme688/blob/main/README.md
Project-URL: Repository, https://github.com/jbussdieker/bme688
Project-URL: Issues, https://github.com/jbussdieker/bme688/issues
Project-URL: Changelog, https://github.com/jbussdieker/bme688/blob/main/CHANGELOG.md
Keywords: bme688
Classifier: Topic :: Scientific/Engineering :: Instrument Drivers
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
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: typed-registers~=0.2.0
Provides-Extra: i2c
Requires-Dist: smbus2; extra == "i2c"
Provides-Extra: cli
Requires-Dist: click; extra == "cli"
Requires-Dist: smbus2; extra == "cli"
Provides-Extra: dev
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# BME688

**bme688** is a **typed, register-accurate Python driver** for the Bosch BME688 environmental sensor.

It provides temperature, pressure, and humidity readings using a clean, explicit register model built on top of typed-registers.

The goal is to make working with the sensor:

* **transparent** (registers are first-class)
* **typed** (dataclasses, no raw byte juggling)
* **predictable** (no hidden state or magic)

## Features

* ✅ Typed register definitions (dataclasses)
* ✅ Accurate Bosch compensation algorithms
* ✅ Temperature, pressure, and humidity readings
* ✅ Forced-mode measurement with polling
* ✅ Clean separation of:

  * register layer
  * device behavior
  * compensation math
* ✅ CLI for quick testing

## Installation

```bash
pip install bme688[i2c,cli]
```

## Requirements

* Python ≥ 3.11
* I²C enabled (e.g. Raspberry Pi)
* `smbus2`

## Quick Start

```python
from smbus2 import SMBus
from typed_registers import SMBusRegisterBus
from bme688 import BME688

bus = SMBusRegisterBus(SMBus(1))
sensor = BME688(bus)

sensor.initialize()

reading = sensor.read()

print(reading)
```

Example output:

```
Reading(
    temperature_c=23.46,
    pressure_pa=101021.0,
    humidity_rh=41.46
)
```

## CLI Usage

Initialize the device:

```bash
bme688 init
```

Read sensor values:

```bash
bme688 read
```

Example:

```
Temperature: 23.46 °C
Pressure:    101021.00 Pa
Humidity:    41.46 %RH
```

Dump raw register state:

```bash
bme688 dump
```

## Architecture

The driver is intentionally structured in layers:

```
Device API
    ↓
Compensation (Bosch algorithms)
    ↓
Typed Registers
    ↓
typed-registers
    ↓
Bus (I²C / SMBus / etc.)
```

### Registers

Each hardware register is modeled as a typed dataclass:

```python
REG_CTRL_MEAS(osrs_t=1, osrs_p=1, mode=0)
```

Multi-byte registers use structured decoding:

```python
REG_FIELD_DATA(
    new_data=True,
    temperature_adc=...,
    pressure_adc=...,
    humidity_adc=...
)
```

## Design Philosophy

This driver follows a simple rule:

> The register map *is* the API.

* No hidden abstractions
* No implicit conversions
* No “magic” state

Everything maps directly to the datasheet.

## Status

**Alpha**

* Temperature, pressure, humidity: ✅ stable
* Gas resistance: ⚠️ partial (raw values available, full pipeline not implemented)

## Development

```bash
pip install -e .[dev]
mypy src/
```

## License

MIT License

## Author

**Joshua B. Bussdieker**
[https://github.com/jbussdieker](https://github.com/jbussdieker)
