ZigBee Light Link フレームの生成と復号化

この例では、Communications Toolbox™ を使用して、ZigBee® Light Link アプリケーションプロファイル [1] のフレームを生成および復号化する方法を説明します。

背景

ZigBee 規格 [2] は、低速無線パーソナルエリアネットワーク (LR-WPAN) のネットワーク (NET または NWK) レイヤーとアプリケーション (APP または APL) レイヤーを規定します。この NET レイヤーおよび APP レイヤーの仕様は、IEEE® 802.15.4™ [3] の PHY 仕様および MAC 仕様に基づいて作成されています。ZigBee デバイスは、ホームオートメーションやセンサーネットワーキングに使用例があり、Internet of Things (IoT) の流行にも密接に関連しています。

ZigBee アプリケーション層は、(i) Application Support Sublayer (APS)、(ii) ZigBee Cluster Library (ZCL) という複数の下位層で構成されます。

APS および ZCL "ヘッダー" はすべてのアプリケーションプロファイルと ZigBee クラスターに共通の形式 (それぞれ、[2] の Clause 2.2.5 および [4] の Clause 2.4 を参照) に従います。ZCL "ペイロード" は、一部のクラスターのみに使用され、クラスター固有の形式に従います。一般的な APS および ZCL ヘッダーの生成と復号化は、ZigBee ホームオートメーションフレームの生成と復号化の例で説明しています。この例では、ZigBee light link ZCL ペイロードのクラスター特有の生成と復号化を説明します。

クラスターとコマンド

light link アプリケーションプロファイル [1] で指定した 7 個のクラスターのうち、この例では次のクラスターのフレームを生成および復号化します。

Identify クラスター: このクラスターは、デバイスを識別モードに設定します (ライトの点滅など)。この例では、"Identify コマンド" ([4] の Clause 3.5 で説明) のフレームの生成と復号化を説明します。
Color control クラスター: このクラスターは、ライティングデバイスの色を変更します。この例では、"Move to Color コマンド" ([4] の Clause 5.2 で説明) のフレームの生成と復号化を説明します。
Level control クラスター: このクラスターはデバイスのレベルを変更します (電球の輝度、ドアの閉まり具合、またはヒーターの強さなど)。この例では、"Move to Level コマンド" ([4] の Clause 3.10 で説明) のフレームの生成と復号化を説明します。
Scenes クラスター: この Scenes クラスターは、シーン (すなわち、同じデバイスの他のクラスターの保存済み属性値のセット) の設定と呼び出しを行います。この例では、"View Scene コマンド" ([4] の Clause 3.7 で説明) のフレームの生成と復号化を説明します。
Group クラスター: このクラスターは、グループの作成や削除、グループメンバーシップの発見などによってデバイスのグループを管理します。この例では、"Add group コマンド" ([4] の Clause 3.6 で説明) のフレームの生成と復号化を説明します。

説明したコマンドに加えて、この例では上述の 5 つのクラスターのすべてのコマンドについてフレームの生成と復号化の実装を提供します (完全なリストについては、その他の調査を参照してください)。

Identify クラスターの ZCL ペイロードの生成と復号化

zigbee.IdentifyFrameConfig 構成オブジェクトは、Identify クラスターの ZCL ペイロードの生成と復号化の両方で使用されます。このようなオブジェクトは、Identify クラスターのペイロードと適用可能なすべてのプロパティを表します。関数 zigbee.IdentifyFrameGenerator は、Identify クラスターのペイロードを表す zigbee.IdentifyFrameConfig オブジェクトを受け入れ、生成されたペイロードをバイト単位で出力します。次のコードは、デバイスに 4 秒間の識別を求めるコマンドの ZCL ペイロードを作成します。

% Creation of configuration object for Identify cluster
identifyConfigTx = zigbee.IdentifyFrameConfig( ...
    'CommandType','Identify', ...
    'IdentifyTime',4);

% Frame generation (ZCL payload) for Identify cluster
identifyPayload = zigbee.IdentifyFrameGenerator(identifyConfigTx);

関数 zigbee.IdentifyFrameDecoder は、コマンド名とバイト単位の Identify クラスターのペイロードを受け入れ、Identify クラスターのペイロードを表す zigbee.IdentifyFrameConfig オブジェクトを出力します。コマンド名は、ZCL ヘッダーの復号化から取得します。ZigBee ホームオートメーションフレームの生成と復号化の例にある「ホームオートメーション ZigBee 無線機の ZCL ヘッダーの復号化」の節を参照してください。

identifyConfigRx = zigbee.IdentifyFrameDecoder('Identify',identifyPayload)

