Matter SDKは、Matterプロトコル仕様のリファレンス実装です。単一の統合されたAPIドキュメントは用意されていません。代わりに、既存のMatterサンプルアプリケーションのソースコードを調べ、ライブラリとの連携方法を学ぶ必要があります。これを容易にするため、Nordic Semiconductorは、Matterコンポーネントの初期化をより使いやすいコードにまとめた高レベルAPIを提供しています。
Matter SDKはC++で記述されている一方、nRF Connect SDKのその他の部分はCを使用している点に注意してください。C++は複雑なプロトコルスタックに適した選択肢であり、Cでは実装が難しいオブジェクト指向プログラミング機能をサポートしています。
Matterデータモデルは Zigbeeソリューションをベースに設計されており、例えばZigbee Cluster Library(ZCL)など一部の要素は本プロトコルで直接再利用されています。このため、最初は命名が紛らわしく感じられる場合があります。
nRF Connect SDKは、nRF Connect Matter APIと、nRF Connect SDKのMatterサンプルのcommon componentsの一部であるユーティリティを提供しており、これらはncs/nrf/samples/matter/commonディレクトリに配置されています。
srcディレクトリには、さまざまなサンプルやアプリケーションで横断的に利用できるオプションモジュールが含まれています。appディレクトリ内のファイルは特に重要で、nRF Connect SDKのすべてのMatterサンプルおよびアプリケーションで使用され、Matterスタックの初期化と管理に役立ちます。
太字で示された項目は、Matter開発を始めるうえで特に重要です。残りのファイルも、ユースケースによっては有用です。
初期化APIにより、開発者はMatterスタックのコアコンポーネント、イベントハンドラー、ネットワーキングバックエンドを設定できます。
スタックコンポーネントの初期化順序は重要です。順序が誤っていると初期化に失敗する可能性があります。nRF Connect SDK Matter APIは、これを正しい順序で処理するラッパー関数を提供します。
nRF Connect Matter APIには、Matterコンポーネントの初期化に使用できる次の関数が含まれています。
| 関数名 | 目的 |
|---|---|
CHIP_ERROR PrepareServer(const InitData) | この関数は、メモリ、サーバー設定、ネットワーキングバックエンドを含むMatterコンポーネントの初期化をスケジュールします。選択した構成に応じて異なるモジュールを初期化でき、ユーザーが初期化内容をカスタマイズすることも可能です。この関数は、必要なMatterインターフェースの実装をすべて含むInitData引数を受け取ります。引数が指定されない場合、この関数はデフォルト構築されたInitDataの一時オブジェクトを使用します。この関数を使用した後、Matterスレッドを開始するためにStartServer()関数を呼び出す必要があります。 |
CHIP_ERROR StartServer() | これはブロッキング関数であり、Matterスレッドを開始して、すべてのMatterサーバーコンポーネントが初期化されるまで待機します。PrepareServer()を呼び出した後に使用してください。 |
FactoryDataProviderBase* GetFactoryDataProvider() | この関数は、初期化時に設定されたFactoryDataProviderオブジェクトへの汎用ポインタを返します。Matterサーバー初期化段階でファクトリデータにアクセスする必要がある場合、またはポスト初期化コールバック(InitData内のmPostServerInitClbk)の一部として使用できます。この関数は、CONFIG_CHIP_FACTORY_DATA Kconfigオプションが選択されている場合にのみ利用できます。 |
PersistentStorageDelegate* GetPersistentStorageDelegate() | この関数は、ユーザーが外部から設定した、またはデフォルト実装により内部で設定されたPersistentStorageDelegateオブジェクトへの汎用ポインタを返します。 |
PrepareServer()に渡されるInitData構造体は、高い設定自由度とカスタマイズ性を備えています。
この構造体内の各Matterコンポーネントは、汎用インターフェースへの公開ポインタとして定義され、初期状態ではデフォルト実装が割り当てられています。アプリケーションでカスタム実装を提供すると、コンパイラは未使用のデフォルト実装を取り除きます。
InitData構造体には、次の内容が含まれます。
/** @brief Matter initialization data.
*
* This structure contains all user specific implementations of Matter interfaces
* and custom initialization callbacks that must be initialized in the Matter thread.
*/
struct InitData {
/** @brief Matter stack events handler. */
chip::DeviceLayer::PlatformManager::EventHandlerFunct mEventHandler{ DefaultEventHandler };
/** @brief Pointer to the user provided NetworkCommissioning instance. */
#ifdef CONFIG_CHIP_WIFI
chip::app::Clusters::NetworkCommissioning::Instance *mNetworkingInstance{ &sWiFiCommissioningInstance };
#else
chip::app::Clusters::NetworkCommissioning::Instance *mNetworkingInstance{ nullptr };
#endif
/** @brief Pointer to the user provided custom server initialization parameters. */
chip::CommonCaseDeviceServerInitParams *mServerInitParams{ &sServerInitParamsDefault };
/** @brief Pointer to the user provided custom device info provider implementation. */
chip::DeviceLayer::DeviceInfoProviderImpl *mDeviceInfoProvider{ nullptr };
#ifdef CONFIG_CHIP_FACTORY_DATA
/** @brief Pointer to the user provided FactoryDataProvider implementation. */
chip::DeviceLayer::FactoryDataProviderBase *mFactoryDataProvider{ &sFactoryDataProviderDefault };
#endif
#ifdef CONFIG_CHIP_CRYPTO_PSA
/** @brief Pointer to the user provided OperationalKeystore implementation. */
chip::Crypto::OperationalKeystore *mOperationalKeyStore{ &sOperationalKeystoreDefault };
#endif
/** @brief Custom code to execute in the Matter main event loop before the server initialization. */
CustomInit mPreServerInitClbk{ nullptr };
/** @brief Custom code to execute in the Matter main event loop after the server initialization. */
CustomInit mPostServerInitClbk{ nullptr };
/** @brief Default implementation static objects that will be stripped by the compiler when above
* pointers are overwritten by the application. */
#ifdef CONFIG_CHIP_WIFI
static chip::app::Clusters::NetworkCommissioning::Instance sWiFiCommissioningInstance;
#endif
static chip::CommonCaseDeviceServerInitParams sServerInitParamsDefault;
#ifdef CONFIG_CHIP_FACTORY_DATA
static chip::DeviceLayer::FactoryDataProvider<chip::DeviceLayer::InternalFlashFactoryData> sFactoryDataProviderDefault;
#endif
#ifdef CONFIG_CHIP_CRYPTO_PSA
static chip::Crypto::PSAOperationalKeystore sOperationalKeystoreDefault;
#endif
};例えば、デフォルト実装でほぼ十分だが、Matterサーバーの初期化後に追加の処理を行う必要がある、といったケースが考えられます。これは、デフォルトのInitData構造体を拡張し、mPostServerInitClbkコールバックのカスタム実装を追加することで容易に実現できます。
CHIP_ERROR MatterAppInit()
{
/* Initialize Matter stack */
ReturnErrorOnFailure(Nrf::Matter::PrepareServer(Nrf::Matter::InitData{ .mPostServerInitClbk = [] {
LOG_INF("Matter server has been initialized.");
/* Change some LED state */
return CHIP_NO_ERROR;
} }));
/* Application specific initialization, for example, hardware initialization.
...
*/
/* Start Matter thread that will run the scheduled initialization procedure. */
return Nrf::Matter::StartServer();
}PrepareServer()呼び出しには、初期化対象となるInitDataのフィールドをさらに含めることもできますし、明示的な引数なしで呼び出すこともできます。明示的な引数がない場合は、デフォルトの初期化が提供されます。
nRF Connect Matter初期化APIの詳細については、 ncs/nrf/samples/matter/common/src/app/matter_init.hヘッダーファイル内のDoxygenコメントを参照してください。
Matter SDKは、スタックからアプリケーション層へ公開イベントを伝播します。nRF Connect MatterイベントハンドラーAPIでは、これらのイベントを処理するカスタム関数を登録/登録解除できます。また、nRF Connect SDKのMatterサンプルおよびアプリケーションで使用されるデフォルトハンドラーも含まれています。
アプリケーションにおける具体的なMatterイベントは、 ncs/modules/lib/matter/src/include/platform/CHIPDeviceEvent.h ヘッダーファイルに一覧化されています。
nRF Connect Matter APIには、イベント処理に使用できる次の関数が含まれています。
| 関数名 | 目的 |
|---|---|
RegisterEventHandler() | この関数は、指定されたMatterイベントハンドラー(EventHandlerFunct)をスレッドセーフに登録するために使用します。Matterサーバーがすでに初期化されている場合でも、アプリケーションから安全に呼び出せます。 |
UnregisterEventHandler() | この関数は、指定されたMatterイベントハンドラー(EventHandlerFunct)をスレッドセーフに登録解除するために使用します。Matterサーバーがすでに初期化されている場合でも、アプリケーションから安全に呼び出せます。 |
DefaultEventHandler() | これは、nRF Connect Matter初期化APIでデフォルトで登録されるnRF Connect Matterイベントハンドラー関数です。必要に応じて、アプリケーション内でUnregisterEventHandler()関数を使用してこのハンドラーを登録解除できます。 |
例えば、Matterのコミッショニング完了時にLEDを点灯させたい場合、次のイベントハンドラーを実装できます。
static void CustomMatterEventHandler(const ChipDeviceEvent *event, intptr_t /* unused */)
{
switch (event->Type) {
case DeviceEventType::kCommissioningComplete:
/* Custom code, for example, control LED */
break;
}
}そして、上記で説明したAPIを使用して登録します。
/* Register custom Matter event handler. */
ReturnErrorOnFailure(Nrf::Matter::RegisterEventHandler(CustomMatterEventHandler, 0));新しいイベントは初期化段階(PrepareServer()メソッド呼び出し後、ただしStartServer()メソッド呼び出し前)に登録してください。
次のフローチャートは、アプリケーションのエントリーポイントから始まる関数の流れを示しています。

nRF Connect MatterイベントハンドラーAPIの詳細については、ncs/nrf/samples/matter/common/src/app/matter_event_handler.hヘッダーファイル内のDoxygenコメントを参照してください。