Ejemplo - IoT Platform - Centro de documentación de Alibaba Cloud

Contexto

Para obtener más información sobre las sombras de dispositivo, consulte Overview.
usa conexiones MQTT. Para consultar los ejemplos de código relacionados, consulte MQTT connection.

no heading

Paso 1: Inicialización

Agregue los archivos de encabezado.
```
...
...

#include "aiot_shadow_api.h"
```

Configure las dependencias subyacentes y la salida de registros.

    aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
    aiot_state_set_logcb(demo_state_logcb);

Llame a la operación aiot_shadow_init para crear un shadow

    shadow_handle = aiot_shadow_init();
    if (shadow_handle == NULL) {
        printf("aiot_shadow_init failed\n");
        return -1;
    }

no heading

Paso 2: Configurar funciones

Llame a la operación aiot_shadow_setopt para configurar los siguientes elementos.

Asocie un handle de conexión MQTT.

Importante

Antes de establecer los parámetros específicos de la sombra de dispositivo,

    aiot_shadow_setopt(shadow_handle, AIOT_SHADOWOPT_MQTT_HANDLE, mqtt_handle);

Parámetro	Ejemplo	Descripción
AIOT_SHADOWOPT_MQTT_HANDLE	mqtt_handle	Las solicitudes TSL usan esta conexión.

Configure una devolución de llamada de mensajes

    aiot_shadow_setopt(shadow_handle, AIOT_SHADOWOPT_RECV_HANDLER, (void *)demo_shadow_recv_handler);

Parámetro	Ejemplo	Descripción
AIOT_SHADOWOPT_RECV_HANDLER	demo_shadow_recv_handler	Esta función se llama cuando se recibe el mensaje de la sombra de dispositivo.

Paso 3: Enviar el estado del dispositivo

El dispositivo llama a la operación aiot_shadow_send para enviar el estado más reciente a la sombra de dispositivo en IoT Platform.
Al enviar el estado, tenga en cuenta los siguientes puntos:
- aiot_shadow_msg_t indica el formato de datos. Este parámetro es un parámetro de entrada de la devolución de llamada aiot_shadow_send().
- AIOT_SHADOWMSG_UPDATE indica el tipo de mensaje.
```
int32_t demo_update_shadow(void *shadow_handle, char *reported_data, int64_t version)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_UPDATE;
    message.data.update.reported = reported_data;
    message.data.update.version = version;

    return aiot_shadow_send(shadow_handle, &message);
}
```

Especifique el contenido del mensaje.

        res = demo_update_shadow(shadow_handle, "{\"LightSwitch\":1}", 0);
        if (res < 0) {
            printf("demo_delete_shadow_report failed, res = -0x%04x\r\n", -res);
        }

Mensaje de ejemplo:

Mensaje de ejemplo Formato Alink Descripción

{
    "LightSwitch": 1
}

{
      "method": "update", 
      "state": {
        "reported": {
          "LightSwitch": 1
        }
      }, 
      "version": 0
    }

El contenido del mensaje está en formato JSON. El contenido lo indica el parámetro state en los datos Alink. Para obtener más información, consulte A device reports its status.

A continuación se describe el contenido del mensaje de este ejemplo:

Establezca la propiedad LightSwitch en 1.
Establezca el número de versión en 0.
Nota
- Los números de versión de las operaciones posteriores deben incrementarse. De lo contrario, IoT Platform devuelve un error.
- Si establece el número de versión en -1, IoT Platform borra los datos de la sombra de dispositivo y actualiza el número de versión a 0.

Una vez que IoT Platform recibe el mensaje, actualiza el archivo de sombra. Después, devuelve una respuesta al dispositivo.

Cuando el dispositivo recibe la respuesta, se llama a la devolución de llamada demo_shadow_recv_handler.

Al definir la lógica de la devolución de llamada, tenga en cuenta los siguientes puntos:

aiot_shadow_recv_t indica el formato de datos. Este parámetro es un parámetro de entrada de la devolución de llamada.
AIOT_SHADOWRECV_GENERIC_REPLY indica el tipo de mensaje.

En la siguiente tabla se describe una respuesta de ejemplo y su formato Alink.

Ejemplo	Formato Alink	Descripción
`{ "status":"success", "version":0 }`	`{ "method": "reply", "payload": { "status": "success", "version": 0 }, "timestamp": 1626317187 }`	La respuesta la indica el parámetro payload en los datos Alink. Esta respuesta de ejemplo indica que el estado se envió correctamente.

En este ejemplo, el mensaje se imprime.

void demo_shadow_recv_handler(void *handle, const aiot_shadow_recv_t *recv, void *userdata)
{
    printf("demo_shadow_recv_handler, type = %d, productKey = %s, deviceName = %s\r\n",
            recv->type, recv->product_key, recv->device_name);

    switch (recv->type) {

        case AIOT_SHADOWRECV_GENERIC_REPLY: {
            const aiot_shadow_recv_generic_reply_t *generic_reply = &recv->data.generic_reply;

            printf("payload = \"%.*s\", status = %s, timestamp = %ld\r\n",
                   generic_reply->payload_len,
                   generic_reply->payload,
                   generic_reply->status,
                   (unsigned long)generic_reply->timestamp);
        }
……
...
        default:
            break;
    }
}

