IoT Platform:Usage example

Step 1: Initialization

1. Add the header file.
   

   ……
   ……
   
   #include "aiot_bootstrap_api.h"

2. Configure underlying dependencies and log output.

       aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
       aiot_state_set_logcb(demo_state_logcb);

3. Call aiot_bootstrap_init to create a Bootstrap

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

Step 2: Configure features

Call aiot_bootstrap_setopt to configure the following features.

• Configure connection parameters.

• Configure message callbacks.

• Configure event callbacks.

1. Important

   The security connection type for the Transport Layer Security (TLS) layer must be certificate-based (AIOT_SYSDEP_NETWORK_CRED_SVRCERT_CA).

   •     int32_t res = STATE_SUCCESS;
         void *bootstrap_handle = NULL, *mqtt_handle = NULL;
         aiot_sysdep_network_cred_t cred;
         demo_info_t demo_info;
     
         /* TODO: Replace with your device's productKey and deviceName. */
         char *product_key       = "a18wP******";
         char *device_name       = "LightSwitch";
         char *device_secret     = "uwMTmVAMnGGHaAkqmeDY6cHxxB******";
         ……
         ……
         memset(&cred, 0, sizeof(aiot_sysdep_network_cred_t));
         cred.option = AIOT_SYSDEP_NETWORK_CRED_SVRCERT_CA;  /* Use an RSA certificate to authenticate the MQTT server. */
         cred.max_tls_fragment = 16384; /* The maximum shard length is 16 KB. Other valid values are 4 KB, 2 KB, 1 KB, and 0.5 KB. */
         cred.sni_enabled = 1;                               /* Support Server Name Indicator (SNI) during TLS connection establishment. */
         cred.x509_server_cert = ali_ca_cert;                 /* The RSA root certificate used to authenticate the MQTT server. */
         cred.x509_server_cert_len = strlen(ali_ca_cert);     /* The length of the RSA root certificate used to authenticate the MQTT server. */
         ……
         ……
         aiot_bootstrap_setopt(bootstrap_handle, AIOT_BOOTSTRAPOPT_HOST, (void *)host);
         aiot_bootstrap_setopt(bootstrap_handle, AIOT_BOOTSTRAPOPT_PORT, (void *)&port);
         aiot_bootstrap_setopt(bootstrap_handle, AIOT_BOOTSTRAPOPT_PRODUCT_KEY, (void *)product_key);
         aiot_bootstrap_setopt(bootstrap_handle, AIOT_BOOTSTRAPOPT_DEVICE_NAME, (void *)device_name);
         aiot_bootstrap_setopt(bootstrap_handle, AIOT_BOOTSTRAPOPT_NETWORK_CRED, (void *)&cred);
     
         ……
         ……

   • Parameter	Example	Description
     product_key	a18wP******	The device authentication information. For more information, see Obtain device verification information. In this example, the unique-certificate-per-device authentication method is used. The device_secret parameter is used when the device establishes an MQTT connection after obtaining the connection domain name and port number.
     device_name	LightSwitch
     device_secret	uwMTmVAMnGGHaAkqmeDY6cHxxB******

2. Configure message callbacks.

   •     aiot_bootstrap_setopt(bootstrap_handle, AIOT_BOOTSTRAPOPT_RECV_HANDLER, (void *)demo_bootstrap_recv_handler); 
         aiot_bootstrap_setopt(bootstrap_handle, AIOT_BOOTSTRAPOPT_USERDATA, (void *)&demo_info);

   • Configuration item	Example value	Description
     AIOT_BOOTSTRAPOPT_RECV_HANDLER	demo_bootstrap_recv_handler	This function is called when a device distribution message is received.
     AIOT_BOOTSTRAPOPT_USERDATA	demo_info	Sets the user context. When demo_bootstrap_recv_handler is triggered, userdata is returned. Cast the returned data to the appropriate type before use.

