Connected Home over IP（CHIP）の概要

1. 概要

Matter は、Connectivity Standards Alliance（旧 Zigbee Alliance）が定めた新しい規格です。この業界統一規格により、信頼性の高い安全な接続性を保証し、現在だけでなく将来にわたって多様なデバイスがシームレスに連携できる環境を実現します。

この規格の目標は、メーカーによる開発を簡素化するとともに、デバイスの互換性を高めて消費者が簡単に利用できるようにすることです。「スマートホームデバイスは、安全で信頼性が高く、シームレスに使用できるものであるべき」という信念のもと、GitHub の Connected Home over IP プロジェクトとして積極的に開発が進められています。このプロジェクトでは、スマートホームデバイス、モバイルアプリ、クラウドサービス間のインターネットプロトコル（IP）による通信を可能にするとともに、デバイス認証のための IP ベースのネットワーク技術を定義しています。

特に記載のない限り、この Codelab のコンテンツは

Apache License 2.0 により使用許諾されます。詳細については、プロジェクト CHIP オープンソースライセンスをご覧ください。

この Codelab では、ESP32 開発ボードを使用した Wi-Fi デバイスのセットアップ、オン / オフ機能の追加、コマンドラインインターフェースによる制御について解説します。

学習する内容

CHIP 対応デバイスを接続して制御する方法。
サンプルデバイスアプリケーションに機能を追加する方法。

必要なもの

Linux の基本的な知識
ESP32 開発ボード
「git」がインストールされている Linux マシン

2. はじめに

シリアルポートターミナル

ターミナルを通じてシリアルポートに接続する方法に精通している必要があります。この Codelab では screen を使用して説明しますが、その他のターミナルソフトウェアも使用できます。

Linux マシン

この Codelab は、x86 ベースの 64 ビット Linux マシンを使用してチップツールを実行し、すべての開発ボードをフラッシュすることを前提として設計されています。すべての手順は Ubuntu 20.04.2.0 LTS でテストしました。

ESP32 開発ボード

この Codelab では、次のいずれかの ESP32 開発ボードを使用します。

ESP32-DevkitC
ESP32-WROVER-KIT V4.1
M5Stack ESP32 シリーズベーシックコア IoT 開発キット

ファームウェアをフラッシュしてデバイスログにアクセスするには、開発キットを USB ケーブルで Linux マシンに接続する必要があります。

3. リポジトリのクローンを作成する

このドキュメントと互換性のあるソースコードのバージョンを確認するには、次の手順に沿ってリポジトリのクローンを作成します。

$ git clone git@github.com:project-chip/connectedhomeip.git
$ cd connectedhomeip
$ git checkout 1de2b73bb4123af5f184eac54d1b1d76985b4f62
$ git submodule update --init

次に、お使いのプラットフォームに応じて、GitHub の Build Documentation の「Prerequisites」と「Build Preparation」の手順を行います。完了したら、こちらの続きをお読みください。

Codelab のパッチを適用する

このパッチを適用すると、CHIP からのオン / オフコマンドを処理するコールバックが削除されます。これについては、後ほど手順の中で追加し直します。

$ git fetch origin ce1e0ab44c367bc9d5907115e09a4c45fc6d8c96
$ git cherry-pick ce1e0ab44c367bc9d5907115e09a4c45fc6d8c96

4. CHIP クライアントのサンプルをビルドする

ホストマシンから CHIP デバイスと通信するには、ホスト用に chip-tool をビルドする必要があります。

GitHub の手順に沿って chip-tool をビルドします。

ビルドされた chip-tool を使用してオペレーション（たとえばデバイスエンドポイントのオンとオフを切り替える）を実行します。

各種の chip-tool オペレーションの詳細については、GitHub の chip-tool のドキュメントとソースコードをご覧ください。

5. All Clusters Example をビルドする

ホストを設定して chip-tool をビルドしたら、ESP32 の All Clusters Example をビルドして実行します。

まず、All Clusters Example のディレクトリに移動します。

$ cd examples/all-clusters-app/esp32

次に、GitHub の手順に沿って、次のコマンドを実行します。

$ idf make menuconfig

コマンドを実行すると、このサンプルの構成エディタが表示されます。

ボードタイプを構成する

[Demo] → [Device Type] に移動し、どのボード用にビルドするかを選択します。

ランデブーモードを無効にする

ランデブーモードを無効にしたデバイスは、安全でないチャネルを介して chip-tool と通信できるようになります。構成メニューで、[Demo] → [Rendezvous Mode] に移動し、モードを [Bypass] に設定します。

Wi-Fi の SSID とパスワードを構成する

構成メニューで、[Component config] → [CHIP Device Layer] → [WiFi Station Options] に移動し、Wi-Fi ネットワークの以下の 2 つのオプションを設定します。

[Default WiFi SSID]
[Default WiFi Password]

ビルドしてフラッシュする

以上の構成設定で、サンプルアプリケーションをビルドしてフラッシュします。

