# 設定ファイルの作成と管理

`haniwers`でデータを取得するには、設定ファイル（`hnw.toml`）を作成する必要があります。このドキュメントでは、設定ファイルの作成方法と各パラメーターの意味を説明します。

:::{tip}
**はじめての方へ**: 設定ファイルは一度作成すれば、同じ測定条件で繰り返し使用できます。最初に基本的な設定を行い、必要に応じてCLIオプションで上書きする使い方がオススメです。
:::

---

## 🚀 クイックスタート

### 1. 設定ファイルの生成

最初のステップは、設定ファイルを生成することです。

```bash
# 測定用ディレクトリに移動
cd ~/haniwers

# 設定ファイルを生成（hnw.tomlが作成される）
haniwers-v1 config init
```

:::{note}
`haniwers-v1`コマンドは、デフォルトで`hnw.toml`という名前の設定ファイルを読み込みます。別の名前にしたい場合は、`--config`オプションで指定できます。
:::

### 2. テキストエディターで編集

```bash
# VSCodeで編集
code hnw.toml

# vimで編集
vi hnw.toml

# Emacsで編集
emacs hnw.toml
```

### 3. 重要なパラメーターを設定

以下の3つは**必ず**設定してください。

```toml
[device]
port = "/dev/ttyUSB0"        # ポート名（haniwers port list で確認）
baudrate = 115200             # 通常は変更不要
timeout = 1.0                 # 秒単位

[sampler]
workspace = "./data"          # データ保存ディレクトリ
filename_prefix = "osechi_data"  # ファイル名の接頭辞
```

### 4. DAQ実行

```bash
haniwers-v1 daq
```

---

## 📋 詳細パラメーター説明

### デバイス設定セクション `[device]`

#### `port` - シリアルポート名

OSECHI検出器が接続されているシリアルポートの名前です。

**初期値**: `/dev/ttyUSB0`

##### 確認方法

```bash
haniwers-v1 port list
```

##### OS別の例

| OS | 例 |
|----|-----|
| Linux | `/dev/ttyUSB0`, `/dev/ttyUSB1` |
| macOS | `/dev/tty.usbserial-AB0JXYZ`, `/dev/cu.usbserial-14120` |
| Windows | `COM3`, `COM4` |

#### `baudrate` - シリアル通信速度

シリアル通信の速度を指定します（単位：ビット/秒）。**通常は変更する必要はありません**。

**推奨値**: `115200`（ボーレート）

#### `timeout` - シリアル通信タイムアウト

データ受信のタイムアウト時間（単位：秒）。

**初期値**: `1.0`

##### 説明

- 短すぎるとデータ受信に失敗しやすい
- 長すぎるとエラー時の反応が遅くなる
- 通常の短い測定: `1.0` ～ `2.0` 秒
- 長い測定・スキャン: `3.0` ～ `5.0` 秒以上推奨

#### `label` - デバイス識別ラベル

この検出器に付ける名前（ログやレポートで使用）。

**例**: `"OSECHI-001"`, `"detector-lab"`, `"cosmic-v2"`

---

### サンプラー設定セクション `[sampler]`

#### `workspace` - データ保存ディレクトリ

測定データを保存するベースディレクトリです。

##### 説明

- ここに自動的に日付フォルダー（`20250120`形式）が作成される
- 実際のファイルはそのフォルダー内に保存される

**例**:

```toml
workspace = "./data"          # 相対パス（推奨）
workspace = "/home/user/cosmic_data"  # 絶対パス
```

#### `filename_prefix` - ファイル名の接頭辞

生成されるCSVファイルの名前の前半部分です。

**例**: `"osechi_data"` → `osechi_data_20250120_130405.csv`

**推奨**: 実験名または測定目的を反映した短い名前

```toml
filename_prefix = "kek_lab_test"
filename_prefix = "outdoor_measurement"
```

#### `filename_suffix` - ファイル拡張子

