Taiko-Drum-Controller-Arduino/README_ja-JP.md

[Click here for English documentation](README.md)

[中文文档在这里](README_zh-CN.md)

![太鼓コントローラ](./images/banner-taiko.png)

# Taiko Drum Controller - Arduino (ATmega32U4/ESP32)

自分の太鼓の達人PCコントローラを作るためのオープンソースハードウェアプログラム。キーボードとして、またはアーケードマシンで遊ぶように打撃力感知を有効にするアナログジョイスティックとしてエミュレートできます。今では2つのドラムもサポートしているので、家で友達と一緒にゲームを楽しむことができます！

## このプロジェクトについて

このプロジェクトは、自宅で自分のハードウェア太鼓を開発するのを助けることを目指しています。

**このプログラムは個人的かつ非商用のみに限ります。**

## 必要なもの

1. Arduino Micro/Leonardo (ATmega32U4) ボードまたは Arduino Nano ESP (ESP32) ボード。
   
   ほとんどのATmega32U4ボードは動作しますが、キーボードエミュレーションをサポートしているかを確認する必要があります。Arduino UnoのようなATmega328Pボードは動作しません。
   
   ESP32はATmega32U4よりも格段にパワフルなため、強く推奨されます。このプロジェクトではESP32-WROOM-32ボードを使用しています。

2. 4つの圧電センサ。
   
3. 8つの100kΩ抵抗。
   
4. (任意) DB107などのブリッジ整流器チップ（詳細は追加ノートセクションを参照）。

5. (任意) 赤と青のLEDいくつか。
   
6. 必要な電子部品（ブレッドボード、ジャンパーワイヤーなど）。
   
7. 木板と切削工具（自分で物理的な太鼓を一から作る必要がある場合のみ）。アフターマーケットの太鼓やBig Power Lv.5ドラムを持っている場合は、それらを直接使用できます。

## コントローラを作る手順

1. 太鼓を作り、4つの圧電センサを太鼓にしっかりと接着します。センサの好ましい位置については画像を参照してください。
   
   ![センサ設定](./images/piezo_locations.png)

2. 圧電センサと他のコンポーネントを以下の通りコントローラに接続します（圧電センサの極性は問いません）;

   以下のスキームはArduino Microボード用です。異なるボードを使用する場合は、接続についてそのドキュメンテーションを参照してください。
   
   ![コントローラスキーム](./images/scheme.png)

   ブリッジ整流器を追加することを選択した場合、以下のスキームを使用してください：
   
   ![ブリッジ整流器付きコントローラスキーム](./images/scheme_bridge.png)

3. ファームウェアをボードにフラッシュします。
   
   `SAMPLE_CACHE_LENGTH`、`HIT_THRES`、`RESET_THRES`、`sensitivity`などのパラメータを微調整する必要があるかもしれません。詳細は以下のセクションを参照してください。

4. 楽しんでください！

## パラメータの調整

1. ヒットとリセットの閾値
   
   `DEBUG 1`を設定し（これによりキーボード出力が無効になり、シリアルポートから信号値が送信されます）、ファームウェアをフラッシュし、太鼓の4つの領域のいずれかでロールして、シリアルモニターの出力からグラフを視覚化します。ヒット閾値は太鼓の最も重いヒットよりも低く、リセット閾値はロールヒットの間のトラフよりも大きくする必要があります。リセット値はまた、ヒット値よりも低くする必要があります。
   
   残りの3つの領域についてもプロセスを繰り返し、すべてに適合する最適なものを見つけます。

   ![ヒットとリセット値の設定](./images/tune_hit_reset.png)

2. サンプリング長
   
   最大の実行時間速度のために、`cache.h`ライブラリは2のべき乗の`SAMPLE_CACHE_LENGTH`ウィンドウサイズで動作するように最適化されています。つまり2、8、16、32などです。実用的には16がArduinoにとって最適な値ですが、少なくとも4000Hz以上の速度で入力をサンプリングするパワフルなマイクロコントローラを持っている場合は、よりスムーズな（つまり、ノイズが少ない）カーブのために値を32に変更することができます。

3. 感度
   
   すべての圧電センサが同じではなく、取り付けエラーにより、4つのセンサからキャプチャされる信号は大きく異なることがあります。感度値は、差異を正規化するための乗数です。以下の例では、右のドンエリアが他の3つよりもはるかに高い値を生成しているため、`sensitivity`を`{1.0, 1.0, 0.5, 1.0}`に調整して問題を解決できます。

   ![感度値の設定](./images/tune_sensitivities.png)

   センサの取り付けは非常に重要です。センサが木にしっかりと取り付けられ、適切な位置にあることを確認してください。

## 追加ノート