下の「USB0」は、開発ボードがアタッチされている TTY で置き換えてください。ホストマシンに複数のシリアルケーブルが接続されている場合は、複数の TTY 値が存在する場合があります（たとえば /dev/ttyUSB1 と /dev/ttyUSB2）。このドキュメントでは、これ以降も USB0 を TTY で置き換えてください。

$ idf make
$ idf make erase_flash ESPPORT=/dev/ttyUSB0
$ idf make flash ESPPORT=/dev/ttyUSB0

上記の手順は、CHIP All Clusters Example の README でも確認できます。

6. オン / オフコマンドを有効にする

examples/all-clusters-app/esp32/main にある DeviceCallbacks.cpp を任意のエディタで開きます。エディタで開いたら、「DeviceCallbacks::PostAttributeChangeCallback()」関数に移動します。

chip-tool からオン / オフコマンドを送信すると、デバイスは ZCL_ON_OFF_CLUSTER_ID イベントを受信します。これらのイベントを処理するため、各種の clusterID を処理するイベントコールバックに追加します。

void DeviceCallbacks::PostAttributeChangeCallback(...)
{
    ...

    switch (clusterId)
    {
    case ZCL_ON_OFF_CLUSTER_ID:
        break;

    default:
        ESP_LOGI(TAG, "Unhandled cluster ID: %d", clusterId);
        break;
    }
    ...
}

各クラスタはさまざまな属性をサポートしています。ここではシンプルなオン / オフ機能のみをサポートします。コード内の ZCL_ON_OFF_ATTRIBUTE_ID の attributeId を確認してください。この時点では空になっているはずです。

void DeviceCallbacks::PostAttributeChangeCallback(...)
{
    ...

    switch (clusterId)
    {
    case ZCL_ON_OFF_CLUSTER_ID:
        if (attributeId == ZCL_ON_OFF_ATTRIBUTE_ID) {

        } else {
          ESP_LOGI(TAG, "Unhandled attribute ID: %d", attributeId);
        }
        break;

    default:
        ESP_LOGI(TAG, "Unhandled cluster ID: %d", clusterId);
        break;
    }

    ...
}

clusterId と attributeId が正しい場合に、開発キットの LED のステータスを制御する関数呼び出しを追加します。

void DeviceCallbacks::PostAttributeChangeCallback(...)
{
    ...

    switch (clusterId)
    {
    case ZCL_ON_OFF_CLUSTER_ID:
        if (attributeId == ZCL_ON_OFF_ATTRIBUTE_ID) {
          statusLED1.Set(*value);
        } else {
          ESP_LOGI(TAG, "Unhandled attribute ID: %d", attributeId);
        }
        break;

    default:
        ESP_LOGI(TAG, "Unhandled cluster ID: %d", clusterId);
        break;
    }

    ...
}

ファイルを保存し、前のステップ「ビルドしてフラッシュする」と同じ手順で、アプリケーションをビルドして開発キットをフラッシュします。

$ idf make
$ idf make erase_flash ESPPORT=/dev/ttyUSB0
$ idf make flash ESPPORT=/dev/ttyUSB0

7. サンプルアプリケーションを実行する

ESP32 ボードからの USB ケーブルをホストマシンに接続し、シリアルターミナルを起動します。おすすめのプログラムは screen です。次のコマンドを実行すると、ESP32 からのシリアル出力を確認できます。

$ screen /dev/ttyUSB0 115200

デバイスが起動して Wi-Fi に接続されると、シリアルコンソールに IP アドレスが表示されます。この IP アドレスは、chip-tool を使ってデバイスを操作するときに必要になります。

上の例では、IP アドレスは 192.168.117.134 で、デバイスはポート 11097 をリッスンしています。

この IP アドレスとポートを使用して、デバイスへの接続を確立します。ペア設定のステップはバイパスします。

$ cd examples/chip-tool
$ ./out/debug/chip-tool pairing bypass 192.168.117.134 11097

接続が確立されたら、次のコマンドを使用してエンドポイント 1 を切り替えることができます。

$ ./out/debug/chip-tool onoff toggle 1

ESP32 DevKitC では、GPIO2 のシグナルが切り替わります。

上の画像では、1.8 V / 20 mA の赤色の LED が、75 オームの抵抗と直列で GPIO2 に接続されています。

ESP32-WROVER-KIT で上記のコマンドを実行すると、ディスプレイの左上にある緑色の仮想 LED に切り替わります。

M5Stack ボードで上記のコマンドを実行すると、ディスプレイの左上にある緑色の仮想 LED に切り替わります。

8. 完了

これで、CHIP を使用して開発キットを制御できるようになりました。

この Codelab では、以下について学びました。

開発キットでオン / オフ機能を有効にする方法。
CHIP コントローラツールを使用して開発キットを制御する方法。

さらに詳しく

さらに詳しく学びたい方は、以下のことをお試しください。

ZAP ファイルを編集して機能を拡張する。
DeviceCallbacks.cpp ファイルに ZCL_IDENTIFY_CLUSTER_ID 機能を追加する。
仕様で ZigBee Cluster Library を定義する。
GitHub でプロジェクト CHIP の最新情報を、buildwithmatter.com で Matter の最新情報を確認する。