# Kurikintonsの設定

**Kurikintons** は、OSECHI検出器のマイクロコントローラ（ESP32-WROOM-32D）に書き込むArduinoスケッチです。

このドキュメントでは、Kurikintonsスケッチをダウンロードしてビルド・書き込みする方法を説明します。

## 概要

### 必要な道具

まず、必要なハードウェアとソフトウェアを確認しましょう。

**ハードウェア**:
- パソコン（スケッチをビルド・書き込むため）
- OSECHI検出器本体
- USB-Aケーブル（通常のUSBケーブル：パソコンとOSECHIを接続）
- Micro-USBケーブル（OSECHIに接続）

**ソフトウェア**:
- Arduino IDE（スケッチのビルド・書き込みに必須）
- Kurikintonsスケッチ（`.ino`ファイル）

:::{note}

**パソコンについて**

自分が普段使っているパソコン（WindowsまたはmacOS）を使うことをお勧めします。

Raspberry Piも使用できますが、ビルドと書き込みに時間がかかる場合があります。

:::

## 動作確認済み環境

このドキュメントは以下の環境で動作確認しています：

| ソフトウェア | バージョン | 備考 |
|-------------|-----------|------|
| Arduino IDE | 2.3.6 | macOS環境で確認 |
| ESP32 Board Support | 3.3.2 | Espressif Systems |
| Adafruit Unified Sensor | 1.1.15 | センサーライブラリ依存 |
| Adafruit BME280 Library | 2.3.0 | 温度・湿度・気圧センサー |
| Adafruit BusIO | 1.17.4 | I2C/SPI通信ライブラリ |

:::{note}

**バージョンについて**

上記のバージョンは動作確認済みですが、最新版でも動作する可能性が高いです。とくに理由がない限り、最新版のインストールをオススメします。

:::

## ステップ1: Arduino IDEをインストールする

Kurikintonsスケッチをビルド・書き込むために、Arduino IDEをインストールします。

### インストール方法

**macOSの場合（Homebrewを使用）**:

```console
$ brew install --cask arduino-ide
```

**Windows / macOS / Linux（公式ウェブサイト）**:

1. [Arduino公式ウェブサイト](https://www.arduino.cc/en/software)にアクセス
2. Arduino IDE 2.0（最新版）をダウンロード
3. インストーラーを実行してインストール

:::{note}

**arduino-cli について**

`arduino-cli`はコマンドライン版のArduino IDEです。VS Codeなどのエディターを使う場合に便利ですが、初心者向けにはGUIの**Arduino IDE 2.0**の使用をお勧めします。

:::

## ステップ2: Arduino IDEを設定する

Arduino IDEをインストールしたら、ESP32とセンサーライブラリをセットアップします。

### 2.1 ESP32ボードサポートをインストール

Arduino IDEでESP32を使うには、ボードの定義をインストールします。

1. Arduino IDEを起動
2. メニューから `Arduino IDE` → `Settings`（macOS）または `File` → `Preferences`（Windows）を選択
3. **Additional Boards Manager URLs** に以下のURLを追加：
   ```
   https://espressif.github.io/arduino-esp32/package_esp32_index.json
   ```
4. **OK** をクリック
5. メニューから `Tools` → `Board` → `Boards Manager` を選択
6. 検索欄で「esp32」と入力
7. **esp32 by Espressif Systems** を探して **Install** をクリック

### 2.2 ボード設定

スケッチを書き込む前に、使用するボードを指定します。

1. メニューから `Tools` → `Board` → `ESP32` を選択
2. **ESP32-WROOM-32D** を選択
   - リストに見つからない場合は、**ESP32 Dev Module** を選択してください

### 2.3 シリアルポート設定

USBケーブルでOSECHIをパソコンに接続した後、ポートを選択します。

1. メニューから `Tools` → `Port` を選択
2. 接続したシリアルポートを選択
   - macOS: `/dev/cu.usbserial-*` または `/dev/cu.SLAB_USBtoUART` のような名前
   - Windows: `COM3`、`COM4` など

:::{tip}

**どのポートを選べばいいか分からない場合**

`Tools` → `Port` を見て、新しく表示されたポートがOSECHIです。不確定な場合は、[ユーザーマニュアル](../../users/index.md)の「シリアルポート確認」を参照してください。

:::

### 2.4 センサーライブラリをインストール

Kurikintonsスケッチは、温度・湿度・気圧センサー（BME280）を使用しています。ライブラリをインストールします。

1. メニューから `Tools` → `Manage Libraries` を選択
2. 検索欄で以下のライブラリを検索して、順にインストール：
   - **Adafruit Unified Sensor** by Adafruit
   - **Adafruit BME280 Library** by Adafruit
   - **Adafruit BusIO** by Adafruit

:::{note}

**ライブラリインストールの順序**

依存関係があるため、上記の順序で3つのライブラリをインストールしてください。

:::

## ステップ3: Kurikintonsスケッチをダウンロード

Kurikintonsスケッチを取得します。

### スケッチの入手

スケッチは以下の場所から取得できます：

- **公式リポジトリ**: [haniwersのスケッチディレクトリ](https://gitlab.com/qumasan/haniwers/-/tree/main/arduino)
- **最新バージョン**: `kurikintons_v1/kurikintons_v1.ino`

:::{note}

**複数のスケッチバージョン**

- **kurikintons_v1/kurikintons_v1.ino**: 現在の推奨版
- **kurikintons_x/kurikintons_x.ino**: テスト・開発版
- **archives/**: 過去のバージョン

特別な理由がない限り、最新版（v1）を使用してください。

:::

### ダウンロード手順

1. [haniwersリポジトリ](https://gitlab.com/qumasan/haniwers)にアクセス
2. `arduino` フォルダを開く
3. `kurikintons_v1` フォルダを開く
4. `kurikintons_v1.ino` ファイルを右クリック → **Download** を選択
5. パソコンの分かりやすい場所（例：`~/Downloads`）に保存

## ステップ4: Kurikintonsスケッチをビルド・書き込み

### 4.1 スケッチをArduino IDEで開く

1. Arduino IDEを起動
2. メニューから `File` → `Open` を選択
3. ダウンロードした `kurikintons_v1.ino` を選択して開く

### 4.2 ビルド（コンパイル）

スケッチが正しいか確認します。

1. メニューから `Sketch` → `Verify/Compile` を選択（または {kbd}`⌘+R` on macOS / {kbd}`Ctrl+R` on Windows）
2. 画面の下部に進捗が表示されます
3. **Compilation complete** と表示されればOK

:::{warning}

**コンパイルエラーが出た場合**

以下を確認してください：
- 全てのライブラリがインストールされているか
- ボード設定が **ESP32-WROOM-32D** になっているか
- Arduino IDEの最新バージョンを使用しているか

:::

### 4.3 USBで接続

1. Micro-USBケーブルでOSECHIをパソコンに接続
2. LEDが点灯することを確認

### 4.4 スケッチを書き込み

1. `Tools` → `Port` でシリアルポートが選択されているか確認
2. メニューから `Sketch` → `Upload` を選択（または {kbd}`⌘+U` on macOS / {kbd}`Ctrl+U` on Windows）
3. 画面の下部に進捗バーが表示されます
4. **Leaving... Hard resetting via RTS pin...** と表示されれば完了

:::{tip}

**書き込み中の画面**

書き込み中は以下のようなメッセージが表示されます：

```
Connecting........_____
Uploading... 100%
Leaving... Hard resetting via RTS pin...
```

時間がかかる場合（30秒～1分）がありますが、辛抱強く待ってください。

:::

## ステップ5: VS Codeでの編集（オプション）

:::{warning}

**非推奨の拡張機能について（2024年10月更新）**

Microsoft製のArduino拡張機能は2024年10月1日に廃止されました。既存ユーザー向けに情報を残していますが、新規ユーザーには**Arduino IDE 2.0**の使用をオススメします。

VS Codeでの開発を希望する場合は、以下の代替案があります：

- **PlatformIO**: ESP32開発で広く使われているコミュニティ標準の拡張機能
- **pioarduino**: PlatformIOのフォーク、ESP32 Arduino Core v3をサポート

これらの拡張機能は別途セットアップが必要で、Arduino IDEとは異なる開発環境になります。

:::

### インストール（非推奨・既存ユーザー向け）

1. VS Code Marketplaceで [Arduino拡張機能](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.vscode-arduino) を検索・インストール
2. 拡張機能は `arduino-cli` をバンドルしており、別途インストール不要

### コマンドパレット（非推奨・既存ユーザー向け）

VS Codeのコマンドパレット（{kbd}`Shift+Command+P` on macOS / {kbd}`Ctrl+Shift+P` on Windows）で以下が使用できます：

- `Arduino: Select Serial Port`: シリアルポートを選択
- `Arduino: Open Serial Monitor`: センサー出力を監視
- `Arduino: Library Manager`: ライブラリを管理

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

### よくある問題と解決方法

**Q: コンパイルエラーが出る**

A: 以下を確認してください：
1. 全てのライブラリが正しくインストールされているか（セクション2.4参照）
2. ボード設定が **ESP32-WROOM-32D** になっているか（セクション2.2参照）
3. Arduino IDEを最新版に更新してみてください

**Q: ファイルが書き込めない / "Permission denied" エラーが出る**

A:
- macOS / Linux: ユーザーが `/dev/ttyUSB*` へのアクセス権を持っていない可能性があります
- Windows: USB ドライバーが正しくインストールされているか確認してください

**Q: ポートが表示されない / 認識されない**

A:
1. USB ケーブルが正しく接続されているか確認
2. ケーブルがデータ通信対応か確認（充電用のケーブルではない）
3. パソコンを再起動してみてください
4. 別のUSBポートに接続してみてください

**Q: 書き込み時に "timeout" や "Connection refused" エラーが出る**

A:
1. ボード設定が正しいか確認（セクション2.2参照）
2. USB ケーブルをしっかり接続し直す
3. Arduino IDE を再起動する
4. パソコンを再起動する

## Arduino関係のリファレンス

スケッチで使っているヘッダーファイルや関数／メソッドなどのリファレンスです。

- [Serial - Arduino Reference](https://www.arduino.cc/reference/en/language/functions/communication/serial/)
- [SPI - Arduino Reference](https://www.arduino.cc/reference/en/language/functions/communication/spi/)
- [BME280 - Arduino Reference](https://www.arduino.cc/reference/en/libraries/bme280/)
- [Arduino ESP32 - Espressif](https://docs.espressif.com/projects/arduino-esp32/en/latest/getting_started.html)