stack-chan

# PY32 I/O expanderの共有寿命

M5StackChanのサーボ電源とLED出力は同じPY32を使用する。従来はモジュール変数に実体を保存し続けており、片方の終了と共有I²Cの終了を結び付けられなかった。新しい取得関数は利用者ごとのleaseを返す。

```ts
const io = acquireSharedPY32IOExpander(options)
try {
  io.digitalWrite(pin, true)
} finally {
  io.close()
}
```

| 対象 | 契約 |
| --- | --- |
| Registry | 一つのボードのPY32を所有する。I/Oクラス、I²Cアドレス、ピン、速度などの設定が異なる共有要求は、別のハンドルを取得する前に拒否する |
| Lease | レジスター操作と終了を公開する。物理I/Oと他の利用者の解放権限は公開しない。close後のI/Oを拒否し、二度目以降のcloseは何もしない |
| 物理I²C | 最後のleaseが閉じたときだけ解放する。物理closeの途中や失敗後には再取得させず、ホストの再起動を復旧の境界とする |
| LED | effect timerを止め、出力を消してから自分のleaseを閉じる。サーボ電源側のleaseが残っていれば、I²Cを使い続けられる |
| サーボ電源 | 電源出力を下げてから自分のleaseを閉じる。LED側のleaseが残っていれば、その出力操作を継続できる |
| 構築失敗 | 取得後のレジスター設定に失敗した場合もleaseを解放する。サーボ電源の構築失敗では、ドライバーが先に取得した2軸とUARTも解放する |

LEDの消灯やサーボ電源の停止に失敗しても、leaseの解放は試みる。出力操作と解放の両方が失敗した場合は最初のエラーを保持する。物理I/Oのcloseは、失敗した場合も二重には呼ばない。GPIOの非整数・非有限値はレジスターを変更する前に拒否する。

レジスター操作の実装は `PY32Registers` にまとめ、直接所有する `PY32IOExpander` と共有leaseが同じ実装を使用する。共有leaseが内部の物理オブジェクトを利用者へ返す方式は採用していない。

XSでは起動後にボードのI/O providerを設定する。preload時の `globalThis` をモジュール変数へ保持すると、その後のproviderを参照できない場合をXS試験で検出した。そのためI²C providerと再試行用Timerは、取得処理の実行時に `globalThis` から解決する。registryも実行時に生成する。

初期化の再試行は、従来の最大25回・間隔50msを維持する。各失敗で取得済みI/Oを閉じるが、物理closeも失敗した場合は再試行を止める。`tryAcquireSharedPY32IOExpander` は最終失敗を一度だけ通知して `undefined` を返す。LED・サーボ電源でPY32が見つからない場合の任意機能としての扱いは維持した。ここから能力情報へ「利用不可」を伝える作業と、起動中の再試行を非同期・取消し可能にする作業は別途必要である。

従来の `getSharedPY32IOExpander` / `tryGetSharedPY32IOExpander` も残した。同じ旧入口からの取得は一つのlegacy leaseを共有し、そのcloseで解放する。新しいLEDとサーボ電源は独立したleaseを取得するため、legacy側のcloseではそれらのI²Cを切断しない。返り値はレジスター操作を提供するleaseであり、物理クラスへの型注釈や `instanceof PY32IOExpander` に依存するコードは移行が必要である。SDK全体の再設計に合わせてリリース影響は **major** とする。

Node試験では共有の100回の開始・終了、設定照合、終了中の再取得、初期化と解放の二重失敗、legacy入口、終了後のI/O拒否を確認する。XSの `py32-lifecycle` は実際のLEDとサーボ電源の実装を使用し、両方の終了順、LEDの遅延処理、複数のレジスター設定段階での失敗、任意ハードウェアの未検出、物理closeの失敗を確認する。

この変更はI²Cの所有と解放を扱う。複数の利用者が同じGPIOやLED出力を変更する場合の調停、能力情報、設定の正本、V1アプリの任意の直接参照まで解決した状態ではない。実機での電源投入・出力・I²Cの解放は未検証であり、偽I/Oとビルドの成功をその代用にはしない。