Chapter 23
落とし穴と設計指針 — 実際にハマるところ
この章がなぜ必要なのか——同じ失敗が繰り返されているから.
Matter の開発でハマる場所は、驚くほど共通している。 各章で個別に警告してきたものを、チェックリストとして 1 か所にまとめる。
設計レビューやコードレビューのときに、この章を横に置いて使ってほしい。
この章で使う既出の用語（定義は各リンク先）. Matter（01 章 3 節）、コミッショニング（01 章 3 節）、セキュリティ（01 章 2 節）、ネットワーク（01 章 3 節）、ACL（02 章 4 節）、Client（02 章 5 節）、Endpoint（02 章 2 節）、IPv6（02 章 1 節）、データモデル（02 章 1 節）、マルチキャスト（03 章 3 節）、Router（04 章 2 節）、Wi-Fi（04 章 9 節）、Ethernet（05 章 1 節）、クライアント分離（05 章 2 節）、必要（05 章 5 節）、SRP（06 章 2 節）、再送（06 章 3 節）、Fabric-Scoped（07 章 7 節）、FeatureMap（07 章 2 節）、ミレッド（07 章 6 節）、Identify（08 章 2 節）、UniqueID（08 章 1 節）、Fail-Safe（09 章 9 節）、パスコード（11 章 5 節）、改竄（11 章 1 節）、総当たり（11 章 1 節）、署名（11 章 2 節）、証明書（11 章 5 節）、CSA（12 章 3 節）、DAC（12 章 11 節）、DCL（12 章 11 節）、RAM（16 章 3 節）、ZAP（16 章 1 節）、Flash（17 章 1 節）、認証実績（17 章 1 節）、セキュアブート（18 章 5 節）、ロールバック（18 章 5 節）、
Reachable（19 章 2 節）、スレッドセーフティ違反（21 章 4 節）、VID（22 章 2 節）
1. 設計段階で決めるべきこと
決定が遅れると手戻りが大きいもの
| 項目 | いつ決めるか | 遅れるとどうなるか |
|---|---|---|
| ネットワーク（Wi-Fi / Thread） | 最初 | 基板からやり直し（05 章） |
| Flash / RAM の容量 | 最初 | OTA が載らない（17 章） |
| 証明書の調達方式 | 開発初期 | 量産に間に合わない（12 章） |
| VID の取得 | 開発初期 | 認証申請ができない（22 章） |
| セキュアストレージの有無 | SoC 選定時 | 鍵の保護ができない（11 章） |
| 対応 Fabric 数 | 設計時 | 不揮発メモリが足りない（14 章） |
| 仕様バージョン | 開発初期 | 認証で対象外になる（22 章） |
| Factory Data の書き込み方式 | 開発中期 | 量産ラインが組めない（17 章） |
| 対象エコシステム | 企画時 | 出荷後に「動かない」と発覚（20 章） |
「あとで考える」が許されるのは、アプリケーションロジックだけである. ハードウェアと認証に関わるものは、すべて最初に決める。
2. 分野別の落とし穴
ネットワーク（03〜06 章）
| 落とし穴 | 対処 |
|---|---|
| IPv6 が無効なルータ | ユーザー向けドキュメントで案内 |
| マルチキャストの遮断 | 検証は素直なフラットなネットワークで |
| ゲスト Wi-Fi のクライアント分離 | 同上 |
| Thread の Border Router がない | 箱に明記（22 章） |
| SRP 登録の失敗 | ot-ctl srp server service で確認 |
| SII/SAI を広告しない | 再送で電池が減る |
| 大きなペイロード | Thread の 127 バイトフレーム。分割して読む |
| メッセージカウンタの巻き戻し | 不揮発に保存する |
| 停電からの一斉復帰 | ランダム遅延を入れる |
データモデル（07〜10 章）
| 落とし穴 | 対処 |
|---|---|
| FeatureMap の過剰宣言 | 宣言したら必ず動かす |
| 必須クラスタの実装漏れ | Device Library でチェック |
| 単位の誤り | 温度 0.01 °C、明るさ 0〜254、色温度ミレッド、照度は対数 |
| Nullable の未対応 | センサー異常時に 0 を返さない |
Identify の未実装 | ユーザーが機器を特定できない |
SoftwareVersion の非単調 | OTA が壊れる |
UniqueID の重複 | 複数台登録で問題 |
| Client 側クラスタの忘れ | スイッチが何も制御できない |
| 報告トリガの呼び忘れ | 「読めば正しいが通知が来ない」 |
| ハードウェア → Matter の反映漏れ | 物理操作がアプリに反映されない |
*/*/* の多用 | Thread で失敗する |
| 独自クラスタへの依存 | 他社エコシステムで主要機能が使えない |
セキュリティ（11〜14 章）
| 落とし穴 | 対処 |
|---|---|
| 弱い乱数 | ハードウェア TRNG を使う。rand() 禁止 |
| DAC 秘密鍵の平文保存 | SE か暗号化領域 |
| 全個体で同じ passcode / discriminator / DAC | 製造時にランダム生成 |
| テスト証明書での量産 | ビルドを分け、CI でチェック |
| ACL の設定漏れ | 0x7E の主因 |
| Fabric-Scoped の実装ミス | 他 Fabric の設定を消す・見せる |
| Commissioning Window の閉じ忘れ | 誰でも参加できる状態が残る |
| ファクトリリセットの不完全性 | 前の持ち主の情報が残る |
| 試行回数の無制限 | パスコードの総当たりを許す |
| ログへの鍵の出力 | リリースビルドで消えることを確認 |
| デバッグポート開放のまま出荷 | 鍵が抜かれる |
| セキュアブート未設定 | 改竄ファームが動く |
実装（15〜19 章）
| 落とし穴 | 対処 |
|---|---|
activate.sh の忘れ | 毎回実行 |
SDK の master を追う | リリースタグで固定 |
| 生成コードを手で編集 | 再生成で消える |
.zap と生成物の不整合 | CI でチェック |
| 別スレッドから SDK API を呼ぶ | ScheduleWork かロック |
| コールバック内でのブロック | スタックが止まる |
| Flash 容量の不足（OTA） | 2 面分を確保 |
| OTA イメージの署名検証なし | 重大な脆弱性 |
| ロールバックなし | 更新失敗で文鎮化 |
| 電池寿命の机上計算のみ | 必ず実測 |
ブリッジの Reachable 未実装 | オフライン機器が操作可能に見える |
| 動的 Endpoint の上限不足 | 機器を追加できない |
認証・製品化（22 章）
| 落とし穴 | 対処 |
|---|---|
| 認証手続きの着手が遅い | 開発開始と同時に |
| Test Harness を直前に回す | 開発中から定期的に |
| VID 取得の遅れ | 最優先 |
| QR コードの印刷品質 | 実際に読み取り試験 |
| 手動コードの併記なし | QR が読めないと救済不能 |
| Border Router の要否を明記しない | ユーザーが設定できない |
| エコシステム別の確認漏れ | 出荷前に全社で実機確認 |
3. 設計指針
(1) 標準を最大限使う
独自クラスタ・独自属性は最後の手段である.
- まず標準クラスタで表現できないか
- 複数クラスタの組み合わせで表現できないか
- Endpoint を分けて表現できないか
- どうしても無理なら CSA に提案する
独自機能を持つ場合でも、基本機能は必ず標準クラスタで提供する。 「Matter 対応だが自社アプリでしか使えない」製品は、ユーザーの期待を裏切る。
(2) 嘘をつかない
できないことを「できる」と宣言しない.
- FeatureMap で宣言した機能は必ず動かす
- ブリッジで到達不能な機器は
Reachable = false- センサーが読めないときは null を返す（0 ではない）
- 実装していないクラスタは載せない
「宣言はあるが動かない」は、動かないより悪い。 ユーザーは操作して何も起きないことに混乱する。
(3) 双方向を忘れない
Matter → ハードウェアだけでなく、ハードウェア → Matter も実装する.
- 物理スイッチの操作を属性に反映する
- 反映したら報告をトリガする
- センサー値が変わったら通知する
片方向だけの実装は、「アプリと実機の表示が食い違う」という 最も基本的な不具合を生む。
(4) ブロックしない
コールバックの中で長時間処理をしない.
- コマンドは即座に受理して応答を返す
- 実際の動作は非同期に行う
- 完了したら属性を更新して通知する
カーテン、ドアロック、調理家電——動作に時間がかかる機器では必須である。
(5) 最初から複数 Fabric で考える
1 Fabric でしか動かない実装は、Matter の意味を半分捨てている.
- Fabric ごとに独立した状態を持つ
- Fabric-Scoped 属性を正しく実装する
SupportedFabrics分の不揮発メモリを確保する- 開発中から 3 Fabric 以上でテストする
(6) 電池機器は測る
机上計算だけで電池寿命を決めない.
- 電流計で実測する
- 通信頻度、再送、OTA を含めた実使用パターンで測る
- 低温・電池の内部抵抗上昇を考慮する
- ポーリング間隔が寿命を支配することを理解して設計する
(7) 出荷後を設計する
OTA が動かない製品を出してはいけない.
- Flash に 2 面分を確保する
- 署名検証とセキュアブート
- ロールバック
- 配信体制と脆弱性対応プロセス
Matter は仕様が更新され続ける。出荷後に追随できることが前提である。
(8) ユーザー体験まで考える
技術的に正しくても、使えなければ意味がない.
- QR コードは読みやすい大きさ・コントラストで
- 手動コードを併記する
Identifyで機器を特定できるように- Thread なら「Border Router が必要」を明記
- トラブルシューティングの手順を用意する
- コミッショニングの進捗と失敗理由を分かりやすく
4. 開発の進め方（推奨）
【企画】
対象エコシステム / ネットワーク / デバイスタイプを決める
CSA 会員登録・VID 申請を開始 ← 最優先
↓
【設計】
SoC 選定（Flash 2MB+、RAM 128KB+、TRNG、SE、認証実績）
仕様バージョンの決定、SDK タグの固定
対応 Fabric 数、メモリ設計
証明書の調達方式、Factory Data の書き込み方式
↓
【実装】
サンプルアプリから出発（ゼロから書かない）
ZAP で構成 → コールバック実装
Linux/Ethernet で先に動かす → 実機へ
Test Harness を定期実行 ← 早期から
↓
【検証】
マルチアドミン（3 Fabric 以上）
異常系（電源断、電波断、Fail-Safe）
停電からの一斉復帰
電池寿命の実測
OTA の全経路
↓
【認証】
CD 取得 → 認証テスト → 申請 → DCL 登録
各エコシステムでの実機確認
↓
【量産】
Factory Data の書き込み、個体の一意性検査
QR コードの印刷品質
↓
【出荷後】
OTA 配信、脆弱性対応、仕様更新への追随5. 「動かない」ときの初手 5 つ
6. まとめ
- ハードウェアと認証に関わる判断は、すべて最初に行う。 ネットワーク、Flash 容量、証明書、VID、仕様バージョン。
- 設計指針の 8 か条: **標準を使う / 嘘をつかない / 双方向 / ブロックしない / 複数 Fabric / 電池は測る / 出荷後を設計する / UX まで考える**
- 実装で最も多いバグ: **報告トリガの呼び忘れ、スレッドセーフティ違反、ACL の設定漏れ、 ハードウェア → Matter の反映漏れ。**
- Test Harness は開発中から回す。 直前では手遅れになる。
- 「動かない」ときは下の層から順に切り分ける。