# ORPHE INSOLE センサ仕様（SENSOR_VALUES）

`src/ORPHE-INSOLE.js` の `parseInsoleSensorValues()`（実装が正）から起こした、
SENSOR_VALUES notification のパケット仕様と単位系のリファレンスです。

## パケット共通部

- 1 notification = **104 バイト固定**（`byteLength !== 104` のパケットはパーサが `null` を返す）
- 多バイト値はすべて **ビッグエンディアン**（`DataView` の既定）

| バイト | 型 | 内容 |
|---|---|---|
| 0 | uint8 | header（50 / 55 / 56） |
| 1–2 | uint16 | `serial_number`（パケット連番。**uint16 なので 65535 の次は 0**。50 packet/s なら約22分で一周） |
| 3 | uint8 | デバイス時刻: 時 |
| 4 | uint8 | デバイス時刻: 分 |
| 5 | uint8 | デバイス時刻: 秒 |
| 6–7 | uint16 | デバイス時刻: ミリ秒 |

`timestamp` は「**ブラウザ側の今日の日付 + デバイス時刻**」で合成された epoch ms です。
デバイス時刻は `begin()` 時に `syncCoreTime()` で PC 時刻に同期されます。
既知の制約: 日付跨ぎ（深夜0時）でタイムスタンプが約24時間ジャンプします。

## header 別レイアウト

### header 50 — mode 1（quat + gyro + acc, 200Hz相当）

1 パケットに **4 サンプル**。サンプルストライド 21 バイト。

| オフセット（+21×n） | 型 | 内容 |
|---|---|---|
| 8,10,12,14 | int16 ×4 | quat w,x,y,z（Q14: /16384。単位クォータニオンのノルムは約1） |
| 16,18,20 | int16 ×3 | gyro x,y,z（/32768） |
| 22,24,26 | int16 ×3 | acc x,y,z（/32768） |
| 28 | uint8 | 次サンプルとの時間差 [ms]（mode 1 のみサンプル毎に加算される） |

### header 55 — mode 3（gyro + acc + press, 200Hz）

1 パケットに **4 サンプル**。サンプルストライド 24 バイト。**quat なし**（`gotQuat`/`gotEuler` は発火しない）。

| オフセット（+24×n） | 型 | 内容 |
|---|---|---|
| 8,10,12 | int16 ×3 | gyro x,y,z（/32768） |
| 14,16,18 | int16 ×3 | acc x,y,z（/32768） |
| 20,22,24,26,28,30 | **uint16 ×6** | press P0〜P5（ADC 生値） |

### header 56 — mode 4（quat + gyro + acc + press, 100Hz・既定）

1 パケットに **2 サンプル**。サンプルストライド 32 バイト。

| オフセット（+32×n） | 型 | 内容 |
|---|---|---|
| 8,10,12,14 | int16 ×4 | quat w,x,y,z（Q14: /16384。単位クォータニオンのノルムは約1） |
| 16,18,20 | int16 ×3 | gyro x,y,z（/32768） |
| 22,24,26 | int16 ×3 | acc x,y,z（/32768） |
| 28,30,32,34,36,38 | uint16 ×6 | press P0〜P5（ADC 生値） |

既知の制約: header 55/56 では**パケット内全サンプルが同一タイムスタンプ**になります
（200Hz でも 4 サンプルが同時刻）。サンプル順は `packet_number`（0 始まり）で判別してください。

## 単位系

| コールバック | 値 | 単位 |
|---|---|---|
| `gotAcc` / `gotGyro` | int16/32768 | 正規化値 -1..1 |
| `gotQuat` | int16/16384（Q14） | w,x,y,z。ノルムは量子化誤差を除き約1 |
| `gotConvertedAcc` | 正規化値 × accRange（既定 16） | G |
| `gotConvertedGyro` | raw int16 × センサー感度（既定レンジでは 0.07 deg/s/LSB） | deg/s |
| `gotEuler` | quaternion から変換 | **rad**（pitch/roll/yaw） |
| `gotPress` | uint16 そのまま | **ADC 生値（物理量ではない）** |

レンジ（accRange/gyroRange）は `getDeviceInformation()` の `range` から取得された値が
パースに反映されます。

`gotGyro` の正規化値（raw int16 / 32768）は後方互換のため維持されます。物理単位の
`gotConvertedGyro` は、LSM6DSOX の代表感度 8.75 / 17.5 / 35 / 70 mdps/LSB
（±250 / 500 / 1000 / 2000 dps）を使うため、正規化値にレンジを単純に掛けた値
（±2000 dps で 61.035 mdps/LSB）とは一致しません。加速度は `/32768 × 16` が
データシート感度 0.488 mg/LSB と一致するため従来どおりです。