identifyConfigRx = 

  IdentifyFrameConfig with properties:

     CommandType: 'Identify'
    IdentifyTime: 4

次のコードは、受信フレームで指定された識別の効果を示す "ソフトウェア電球" を視覚化します。

bulb = plotBulb('white');
zigbeeIdentifyBulb(bulb, identifyConfigRx.IdentifyTime);
close(bulb);

Color Control クラスターの ZCL ペイロードの生成と復号化

zigbee.ColorControlFrameConfig 構成オブジェクトは、color control クラスターの ZCL ペイロードの生成と復号化の両方で使用されます。このようなオブジェクトは、color control クラスターのペイロードと適用可能なすべてのプロパティを表します。関数 zigbee.ColorControlFrameGenerator は、color control クラスターのペイロードを表す zigbee.ColorControlFrameConfig オブジェクトを受け入れ、生成されたペイロードをバイト単位で出力します。次のコードでは、50 デシ秒 (5 秒) 以内に現在の色 (赤) を別の値 (緑) に徐々に変えるようライティングデバイスに指示する color control クラスターのペイロードを生成します。色は、国際照明委員会 (CIE) によって確立された CIE 1931 色空間 [5] による "x"、"y" の値を使用して記述されます。

bulb = plotBulb('red');

% Creation of configuration object for color control cluster
colorCtrlConfigTx = zigbee.ColorControlFrameConfig( ...
    'CommandType','Move to Color', ...
    'ColorX',16384, ...
    'ColorY',39322, ...
    'Time',50); % Units of deciseconds

% Frame generation (ZCL payload) for color control cluster
colorControlPayload = zigbee.ColorControlFrameGenerator(colorCtrlConfigTx);

関数 zigbee.ColorControlFrameDecoder は、コマンド名とバイト単位の color control クラスターのペイロードを受け入れ、color control クラスターのペイロードを表す zigbee.ColorControlFrameConfig オブジェクトを出力します。コマンド名は、ZCL ヘッダーの復号化から取得します。ZigBee ホームオートメーションフレームの生成と復号化の例にある「ホームオートメーション ZigBee 無線機の ZCL ヘッダーの復号化」の節を参照してください。

colorCtrlConfigRx = zigbee.ColorControlFrameDecoder( ...
    'Move to Color',colorControlPayload)

colorCtrlConfigRx = 

  ColorControlFrameConfig with properties:

    CommandType: 'Move to Color'
         ColorX: 16384
         ColorY: 39322
           Time: 50

次のコマンドは、"ソフトウェア電球" を使用して受信フレームで指定されたカラーコントロールの効果を視覚化します。具体的には、電球の色が赤から緑に 5 秒以内に徐々に変化します。

zigbeeMoveBulbColor( ...
    bulb, ...
    colorCtrlConfigRx.ColorX, ...
    colorCtrlConfigRx.ColorY, ...
    colorCtrlConfigRx.Time);

次に、同じ効果が別の色軌跡で生じます (緑から紫)。

colorCtrlConfigTx2 = zigbee.ColorControlFrameConfig( ...
    'CommandType','Move to Color', ...
    'ColorX',19661, ...
    'ColorY',6554, ...
    'Time',50);
colorControlPayload2 = zigbee.ColorControlFrameGenerator( ...
    colorCtrlConfigTx2);
colorCtrlConfigRx2 = zigbee.ColorControlFrameDecoder( ...
    'Move to Color',colorControlPayload2);
zigbeeMoveBulbColor( ...
    bulb, ...
    colorCtrlConfigRx2.ColorX, ...
    colorCtrlConfigRx2.ColorY, ...
    colorCtrlConfigRx2.Time);

pause(1.5);

Level Control クラスターの ZCL ペイロードの生成と復号化

zigbee.LevelControlFrameConfig 構成オブジェクトは、level control クラスターの ZCL ペイロードの生成と復号化の両方で使用されます。このようなオブジェクトは、level control クラスターのペイロードと適用可能なすべてのプロパティを表します。関数 zigbee.LevelControlFrameGenerator は、level control クラスターのペイロードを表す zigbee.LevelControlFrameConfig オブジェクトを受け入れ、生成されたペイロードをバイト単位で出力します。次のコードでは、現在のレベルを指定した値に変えるようデバイスに指示する level control クラスターのペイロードを生成します。

% Creation of level control cluster configuration object
levelCtrlConfigTx = zigbee.LevelControlFrameConfig( ...
    'CommandType','Move to Level', ...
    'Level',20, ...
    'TransitionTime',1);

