# クイックスタート

このガイドは、`haniwers`を使って
**30分以内**に最初の宇宙線データを測定できることを
目的としたものです。

## 必要なもの

- パソコン（macOS、Linux、Windows+WSL）
- Python 3.9 以上
- OSECHI 検出器（USB 接続）
- インターネット接続（インストール時）

## セットアップ

```bash
brew install uv
```

`hanwers`を隔離した仮想環境で実行するために`uv`を使います。
`uv`はHomebrewなどでインストールできます。

## インストール

```bash
# 初回は自動ダウンロード
uv run haniwers version

# バージョン指定
uv run --with haniwers==0.24.2 haniwers version
```

## 🚀 はじめての測定（10分）

### ステップ 1: 検出器を接続する

```bash
# 利用可能なポート確認
uv run --with haniwers==0.24.2 haniwers ports
```

USB ポート一覧が表示されます。
通常は `/dev/ttyUSB0` (Linux) または `/dev/cu.usbserial-*` (macOS) です。

### ステップ 2: スレッショルドを設定する

```bash
# スレッショルド設定コマンド
uv run --with haniwers==0.24.2 haniwers vth --ch 1 --vth 300
```

チャンネルごとにスレッショルドを設定してください。
検出器の LED の光り方を確認してください。

**スレッショルド値について：**
- 各ステップ = 4mV（例：250 = 1000mV）
- 推奨範囲：250〜350

### ステップ 3: データを測定する

```bash
uv run --with haniwers==0.24.2 haniwers daq
```

実行中は `Ctrl+C` で停止できます。

データは `YYYYMMDD` 形式の日付ごとのディレクトリに自動保存されます。

### ステップ 4: データを確認する

```bash
# データをCSV形式に変換
uv run --with haniwers==0.24.2 haniwers run2csv 1 --save

# ファイル一覧表示
ls data/
```

`data/` ディレクトリに CSV ファイルが作成されます！

---

## 📊 よくある次のステップ

### 1. 複数チャンネルで測定したい

```bash
# チャンネル 1, 2, 3 でそれぞれスレッショルドを設定
uv run --with haniwers==0.24.2 haniwers vth --ch 1 --vth 300
uv run --with haniwers==0.24.2 haniwers vth --ch 2 --vth 300
uv run --with haniwers==0.24.2 haniwers vth --ch 3 --vth 300

# 測定開始
uv run --with haniwers==0.24.2 haniwers daq
```

### 2. スレッショルドを自動検出したい

```bash
# スレッショルドスキャン（推奨範囲: 250-350）
uv run --with haniwers==0.24.2 haniwers scan --ch 1 --duration 10 --vmin 250 --vmax 350

# スキャン結果から最適値を計算
uv run --with haniwers==0.24.2 haniwers fit scan_results

# 計算された値を自動設定
uv run --with haniwers==0.24.2 haniwers vth
```

### 3. 長時間測定したい

```bash
uv run --with haniwers==0.24.2 haniwers daq --quiet
```

長時間測定する場合は、出力を非表示（`--quiet`）にすることをオススメします。

### 4. 設定ファイルを使いたい

```bash
# 設定ファイルを作成
cat > daq.toml << EOF
[daq]
port = "/dev/ttyUSB0"
baudrate = 115200
interval = 60
EOF

# 設定ファイルを使って測定
uv run --with haniwers==0.24.2 haniwers daq --load-from daq.toml
```

---

## 🎯 主要コマンド一覧

| コマンド | 説明 | 例 |
|---------|------|-----|
| `version` | バージョン確認 | `uv run --with haniwers==0.24.2 haniwers version` |
| `ports` | 利用可能なポート確認 | `uv run --with haniwers==0.24.2 haniwers ports` |
| `vth` | スレッショルド設定 | `uv run --with haniwers==0.24.2 haniwers vth --ch 1 --vth 300` |
| `daq` | データ測定開始 | `uv run --with haniwers==0.24.2 haniwers daq` |
| `scan` | スレッショルドスキャン | `uv run --with haniwers==0.24.2 haniwers scan --ch 1 --vmin 250 --vmax 350` |
| `fit` | スレッショルド計算 | `uv run --with haniwers==0.24.2 haniwers fit scan_results` |
| `run2csv` | データ形式変換 | `uv run --with haniwers==0.24.2 haniwers run2csv 1 --save` |
| `docs` | ドキュメント表示 | `uv run --with haniwers==0.24.2 haniwers docs` |