ファイル形式を指定します。

**利用可能**: `.csv` (推奨), `.dat`

```toml
filename_suffix = ".csv"
```

#### `mode` - 取得モード

データ取得の方式を指定します。

| モード | 説明 | パラメーター |
|--------|------|------------|
| `"count_based"` | イベント数ベース（デフォルト） | `events_per_file`, `number_of_files` |
| `"time_based"` | 時間ベース | `duration` |

**デフォルト**: `"count_based"`

```toml
mode = "count_based"    # イベント数で区切る
mode = "time_based"     # 時間で区切る
```

#### `events_per_file` - 1ファイルあたりのイベント数（count_based用）

各CSVファイルに何個のイベントを記録するかを指定します。

**説明**:

- ファイルサイズとの関係: 1イベント ≈ 50～100バイト
- 1000イベント ≈ 50～100 KB

**推奨値**:

| 想定環境 | 値 |
|---------|-----|
| 短い測定テスト | 100 ～ 500 |
| 通常の測定 | 1000 ～ 5000 |
| 長時間測定 | 10000 ～ 100000 |

```toml
events_per_file = 1000    # 1ファイル1000イベント
events_per_file = 5000    # 1ファイル5000イベント
```

#### `number_of_files` - ファイル数（count_based用）

1回のDAQセッションで最大何個のファイルを作成するか。

**計算例**:

- `events_per_file = 1000`, `number_of_files = 10`
- → 最大10,000イベント取得

```toml
number_of_files = 10    # 最大10ファイル
number_of_files = 100   # 最大100ファイル
```

#### `duration` - 測定時間（time_based用）

時間ベースの測定では、何秒間データを取得するかを指定します。

**単位**: 秒（例: 30.0, 60.0, 300.0）

```toml
duration = 30.0    # 30秒間取得
duration = 300.0   # 5分間取得
```

#### `stream_mode` - リアルタイム書き込みモード

データをバッファに貯めずにリアルタイムで書き込むかを指定します。

| 値 | 説明 |
|----|------|
| `true` | リアルタイム書き込み（安全だが遅い） |
| `false` | バッファリング（高速だがメモリ使用） |

**推奨**: `false`（デフォルト）通常はバッファリングで十分です。

```toml
stream_mode = false   # 高速モード（推奨）
stream_mode = true    # 安全モード
```

#### `suppress_threshold` - 抑制閾値

スレッショルドスキャン時に、対象以外のチャネルを抑制する閾値です。

**説明**: スキャン時に特定のチャネルのノイズを減らす

**初期値**: `1000`（通常は変更不要）

```toml
suppress_threshold = 1000
```

#### `max_retry` - リトライ回数

通信エラー時の最大リトライ回数です。

**初期値**: `3`

```toml
max_retry = 3
```

---

## 設定ファイルの例

### 例1: シンプルな設定（初心者向け）

```toml
[device]
port = "/dev/ttyUSB0"
baudrate = 115200
timeout = 1.0
label = "My OSECHI"

[sampler]
workspace = "./data"
filename_prefix = "measurement"
filename_suffix = ".csv"
mode = "count_based"
events_per_file = 1000
number_of_files = 10
stream_mode = false
suppress_threshold = 1000
max_retry = 3
```

### 例2: 時間ベースの測定

```toml
[device]
port = "/dev/ttyUSB0"
baudrate = 115200
timeout = 2.0
label = "Lab Detector"

[sampler]
workspace = "./data"
filename_prefix = "time_based_daq"
filename_suffix = ".csv"
mode = "time_based"
duration = 60.0         # 60秒間測定
stream_mode = false
```

### 例3: 長時間測定

```toml
[device]
port = "/dev/ttyUSB0"
baudrate = 115200
timeout = 3.0
label = "Outdoor Measurement"

[sampler]
workspace = "/mnt/usb_drive/cosmic_data"
filename_prefix = "outdoor_run01"
filename_suffix = ".csv"
mode = "count_based"
events_per_file = 50000    # ファイルを大きめに
number_of_files = 100      # 最大500万イベント
stream_mode = false
```