% Level control cluster frame generation (ZCL payload)
levelControlPayload = zigbee.LevelControlFrameGenerator(levelCtrlConfigTx);

関数 zigbee.LevelControlFrameDecoder は、コマンド名とバイト単位の level control クラスターのペイロードを受け入れ、level control クラスターのペイロードを表す zigbee.LevelControlFrameConfig オブジェクトを出力します。コマンド名は、ZCL ヘッダーの復号化から取得します。ZigBee ホームオートメーションフレームの生成と復号化の例にある「ホームオートメーション ZigBee 無線機の ZCL ヘッダーの復号化」の節を参照してください。

levelCtrlConfigRx = zigbee.LevelControlFrameDecoder( ...
    'Move to Level',levelControlPayload)

levelCtrlConfigRx = 

  LevelControlFrameConfig with properties:

       CommandType: 'Move to Level'
             Level: 20
    TransitionTime: 1

level control クラスターは光の強度を調節するために使用できます。一方、color control クラスターは、ライティングデバイスの色の輝度のコントロールを level control クラスターに任せます。次の例では、受信した level control フレームを使用して電球の輝度レベルを増加させます。

zigbeeMoveBulbColor( ...
    bulb, ...
    colorCtrlConfigRx2.ColorX, ...
    colorCtrlConfigRx2.ColorY,1, ...
    levelCtrlConfigRx.Level);

Scenes クラスターの ZCL ペイロードの生成と復号化

zigbee.SceneFrameConfig 構成オブジェクトは、Scenes クラスターの ZCL ペイロードの生成と復号化の両方で使用されます。このようなオブジェクトは、Scenes クラスターのペイロードと適用可能なすべてのプロパティを表します。関数 zigbee.ScenesFrameGenerator は、Scenes クラスターのペイロードを表す zigbee.ScenesFrameConfig オブジェクトを受け入れ、生成されたペイロードをバイト単位で出力します。次のコードは、デバイスにシーンを表す別のフレーム (View Scene Response) の送信を要求する Scenes クラスターのペイロードを生成します。

% Creation of Scenes cluster configuration object
scenesConfigTx = zigbee.ScenesFrameConfig('CommandType','View Scene', ...
    'GroupID','1234','SceneID','56');

% Scenes cluster frame generation (ZCL payload)
scenesPayload = zigbee.ScenesFrameGenerator(scenesConfigTx);

関数 zigbee.SceneFrameDecoder は、コマンド名とバイト単位の Scenes クラスターのペイロードを受け入れ、Scenes クラスターのペイロードを表す zigbee.SceneFrameConfig オブジェクトを出力します。コマンド名は、ZCL ヘッダーの復号化から取得します。ZigBee ホームオートメーションフレームの生成と復号化の例にある「ホームオートメーション ZigBee 無線機の ZCL ヘッダーの復号化」の節を参照してください。

scenesConfigRx = zigbee.ScenesFrameDecoder('View Scene',scenesPayload)

scenesConfigRx = 

  ScenesFrameConfig with properties:

    CommandType: 'View Scene'
        GroupID: '1234'
        SceneID: '56'

Groups クラスターの ZCL ペイロードの生成と復号化

zigbee.GroupFrameConfig 構成オブジェクトは、Groups クラスターの ZCL ペイロードの生成と復号化の両方で使用されます。このようなオブジェクトは、Groups クラスターのペイロードと適用可能なすべてのプロパティを表します。関数 zigbee.GroupsFrameGenerator は、Groups クラスターのペイロードを表す zigbee.GroupsFrameConfig オブジェクトを受け入れ、生成されたペイロードをバイト単位で出力します。次のコードでは、指定したグループを Group テーブルに追加するようデバイスに指示する Groups クラスターのペイロードを生成します。

% Creation of Groups cluster configuration object
groupsConfigTx = zigbee.GroupsFrameConfig('CommandType','Add group', ...
    'GroupName','Dining Hall','GroupID','1234');

% Groups cluster frame generation (ZCL payload)
groupsPayload = zigbee.GroupsFrameGenerator(groupsConfigTx);

関数 zigbee.GroupFrameDecoder は、コマンド名とバイト単位の Groups クラスターのペイロードを受け入れ、Groups クラスターのペイロードを表す zigbee.GroupFrameConfig オブジェクトを出力します。コマンド名は、ZCL ヘッダーの復号化から取得します。ZigBee ホームオートメーションフレームの生成と復号化の例にある「ホームオートメーション ZigBee 無線機の ZCL ヘッダーの復号化」の節を参照してください。

groupsConfigRx = zigbee.GroupsFrameDecoder('Add group',groupsPayload)