詳細は `uv run --with haniwers==0.24.2 haniwers <コマンド> --help` で確認できます。

---

## 📁 データはどこに保存される？

測定データは自動的に以下の場所に保存されます：

```
~/haniwers-workspace/
├── data/                 # 📊 測定データ（CSV）
│   ├── run001.csv
│   ├── run002.csv
│   └── ...
├── logs/                 # 📝 ログファイル
└── daq.toml             # ⚙️ 設定ファイル
```

**重要:** `data/` フォルダーをバックアップしてください！

---

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

### 「haniwers: command not found」

```bash
# インストール確認
pipx list

# 再インストール
pipx reinstall haniwers
```

### 「ポートが見つからない」

```bash
# ポート確認
uv run --with haniwers==0.24.2 haniwers ports

# USB接続確認
# 検出器がUSBで接続されているか確認してください
```

### 「Permission denied」エラー

```bash
# Linux の場合、ユーザーをグループに追加
sudo usermod -a -G dialout $USER
sudo reboot
```

### データが記録されない

```bash
# LED が光っているか確認
# スレッショルド値が適切か確認
# ログを確認
uv run --with haniwers==0.24.2 haniwers daq --duration 10  # ログがターミナルに表示されます
```

---

## 📚 次に読むドキュメント

測定がうまくいったら、以下のドキュメントを参照してください：

1. **詳しい使用方法**: [ユーザーガイド](user/index.md) - スクリーンショット付き
2. **コマンド詳細**: [コマンドリファレンス](command/v0/index.md) - 全コマンドの説明
3. **設定方法**: [設定ガイド](usage/settings.md) - 詳細な設定方法
4. **ワークフロー**: [標準的なワークフロー](usage/workflows.md) - 測定の流れ

---

## 💡 Tips

### オンラインドキュメントを開く

```bash
uv run --with haniwers==0.24.2 haniwers docs
```

---

## ❓ よくある質問

### Q: どのスレッショルド値を使えばいい？

**A:** 環境によって異なります。推奨範囲は 250〜350 です。最初は 300 で試してから、`haniwers scan` で自動検出するのがおすすめです。

### Q: 複数の測定を同時に実行できる？

**A:** いいえ、同じパソコンからは 1 つの検出器のみ接続できます。複数測定する場合は、異なるパソコンを使用してください。

### Q: 測定中に接続が切れた場合は？

**A:** データファイルは自動的に保存されます。接続を再度確認してから、`haniwers daq` を再実行してください。

### Q: データをバックアップしたい場合は？

**A:** `data/` ディレクトリをコピーしてください。または、Google Drive などのクラウドストレージと同期させるのも便利です。

### Q: Windows で使用できる？

**A:** Windows Subsystem for Linux（WSL）の使用を推奨します。WSL を使えば、ほぼ Linux と同じように使用できます。

---

## 🆘 サポート

問題が発生した場合：

1. このページの [トラブルシューティング](#トラブルシューティング) を確認
2. [インストールガイド](install.md) の FAQ を確認
3. コマンドで `--help` オプションを使用：`haniwers <コマンド> --help`
4. [GitLab Issues](https://gitlab.com/qumasan/haniwers/-/issues) に報告

---

## 📖 関連ドキュメント

- [インストールガイド](install.md) - 詳細なインストール手順
- [セットアップ](usage/setup.md) - 環境準備
- [標準ワークフロー](usage/workflows.md) - 実例
- [コマンドリファレンス](command/index.md) - 全コマンド一覧