IoT Platform:Sample code

Step 1: Initialize a client

1. Add header files.

   ...
   ……
   #include "aiot_ota_api.h"
   ……

2. Add the underlying dependency and configure the log output feature.

       aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
       aiot_state_set_logcb(demo_state_logcb);

3. Call the aiot_ota_init operation to create an OTA client instance and initialize the default parameters.

       ota_handle = aiot_ota_init();
       if (NULL == ota_handle) {
           printf("aiot_ota_init failed\r\n");
           aiot_mqtt_deinit(&mqtt_handle);
           return -2;
       }

Step 2: Configure required features

Call the aiot_ota_setopt operation to configure the following items.

1. Associate with an MQTT connection handle.
   Notice Before you set OTA update-specific parameters, make sure that device authentication information is specified. For more information, see Example.

   • Sample code

         aiot_ota_setopt(ota_handle, AIOT_OTAOPT_MQTT_HANDLE, mqtt_handle);

   • Parameters:

     Parameter	Example	Description
     AIOT_OTAOPT_MQTT_HANDLE	mqtt_handle	You must establish an MQTT connection. This parameter is used to associate with the MQTT connection handle.

2. Configure a callback to process OTA update commands.
   • Sample code

         aiot_ota_setopt(ota_handle, AIOT_OTAOPT_RECV_HANDLER, demo_ota_recv_handler);

   • Parameters:

     Parameter	Example	Description
     AIOT_OTAOPT_MQTT_HANDLER	demo_ota_recv_handler	This callback function is called when the device receives an OTA update command from IoT Platform.

Step 3: Submit the version number of the device

After the device establishes an MQTT connection with IoT Platform, call the aiot_ota_report_version operation to submit the version number of the device. IoT Platform determines whether an update is required based on the version number.

In this example, the submitted version number is 1.0.0. In actual business scenarios, you must obtain the version number from the device settings and specify the logic to submit the version number.

    cur_version = "1.0.0";
    res = aiot_ota_report_version(ota_handle, cur_version);
    if (res < STATE_SUCCESS) {
        printf("aiot_ota_report_version failed: -0x%04X\r\n", -res);
    }

Step 4: Receive update commands

1. After you add an update package to IoT Platform and initiate an update task, IoT Platform sends an update command to the device.
   For more information, see Add an update package.
