:Integración de un Link SDK en un módulo WAN basado en TCP

A continuación se muestra el proceso para conectar a IoT Platform un dispositivo que contiene un módulo de comunicación con un Link SDK integrado.

Operaciones en la consola de IoT Platform

Para comprobar que un Link SDK integrado en un módulo funciona correctamente, debe conectar un dispositivo de prueba a IoT Platform. Para ello, cree un producto en la consola de IoT Platform y luego agregue un dispositivo dentro de ese producto para obtener su información de identidad.

1. Inicie sesión en la consola de IoT Platform. Si inicia sesión como proveedor de módulos, necesitará una cuenta de Alibaba Cloud. Esta cuenta se crea de forma gratuita.

2. Una vez iniciada la sesión en IoT Platform, siga los pasos descritos en el tema Create a product para crear un producto. En la página de detalles del producto, consulte el ProductKey y el ProductSecret correspondientes.

3. Cree un dispositivo de prueba. En la página de detalles del dispositivo, consulte el DeviceName y el DeviceSecret correspondientes.

Proceso de integración de un Link SDK

Cuando un proveedor de módulos integra un Link SDK, el proceso abarca varias etapas, tal como se muestra en la siguiente figura.

Configuración de un Link SDK y extracción del código

Configurar el Link SDK

Un Link SDK ofrece una gran cantidad de funciones. A continuación se explica cómo configurar las funciones que requiere este ejemplo.

Ejecutar un comando de configuración

• Linux

  Vaya al directorio raíz del Link SDK y ejecute el siguiente comando:

  make menuconfig
              

• Windows

  Vaya al directorio raíz del Link SDK y ejecute el siguiente comando:

  config.bat

Con cualquiera de los métodos anteriores se inicia la herramienta de configuración del Link SDK. La siguiente imagen muestra la interfaz gráfica de dicha herramienta.

Habilitar las funciones necesarias

En la interfaz gráfica, presione la barra espaciadora para seleccionar o deseleccionar una función. Use las flechas hacia arriba o hacia abajo del teclado numérico para desplazarse entre las opciones. Si desea conocer los detalles de una opción, muévala con las flechas hasta posicionar el cursor sobre ella y presione la tecla H. De esta manera se mostrará la descripción de la opción y las acciones del sistema que se ejecutan al seleccionarla o deseleccionarla.

• Si el entorno de compilación incluye el archivo de encabezado stdint.h, seleccione la siguiente opción.

  PLATFORM_HAS_STDINT

• Si en su entorno se ejecuta un sistema operativo embebido, seleccione la siguiente opción.

  PLATFORM_HAS_OS

• Si el módulo admite TCP en lugar de Message Queuing Telemetry Transport (MQTT), debe habilitar las siguientes opciones:

  • FEATURE_MQTT_COMM_ENABLED: proporciona la API MQTT del Alibaba SDK para permitir la comunicación entre los dispositivos e IoT Platform.

  • FEATURE_MQTT_DEFAULT_IMPL: proporciona la implementación de MQTT Client predefinida en el Alibaba SDK. Debe escribir código para crear y establecer conexiones TCP, así como para transmitir datos a través de dichas conexiones con base en esta implementación.

  • FEATURE_MQTT_DIRECT: proporciona los endpoints de IoT Platform a los que se pueden conectar los dispositivos.

Se recomienda seleccionar la opción FEATURE_SUPPORT_TLS. Al hacerlo, se cifran los datos transmitidos entre los dispositivos e IoT Platform. En este ejemplo no se selecciona la opción para reducir la carga de trabajo de configuración.

No es necesario habilitar ninguna otra función.

Extraer el código fuente de las funciones seleccionadas

Integrar los archivos de código del Link SDK en el entorno de compilación

Copie los archivos de código obtenidos en el paso anterior desde el directorio output hacia el directorio de su proyecto. Después, modifique su entorno de compilación o herramienta de desarrollo para integrarlos.

Implementar las funciones de la capa de abstracción de hardware (HAL)

