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

接続・データ受信のトラブルを上から順に切り分けるためのガイドです。

## 0. まず debug ログを有効にする

```javascript
insole.debug = true;  // 接続手順の詳細ログ（onConnect 等の既定ログ含む）が console に出る
```

v1.2.0 から、既定の進行ログ（onConnect / onStartNotify 等）は `debug = true` のときだけ出力されます。
「ログが出なくなった」と感じたらまずこのフラグを確認してください。
エラーは debug に関係なく常時 console.error に出ます（`error.code` で種別判定できます:
`NO_DEVICE` / `ALREADY_DISCONNECTED` / `CONNECT_TIMEOUT` / `INVALID_MODE`）。
接続状態は `insole.connectionState`（disconnected / connecting / connected / reconnecting）で取得できます。

## 1. デバイス選択ダイアログ（chooser）に INSOLE が出ない

- **INSOLE の電池残量を確認**。バッテリー切れが最多原因。充電して数分待つ
- 他のタブ・他のPC・スマホアプリが**既に接続していないか**（BLE は1接続のみ）
- ページが **HTTPS または http://localhost** で配信されているか（`file://` や http の LAN IP では Web Bluetooth 自体が使えない）
- OS の Bluetooth が ON か。macOS はシステム設定で Chrome に Bluetooth 権限が必要
- それでも出ない場合は `chrome://bluetooth-internals` でデバイスがスキャンできているか確認

## 2. ブラウザが対応していない

| ブラウザ | Web Bluetooth |
|---|---|
| Chrome（デスクトップ / Android） | ✅ |
| Edge / Opera | ✅ |
| **Firefox** | ❌ 非対応 |
| **Safari（macOS / iOS 全ブラウザ含む）** | ❌ 非対応（iOS は Chrome でも不可） |

`navigator.bluetooth` が `undefined` の環境では接続できません。アプリ側でフィーチャー検出して案内を出してください。

```javascript
if (!navigator.bluetooth) {
  alert('このブラウザは Web Bluetooth 非対応です。Chrome / Edge をご利用ください。');
}
```

## 3. 接続はされるがデータが来ない

- `insole.setup()` を `begin()` の**前に**呼んだか（最頻の実装ミス）
- `gotData` をオーバーライドしていないか。**`gotData` を上書きすると他のすべての got\* コールバックが停止**します（TERMINALモード）。デバッグ後は必ず外す
- streaming mode と受信データの対応を確認: mode 3 では `gotQuat`/`gotEuler` は来ない。mode 1 では `gotPress` は来ない
- `gotEuler` だけ来ない場合: quaternion.js（CDN からの実行時ロード）が読み込めていない可能性。オフライン環境では発生する

## 3b. Step Analysis だけ来ない（GAIT_NO_NOTIFICATIONS）

Toolkit の Step 系プロファイルは、購読成功後に有効パケットの到着まで検証します。
Raw（SENSOR_VALUES）は正常なのに `GAIT_NO_NOTIFICATIONS` で失敗する場合:

- **デバイスFWが STEP_ANALYSIS を publish していない可能性**があります。
  実測では **FW 1.0.1 の個体**が、購読成功・Raw 50通知/秒の正常受信下でも
  STEP_ANALYSIS を transport レベルで0件のまま送信しませんでした（FW更新を検討してください）
- FWバージョンは `await insole.getFirmwareVersion()` で確認できます（Toolkit 接続中は
  ヘッダの FW バッジ / 歯車モーダルの Firmware 行にも表示）。標準BLE DIS(0x180A) 未実装の
  FW では advertisement 由来（`insole.lastStatus.version`）が使われ、それも無い環境では
  null（バッジ非表示）になります
- advertisement からバージョンを読むには `watchAdvertisements()` 対応ブラウザが必要です。
  未対応の Chrome では `--enable-features=WebBluetoothNewPermissionsBackend`
  `--enable-experimental-web-platform-features` を付けて起動すると
  `getDevices()` + `watchAdvertisements()` が有効になります
- 切り分けには `session.snapshot().gaitDiagnostics` の `transportNotifications` を確認
  （0のまま = FW側が送っていない / 増えるが valid 0 = デコード問題）

### 3c. Step は来るが「歩いたのに row にならない歩」が多い

通知は来ているのに `onGait` の歩数が体感より少ない場合は、
`session.snapshot().gaitDiagnostics.stepLoss` で歩単位の損失を確認できます:

| カウンタ | 意味 | 疑う場所 |
|---|---|---|
| `completedSteps` | 3点セットが揃って row になった歩 | — |
| `incompleteSteps` + `missingParts` | 一部のサブパケットだけ届いた歩（欠けた種類の内訳つき） | BLE欠損（ホスト負荷・距離・干渉） |
| `gapSteps` | FWが採番したのに1パケットも届かなかった歩 | FW未送信 or 全パケット欠損 |
| `jumps` | 採番リセット/大ジャンプ | `resetAnalysisLogs()`・FW再起動（欠損ではない） |

1歩ごとの通知は `gait.onStepLoss`（Toolkitでは `gait: { onStepLoss }`）でも受け取れます。
実測（両足歩行・94歩区間）では 38〜44% の歩が row にならないケースがあり、
この内訳での切り分けを目的に追加されました。

## 4. 記憶したデバイスに自動接続しない（毎回ダイアログが出る）

- デバイス記憶による無ダイアログ再接続には `navigator.bluetooth.getDevices()` が必要（Chrome では既定で有効）。無効な環境では選択ダイアログへ自動フォールバックします
- 別の INSOLE に切り替えたいときは `insole.selectBluetoothDevice()`（強制ダイアログ）または `insole.forgetLastBluetoothDevice()`