groupsConfigRx = 

  GroupsFrameConfig with properties:

    CommandType: 'Add group'
        GroupID: '1234'
      GroupName: 'Dining Hall'

Wireshark 復号化

生成したフレームは PCAP 形式に変換することができます。その後、Wireshark で解析および可視化することで [6]、生成および復号化した ZigBee データフレームが規格に準拠しているかどうかをさらに詳しく検証することができます。

PCAP ファイルでは、ZCL ペイロードがすべての他の層およびサブ層 (MAC、NET、APS、ZCL) のヘッダーと共に封入される必要があります。次のコマンドは、Wireshark で読み込み可能な、この例で生成された ZCL ペイロードの PCAP ファイルを生成します。

% ZLL profile ID
zllProfileID = zigbee.profileID('Light Link');

payloadsWithInfo(1) = struct( ...
    'Payload',identifyPayload, ...
    'ProfileID',zllProfileID, ...
    'ClusterSpecific',true, ...
    'ClusterID',zigbee.clusterID('Identify'), ...
    'CommandType','Identify', ...
    'Direction','Uplink');
payloadsWithInfo(2) = struct( ...
    'Payload',colorControlPayload, ...
    'ProfileID',zllProfileID, ...
    'ClusterSpecific',true, ...
    'ClusterID',zigbee.clusterID('Color Control'), ...
    'CommandType','Move to Color', ...
    'Direction','Uplink');
payloadsWithInfo(3) = struct( ...
    'Payload',levelControlPayload, ...
    'ProfileID',zllProfileID, ...
    'ClusterSpecific',true, ...
    'ClusterID',zigbee.clusterID('Level Control'), ...
    'CommandType','Move to Level', ...
    'Direction','Uplink');
payloadsWithInfo(4) = struct( ...
    'Payload',scenesPayload, ...
    'ProfileID',zllProfileID, ...
    'ClusterSpecific',true, ...
    'ClusterID',zigbee.clusterID('Scenes'), ...
    'CommandType','View Scene', ...
    'Direction','Uplink');
payloadsWithInfo(5) = struct( ...
    'Payload',groupsPayload, ...
    'ProfileID',zllProfileID, ...
    'ClusterSpecific',true, ...
    'ClusterID',zigbee.clusterID('Groups'), ...
    'CommandType','Add group', ...
    'Direction','Uplink');

% Add headers from other layers/sublayers:
MPDUs = zigbeeAddProtocolHeaders(payloadsWithInfo);

% Export MPDUs to a PCAP format
zigbeeExportToPcap(MPDUs,'zigbeeLightLink.pcap');

% Open PCAP file with Wireshark

その他の調査

この例では、ドキュメンテーションにない以下のユーティリティを使用します。ドキュメンテーションにないユーティリティの API と機能は、将来変更される可能性があります。ユーティリティのソースコードを表示するには、関数 edit を使用します。

zigbee.APSFrameConfig, zigbee.APSFrameGenerator, zigbee.APSFrameDecoder
zigbee.ZCLFrameConfig, zigbee.ZCLFrameGenerator, zigbee.ZCLFrameDecoder
zigbee.IdentifyFrameConfig, zigbee.IdentifyFrameGenerator, zigbee.IdentifyFrameDecoder
zigbee.ColorControlFrameConfig, zigbee.ColorControlFrameGenerator, zigbee.ColorControlFrameDecoder
zigbee.LevelControlFrameConfig, zigbee.LevelControlFrameGenerator, zigbee.LevelControlFrameDecoder
zigbee.ScenesFrameConfig, zigbee.ScenesFrameGenerator, zigbee.ScenesFrameDecoder
zigbee.GroupsFrameConfig, zigbee.GroupsFrameGenerator, zigbee.GroupsFrameDecoder

この例で説明したコマンドに加えて、提示した実装では次の表に示すコマンドもサポートします。中央列に示したコマンドは、Wireshark で解析可能な PCAP ファイルにエクスポートすることができます。

参考文献

ZigBee Alliance, ZigBee Light Link Standard, v. 1.0, April 5th, 2012.
ZigBee Alliance, ZigBee Specification Document 053474r17, 2007
IEEE 802.15.4-2011 - IEEE Standard for Local and Metropolitan Area Networks--Part 15.4: Low-Rate Wireless Personal Area Networks (LR-WPANs)
ZigBee Alliance, ZigBee Cluster Library Specification, Revision 6, Jan. 2016.
CIE 1931 Color Space.Commission Internationale de l'Eclairage Proceedings.Cambridge University Press, Cambridge
Wireshark software: https://www.wireshark.org/