Client di comunicazione interprocesso (IPC) APIs - Integrazioni gestite per AWS IoT Device Management
Configurazione del client IPCDefinizioni e payload dell'interfaccia IPC

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Client di comunicazione interprocesso (IPC) APIs

I componenti esterni dell'hub di integrazione gestito possono comunicare con l'SDK Hub per le integrazioni gestite utilizzando il componente Agent e le comunicazioni tra processi (IPC). Un esempio di componente esterno dell'hub è un demone (un processo in background in esecuzione continua) che gestisce le routine locali. Durante la comunicazione, il client IPC è il componente esterno che pubblica comandi o altre richieste e sottoscrive gli eventi. Il server IPC è il componente Agent dell'SDK Hub per le integrazioni gestite. Per ulteriori informazioni, vedere Configurazione del client IPC.

Per creare il client IPC, viene fornita una libreria IotmiLocalControllerClient client IPC. Questa libreria consente la comunicazione lato client APIs con il server IPC in Agent, tra cui l'invio di richieste di comandi, l'interrogazione degli stati del dispositivo, la sottoscrizione agli eventi (come l'evento sullo stato del dispositivo) e la gestione delle interazioni basate sugli eventi.

Configurazione del client IPC

La IotmiLocalControllerClient libreria è una sorta di supporto all'IPC di base APIs, che semplifica e ottimizza il processo di implementazione dell'IPC nelle applicazioni. Le sezioni seguenti descrivono ciò che fornisce. APIs

Nota

Questo argomento riguarda specificamente un componente esterno come client IPC e non le implementazioni di un server IPC.

  1. Creare un client IPC

    È necessario inizializzare il client IPC prima che possa essere utilizzato per elaborare le richieste. È possibile utilizzare un costruttore nella IotmiLocalControllerClient libreria, che prende il contesto del sottoscrittore char *subscriberCtx come parametro e crea un client manager IPC basato su di esso. Di seguito è riportato un esempio di creazione di un client IPC:

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

// Instantiate the client
IotmiLocalControllerClient lcc(subscriberCtx);
  2. Iscriviti a un evento

    È possibile sottoscrivere il client IPC agli eventi del server IPC di destinazione. Quando il server IPC pubblica un evento a cui il client è abbonato, il client riceverà quell'evento. Per iscriverti, usa la registerSubscriber funzione e fornisci l'evento IDs a cui iscriverti, oltre al callback personalizzato.

    Di seguito è riportata una definizione della registerSubscriber funzione e il suo utilizzo di esempio:

    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È definito per verificare se l'operazione (come iscriversi o inviare una richiesta) ha esito positivo. Se l'operazione ha esito positivo, lo stato restituito èIOTMI_STATUS_OK (= 0).

    Nota

    La libreria IPC ha le seguenti quote di servizio per il numero massimo di abbonati ed eventi in un abbonamento:

    • Numero massimo di abbonati per processo: 5

      Definito come IOTMI_IPC_MAX_SUBSCRIBER nella libreria IPC.

    • Numero massimo di eventi definito: 32

      Definito come IOTMI_IPC_EVENT_PUBLIC_END nella libreria IPC.

    • Ogni sottoscrittore dispone di un campo di eventi a 32 bit, in cui ogni bit corrisponde a un evento definito.

  3. Connect il client IPC al server

    La funzione di connessione nella IotmiLocalControllerClient libreria esegue operazioni come l'inizializzazione del client IPC, la registrazione degli abbonati e la sottoscrizione agli eventi forniti nella funzione. registerSubscriber È possibile chiamare la funzione di connessione sul client IPC.

    status = lcc.connect();

    Conferma che lo stato restituito sia quello restituito IOTMI_STATUS_OK prima di inviare richieste o effettuare altre operazioni.

  4. Invia una richiesta di comando e una richiesta sullo stato del dispositivo

    Il server IPC di Agent può elaborare le richieste di comando e le richieste di stato del dispositivo.

    • Richiesta di comando

      Formate una stringa di payload per la richiesta di comando, quindi chiamate la sendCommandRequest funzione per inviarla. Per esempio:

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

      Per ulteriori informazioni sul formato della richiesta di comando, vedere Richieste di comando.

      Esempio funzione di callback

      Il server IPC invia innanzitutto un messaggio di conferma Command received, will send command response back al client IPC. Dopo aver ricevuto questo riconoscimento, il client IPC può aspettarsi un evento di risposta al comando.

      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);
}
    • Richiesta di stato del dispositivo

      Analogamente alla sendCommandRequest funzione, questa sendDeviceStateQuery funzione accetta anche una stringa di payload, il callback corrispondente e il contesto del client. 

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

Definizioni e payload dell'interfaccia IPC

Questa sezione si concentra sulle interfacce IPC specificamente per la comunicazione tra l'agente e i componenti esterni e fornisce esempi di implementazioni di IPC APIs tra questi due componenti. Negli esempi seguenti, il componente esterno gestisce le routine locali.

Nella IoTManagedIntegrationsDevice-IPC libreria, i seguenti comandi ed eventi sono definiti per la comunicazione tra l'agente e il componente esterno.

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;

Richiesta di comando

Formato di richiesta di comando
  • Esempio richiesta di comando
    {
   "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
                            }
                        }
                    ]
                }
            ]
        }]
    }
}
Formato di risposta al comando

  • Se la richiesta di comando dal componente esterno è valida, l'agente la invia al CDMB (Common Data Model Bridge). L'effettiva risposta al comando che contiene il tempo di esecuzione del comando e altre informazioni non viene restituita immediatamente al componente esterno, poiché l'elaborazione dei comandi richiede tempo. Questa risposta al comando è una risposta istantanea dell'agente (come un riconoscimento). La risposta indica al componente esterno che le integrazioni gestite hanno ricevuto il comando e lo elaborerà o lo eliminerà se non esiste un token locale valido. La risposta al comando viene inviata in formato stringa.

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

Richiesta di stato del dispositivo

Il componente esterno invia una richiesta di stato del dispositivo all'agente. La richiesta fornisce il managedThingId nome di un dispositivo, quindi l'agente risponde indicando lo stato del dispositivo.

Formato di richiesta dello stato del dispositivo

  • La richiesta di stato del dispositivo deve contenere lo stesso managedThingId del dispositivo interrogato.

    {
    "payload": {
        "managedThingId": "testManagedThingId"
    }
}
Formato di risposta allo stato del dispositivo

  • Se la richiesta dello stato del dispositivo è valida, l'agente restituisce lo stato in formato stringa.

    Esempio risposta allo stato del dispositivo per una richiesta valida
    {
    "payload": {
        "currentState": "exampleState"
    }
}

    Se la richiesta dello stato del dispositivo non è valida (ad esempio se non esiste un token valido, il payload non può essere elaborato o se si verifica un altro caso di errore), l'agente restituisce la risposta. La risposta include il codice di errore e il messaggio di errore.

    Esempio risposta sullo stato del dispositivo per una richiesta non valida
    {
    "payload": {
        "response":{
            "code": 111,
            "message": "errorMessage"
        }
    }
}

Risposta al comando

Esempio formato di risposta al comando
{
   "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":[
                        {}
                    ]
                }
            ]
        }]
    }
}

Evento di notifica

Esempio formato dell'evento di notifica
{
   "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
                        }
                    ]
                }
            ]
        }]
    }
}