Los Link SDK están diseñados para ejecutarse en distintos sistemas operativos o en MCU que no admiten sistemas operativos. Las operaciones relacionadas con el sistema operativo se definen como funciones HAL que usted debe implementar. El sistema operativo varía según el módulo de comunicación. Las operaciones TCP que desea ejecutar en el módulo también se definen como funciones HAL que debe implementar.

Todas las funciones HAL se encuentran en el archivo output/eng/wrappers/wrapper.c.

Funciones HAL relacionadas con el sistema operativo

A continuación se describen las funciones HAL que debe implementar.

El directorio wrappers/os del paquete comprimido del SDK incluye ejemplos sobre cómo implementar las funciones HAL. Si alguno cumple con los requisitos de su sistema operativo, puede utilizarlo. De lo contrario, deberá implementar las funciones HAL según su escenario de negocio.

Funciones HAL opcionales

Si el módulo no ejecuta ningún sistema operativo o si varios hilos no invocan la API MQTT del Link SDK, no es necesario modificar las definiciones de las siguientes funciones en el archivo wrapper.c. En cambio, si el módulo sí ejecuta un sistema operativo y varios hilos llaman a la API MQTT del Link SDK, debe implementar estas funciones.

Funciones HAL relacionadas con TCP

Las conexiones MQTT se establecen sobre TCP. Un proveedor de módulos debe implementar las siguientes funciones HAL relacionadas con TCP.

Funciones HAL relacionadas con el producto

Las siguientes funciones HAL se invocan para obtener la información de verificación de identidad de un producto. El fabricante del dispositivo debe proporcionar instrucciones para grabar la información de identidad en el equipo, obtenerla mediante estas funciones HAL y luego configurarla en el Link SDK.

Al configurar un producto en escenarios reales, los elementos de datos anteriores deben enviarse al módulo mediante los comandos AT del fabricante del dispositivo. Cuando un proveedor de módulos depura un dispositivo de prueba, puede obtener el ProductKey, el DeviceName y el DeviceSecret del equipo llamando a las funciones anteriores.

Implementar las funciones del producto con base en el código de ejemplo

Un proveedor de módulos puede depurar funciones con base en el archivo eng/examples/mqtt_example.c ubicado en el directorio output. Un fabricante de dispositivos puede copiar dicho archivo a su propio proyecto y modificarlo para utilizar alguna función.

El código de ejemplo del archivo sirve para conectar un dispositivo a IoT Platform, suscribirse a un topic y enviar datos a ese topic. En este caso, IoT Platform envía los datos remitidos por el dispositivo a todos los equipos suscritos al mismo topic. La siguiente figura ilustra el funcionamiento del código de ejemplo.

Debe cambiar el permiso predeterminado del topic de Subscribe a Publish and Subscribe en la consola de IoT Platform.

El código de ejemplo comienza en la función main(). Dentro de su definición se invocan las funciones HAL relacionadas con el producto para obtener la información de identidad, como se muestra en el siguiente código.