2. The device calls the aiot_mqtt_recv operation to receive the message. After the device recognizes the message as an OTA update command, the demo_ota_recv_handler callback is called.
3. Specify the processing logic of the callback.
   When you specify the processing logic of the callback, take note of the following items:

   • IoT Platform uses the /ota/device/upgrade/${ProductKey}/${DeviceName} topic to send the OTA update command to the device.

     For more information about ${ProductKey} and ${DeviceName}, see Obtain device authentication information.

   • AIOT_OTARECV_FOTA indicates the message type.

     void demo_ota_recv_handler(void *ota_handle, aiot_ota_recv_t *ota_msg, void *userdata)
     {
         switch (ota_msg->type) {
             case AIOT_OTARECV_FOTA: {
                 uint32_t res = 0;
                 uint16_t port = 443;
                 uint32_t max_buffer_len = (8 * 1024);
                 aiot_sysdep_network_cred_t cred;
                 void *dl_handle = NULL;
                 void *last_percent = NULL;
     
                 if (NULL == ota_msg->task_desc) {
                     break;
                 }
          ……
          ……
     
     }

   • For more information about the Alink data format of OTA update commands, see Push OTA update package information to a device.
   • aiot_ota_recv_t indicates the data format. Link SDK automatically parses the received message.
   • You can specify the processing logic of the callback based on the sample code. For more information, see Step 5: Download the update package and perform an OTA update.

Step 5: Download the update package and perform an OTA update

After the demo_ota_recv_handler callback is called, the downloader initiates an HTTPS request to receive the OTA update package.

1. Initialize the downloader.
   Call the aiot_download_init operation to create a download client instance and initialize the default parameters.

               dl_handle = aiot_download_init();
               if (NULL == dl_handle) {
                   break;
               }
               printf("OTA target firmware version: %s, size: %u Bytes \r\n", ota_msg->task_desc->version,
                      ota_msg->task_desc->size_total);
   
               if (NULL != ota_msg->task_desc->extra_data) {
                   printf("extra data: %s\r\n", ota_msg->task_desc->extra_data);
               }
   
               memset(&cred, 0, sizeof(aiot_sysdep_network_cred_t));
               cred.option = AIOT_SYSDEP_NETWORK_CRED_SVRCERT_CA;
               cred.max_tls_fragment = 16384;
               cred.x509_server_cert = ali_ca_cert;
               cred.x509_server_cert_len = strlen(ali_ca_cert);

2. Set the parameters.
   Call the aiot_download_setopt operation to set the parameters that are related to the download task.

               /* Set the TLS protocol for downloading. */
               aiot_download_setopt(dl_handle, AIOT_DLOPT_NETWORK_CRED, (void *)(&cred));
               /* Set the port number of the server to be accessed. */
               aiot_download_setopt(dl_handle, AIOT_DLOPT_NETWORK_PORT, (void *)(&port));
               /* Specify the information of the download task, which can be obtained from the task_desc member in the ota_msg input parameter. The information includes the download URL, firmware size, and firmware signature. */
               aiot_download_setopt(dl_handle, AIOT_DLOPT_TASK_DESC, (void *)(ota_msg->task_desc));
               /* Set the callback that the SDK calls when the downloaded content is received. */
               aiot_download_setopt(dl_handle, AIOT_DLOPT_RECV_HANDLER, (void *)(demo_download_recv_handler));
               /* Set the maximum buffer length for a single download. Users are notified if the limit is reached. */
               aiot_download_setopt(dl_handle, AIOT_DLOPT_BODY_BUFFER_MAX_LEN, (void *)(&max_buffer_len));
               /* Specify the information that is shared among different calls of AIOT_DLOPT_RECV_HANDLER. In this example, the progress information is stored. */
               last_percent = malloc(sizeof(uint32_t));
               if (NULL == last_percent) {
                   aiot_download_deinit(&dl_handle);
                   break;
               }
               memset(last_percent, 0, sizeof(uint32_t));
               aiot_download_setopt(dl_handle, AIOT_DLOPT_USERDATA, (void *)last_percent);

3. Initiate a download request.
   1. Start the demo_ota_download_thread download thread.

                  res = pthread_create(&g_download_thread, NULL, demo_ota_download_thread, dl_handle);
                  if (res != 0) {
                      printf("pthread_create demo_ota_download_thread failed: %d\r\n", res);
                      aiot_download_deinit(&dl_handle);
                      free(last_percent);
                  } else {
                      /* Set the type of the downloading thread to detach. After the firmware is obtained, the downloading thread automatically exits. */
                      pthread_detach(g_download_thread);
                  }

   2. After the demo_ota_download_thread thread is enabled, call the aiot_download_send_request operation to initiate an HTTPS GET request to download the update package from the storage server.
      • Sample code

        void *demo_ota_download_thread(void *dl_handle)
        {
            int32_t     ret = 0;
        
            printf("starting download thread in 2 seconds ......\n");
            sleep(2);
        
            /* Initiate a request to download the update package from the storage server.  */
            /*
             * TODO: In this example, a single request is initiated to obtain all the content of the update package. 
             *       If the device has limited resources or the network connection is in poor condition, you can implement a segmented download.
             *
             *       aiot_download_setopt(dl_handle, AIOT_DLOPT_RANGE_START, ...);
             *       aiot_download_setopt(dl_handle, AIOT_DLOPT_RANGE_END, ...);
             *       aiot_download_send_request(dl_handle);
             *
             *      If you implement a segmented download, specify the preceding three statements in a loop. In this case, multiple requests are sent and multiple responses are received.
             *
             */
        
             ……
             ……
        
        }

      • Parameters:

        To implement a segmented download, set the AIOT_DLOPT_RANGE_START and AIOT_DLOPT_RANGE_END parameters.

        For example, if you want to download a 1,024-byte update package by using two segments, specify the following values for the parameters:

        • First segment: AIOT_DLOPT_RANGE_START=0, AIOT_DLOPT_RANGE_END=511
        • Second segment: AIOT_DLOPT_RANGE_START=512, AIOT_DLOPT_RANGE_END=1023
4. Receive the update package.
   1. After the download request is sent, call the aiot_download_recv operation to receive the update package by using the demo_ota_download_thread download thread. After the device receives the package, the demo_download_recv_handler callback is called. You must save the downloaded update package to the local storage or file system of the device.

      void *demo_ota_download_thread(void *dl_handle)
      {
           ……
           ……
      
           while (1) {
              /* Receive the firmware that is sent from the server. */
              ret = aiot_download_recv(dl_handle);
      
              /* After the firmware is downloaded, the return value of aiot_download_recv() is STATE_DOWNLOAD_FINISHED. Otherwise, the value is the number of bytes that are obtained. */  */
              if (STATE_DOWNLOAD_FINISHED == ret) {
                  printf("download completed\n");
                  break;
              }
          }
           ……
           ……
      }

   2. Define the demo_download_recv_handler callback to store the downloaded update package and perform an update.
      Note In this example, the response is printed. The logic to store and burn the update package is not specified. In actual business scenarios, you must store the update package and install the package to complete the OTA update.

      void demo_download_recv_handler(void *handle, const aiot_download_recv_t *packet, void *userdata)
      {
          uint32_t data_buffer_len = 0;
          uint32_t last_percent = 0;
          int32_t  percent = 0;
      
          /* You can set packet->type only to AIOT_DLRECV_HTTPBODY. */
          if (!packet || AIOT_DLRECV_HTTPBODY != packet->type) {
              return;
          }
          percent = packet->data.percent;
      
          /* userdata can store the data that needs to be shared between different calls of demo_download_recv_handler(). */
          /* In this example, the percentage of the firmware download progress is stored. */
          if (userdata) {
              last_percent = *((uint32_t *)(userdata));
          }
      
          data_buffer_len = packet->data.len;
      
          /* A negative value of percent indicates that an exception occurs during data receiving or the digest authentication fails. */
          if (percent < 0) {
              printf("exception: percent = %d\r\n", percent);
              if (userdata) {
                  free(userdata);
              }
              return;
          }
           ……
           ……
      
      }

5. Submit the download progress.

   After the demo_download_recv_handler callback is called, call the aiot_download_report_progress operation to submit the download progress and update errors to IoT Platform. The update errors include burning failure and network disconnection.

   • View the submitted progress:

     The progress is displayed in the IoT Platform console. For more information, see View update status.

   • Submit the progress in normal or abnormal condition:
     • If the download is successful, an integer that indicates the progress is submitted to IoT Platform. Link SDK automatically calculates the value of the percent parameter and submits the value to IoT Platform by using a callback.
     • If an error occurs during the download or the downloaded firmware fails to be burnt, the error is submitted to IoT Platform. For more information about error codes, see aiot_ota_protocol_errcode_t.

   void demo_download_recv_handler(void *handle, const aiot_download_recv_t *packet, void *userdata)
   {
        ……
        ……
       /*
        * TODO:
        *       After you download the update package, save the memory whose initial position is packet->data.buffer and length is packet->data.len to the local storage location or file system of the device. 
        *
        *      If the burning fails, you must call the aiot_download_report_progress(handle, -4) operation to submit the error message to IoT Platform. 
        */
       /* If the value of percent is 100, all the content of the update package is downloaded.  */
       if (percent == 100) {
           /*
            * TODO: Burn the firmware, save the configurations, restart the device, and then switch to the new firmware to boot the device. 
                    The device must submit the version number of the new firmware to IoT Platform after the update.
   
                    aiot_ota_report_version(ota_handle, new_version);
   
                    For example, if the version is updated from 1.0.0 to 1.1.0, the value of new_version is 1.1.0 must be submitted to IoT Platform. 
                    IoT Platform determines that the update is successful after it receives the version number of the new firmware. Otherwise, IoT Platform determines that the update fails. 
            */
       }
   
       /* Simplify the output. Each time the download progress increases by at least 5%, the progress is printed and submitted to IoT Platform. */
       if (percent - last_percent >= 5 || percent == 100) {
           printf("download %03d%% done, +%d bytes\n", percent, data_buffer_len);
           aiot_download_report_progress(handle, percent);
           if (userdata) {
               *((uint32_t *)(userdata)) = percent;
           }
       }
   }

6. Exit the downloader.

   After the update package is downloaded, call the aiot_download_deinit operation to destroy the download session. Then, the download thread is closed.

       aiot_download_deinit(&dl_handle);
       printf("download thread exit\n");

Step 6: Submit the version number after the update

For more information, see Step 3: Submit the version number of the device.

Step 7: End the connection

Call the aiot_mqtt_disconnect operation to disconnect the device from IoT Platform.

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

Step 8: Exit the program

Call the aiot_ota_deinit operation to destroy the OTA client instance and release resources.

    aiot_ota_deinit(&ota_handle);