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

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

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

Tip

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

🚀 クイックスタート#

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

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

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

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

注釈

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

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

# VSCodeで編集
code hnw.toml

# vimで編集
vi hnw.toml

# Emacsで編集
emacs hnw.toml

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

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

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

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

4. DAQ実行#

haniwers-v1 daq

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

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

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

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

初期値: /dev/ttyUSB0

確認方法#

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形式）が作成される
実際のファイルはそのフォルダー内に保存される

例:

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

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

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

例: "osechi_data" → osechi_data_20250120_130405.csv

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

filename_prefix = "kek_lab_test"
filename_prefix = "outdoor_measurement"

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

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

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

filename_suffix = ".csv"

`mode` - 取得モード#

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

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

デフォルト: "count_based"

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

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イベント取得

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

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

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

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

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

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

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

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

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

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

`suppress_threshold` - 抑制閾値#

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

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

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

suppress_threshold = 1000

`max_retry` - リトライ回数#

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

初期値: 3

max_retry = 3

設定ファイルの例#

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

[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: 時間ベースの測定#

[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: 長時間測定#

[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（コマンドライン）オプションで上書きできます。

使用例#

# 基本的な上書き
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

優先順位#

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

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

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

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

[ERROR] Config file not found: config.toml

解決方法:

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

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

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

[ERROR] Failed to open port /dev/ttyUSB99

解決方法:

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

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

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

[ERROR] No space left on device

解決方法:

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

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

パラメーター値が無効#

[ERROR] Invalid configuration: value must be positive integer

確認項目:

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

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

💡 ベストプラクティス#

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

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

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

使い分け:

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

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

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

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

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

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

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

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

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

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

🔗 参考資料#

ポート管理ガイド: ポート名の確認方法
データ品質について: ノイズ対処とデータ検証
DAQコマンド: DAQコマンドの詳細
よくある質問: その他の質問と回答

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

目次

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

🚀 クイックスタート#

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

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

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

4. DAQ実行#

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

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

port - シリアルポート名#

確認方法#

OS別の例#

baudrate - シリアル通信速度#

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

説明#

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

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

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

説明#

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

filename_suffix - ファイル拡張子#

mode - 取得モード#

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

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

duration - 測定時間（time_based用）#

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

suppress_threshold - 抑制閾値#

max_retry - リトライ回数#

設定ファイルの例#

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

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

例3: 長時間測定#

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

使用例#

優先順位#

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

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

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

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

パラメーター値が無効#

💡 ベストプラクティス#

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

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

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

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

🔗 参考資料#

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

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

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

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

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

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

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

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

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

`mode` - 取得モード#

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

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

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

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

`suppress_threshold` - 抑制閾値#

`max_retry` - リトライ回数#