プロセス間通信 (IPC) APIs - のマネージド統合 AWS IoT Device Management
IPC クライアントのセットアップIPC インターフェイスの定義とペイロード

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

プロセス間通信 (IPC) APIs

マネージド統合ハブの外部コンポーネントは、エージェントコンポーネントとプロセス間通信 (IPC) を使用してマネージド統合 Hub SDK と通信できます。ハブの外部コンポーネントの例は、ローカルルーチンを管理するデーモン (継続的に実行されるバックグラウンドプロセス) です。通信中、IPC クライアントはコマンドやその他のリクエストを発行し、イベントをサブスクライブする外部コンポーネントです。IPC サーバーは、マネージド統合 Hub SDK の エージェントコンポーネントです。詳細については、「IPC クライアントのセットアップ」を参照してください。

IPC クライアントを構築するために、IPC クライアントライブラリIotmiLocalControllerClientが用意されています。このライブラリは、コマンドリクエストの送信、デバイス状態のクエリ、イベント (デバイス状態イベントなど) のサブスクライブ、イベントベースのインタラクションの処理など、 エージェントで IPC サーバーと通信するためのクライアント側の APIs を提供します。

IPC クライアントのセットアップ

IotmiLocalControllerClient ライブラリは基本的な IPC APIs のラッパーであり、アプリケーションに IPC を実装するプロセスを簡素化および合理化します。以下のセクションでは、提供する APIsについて説明します。

注記

このトピックは、IPC サーバーの実装ではなく、IPC クライアントとしての外部コンポーネント専用です。

  1. IPC クライアントを作成する

    リクエストの処理に使用する前に、まず IPC クライアントを初期化する必要があります。IotmiLocalControllerClient ライブラリでコンストラクタを使用できます。これは、サブスクライバーコンテキストをパラメータ char *subscriberCtxとして受け取り、それに基づいて IPC クライアントマネージャーを作成します。IPC クライアントを作成する例を次に示します。

    // Context for subscriber
char subscriberCtx[] = "example_ctx";

// Instantiate the client
IotmiLocalControllerClient lcc(subscriberCtx);
  2. イベントをサブスクライブする

    IPC クライアントをターゲット IPC サーバーのイベントにサブスクライブできます。IPC サーバーがクライアントがサブスクライブしているイベントを発行すると、クライアントはそのイベントを受け取ります。サブスクライブするには、 registerSubscriber関数を使用して、サブスクライブするイベント IDs とカスタマイズされたコールバックを指定します。

    以下は、 registerSubscriber関数の定義とその使用例です。

    iotmi_statusCode_t registerSubscriber(
        std::vector<iotmiIpc_eventId_t> eventIds, 
        SubscribeCallbackFunction cb);
    // A basic example of customized subscribe callback, which prints the event ID, data, and length received
void customizedSubscribeCallback(iotmiIpc_eventId_t event_id, uint32_t length, const uint8_t *data, void *ctx) {
    IOTMI_IPC_LOGI("Received subscribed event id: %d\n"
                    "length: %d\n"
                    "data: %s\n",
                    event_id, length, data);
}

iotmi_statusCode_t status;
status = lcc.registerSubscriber({IOTMI_IPC_EVENT_DEVICE_UPDATE_TO_RE}, customerProvidedSubscribeCallback);

    status は、オペレーション (サブスクライブやリクエストの送信など) が成功したかどうかを確認するように定義されています。オペレーションが成功した場合、返されるステータスは ですIOTMI_STATUS_OK (= 0)。

    注記

    IPC ライブラリには、サブスクリプション内のサブスクライバーとイベントの最大数に対して次のサービスクォータがあります。

    • プロセスあたりのサブスクライバーの最大数: 5

      IPC ライブラリIOTMI_IPC_MAX_SUBSCRIBERで として定義されます。

    • 定義されたイベントの最大数: 32

      IPC ライブラリIOTMI_IPC_EVENT_PUBLIC_ENDで として定義されます。

    • 各サブスクライバーには 32 ビットのイベントフィールドがあり、各ビットは定義されたイベントに対応します。

  3. IPC クライアントをサーバーに接続する

    IotmiLocalControllerClient ライブラリの接続関数は、IPC クライアントの初期化、サブスクライバーの登録、registerSubscriber関数で提供されたイベントのサブスクライブなどのジョブを実行します。IPC クライアントで接続関数を呼び出すことができます。

    status = lcc.connect();

    リクエストを送信したり、他のオペレーションを行ったりIOTMI_STATUS_OKする前に、返されたステータスが であることを確認します。

  4. コマンドリクエストとデバイス状態のクエリを送信する

    エージェント内の IPC サーバーは、コマンドリクエストとデバイス状態リクエストを処理できます。

    • コマンドリクエスト

      コマンドリクエストペイロード文字列を形成し、 sendCommandRequest関数を呼び出して送信します。例:

      status = lcc.sendCommandRequest(payloadData, iotmiIpcMgr_commandRequestCb, nullptr);
      /**
* @brief method to send local control command
* @param payloadString A pre-defined data format for local command request.
* @param callback a callback function with typedef as PublishCallbackFunction
* @param client_ctx client provided context
* @return
*/
iotmi_statusCode_t sendCommandRequest(std::string payloadString, PublishCallbackFunction callback, void *client_ctx);

      コマンドリクエスト形式の詳細については、「 コマンドリクエスト」を参照してください。

      例 コールバック関数

      IPC サーバーはまず、IPC クライアントCommand received, will send command response backにメッセージ確認を送信します。この確認を受け取ると、IPC クライアントはコマンドレスポンスイベントを期待できます。

      void iotmiIpcMgr_commandRequestCb(iotmi_statusCode_t ret_status,
                                   void *ret_data, void *ret_client_ctx) {
    char* data = NULL;
    char *ctx = NULL;

    if (ret_status != IOTMI_STATUS_OK)
        return;

    if (ret_data == NULL) {
        IOTMI_IPC_LOGE("error, event data NULL");
        return;
    }

    if (ret_client_ctx == NULL) {
        IOTMI_IPC_LOGE("error, event client ctx NULL");
        return;
    }

    data = (char *)ret_data;
    ctx = (char *)ret_client_ctx;
    IOTMI_IPC_LOGI("response received: %s \n", data);
}
    • デバイス状態リクエスト

      sendCommandRequest 関数と同様に、このsendDeviceStateQuery関数はペイロード文字列、対応するコールバック、およびクライアントコンテキストも受け取ります。

      status = lcc.sendDeviceStateQuery(payloadData, iotmiIpcMgr_deviceStateQueryCb, nullptr);