int main(int argc, char *argv[])
{
    void                   *pclient = NULL;
    int                     res = 0;
    int                     loop_cnt = 0;
    iotx_mqtt_param_t       mqtt_params;

    HAL_GetProductKey(DEMO_PRODUCT_KEY);
    HAL_GetDeviceName(DEMO_DEVICE_NAME);
    HAL_GetDeviceSecret(DEMO_DEVICE_SECRET);

    EXAMPLE_TRACE("mqtt example");
            

• Las funciones HAL anteriores, que comienzan con HAL_Get, se invocan para obtener la información del certificado del dispositivo. Un proveedor de módulos puede especificar la información del certificado de un dispositivo de prueba.

El siguiente código muestra cómo configurar los parámetros de conexión MQTT según sus necesidades de negocio.

/* Initialize MQTT parameter */
    memset(&mqtt_params, 0x0, sizeof(mqtt_params));
    mqtt_params.port = sign_mqtt.port;
    mqtt_params.host = sign_mqtt.hostname;
    mqtt_params.client_id = sign_mqtt.clientid;
    mqtt_params.username = sign_mqtt.username;
    mqtt_params.password = sign_mqtt.password;
    mqtt_params.request_timeout_ms = 2000;
    mqtt_params.clean_session = 0;
    mqtt_params.keepalive_interval_ms = 60000;
    mqtt_params.read_buf_size = 1024;
    mqtt_params.write_buf_size = 1024;
    mqtt_params.handle_event.h_fp = example_event_handle;
    mqtt_params.handle_event.pcontext = NULL;
    pclient = IOT_MQTT_Construct(&mqtt_params);
            

Llame a la función IOT_MQTT_Construct() del Link SDK para conectar el dispositivo a IoT Platform. Si la función devuelve un valor distinto de nulo, la conexión con IoT Platform se estableció correctamente. Luego, invoque la función example_subscribe para suscribirse a un topic.

res = example_subscribe(pclient);
            

• El fabricante del dispositivo debe suscribirse a un topic e implementar una función de procesamiento según el diseño de sus productos.

• En el código de ejemplo anterior, el fragmento dentro del primer rectángulo naranja indica que el topic tiene el formato /$ProductKey/$DeviceName. Cuando crea un producto en la consola de IoT Platform, el sistema genera automáticamente un topic con ese formato.

• El código dentro del segundo rectángulo naranja especifica la información del topic.

• El código dentro del segundo rectángulo naranja define cómo suscribirse al topic y qué función se invoca para procesar los datos recibidos.

El siguiente código muestra cómo usar la función de publicación de MQTT para enviar paquetes de negocio a IoT Platform.

 while (1) {
        if (0 == loop_cnt % 20) {
            example_publish(pclient);
        }

        IOT_MQTT_Yield(pclient, 200);

        loop_cnt += 1;
    }
            

• El código de ejemplo anterior envía periódicamente un mensaje fijo a IoT Platform. Se recomienda que el fabricante del dispositivo envíe únicamente los datos necesarios, de acuerdo con las características de sus propios productos.

• Para evitar el envío periódico de datos no válidos a IoT Platform, elimine la instrucción example_publish(pclient) de la función main().

• La función IOT_MQTT_Yield del Link SDK se invoca para recibir datos de un broker MQTT. El valor 200 indica que la función debe esperar 200 milisegundos antes de recibir los datos. Si maneja una gran cantidad de mensajes o tiene requisitos estrictos de latencia, especifique un valor menor.

En la figura anterior, el código dentro del primer rectángulo naranja define el contenido del mensaje que se enviará. El código dentro del segundo rectángulo naranja invoca una función del Link SDK para enviar el mensaje a un topic específico.

Cargar el identificador del proveedor de módulos y el modelo del módulo

Si un proveedor de módulos desea verificar un módulo en IoT Platform, debe enviar el identificador del proveedor y el modelo del módulo. De esta manera, IoT Platform puede contabilizar la cantidad de dispositivos conectados por identificador de proveedor o por modelo de módulo.

Antes de integrar un Link SDK, comuníquese con Alibaba Cloud para obtener un identificador de proveedor y un modelo de módulo. Para ello, envíe un mensaje con la siguiente plantilla. Para más información, visite Contáctenos.

Subject: Use a Link SDK to connect a device - Apply for module or chip model

Una vez conectado el módulo a IoT Platform, copie el siguiente código en su entorno y ejecute la función incluida para enviar la información. El parámetro pid especifica el identificador del proveedor de módulos y el parámetro mid indica el identificador del modelo del módulo.

#define PID_STRING_LEN_MAX          32  /* The maximum length of the value of the pid parameter. The value is a string.*/
#define MID_STRING_LEN_MAX          32  /* The maximum length of the value of the mid parameter. The value is a string.*/

int example_report_pid_mid(void *pclient, const char *product_key, const char *device_name, const char *pid, const char *mid)
{
    int res = 0;
    iotx_mqtt_topic_info_t topic_msg;

    const char topic_frag1[] = "/sys/";
    const char topic_frag2[] = "/thing/deviceinfo/update";
    char topic[sizeof(topic_frag1) + sizeof(topic_frag2) + IOTX_PRODUCT_KEY_LEN + IOTX_DEVICE_NAME_LEN] = {0};

    const char payload_frag1[] = "{\"id\":\"0\",\"version\":\"1.0\",\"params\":[{\"attrKey\":\"SYS_MODULE_ID\",\"attrValue\":\"";
    const char payload_frag2[] = "\",\"domain\":\"SYSTEM\"},{\"attrKey\":\"SYS_PARTNER_ID\",\"attrValue\":\"";
    const char payload_frag3[] = "\",\"domain\":\"SYSTEM\"}],\"method\": \"thing.deviceinfo.update\"}";
    char payload[sizeof(payload_frag1) + sizeof(payload_frag2) + sizeof(payload_frag3) + PID_STRING_LEN_MAX + MID_STRING_LEN_MAX] = {0};

    if (strlen(pid) > PID_STRING_LEN_MAX || strlen(mid) > MID_STRING_LEN_MAX) {
        return -1;
    }

    /* Combine strings to create an MQTT topic. */
    memcpy(topic, topic_frag1, strlen(topic_frag1));
    memcpy(topic + strlen(topic), product_key, strlen(product_key));
    memcpy(topic + strlen(topic), "/", 1);
    memcpy(topic + strlen(topic), device_name, strlen(device_name));
    memcpy(topic + strlen(topic), topic_frag2, strlen(topic_frag2));

    /* Combine strings to create the payload of the MQTT topic. The payload includes the values of the pid and mid parameters. */
    memcpy(payload, payload_frag1, strlen(payload_frag1));
    memcpy(payload + strlen(payload), mid, strlen(mid));
    memcpy(payload + strlen(payload), payload_frag2, strlen(payload_frag2));
    memcpy(payload + strlen(payload), pid, strlen(pid));
    memcpy(payload + strlen(payload), payload_frag3, strlen(payload_frag3));

    topic_msg.qos = IOTX_MQTT_QOS0;
    topic_msg.retain = 0;
    topic_msg.dup = 0;
    topic_msg.payload = (void *)payload;
    topic_msg.payload_len = strlen(payload);

    /* Call the MQTT IOT_MQTT_Publish to send a message that include the values of the pid and mid parameters.*/
    res = IOT_MQTT_Publish(pclient, topic, &topic_msg);
    if (res < 0) {
        return -1;
    }

    return 0;
}

            

Depurar funciones

Las siguientes capturas de pantalla muestran el resultado obtenido después de modificar y ejecutar el archivo mqtt_example.c.

Comprobar si un dispositivo está conectado a IoT Platform

De forma predeterminada, un dispositivo tiene el permiso Subscribe sobre el topic /${productKey}/${deviceName}/get. Para evitar que los mensajes se pierdan después de enviarlos a IoT Platform, se recomienda cambiar el permiso del topic a Subscribe and Publish. Así, el programa de ejemplo se ejecutará correctamente y sin errores.

Comprobar si un dispositivo envía datos a IoT Platform

La figura anterior muestra el topic al que se envió un mensaje, aunque no despliega su contenido.

Comprobar si un dispositivo recibe datos de IoT Platform

Implementar comandos AT

Un proveedor de módulos no ofrece un entorno de desarrollo para personalizar el módulo. En su lugar, conecta una MCU externa donde se ejecuta la lógica de negocio del producto. En este caso, el proveedor debe proporcionar comandos AT que la MCU pueda invocar. En la mayoría de los casos, los módulos solo admiten TCP, por lo que es necesario ofrecer operaciones de API para configurar conexiones MQTT, establecerlas, cerrarlas, suscribirse a mensajes y publicarlos.

La siguiente tabla describe los comandos AT recomendados. Un proveedor de módulos puede combinar varios comandos AT en uno solo o dividir un comando en varios. También puede definir un formato personalizado para dichos comandos.

Cuando la MCU ejecute comandos AT para enviar la información de identidad del dispositivo al módulo, se recomienda asignar dicha información a variables globales. De esta manera, las funciones HAL_GetProductKey, HAL_GetDeviceName y HAL_GetDeviceSecret podrán devolver esas variables globales sin necesidad de modificar el código de ejemplo.