Paso 4: Cambiar el estado del dispositivo mediante propiedades deseadas

Para cambiar el estado del dispositivo, puede usar una aplicación que envíe propiedades deseadas a la sombra de dispositivo. También puede iniciar sesión en la consola de IoT Platform y modificar las propiedades deseadas en la sombra de dispositivo.

Actualice las propiedades deseadas en la sombra de dispositivo. Están disponibles los siguientes métodos:
- Desarrolle una aplicación en la nube y llame a la operación de API para enviar propiedades deseadas a la sombra de dispositivo. Para obtener más información, consulte UpdateDeviceShadow.
- En la página Device Details de IoT Platform, modifique las propiedades deseadas en la sombra de dispositivo. Para obtener más información, consulte View and update a device shadow.
IoT Platform actualiza el archivo de sombra y luego lo envía al dispositivo.

Cuando el dispositivo recibe el archivo de sombra, se llama a la devolución de llamada demo_shadow_recv_handler.

Importante

Si el dispositivo está desconectado, puede solicitar la sombra de dispositivo después de que vuelva a conectarse. Para obtener más información, consulte

Step 5: Request the device shadow

.

Al definir la lógica de la devolución de llamada, tenga en cuenta los siguientes puntos:

aiot_shadow_recv_t indica el formato de datos. Este parámetro es un parámetro de entrada de la devolución de llamada.
AIOT_SHADOWRECV_CONTROL indica el tipo de mensaje.

En la siguiente tabla se describe un mensaje de ejemplo y su formato Alink.

Ejemplo Formato Alink Descripción

{
    "state": {
        "desired": {
            "LightSwitch": 0
        }
    },
    "metadata": {
        "desired": {
            "LightSwitch": {
                "timestamp": 1626319658
            }
        }
    }
}

{
      "method": "control", 
      "payload": { 
       "state": {
            "desired": {
                "LightSwitch": 0
            }
        },
        "metadata": {
            "desired": {
                "LightSwitch": {
                    "timestamp": 1626319658 
           }
          }
        }
      }, 
      "version": 2, 
      "timestamp": 1469564576
    }

La respuesta la indica el parámetro payload en los datos Alink.

En este ejemplo, la propiedad deseada LightSwitch se establece en 0.

En este ejemplo, el mensaje se imprime.

void demo_shadow_recv_handler(void *handle, const aiot_shadow_recv_t *recv, void *userdata)
{
    printf("demo_shadow_recv_handler, type = %d, productKey = %s, deviceName = %s\r\n",
            recv->type, recv->product_key, recv->device_name);

    switch (recv->type) {
...
...
        case AIOT_SHADOWRECV_CONTROL: {
            const aiot_shadow_recv_control_t *control = &recv->data.control;

            printf("payload = \"%.*s\", version = %ld\r\n",
                   control->payload_len,
                   control->payload,
                   (unsigned long)control->version);
        }
……
...
        default:
            break;
    }
}

Una vez que el dispositivo actualiza el estado local, envía el estado más reciente a la sombra de dispositivo y procesa la respuesta.

Para obtener más información, consulte

Step 3: Submit the device status

.

El dispositivo llama a la operación aiot_shadow_send para eliminar las propiedades deseadas.

Al eliminar propiedades deseadas, tenga en cuenta los siguientes puntos:

aiot_shadow_msg_t indica el formato de datos. Este parámetro es un parámetro de entrada de la devolución de llamada aiot_shadow_send().
AIOT_SHADOWMSG_CLEAN_DESIRED indica el tipo de mensaje.
En este ejemplo, se eliminan todas las propiedades deseadas y el número de versión se establece en 1.

int32_t demo_clean_shadow_desired(void *shadow_handle, int64_t version)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_CLEAN_DESIRED;
    message.data.clean_desired.version = version;

    return aiot_shadow_send(shadow_handle, &message);
}
……
...
        res = demo_clean_shadow_desired(shadow_handle, 1);
        if (res < 0) {
            printf("demo_clean_shadow_desired failed, res = -0x%04x\r\n", -res);
        }

Cuando IoT Platform recibe la solicitud para eliminar propiedades deseadas, devuelve una respuesta. En este caso, se llama a la devolución de llamada demo_shadow_recv_handler.

Para obtener más información, consulte

Configure a callback to process responses

.

Paso 5: Solicitar la sombra de dispositivo

El dispositivo llama a la operación aiot_shadow_send para solicitar el contenido de la sombra de dispositivo a IoT Platform.

AIOT_SHADOWMSG_GET

indica el tipo de mensaje.