3. Configure status monitoring.

   1. Define the callback to monitor status.

      void demo_bootstrap_event_handler(void *handle, const aiot_bootstrap_event_t *event, void *userdata)
      {
          switch (event->type) {
              case AIOT_BOOTSTRAPEVT_INVALID_RESPONSE: {
                  printf("AIOT_BOOTSTRAPEVT_INVALID_RESPONSE\n");
              }
              break;
              case AIOT_BOOTSTRAPEVT_INVALID_CMD: {
                  printf("AIOT_BOOTSTRAPEVT_INVALID_CMD\n");
              }
              break;
              default: {
      
              }
              break;
          }
      }

   2. Specify the callbacks to monitor status.

      • Sample code:

            aiot_bootstrap_setopt(bootstrap_handle, AIOT_BOOTSTRAPOPT_EVENT_HANDLER, (void *)demo_bootstrap_event_handler);

      • Parameters:

        Configuration item	Example value	Description
        AIOT_BOOTSTRAPOPT_EVENT_HANDLER	demo_bootstrap_event_handler	When the device connection status changes, the corresponding processing logic defined in this callback function is executed.

Step 3: Send a request

Call aiot_bootstrap_send_request to send an HTTPS device distribution request to the server based on the parameters configured in the previous step.

For more information about the HTTPS request, see Request data format for device distribution.

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

Step 4: Receive an acknowledgement

1. After the message is sent, IoT Platform returns a response. The device calls aiot_bootstrap_recv to receive the response data and process it through the message callback.

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

2. Write the logic for the callback function.

   Write the logic for the callback function based on the following information:

   Message type	Description
   AIOT_BOOTSTRAPRECV_STATUS_CODE	The HTTP status code returned by the server. For more information, see HTTP status codes. The sample code does not process the received status code. Add your own processing logic as needed.
   AIOT_BOOTSTRAPRECV_CONNECTION_INFO	The acknowledgement message that IoT Platform returns after device distribution is initiated. The received message is of the aiot_bootstrap_recv_t type. Save the host and port values, which are the domain name and port number for device connection, to your local device. The sample code only prints the received device distribution message.
   AIOT_BOOTSTRAPRECV_NOTIFY	The device distribution notification message pushed by IoT Platform. After you perform the device distribution operation in IoT Platform, a device distribution message is pushed to the device. For more information, see Device distribution in IoT Platform. The sample code only prints the message. Add logic to disconnect the device, send a new device distribution request, and then re-establish the connection.

   void demo_bootstrap_recv_handler(void *handle, const aiot_bootstrap_recv_t *packet, void *userdata)
   {
       demo_info_t *demo_info = (demo_info_t *)userdata;
   
       switch (packet->type) {
           case AIOT_BOOTSTRAPRECV_STATUS_CODE: {
               demo_info->code = packet->data.status_code.code;
           }
           break;
           case AIOT_BOOTSTRAPRECV_CONNECTION_INFO: {
               demo_info->host = malloc(strlen(packet->data.connection_info.host) + 1);
               if (demo_info->host != NULL) {
                   memset(demo_info->host, 0, strlen(packet->data.connection_info.host) + 1);
                   /* TODO: In the callback, store the device distribution message content in a specified location. This space will then be released by the SDK. */
                   memcpy(demo_info->host, packet->data.connection_info.host, strlen(packet->data.connection_info.host));
                   demo_info->port = packet->data.connection_info.port;
               }
           }
           break;
           case AIOT_BOOTSTRAPRECV_NOTIFY: {
               printf("AIOT_BOOTSTRAPRECV_NOTIFY, cmd: %d\n", packet->data.notify.cmd);
   
           }
           default: {
   
           }
           break;
       }
   }

(Optional) Step 5: Establish an MQTT connection

After you obtain the required domain name and port for the device, establish an MQTT connection between the device and IoT Platform. For more information about MQTT connections, see MQTT connection.

After the MQTT connection is established, perform the following steps to initiate device distribution again.

1. Call aiot_bootstrap_setopt to associate the MQTT connection handle.

   •     aiot_bootstrap_setopt(bootstrap_handle, AIOT_BOOTSTRAPOPT_MQTT_HANDLE, (void *)mqtt_handle);

   • Configuration item	Example	Description
     AIOT_BOOTSTRAPOPT_MQTT_HANDLE	mqtt_handle	This callback function is triggered when the device receives a device distribution message pushed by IoT Platform.

2. Log in to the IoT Platform console and perform the device distribution operation.

   For more information, see Device distribution in IoT Platform.

3. When the device receives the pushed device distribution message, it goes offline. Then, repeat Step 1 to Step 4 to obtain the new device connection domain name and reconnect the device to IoT Platform.

Step 6: Exit the program

Call aiot_bootstrap_deinit to destroy the bootstrap client instance and release resources.

    res = aiot_bootstrap_deinit(&bootstrap_handle);
    if (res < 0) {
        printf("demo_start_stop failed\n");
        return -1;
    }