feat: add ENS210 temperature/humidity sensor plug-in

Adds support for the ENS210 relative humidity and temperature sensor
as a new plug-in under repeater/sensors/ens210.py. Also adds a
commented configuration example to config.yaml.example and a
contributor guide at docs/adding_sensors.md explaining how to add
further sensor plug-ins.

## Implementation notes

### Why smbus2 instead of an Adafruit/CircuitPython library

The ENS210 has no maintained Adafruit CircuitPython driver. The
available third-party options are either unmaintained or bring in the
full Blinka/CircuitPython hardware-abstraction stack as a dependency.
smbus2 is a thin, widely-packaged wrapper around the Linux i2c-dev
kernel interface that is already present on Raspberry Pi OS and most
Debian-based systems. It has no transitive dependencies and adds no
abstraction cost.

The ENS210 protocol is simple enough that direct register access is
preferable: two writes to start a measurement (REG_SENS_RUN + REG_SENS_START)
and two three-byte block reads to retrieve temperature and humidity.
The status/validity bit is checked inline rather than relying on a
library to surface it. There is no value a higher-level driver would
add here.

### Read strategy

A fixed post-trigger delay is unreliable — the sensor datasheet quotes
~130 ms typical conversion time but the actual ready time varies. The
implementation instead polls the data-valid status bit (bit 1 of the
third byte in each register block) every 50 ms for up to
read_timeout_seconds (default 1.0 s), breaking as soon as both T and
H report valid data. This is the same approach used in the validated
reference script.

The I2C bus is opened and closed on every read rather than kept open
across poll cycles. Keeping a persistent SMBus handle caused subsequent
reads to time out, consistent with the Linux i2c-dev file descriptor
accumulating state between transactions.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/adding_sensors.md