int32_t demo_get_shadow(void *shadow_handle)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_GET;

    return aiot_shadow_send(shadow_handle, &message);
}
……
...
        res = demo_get_shadow(shadow_handle);
        if (res < 0) {
            printf("demo_get_shadow failed, res = -0x%04x\r\n", -res);
        }

Cuando IoT Platform recibe la solicitud, devuelve una respuesta. Una vez que el dispositivo recibe la respuesta, se llama a la devolución de llamada demo_shadow_recv_handler.

Al definir la lógica de la devolución de llamada, tenga en cuenta los siguientes puntos:

aiot_shadow_recv_t indica el formato de datos. Este parámetro es un parámetro de entrada de la devolución de llamada.
AIOT_SHADOWRECV_GET_REPLY indica el tipo de mensaje.

En la siguiente tabla se describe una respuesta de ejemplo y su formato Alink.

Ejemplo	Formato Alink	Descripción
`{ "status": "success", "state": { "reported": { } }, "metadata": { "reported": { } } }`	`{ "method": "reply", "payload": { "status": "success", "state": { "reported": { } }, "metadata": { "reported": { } } }, "version": 5, "timestamp": 1626320690 }`	La respuesta la indica el parámetro payload en los datos Alink. Esta respuesta de ejemplo indica que la solicitud fue exitosa. El parámetro reported no contiene datos, lo cual significa que no se enviaron propiedades.

En este ejemplo, el mensaje se imprime.

void demo_shadow_recv_handler(void *handle, const aiot_shadow_recv_t *recv, void *userdata)
{
    printf("demo_shadow_recv_handler, type = %d, productKey = %s, deviceName = %s\r\n",
            recv->type, recv->product_key, recv->device_name);

    switch (recv->type) {
...
...
        case AIOT_SHADOWRECV_GET_REPLY: {
            const aiot_shadow_recv_get_reply_t *get_reply = &recv->data.get_reply;

            printf("payload = \"%.*s\", version = %ld\r\n",
                   get_reply->payload_len,
                   get_reply->payload,
                   (unsigned long)get_reply->version);
        }
        default:
            break;
    }
}

Paso 6: Eliminar propiedades de la sombra de dispositivo

El dispositivo llama a la operación aiot_shadow_send para eliminar propiedades específicas de la sombra de dispositivo.

Al enviar una solicitud, tenga en cuenta los siguientes puntos:

aiot_shadow_msg_t indica el formato de datos. Este parámetro es un parámetro de entrada de la devolución de llamada aiot_shadow_send().
AIOT_SHADOWMSG_DELETE_REPORTED indica el tipo de mensaje.

int32_t demo_delete_shadow_report(void *shadow_handle, char *reported, int64_t version)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_DELETE_REPORTED;
    message.data.delete_reporte.reported = reported;
    message.data.delete_reporte.version = version;

    return aiot_shadow_send(shadow_handle, &message);
}

Especifique las propiedades que desea eliminar.

        res = demo_delete_shadow_report(shadow_handle, "{\"LightSwitch\":\"null\"}", 2);
        if (res < 0) {
            printf("demo_delete_shadow_report failed, res = -0x%04x\r\n", -res);
        }

Mensaje de ejemplo:

Ejemplo Formato Alink Descripción

"{\"LightSwitch\":\"null\"}", 2

{
      "method": "delete", 
      "state": {
        "reported": {
          "LightSwitch": "null", 
        }
      }, 
      "version": 2
    }

El contenido del mensaje está en formato JSON. El contenido lo indica el parámetro state en los datos Alink. Para obtener más información, consulte A device deletes shadow properties.

A continuación se describe el contenido del mensaje de este ejemplo:

Establezca la propiedad LightSwitch en null. Este valor indica que se borrarán todos los datos de la sombra de dispositivo.
Establezca el número de versión en 2.

Cuando IoT Platform recibe la solicitud, devuelve una respuesta. Una vez que el dispositivo recibe la respuesta, se llama a la devolución de llamada demo_shadow_recv_handler.

Para obtener más información, consulte

Configure a callback to process responses

.

Paso 7: Salir del programa

Llame a la operación aiot_shadow_deinit para destruir el shadow

    res = aiot_shadow_deinit(&shadow_handle);
    if (res < STATE_SUCCESS) {
        printf("aiot_shadow_deinit failed: -0x%04X\n", -res);
        return -1;
    }

Pasos siguientes

En este ejemplo, se genera el archivo ejecutable ./demos/shadow-basic-demo.

Para obtener más información, consulte Compile and run.
Importante
- Al configurar el archivo de código de ejemplo, elimine los símbolos de comentario (/* y */) a ambos lados del código y cambie los números de versión según sus escenarios reales.
- Al cambiar los números de versión, tenga en cuenta los siguientes puntos:
  - Los números de versión de las operaciones posteriores deben incrementarse. De lo contrario, IoT Platform devuelve un error.
  - Si establece el número de versión en -1, IoT Platform borra los datos de la sombra de dispositivo y actualiza el número de versión a 0.
Running logs.