IPC(프로세스 간 통신) 클라이언트 APIs - 에 대한 관리형 통합 AWS IoT Device Management
IPC 클라이언트 설정IPC 인터페이스 정의 및 페이로드

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

IPC(프로세스 간 통신) 클라이언트 APIs

관리형 통합 허브의 외부 구성 요소는 에이전트 구성 요소 및 프로세스 간 통신(IPC)을 사용하여 관리형 통합 Hub SDK와 통신할 수 있습니다. 허브의 외부 구성 요소의 예로는 로컬 루틴을 관리하는 데몬(지속적으로 실행되는 백그라운드 프로세스)이 있습니다. 통신 중에 IPC 클라이언트는 명령 또는 기타 요청을 게시하고 이벤트를 구독하는 외부 구성 요소입니다. IPC 서버는 관리형 통합 Hub SDK의 에이전트 구성 요소입니다. 자세한 내용은 IPC 클라이언트 설정을 참조하세요.

IPC 클라이언트를 빌드하기 위해 IPC 클라이언트 라이브러리IotmiLocalControllerClient가 제공됩니다. 이 라이브러리는 명령 요청 전송, 디바이스 상태 쿼리, 이벤트(예: 디바이스 상태 이벤트) 구독, 이벤트 기반 상호 작용 처리 등 Agent의 IPC 서버와 통신하기 위한 클라이언트 측 APIs를 제공합니다.

IPC 클라이언트 설정

IotmiLocalControllerClient 라이브러리는 애플리케이션에서 IPC를 구현하는 프로세스를 단순화하고 간소화하는 기본 IPC APIs를 중심으로 하는 래퍼입니다. 다음 섹션에서는 APIAPIs에 대해 설명합니다.

참고

이 주제는 특히 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 인터페이스에 중점을 두고이 두 구성 요소 간의 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
                        }
                    ]
                }
            ]
        }]
    }
}