---

---

## 🔧 CLIオプションによる上書き

設定ファイルのパラメーターは、CLI（コマンドライン）オプションで上書きできます。

### 使用例

```bash
# 基本的な上書き
haniwers-v1 daq --config config.toml --workspace ./output

# ポートを変更
haniwers-v1 daq --config config.toml --port /dev/ttyUSB1

# 30秒測定に変更
haniwers-v1 daq --config config.toml --duration 30

# 複数の上書き
haniwers-v1 daq --config config.toml \
    --workspace ./exp02 \
    --filename-prefix run002 \
    --events-per-file 5000
```

### 優先順位

設定の優先順位は以下の通りです（高い順）：

1. **CLIオプション** - コマンドラインで指定した値
2. **環境変数** - `HANIWERS_*` で始まる環境変数
3. **設定ファイル** - `config.toml` の値
4. **デフォルト値** - プログラムで定義された値

---

## ❓ トラブルシューティング

### 「ファイルが見つかりません」エラー

```text
[ERROR] Config file not found: config.toml
```

**解決方法**:

```bash
# 設定ファイルの位置確認
ls -la config.toml

# フルパスで指定
haniwers-v1 daq --config /full/path/to/config.toml
```

### ポート設定が間違っている

```bash
[ERROR] Failed to open port /dev/ttyUSB99
```

**解決方法**:

```bash
# 利用可能なポートを確認
haniwers-v1 port list

# ポートをテスト
haniwers-v1 port test /dev/ttyUSB0
```

### ファイルシステムが満杯

```bash
[ERROR] No space left on device
```

**解決方法**:

```bash
# ディスク容量確認
df -h

# 別のディレクトリに変更
haniwers-v1 daq --config config.toml --workspace /mnt/external_drive/data
```

### パラメーター値が無効

```text
[ERROR] Invalid configuration: value must be positive integer
```

**確認項目**:

```toml
# ❌ 間違い
events_per_file = -1000    # 負の数
timeout = 0                # 0以下

# ✅ 正解
events_per_file = 1000     # 正の整数
timeout = 1.0              # 1秒以上
```

---

## 💡 ベストプラクティス

### 1. 複数の設定ファイルを用意

測定内容に応じて複数の設定ファイルを管理：

```text
config/
├── config-quick-test.toml      # 短いテスト用
├── config-normal-daq.toml      # 通常測定用
├── config-long-measurement.toml # 長時間測定用
└── config-outdoor.toml         # 屋外測定用
```

**使い分け**:

```bash
# クイックテスト
haniwers-v1 daq --config config/config-quick-test.toml

# 実際の測定
haniwers-v1 daq --config config/config-normal-daq.toml
```

### 2. ファイル名にタイムスタンプを含める

測定履歴の管理が簡単になります：

```toml
filename_prefix = "20250120_kek_lab_test"  # 日付を含める
filename_prefix = "exp02_threshold_scan"   # 実験番号を含める
```

### 3. ディレクトリ構造を整理

```text
~/cosmic_data/
├── config/              # 設定ファイル
│   └── config.toml
├── data/                # 測定データ
│   ├── 20250120/
│   ├── 20250121/
│   └── 20250122/
└── archive/             # 古いデータ
```

### 4. 定期的なバックアップ

重要な設定とデータをバックアップ：

```bash
# 毎日バックアップ
tar -czf backup_$(date +%Y%m%d).tar.gz config/ data/
```

---

## 🔗 参考資料

- **[ポート管理ガイド](./port.md)**: ポート名の確認方法
- **[データ品質について](./data-quality.md)**: ノイズ対処とデータ検証
- **[DAQコマンド](./daq.md)**: DAQコマンドの詳細
- **[よくある質問](../faq.md)**: その他の質問と回答