# `haniwers.daq.device` 機能一覧

このモジュールは、シリアルデバイスとの接続と入出力を抽象化する低レベルI/Oユーティリティです。
主に `serial.Serial` オブジェクトを安全かつ簡潔に扱うための関数を提供します。

---

## ✅ 基本機能

| 関数名 | シグネチャ | 説明 |
|--------|------------|------|
| `connect` | `connect(config: DeviceConfig) -> serial.Serial` | デバイス設定から `Serial` オブジェクトを生成して接続します。 |
| `is_available` | `is_available(config: DeviceConfig) -> bool` | 接続可能かどうか（例外が発生しないか）をチェックします。 |
| `readline` | `readline(device: serial.Serial) -> str` | 1行分読み取り、UTF-8でデコード＆stripして返します。 |
| `write` | `write(device: serial.Serial, data: str) -> None` | デバイスにコマンドや文字列を送信します。 |
| `flush` | `flush(device: serial.Serial) -> None` | 入出力バッファをクリアします。 |
| `with_timeout` | `with_timeout(device: serial.Serial, sec: float) -> Generator[serial.Serial, None, None]` | 一時的に `timeout` を変更するためのコンテキストマネージャです。 |

---

## ⬜ 拡張候補（必要に応じて追加）

| 関数名 | シグネチャ | 説明 |
|--------|------------|------|
| `read_n_lines` | `read_n_lines(device: serial.Serial, n: int) -> list[str]` | 複数行を一括で読み取ります（初期化時のガベージ処理など）。 |
| `disconnect` | `disconnect(device: serial.Serial) -> None` | `Serial.close()` のラッパーとして明示的に切断したい場合に。 |
| `get_port_description` | `get_port_description(device: serial.Serial) -> str` | デバイスのポート名と説明を返します（ログやUI表示向け）。 |

---

## 🧠 使用例（最小構成）

```python
from haniwers.daq import device
from haniwers.config import load_config

cfg = load_config("config.toml")
dev = device.connect(cfg.device)

line = device.readline(dev)
device.write(dev, "SET VTH 300")
device.flush(dev)

with device.with_timeout(dev, 2.0):
    line = device.readline(dev)
```

## 🎯 設計方針

- `DeviceConfig` を引数に使うことで構成ファイルと直結
- シリアル通信に関する関心をすべて `device.py` に集約
- 上位モジュール（`sampler`, `scanner`, `watcher` など）からは `serial.Serial` を意識しなくて済むように