IPC インターフェイスの定義とペイロード

このセクションでは、エージェントと外部コンポーネント間の通信専用の IPC インターフェイスに焦点を当て、これら 2 つのコンポーネント間の IPC APIs の実装例を示します。次の例では、外部コンポーネントがローカルルーチンを管理します。

IoTManagedIntegrationsDevice-IPC ライブラリでは、エージェントと外部コンポーネント間の通信用に以下のコマンドとイベントが定義されています。

typedef enum {
    // The async cmd used to send commands from the external component to Agent
    IOTMI_IPC_SVC_SEND_REQ_FROM_RE = 32,
    // The async cmd used to send device state query from the external component to Agent
    IOTMI_IPC_SVC_SEND_QUERY_FROM_RE = 33,
    // ...
} iotmiIpcSvc_cmd_t;
typedef enum {
    // Event about device state update from Agent to the component
    IOTMI_IPC_EVENT_DEVICE_UPDATE_TO_RE = 3,
    // ...
} iotmiIpc_eventId_t;

コマンドリクエスト

コマンドリクエスト形式
  • 例 コマンドリクエスト
    {
   "payload": {
        "traceId": "LIGHT_DIMMING_UPDATE",          
        "nodeId": "1",  
        "managedThingId": <ManagedThingId of the device>,         
        "endpoints": [{
            "id": "1",                   
            "capabilities": [
                {
                    "id": "matter.LevelControl@1.4",
                    "name": "Level Control",         
                    "version": "1.0",
                    "actions":[
                        {
                            "name": "UpdateState",
                            "parameters": { 
                                "OnLevel": 5,
                                "DefaultMoveRate": 30
                            }
                        }
                    ]
                }
            ]
        }]
    }
}
コマンドレスポンス形式

  • 外部コンポーネントからのコマンドリクエストが有効な場合、エージェントは CDMB (Common Data Model Bridge) に送信します。コマンドの実行時間やその他の情報を含む実際のコマンドレスポンスは、コマンドの処理に時間がかかるため、外部コンポーネントにすぐには送信されません。このコマンドレスポンスは、 エージェントからの即時レスポンスです (確認応答など）。レスポンスは、マネージド統合が コマンドを受信した外部コンポーネントに指示し、有効なローカルトークンがない場合は処理するか破棄します。コマンドレスポンスは文字列形式で送信されます。

    std::string errorResponse = "No valid token for local command, cannot process.";
    *ret_buf_len = static_cast<uint32_t>(errorResponse.size());
    *ret_buf = new uint8_t[*ret_buf_len];
    std::memcpy(*ret_buf, errorResponse.data(), *ret_buf_len);

デバイス状態リクエスト

外部コンポーネントは、デバイス状態リクエストを エージェントに送信します。リクエストはmanagedThingIdデバイスの を提供し、エージェントはそのデバイスの状態を返信します。

デバイス状態のリクエスト形式

  • デバイス状態リクエストには、クエリされたデバイスの managedThingId が必要です。

    {
    "payload": {
        "managedThingId": "testManagedThingId"
    }
}
デバイス状態のレスポンス形式

  • デバイス状態リクエストが有効な場合、エージェントは文字列形式で状態を返します。

    例 有効なリクエストのデバイス状態レスポンス
    {
    "payload": {
        "currentState": "exampleState"
    }
}

    デバイス状態リクエストが有効でない場合 (有効なトークンがない場合、ペイロードを処理できない場合、または別のエラーケースがある場合など）、エージェントはレスポンスを返します。レスポンスには、エラーコードとエラーメッセージが含まれます。

    例 無効なリクエストに対するデバイス状態レスポンス
    {
    "payload": {
        "response":{
            "code": 111,
            "message": "errorMessage"
        }
    }
}

コマンドレスポンス

例 コマンドレスポンス形式
{
   "payload": {
        "traceId": "LIGHT_DIMMING_UPDATE",   
        "commandReceivedAt": "1684911358.533",  
        "commandExecutedAt": "1684911360.123",
        "managedThingId": <ManagedThingId of the device>,       
        "nodeId": "1",                  
        "endpoints": [{
            "id": "1",                   
            "capabilities": [
                {
                    "id": "matter.OnOff@1.4",
                    "name": "On/Off",         
                    "version": "1.0",
                    "actions":[
                        {}
                    ]
                }
            ]
        }]
    }
}

通知イベント

例 通知イベント形式
{
   "payload": { 
        "hasState": "true"      
        "nodeId": "1",    
        "managedThingId": <ManagedThingId of the device>,              
        "endpoints": [{
            "id": "1",                   
            "capabilities": [
                {
                    "id": "matter.OnOff@1.4",
                    "name": "On/Off",         
                    "version": "1.0",
                    "properties":[
                        {
                            "name": "OnOff",
                            "value": true
                        }
                    ]
                }
            ]
        }]
    }
}