@@ -0,0 +1,167 @@
+# Adding a New Sensor Plug-in
+
+Sensors in pyMC_Repeater are self-contained modules that live in `repeater/sensors/`. The subsystem is plug-in based: adding a new sensor requires only one new file. The manager discovers and loads it automatically at runtime by importing the module named after the sensor type.
+
+---
+
+## How the sensor subsystem works
+
+| Component | File | Role |
+|-----------|------|------|
+| `SensorBase` | `repeater/sensors/base.py` | Abstract base class all sensors inherit from |
+| `SensorRegistry` | `repeater/sensors/registry.py` | Maps type strings → sensor classes via `@SensorRegistry.register` |
+| `SensorManager` | `repeater/sensors/manager.py` | Reads config, imports sensor modules, polls sensors in background |
+
+When `SensorManager` loads a sensor of type `"foo"`, it calls `importlib.import_module("repeater.sensors.foo")`. That import runs the `@SensorRegistry.register("foo")` decorator on your class, making it available. No changes to `__init__.py` or the manager are needed.
+
+---
+
+## Step-by-step guide
+
+### 1. Create `repeater/sensors/<type>.py`
+
+Name the file after the sensor type string (lowercase, underscores for hyphens). The type string is what operators write in `config.yaml`.
+
+Minimal template:
+
+```python
+"""
+<SensorName> sensor plug-in.
+
+Requires: pip install <package>
+
+Config example:
+  - type: <type>
+    name: "my-sensor"
+    enabled: true
+    auto_install_packages: false
+    settings:
+      some_option: value
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .base import SensorBase
+from .registry import SensorRegistry
+
+
+@SensorRegistry.register("<type>")
+class MySensor(SensorBase):
+    sensor_type = "<type>"
+
+    def __init__(self, name: str, config: Optional[Dict[str, Any]] = None, log=None):
+        super().__init__(name=name, config=config, log=log)
+
+        # Read settings with safe defaults
+        self.some_option = self.settings.get("some_option", "default")
+
+        self.available = False
+        if not self.ensure_python_modules([("import_name", "pip-package-name")]):
+            return  # logs a warning; sensor will report unavailable
+
+        try:
+            import import_name  # type: ignore[import-not-found]
+            # Initialise hardware here
+            self.device = import_name.Device(...)
+            self.available = True
+            self.log.info("MySensor initialized")
+        except Exception as exc:
+            self.log.warning("MySensor init failed: %s", exc)
+            self.available = False
+
+    def _read(self) -> Dict[str, Any]:
+        if not self.available:
+            raise RuntimeError("device not available")
+        try:
+            return {
+                "field_one": ...,
+                "field_two": ...,
+            }
+        except Exception as exc:
+            raise RuntimeError(f"read failed: {exc}") from exc
+```
+
+Key rules:
+
+- **`sensor_type`** class attribute must match the string passed to `@SensorRegistry.register`.
+- **`self.settings`** is the `settings:` block from the sensor's config entry (a plain dict).
+- **`ensure_python_modules`** handles missing dependencies gracefully. Pass a list of `(import_name, pip_package)` tuples. Returns `False` and logs a warning if any are missing and `auto_install_packages` is `false`; installs them if `true`.
+- **`_read`** must return a flat `dict[str, Any]`. The base class wraps it in a standard envelope (`name`, `type`, `ok`, `timestamp`, `data`, optional `error`).
+- **`_read`** must raise `RuntimeError` on failure — the base class catches it, marks `ok=False`, and logs it without crashing the polling loop.
+- All hardware initialisation belongs in `__init__`, not in `_read`. Keep `_read` fast.
+- Lazy-import third-party packages inside `__init__` (after `ensure_python_modules` returns `True`) so the module can be imported on hosts that don't have the package installed.
+
+### 2. Add a commented example to `config.yaml.example`
+
+Find the `sensors.definitions` block and add your sensor alongside the existing examples:
+
+```yaml
+    # Example MySensor (commented out by default)
+    # - type: <type>
+    #   name: my-sensor
+    #   enabled: true
+    #   auto_install_packages: true
+    #   settings:
+    #     some_option: value
+```
+
+Use decimal for numeric config values that would naturally be written in hex (e.g. I2C addresses: `0x43` = `67`). Add a comment showing both forms if the value is commonly written in hex.
+
+### 3. Test locally
+
+Add a test to `tests/test_sensors.py` that:
+
+1. Registers a lightweight mock of your sensor (or stubs the hardware import).
+2. Verifies that `SensorManager` loads it and `read_all()` returns the expected structure.
+3. Verifies that a hardware failure in `_read` produces an `ok=False` result rather than raising.
+
+Example pattern from the existing test suite:
+
+```python
+class _MockMySensor(SensorBase):
+    sensor_type = "<type>"
+
+    def _read(self):
+        return {"field_one": 42.0, "field_two": 55.0}
+
+SensorRegistry.register("<type>", _MockMySensor)
+
+def test_my_sensor_loads_and_reads():
+    config = {
+        "sensors": {
+            "enabled": True,
+            "definitions": [
+                {"name": "test-sensor", "type": "<type>", "settings": {}},
+            ],
+        }
+    }
+    manager = SensorManager(config)
+    readings = manager.read_all()
+    assert readings[0]["ok"] is True
+    assert readings[0]["data"]["field_one"] == 42.0
+```
+
+---
+
+## Checklist
+
+- [ ] `repeater/sensors/<type>.py` created
+- [ ] `sensor_type` class attribute matches the `@SensorRegistry.register` key
+- [ ] All settings read from `self.settings` with sensible defaults
+- [ ] `ensure_python_modules` called before any third-party import
+- [ ] Hardware initialised in `__init__`, not `_read`
+- [ ] `_read` raises `RuntimeError` on failure (never returns `None` or partial data silently)
+- [ ] Commented example added to `config.yaml.example`
+- [ ] Unit test added to `tests/test_sensors.py`
+
+---
+
+## Existing sensors
+
+| Type | File | Hardware |
+|------|------|----------|
+| `hardware_stats` | `repeater/sensors/hardware_stats.py` | Host CPU / memory / disk / network (via `psutil`) |
+| `ina219` | `repeater/sensors/ina219.py` | INA219 I²C current/voltage/power monitor |
+| `ens210` | `repeater/sensors/ens210.py` | ENS210 I²C relative humidity and temperature sensor |