Chapter 08
クラスタとデバイスタイプ — 実際に使う部品のカタログ
この章がなぜ必要なのか——「何を実装すればよいか」は Device Library が決めている.
「調光できる電球を作る」と決めたとき、実装すべきクラスタは自分で選ぶものではない。 Device Library Specification が「Dimmable Light なら On/Off と Level Control は必須」と規定している。
必須のものを 1 つでも欠けば認証は通らない。 逆に、必須でないものを実装する自由はある。
この章は、よく使うクラスタとデバイスタイプの実務的なカタログである。 正確な定義は必ず仕様書で確認すること——ここは地図であって領土ではない。
この章で使う既出の用語（定義は各リンク先）. コミッショニング（01 章 3 節）、ネットワーク（01 章 3 節）、相互運用性（01 章 2 節）、ACL（02 章 4 節）、Administrator（02 章 5 節）、Attribute（02 章 2 節）、Client（02 章 5 節）、Cluster（02 章 2 節）、Command（02 章 2 節）、Endpoint（02 章 2 節）、Wi-Fi（04 章 9 節）、Group（06 章 4 節）、FeatureMap（07 章 2 節）、ミレッド（07 章 6 節）
1. ユーティリティクラスタ（Endpoint 0）
機器全体に関わるもの。Root Node に載る。
| ID | クラスタ | 役割 | 必須 |
|---|---|---|---|
0x001D | Descriptor | Endpoint の目次 | 全 Endpoint で必須 |
0x0028 | Basic Information | VID/PID、製品名、シリアル、ソフトウェアバージョン | 必須 |
0x001F | Access Control | ACL（14 章） | 必須 |
0x003E | Operational Credentials | 証明書・Fabric 管理（12 章〜14 章） | 必須 |
0x003F | Group Key Management | グループ鍵 | 必須 |
0x0030 | General Commissioning | コミッショニングの進行・Fail-Safe | 必須 |
0x0031 | Network Commissioning | Wi-Fi/Thread の設定 | ネットワーク種別に応じて |
0x0033 | General Diagnostics | 再起動理由、ネットワーク状態 | 必須 |
0x0034 | Software Diagnostics | ヒープ使用量など | 任意 |
0x0035 | Thread Network Diagnostics | Thread の統計 | Thread なら |
0x0036 | WiFi Network Diagnostics | Wi-Fi の統計 | Wi-Fi なら |
0x002A | OTA Software Update Requestor | 更新を受ける側（18 章） | OTA 対応なら |
0x0029 | OTA Software Update Provider | 更新を配る側 | Provider なら |
0x002B | Localization Configuration | 言語 | 任意 |
0x002C | Time Format Localization | 時刻表示 | 任意 |
0x002E | Power Source Configuration | 電源構成 | 任意 |
0x002F | Power Source | 電池残量など | 電池機器なら推奨 |
0x0038 | Time Synchronization | 時刻同期 | 任意 |
0x0046 | ICD Management | 間欠動作の管理（17 章） | ICD なら |
0x003C | Administrator Commissioning | Commissioning Window の開閉（14 章） | 必須 |
Basic Information の主な属性
| ID | 属性 | 内容 |
|---|---|---|
0x0001 | VendorName | メーカー名 |
0x0002 | VendorID | CSA 割り当ての VID |
0x0003 | ProductName | 製品名 |
0x0004 | ProductID | メーカーが決める PID |
0x0005 | NodeLabel | ユーザーが付ける名前（書き込み可） |
0x0006 | Location | 国コード |
0x0007 | HardwareVersion | ハードのバージョン |
0x0009 | SoftwareVersion | ソフトのバージョン（OTA の判定に使う） |
0x000F | SerialNumber | シリアル番号 |
0x0012 | UniqueID | 機器固有の識別子 |
0x0013 | CapabilityMinima | 対応する最小のサブスクリプション数など |
SoftwareVersionは単調増加の整数でなければならない. OTA では「Provider の版がこれより大きいか」で更新を判断する（18 章）。1.2.3のような文字列はSoftwareVersionStringの方で、 数値のSoftwareVersionとは別物である。両方を整合させること。
UniqueIDは個体ごとに違う値にすること. エコシステムが機器を追跡・再認識するのに使う。全個体同じにすると、 「同じ機器を 2 台登録できない」といった不具合が出る。
2. 汎用アプリケーションクラスタ
| ID | クラスタ | 用途 |
|---|---|---|
0x0003 | Identify | 「どれ？」を知らせる。点滅・音など |
0x0004 | Groups | グループへの参加 |
0x0006 | On/Off | ON / OFF |
0x0008 | Level Control | 明るさ・強さのレベル |
0x0300 | Color Control | 色（HS / XY / 色温度） |
0x0062 | Scenes Management | シーン（1.4 以降。旧 0x0005） |
0x001E | Binding | 機器どうしの直接連携（07 章） |
0x0045 | Boolean State | 単純な真偽値センサー（接点など） |
Identifyは軽視されがちだが必須級である. ユーザーが「10 個ある電球のうちどれを設定しているのか」を知る唯一の手段である。 多くのデバイスタイプで必須とされ、認証テストでも確認される。 実装は「LED を点滅させる」程度でよいが、必ず目に見える反応を返すこと。
On/Off (0x0006)
| 種別 | ID | 内容 |
|---|---|---|
| Attribute | 0x0000 | OnOff（bool、読み取り専用） |
| Attribute | 0x4003 | StartUpOnOff（電源投入時の状態） |
| Command | 0x00 | Off |
| Command | 0x01 | On |
| Command | 0x02 | Toggle |
| Command | 0x40 | OffWithEffect（フェードアウトなど） |
| Command | 0x42 | OnWithTimedOff（一定時間後に自動 OFF） |
Level Control (0x0008)
| 種別 | ID | 内容 |
|---|---|---|
| Attribute | 0x0000 | CurrentLevel（0〜254） |
| Attribute | 0x0002 / 0x0003 | MinLevel / MaxLevel |
| Attribute | 0x0011 | OnLevel |
| Command | 0x00 | MoveToLevel（レベル + 遷移時間） |
| Command | 0x01 | Move（連続的に増減） |
| Command | 0x02 | Step（一定量ずつ） |
| Command | 0x03 | Stop |
| Command | 0x04〜0x07 | 上記の WithOnOff 版 |
WithOnOffの意味. 「明るさを 0 にしたら、OnOff 属性も false にする」という連動を行う版。 通常版は OnOff を変えない。ユーザーがスライダーを 0 に下げたとき、電球が「消えた」ことになるべきか—— という UX の話が、そのままコマンドの選択に現れている。
Color Control (0x0300)
FeatureMap で対応方式を宣言する。
| ビット | 機能 | 内容 |
|---|---|---|
| 0 | HS | 色相・彩度 |
| 1 | EHUE | 拡張色相 |
| 2 | CL | 色ループ |
| 3 | XY | CIE xy 座標 |
| 4 | CT | 色温度（ミレッド） |
| 属性 | 内容 |
|---|---|
CurrentHue / CurrentSaturation | 0〜254 |
CurrentX / CurrentY | CIE xy（16 bit） |
ColorTemperatureMireds | ミレッド = 1,000,000 / K |
ColorMode | 現在どの方式で色が決まっているか |
色温度がミレッドである理由. ケルビンだと 2700K〜6500K の範囲で、 「低い側の 100K の差」と「高い側の 100K の差」の見た目の差が大きく違う。 ミレッド（逆数）にすると知覚的に線形に近くなり、スライダーの操作感がよくなる。
2700K → 370 mired、6500K → 154 mired。大小が逆転するので実装で混乱しやすい。
3. センサークラスタ
| ID | クラスタ | 主な属性 | 単位 |
|---|---|---|---|
0x0402 | Temperature Measurement | MeasuredValue | 0.01 °C |
0x0405 | Relative Humidity Measurement | MeasuredValue | 0.01 % |
0x0403 | Pressure Measurement | MeasuredValue | kPa |
0x0400 | Illuminance Measurement | MeasuredValue | 対数スケール |
0x0406 | Occupancy Sensing | Occupancy | ビットマップ |
0x0045 | Boolean State | StateValue | bool |
0x005B | Air Quality | AirQuality | enum |
0x005C | Smoke CO Alarm | 各種アラーム状態 | — |
Illuminance は対数である.
MeasuredValue = 10000 × log10(lux) + 1。 生の lux を入れると桁が違う値になる。仕様を必ず確認すること。センサー系はどれも Nullable である（07 章）。 測定できていないときは null を返す。0 を返してはいけない。
4. 主なデバイスタイプ
Device Library Specification が定義する。必須クラスタの組み合わせが本体である。
照明
| ID | デバイスタイプ | 必須クラスタ（概略） |
|---|---|---|
0x0100 | On/Off Light | Identify, Groups, On/Off |
0x0101 | Dimmable Light | + Level Control |
0x010C | Color Temperature Light | + Color Control (CT) |
0x010D | Extended Color Light | + Color Control (HS/XY/CT) |
電源・スイッチ
| ID | デバイスタイプ |
|---|---|
0x010A | On/Off Plug-in Unit |
0x010B | Dimmable Plug-in Unit |
0x0103 | On/Off Light Switch（Client 側） |
0x0104 | Dimmer Switch（Client 側） |
0x0105 | Color Dimmer Switch（Client 側） |
0x000F | Generic Switch（ボタン。イベントで通知） |
センサー
| ID | デバイスタイプ |
|---|---|
0x0015 | Contact Sensor |
0x0106 | Light Sensor |
0x0107 | Occupancy Sensor |
0x0302 | Temperature Sensor |
0x0307 | Humidity Sensor |
0x0305 | Pressure Sensor |
0x0303 | Pump（など、機器系） |
0x0076 | Smoke CO Alarm |
0x002C | Air Quality Sensor |
住宅設備
| ID | デバイスタイプ |
|---|---|
0x000A | Door Lock |
0x0202 | Window Covering |
0x0301 | Thermostat |
0x002B | Fan |
0x002D | Air Purifier |
0x0072 | Room Air Conditioner |
システム系
| ID | デバイスタイプ | 用途 |
|---|---|---|
0x0016 | Root Node | Endpoint 0 |
0x000E | Aggregator | ブリッジの親（19 章） |
0x0013 | Bridged Node | ブリッジされた機器（19 章） |
0x0011 | Power Source | 電源情報 |
0x0012 | OTA Requestor | |
0x0014 | OTA Provider |
Generic Switch (
0x000F) が「ボタン」の正解である. 壁スイッチやリモコンのボタンは、状態（ON/OFF）ではなく 「押された」というイベントを通知する。Switchクラスタ (0x003B) のInitialPress/ShortRelease/MultiPressComplete/LongPressなどのイベントで、 シングルクリック・ダブルクリック・長押しを区別できる。これを On/Off Light Switch（Client）と混同しないこと。前者は「イベントを上げる」、 後者は「他の機器にコマンドを送る」である。両方を実装することも多い。
5. Conformance（適合性）の読み方
Device Library の表には、各クラスタ・属性に適合性の記号が付く。
| 記号 | 意味 |
|---|---|
| M | Mandatory（必須） |
| O | Optional（任意） |
| P | Provisional（暫定。将来変わりうる） |
| D | Deprecated（非推奨） |
| X | Disallowed（禁止） |
[FEATURE] | その FeatureMap ビットが立っているなら必須 |
A, B | 条件付き（A または B のとき） |
Provisional (P) には手を出さないのが安全である. 仕様が固まっておらず、次のバージョンで変わる可能性がある。 認証テストの対象外でもあり、実装しても他社が対応していないことが多い。
6. 実装の進め方
1. 作りたい製品に最も近い Device Type を Device Library から選ぶ
↓
2. その必須クラスタ（M）をリストアップ
↓
3. Application Cluster Specification で各クラスタの必須属性・コマンドを確認
↓
4. FeatureMap で「どの機能を宣言するか」を決める
（宣言したら必ず動かす）
↓
5. ZAP で構成を作る（[16 章](16_ZAPとクラスタ実装.md)）
↓
6. 生成コードのコールバックを実装
↓
7. Device Library に照らして実装漏れをチェックStep 1 で「近いものがない」場合が難所である. 標準に存在しないカテゴリの製品なら、
- 最も近いデバイスタイプで基本機能を提供する
- 追加機能は独自クラスタで補う（相互運用性は諦める）
- CSA に新デバイスタイプを提案する
という選択になる。3 番目は時間がかかるが、 市場を作る立場なら検討する価値がある。実際、1.2 以降の追加は こうした提案の積み重ねである。
7. 落とし穴
| 落とし穴 | 内容 |
|---|---|
| 必須クラスタの実装漏れ | 認証で落ちる。Device Library でチェック |
| FeatureMap の過剰宣言 | 宣言したが動かない機能は確実に落ちる |
| 単位の誤り | 温度 0.01 °C、明るさ 0〜254、色温度ミレッド、照度は対数 |
| Nullable の未対応 | センサー異常時に 0 を返してしまう |
| Identify の未実装 | ユーザーが機器を特定できない |
SoftwareVersion の非単調 | OTA が正しく動かない |
UniqueID の重複 | 複数台登録で問題が出る |
| Client 側クラスタの忘れ | スイッチが何も制御できない |
| 独自クラスタへの依存 | 他社エコシステムで主要機能が使えない |
8. まとめ
- Endpoint 0 にはユーティリティクラスタ（Basic Information、Access Control、 Operational Credentials、General/Network Commissioning など）が載る。
- アプリケーションクラスタの主役は On/Off・Level Control・Color Control、 そしてセンサー系。単位が独特なので必ず仕様を確認する。
- Device Type が必須クラスタを決める。自分で選ぶものではない。 Device Library Specification が最終的なチェックリストになる。
- Conformance の M / O / P を読み分ける。Provisional には手を出さない。
- ボタンは
Generic Switch+Switchクラスタのイベントで表現する。 - 実装の順序は「Device Type を決める → 必須を洗い出す → FeatureMap を決める → ZAP」。