## 5. 自動再接続が走らない

- `begin()` に `{ autoReconnect: true }` を渡したか
- `insole.stop()` / `insole.reset()` は**手動切断の意思表示**とみなし自動再接続も解除します。切断検知だけしたい場合は `onDisconnect` を使う
- 再接続の進行は `onReconnectAttempt` / `onReconnectSuccess` / `onReconnectFailed` で観測できます
- 間隔・回数は `begin()` の `reconnectIntervalMs`（既定 3000）/ `reconnectMaxAttempts`（既定 120）で調整

## 6. lostData が頻発する

- 数件/分程度のパケット欠損は BLE では正常範囲
- stopNotify → startNotify / streaming mode 切替の直後に数件カウントされるのは仕様（serial 番号が飛ぶため）
- 継続的に大量発生する場合: 距離・遮蔽物・2.4GHz 干渉（Wi-Fi/USB3）を疑う。`gotBLEFrequency` で実測レートも確認
- 検証には `examples/device-test/` の実機チェックページが使えます

## 7. タブが固まる・チャートが重い

100Hz のコールバック内で DOM 更新や `chart.update()` をしていないか確認。
データはバッファに溜め、描画は `requestAnimationFrame` で 30fps に間引きます
（[CLAUDE.md](../CLAUDE.md) の Pattern 5、実装例は `examples/VISUALIZE`）。

## 8. 実機がない・実機なしでデバッグしたい

`OrpheInsoleSimulator`（`src/InsoleSimulator.js`）が `OrpheInsole` と同じコールバック面で
合成データ（歩行・静止・重心揺れ）を再生します。README の「実機がない場合」を参照。

---

解決しない場合は [GitHub Issues](https://github.com/Orphe-OSS/ORPHE-INSOLE.js/issues) へ。
`insole.debug = true` のログと、ブラウザ / OS / INSOLE の FW バージョンを添えてください。

## 9. INSOLE 1.5（INS2）が繋がらない・欠損する

- **チューザに `INS2` が出るのに接続に失敗する（`INSOLE15_CLIENT_UNAVAILABLE`）**: コア SDK は INS2 を選ぶと
  自身の URL と同じディレクトリから `Insole15Client.js` を遅延ロードする。SDK を `type="module"` やインライン評価で
  読み込んでいて URL が取れない場合、または配信先に `Insole15Client(.min).js` を置いていない場合に失敗する。
  `<script src=".../src/Insole15Client.js"></script>` を `ORPHE-INSOLE.js` の後に明示して読み込む。
- **`NotFoundError: No Services matching UUID 01a9d6b5-…`**: 古い SDK（v1.3.4 以前）で INS2 を選んだとき。
  1.5 対応版へ更新する。
- **接続はできるが `press.values` が 590 前後で固定**: 正常。1.5 の圧力は mV × 10 で、無負荷が約 59 mV（= 590）。
  製品版の ADC 生値とは由来が違うので、固定しきい値は見直す（相対しきい値・自動ベースラインは使える）。
- **2 台同時で片方だけ欠損する**: `insoles[i].insole15Diagnostics()` の `rttMs.p90` を見る。get_window 1 回の往復が
  100 ms を超え続けると 100 ms 窓に追従できず、FW キャッシュ（約 1.7 秒）を追い越した分が `tooOld` / `skippedSamples`
  として失われる（`lostData` も呼ばれる）。描画の重いページ（3D・高頻度 chart）やホストの Bluetooth 負荷で RTT が
  伸びる。軽いページ（fifo-guide など）で収録する、片足ずつ収録する、`gotBLEFrequency` の実効レートが 200 Hz に
  張り付いているか見る。実測: 軽いページで両足 6 分間 missing 0（RTT 30〜90 ms）、重いページで片側 25〜40% 欠損（RTT 123 ms）。
- **動きが画面に出るまで遅い・速く動かすと止まって見える**: 1.5 はプル型で、データは 100 ms 窓単位（10 Hz）で届く。
  1 台では窓の遅れ 40〜60 ms（製品版 20〜40 ms）に描画が乗る。SDK は既定で窓内のパケットを 10 ms 間隔に
  並べ直して流す（`pacing: 'smooth'`）ので、100 ms ごとの飛び飛びにはならない。それでも 1 秒前後遅れるなら
  `insoles[i].insole15Diagnostics().lagMs.last`（Toolkit の設定モーダルの状態表示 `lag x.x s`）を見る。往復（RTT）が
  100 ms に近いリンク（2 台同時の先に接続した側、実測 90〜120 ms）ではループが追いつけず、遅れが FW キャッシュ
  上限（約 1.7 秒）近くまで溜まる（実測 1.1 秒）。表示用途なら `begin({ insole15: { maxLagMs: 300 } })` で最新の窓へ
  飛ばす（exhibition が指定。飛ばした分は `lagSkips` / `lostData` に欠損として出るので収録では使わない）。
  片足だけなら RTT 30 ms で遅れは溜まらない。
- **Step Analysis が `INSOLE15_GAIT_UNSUPPORTED`**: FW が `get_gait_live` のライブ解析に未対応（0.1.7 未満）。FW 更新。
- **FIFO を選んだのに Realtime になる**: 仕様。1.5 に FIFO は無く、Toolkit が Realtime へ退避する
  （診断 `insole15-fifo-unavailable`）。Realtime 自体がプル型でリンクが追従できている限りロスレス。
- **`setDataStreamingMode` / `read` / `write` / `getDateTime` が効かない・`INSOLE15_UNSUPPORTED`**: 仕様。
  1.5 は常に全データ 200 Hz。保守系 RPC は公開クライアントに含めていない。