FIFO 収録（`src/InsoleFifo.js`）の `gyro_*[dps]` も同じ 0.07 deg/s/LSB を使います。
Python 参照実装（insole_client）の理想 Q15 換算とは意図的に係数 1.14688 倍だけ異なります。

FIFO のパケット内フレーム間隔（`decodePacket()` が返す各サンプルの `t`）は、従来仮定していた
200Hz（5ms/frame）ではなく、実機の実測 IMU ODR（LSM6DSOXの標準 208Hz、`FRAME_INTERVAL_MS`≈
4.8077ms/frame）を使います。`packetToCsvRows()` の CSV timestamp 文字列だけは Python 参照実装と
のバイト互換のため、意図的に旧来の5ms間隔（`LEGACY_CSV_FRAME_INTERVAL_MS`）のまま据え置きます。
dt を計算する用途は `decodePacket()` の `t`（`FRAME_INTERVAL_MS` 基準）を使ってください。

Euler 角は `gotQuat` と同じ成分を単位ノルムへ正規化してから計算します。これにより、
量子化誤差や将来の転送スケール変更があっても Euler 角の振幅が圧縮されません。

### v1.2.0 以前に記録した CSV の救済

v1.2.0 以前の SDK で記録し、各行の quaternion ノルムが約0.5になっている CSV は救済できます。
各行で `n = sqrt(w² + x² + y² + z²)` を計算し、`w/n, x/n, y/n, z/n` に置き換えてください。
`n ≈ 0.5` のデータでは4成分を一律2倍することと同じです。既存の `euler_*` 列は使わず、
修正後の quaternion から再計算してください。`n = 0` または非有限値の行は無効データとして除外します。
詳しい確認項目は [QUATERNION_FIX_VALIDATION.md](./QUATERNION_FIX_VALIDATION.md) を参照してください。

### 圧力 ADC 生値の扱い（重要）

`press.values` は **無次元の ADC 生値**です。体重[kg]や荷重[N]ではありません。

- 個体差・装着差・温度で大きく変わるため、**機種間・個体間の生値比較は無意味**
- 物理量的な扱いが必要な場合はアプリ起動時に 2 点キャリブレーション
  （`OrpheInsoleUtils.PressureCalibrator`、無負荷時・全体重時）を行い 0..1 に正規化する
- uint16 上限（65535）に張り付いたチャネルは飽和 → `OrpheInsoleUtils.validatePress` の
  `SATURATED_CH` フラグで検出できる

## mount_position ビット定義

`getDeviceInformation()` が返す `device_information.mount_position`:

| bit | 0 | 1 |
|---|---|---|
| bit0 | LEFT（左足） | RIGHT（右足） |
| bit1 | 足底（インソール） | 足背（アッパー装着） |

**`insoles[0]` が左足とは限りません。** 必ず `mount_position` で判定してください。
`OrpheInsoleUtils.sideFromMountPosition(mount_position)` が
`{side: 'left'|'right', surface: 'plantar'|'dorsal'}` を返します。

## 圧力チャネルの物理配置とリマップ方針

チャネル番号（P0〜P5）と足底上の物理位置の対応は**モデルによって異なる場合があります**。

- SDK の既定レイアウトは `OrpheInsoleUtils.SENSOR_LAYOUT`（右足基準・実機採寸値）
- 左足は `mirrorForSide(SENSOR_LAYOUT, 'left')` で x 軸反転
- 配置が異なるモデルでは、**チャネル→位置のリマップ層を1枚挟み**、
  アプリロジックは位置ベース（前足部/踵部など）で書く
  （[PRESSURE_RECIPES.md](./ai/PRESSURE_RECIPES.md) レシピ4の REGION パターン）

## アドバタイズメント（接続前の gotStatus）

manufacturer data（company ID 0x0000）から `gotStatus` に渡される値:

| バイト | 内容 |
|---|---|
| 5 | model_type |
| 6 | mounting_position |
| 7 | human_activity_recognition |
| 14 | battery |
| 15–17 | version（major.minor.patch） |

## 免責事項

本仕様はリバースエンジニアリングではなく SDK 実装のドキュメント化です。
ファームウェア更新により変わる可能性があります。本ライブラリは医療機器ではありません。