1. ブリッジ整流器の使用理由

   圧電センサの電圧を偏らせない場合、その出力電圧範囲は約-5Vから+5Vです。しかし、アナログ入力のADCは正の電圧値（ESP32の場合は0-3.3V、ATmega32U4の場合は0-5V）のみを受け付けます。負の電圧を受け取ると、単に0に切り捨てられます。
   
   通常の電子ドラムでは、入力エネルギーの半分を失っても、ヒットタイミングの計算には影響しませんので問題ありません。しかし、*太鼓*のドラムでは、特にATmega32U4のような遅いプロセッサを使用すると問題が発生することがあります。
   
   太鼓のドラムでは、4つの振動する部分がすべて繋がっているため、左のドンを叩くと、プロセッサは左のカツ、右のドン、右のカツからも信号を受信します。左のドンの圧電センサが最初に負の電圧を生成し、ADCによって切り捨てられると、約3〜4ミリ秒のわずかな「遅延」が発生し、プロセッサはこのヒットを誤って右のドン、左のカツ、または右のカツとして処理する可能性があります。どちらかが最高の正の値を送信した場合です。

   ブリッジ整流器を使用すると、すべての負の値が正の値に変換されます。言い換えれば、それは`abs()`関数のようなもので、負の電圧を失わないことを保証します。

   ![ブリッジ整流器の使用理由](./images/bridge_signal.png)

# Taiko Controller - アナログ入力モード（Beta）

ESP32-S2またはESP32-S3コントローラーを使用すると、キーボードエミュレーションの代わりに、ドラムコントローラーがゲームパッドとして機能し、その軸の値をゲームに送信できます（ゲームもアナログ入力をサポートしている必要があります）。この方法では、ゲームはヒットの異なる力のレベルを認識できます。

Arduino Micro/Leonardoボードを使用する場合は、[Arduino XInputライブラリ](https://github.com/dmadison/ArduinoXInput)を参照して、ゲームパッドを実装してください。

## 必要なもの

1. 自分のドラムを作るか、Taiko Force Lv.5を使用してください。詳細はメインブランチをチェックしてください。

2. `ESP32-S3-Analog/ESP32-S3-Analog.ino`をコントローラーにフラッシュします。

3. 以下の変更を加えたゲーム：

   - ゲームフォルダ内の`bnusio.dll`ファイルをバックアップし、`extra/`フォルダーこちらのファイルで置き換えてください。

     このファイルは[このフォーク](https://github.com/ShikyC/TaikoArcadeLoader/tree/Refactor)からコンパイルされており、必要に応じて自分でコンパイルすることができます。

     *この変更されたライブラリは特定のゲームバージョンでのみ機能します。ゲームが壊れた場合は、元のリポジトリをクローンして、対応する変更を加え、コンパイルしてください。*

   - ゲームフォルダ内の`gamecontrollerdb.txt`ファイルを開き、`#Windows`の下に次のエントリを追加します：

     `030052a8694800006948000000000000,Taiko Controller,-leftx:-a0,+leftx:+a0,-lefty:-a1,+lefty:+a1,-rightx:-a2,+rightx:+a2,-righty:-a3,+righty:+a3,platform:Windows,`

     これにより、ゲームはESP32コントローラーが「Taiko Controller」というゲームパッドであることを認識し、標準のSDL2ライブラリに軸をマップするため、ゲームがアナログ入力を認識できるようになります。

   - `config.toml`ファイルを開き、最後に次の行を追加します：

     ```
     [controller]
     analog = true
     ```

     `analog = true`で、すべてのキーボードドラム入力が無効になります。これはさらなるリファクタリングが必要ですが、一緒に機能させるために申し訳ありません。キーボード入力に戻したい場合は、`analog = false`に設定してください。

4. ゲームを起動して楽しんでください！

## オンライン信号ビジュアライザーツール

シリアルポートの通信でデバッグを行うのが不便で、最適な感度値を見つけるのが困難な場合、この[太鼓信号ビジュアライザー](https://shiky.me/taiko)を使用することができます。これは私が作成したシンプルなツールで、太鼓コントローラー（ESP32-Analog版のみ）の出力を表示します。

ボードをコンピュータに接続するだけ（USBポートを使用し、シリアルポートは使用しない）と、波形がグラフに表示されます。したがって、デバッグモードをオンにする必要もなく、`Serial.print()` コマンドを使用して感度を調整するための値を取得する必要もありません。

### 使い方

コントローラのアナログバージョンはゲームパッドとして動作し、ヒット力の値をゲームに左右のジョイスティックの軸値として送信します。内蔵の `Gamepad` APIを使用すると、値を直接読み取るのが非常に簡単です。他のゲームパッドからのツールの読み取りを防ぐために、コントローラは `Taiko Controller (Vendor: 4869 Product: 4869)` という名前でなければなりませんので、ファームウェアの `pID` と `vID` の値を変更しないでください。

![太鼓テストツール](./images/taiko_test.webp)