Klien komunikasi antar proses (IPC) APIs - Integrasi terkelola untuk AWS IoT Device Management
Menyiapkan klien IPCDefinisi dan muatan antarmuka IPC

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Klien komunikasi antar proses (IPC) APIs

Komponen eksternal pada hub integrasi terkelola dapat berkomunikasi dengan integrasi terkelola Hub SDK menggunakan komponen Agen dan komunikasi antar proses (IPC). Contoh komponen eksternal pada hub adalah daemon (proses latar belakang yang terus berjalan) yang mengelola rutinitas lokal. Selama komunikasi, klien IPC adalah komponen eksternal yang menerbitkan perintah atau permintaan lainnya, dan berlangganan acara. Server IPC adalah komponen Agen dalam integrasi terkelola Hub SDK. Untuk informasi selengkapnya, lihat Menyiapkan klien IPC.

Untuk membangun klien IPC, perpustakaan klien IPC IotmiLocalControllerClient disediakan. Pustaka ini menyediakan sisi klien APIs untuk berkomunikasi dengan server IPC di Agen, termasuk mengirim permintaan perintah, menanyakan status perangkat, berlangganan peristiwa (seperti peristiwa status perangkat), dan menangani interaksi berbasis peristiwa.

Menyiapkan klien IPC

IotmiLocalControllerClientPustaka adalah pembungkus di sekitar IPC dasar APIs, yang menyederhanakan dan merampingkan proses penerapan IPC dalam aplikasi Anda. Bagian berikut menjelaskan yang APIs disediakannya.

catatan

Topik ini khusus untuk komponen eksternal sebagai klien IPC dan bukan implementasi server IPC.

  1. Buat klien IPC

    Anda harus terlebih dahulu menginisialisasi klien IPC sebelum dapat digunakan untuk memproses permintaan. Anda dapat menggunakan konstruktor di IotmiLocalControllerClient perpustakaan, yang mengambil konteks pelanggan char *subscriberCtx sebagai parameter, dan membuat manajer klien IPC berdasarkan itu. Berikut ini adalah contoh pembuatan klien IPC:

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

// Instantiate the client
IotmiLocalControllerClient lcc(subscriberCtx);
  2. Berlangganan acara

    Anda dapat berlangganan klien IPC ke acara server IPC penargetan. Ketika server IPC menerbitkan acara yang klien berlangganan, klien akan menerima acara itu. Untuk berlangganan, gunakan registerSubscriber fungsi dan sediakan acara IDs untuk berlangganan, serta panggilan balik yang disesuaikan.

    Berikut ini adalah definisi registerSubscriber fungsi dan contoh penggunaannya:

    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);

    statusIni didefinisikan untuk memeriksa apakah operasi (seperti berlangganan atau mengirim permintaan) berhasil. Jika operasi berhasil, status yang dikembalikan adalahIOTMI_STATUS_OK (= 0).

    catatan

    Pustaka IPC memiliki kuota layanan berikut untuk jumlah maksimum pelanggan dan acara dalam langganan:

    • Jumlah maksimum pelanggan per proses: 5

      Didefinisikan seperti IOTMI_IPC_MAX_SUBSCRIBER di perpustakaan IPC.

    • Jumlah maksimum peristiwa yang ditentukan: 32

      Didefinisikan seperti IOTMI_IPC_EVENT_PUBLIC_END di perpustakaan IPC.

    • Setiap pelanggan memiliki bidang peristiwa 32-bit, di mana setiap bit sesuai dengan peristiwa yang ditentukan.

  3. Connect klien IPC ke server

    Fungsi connect di IotmiLocalControllerClient perpustakaan melakukan pekerjaan seperti menginisialisasi klien IPC, mendaftarkan pelanggan, dan berlangganan acara yang disediakan dalam fungsi tersebut. registerSubscriber Anda dapat memanggil fungsi connect pada klien IPC.

    status = lcc.connect();

    Konfirmasikan bahwa status yang dikembalikan adalah IOTMI_STATUS_OK sebelum Anda mengirim permintaan atau melakukan operasi lain.

  4. Kirim permintaan perintah dan kueri status perangkat

    Server IPC di Agen dapat memproses permintaan perintah dan permintaan status perangkat.

    • Permintaan perintah

      Membentuk perintah permintaan payload string, dan kemudian memanggil sendCommandRequest fungsi untuk mengirimnya. Misalnya:

      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);

      Untuk informasi selengkapnya tentang format permintaan perintah, lihat permintaan perintah.

      contoh fungsi callback

      Server IPC pertama mengirim pesan pengakuan Command received, will send command response back ke klien IPC. Setelah menerima pengakuan ini, klien IPC dapat mengharapkan peristiwa respons perintah.

      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);
}
    • Permintaan status perangkat

      Demikian pula dengan sendCommandRequest fungsi, sendDeviceStateQuery fungsi ini juga mengambil string payload, callback yang sesuai, dan konteks klien. 

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

Definisi dan muatan antarmuka IPC

Bagian ini berfokus pada antarmuka IPC khusus untuk komunikasi antara Agen dan komponen eksternal, dan memberikan contoh implementasi IPC APIs antara kedua komponen tersebut. Dalam contoh berikut, komponen eksternal mengelola rutinitas lokal.

Di IoTManagedIntegrationsDevice-IPC perpustakaan, perintah dan peristiwa berikut didefinisikan untuk komunikasi antara Agen dan komponen eksternal.

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;

Permintaan perintah

Format permintaan perintah
  • contoh permintaan perintah
    {
   "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
                            }
                        }
                    ]
                }
            ]
        }]
    }
}
Format respons perintah

  • Jika permintaan perintah dari komponen eksternal valid, Agen mengirimkannya ke CDMB (Common Data Model Bridge). Respons perintah aktual yang berisi waktu eksekusi perintah dan informasi lainnya tidak segera dikirim kembali ke komponen eksternal, karena perintah pemrosesan membutuhkan waktu. Respons perintah ini adalah respons instan dari Agen (seperti pengakuan). Respons memberi tahu komponen eksternal bahwa integrasi terkelola menerima perintah, dan akan memprosesnya atau membuangnya jika tidak ada token lokal yang valid. Respons perintah dikirim dalam format string.

    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);

Permintaan status perangkat

Komponen eksternal mengirimkan permintaan status perangkat ke Agen. Permintaan menyediakan perangkat, dan kemudian Agen membalas dengan status perangkat itu. managedThingId

Format permintaan status perangkat

  • Permintaan status perangkat Anda harus memiliki perangkat yang ditanyakan. managedThingId

    {
    "payload": {
        "managedThingId": "testManagedThingId"
    }
}
Format respons status perangkat

  • Jika permintaan status perangkat valid, Agen akan mengirimkan status kembali dalam format string.

    contoh respons status perangkat untuk permintaan yang valid
    {
    "payload": {
        "currentState": "exampleState"
    }
}

    Jika permintaan status perangkat tidak valid (seperti jika tidak ada token yang valid, payload tidak dapat diproses, atau kasus kesalahan lainnya), Agen akan mengirimkan respons kembali. Respons termasuk kode kesalahan dan pesan kesalahan.

    contoh respons status perangkat untuk permintaan yang tidak valid
    {
    "payload": {
        "response":{
            "code": 111,
            "message": "errorMessage"
        }
    }
}

Tanggapan perintah

contoh format respons perintah
{
   "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":[
                        {}
                    ]
                }
            ]
        }]
    }
}

Acara pemberitahuan

contoh format acara pemberitahuan
{
   "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
                        }
                    ]
                }
            ]
        }]
    }
}