Device OTA upgrade

Basic OTA update process

1. The device reports its version number.

2. The device subscribes to OTA update-related topics.

3. In the IoT Platform console, you can configure an OTA update task on the OTA Update page. You can specify the devices to update based on multiple dimensions.

4. A device that has subscribed to the OTA update topics receives a push message for the configured OTA update task. The message includes:

   • The version number to which the device can be updated.

   • The URL, size, and MD5 hash of the OTA update package.

5. The device downloads the OTA update package, starts the update, and reports the update progress.

6. After the update is complete, the device automatically reports the new version number.

For more information about how to configure an OTA update, see OTA update overview.

Limits

During an OTA upgrade, the upgrade package must be downloaded over HTTPS.

• When you verify an upgrade package and create an update batch in the IoT Platform console, set Upgrade Package Download Protocol to HTTPS. For more information, see Verify an upgrade package and Create an update batch.

• When you call the cloud APIs to verify an upgrade package (CreateOTAVerifyJob) and create an update batch (CreateOTAStaticUpgradeJob and CreateOTADynamicUpgradeJob), you must set the DownloadProtocol request parameter to HTTPS.

SDK implementation method

For more information about the code, see the ota_demo.py file in the demo package.

1. Register an OTA callback and configure an OTA upgrade task in the IoT Platform console.

2. When an OTA update is pushed, the on_ota_message_arrived callback returns information about the OTA upgrade package, such as its URL, version number, size, signature, module name, and signature method.

   Then, you can perform an OTA update based on the preceding information. If you want to perform an OTA update, call the download_ota_firmware function.

   from linkkit import linkkit
   import logging
   import time
   
   
   def on_ota_message_arrived(ota_notice_type, version, size, url, sign_method, sign, module, extra):
       # If ota_notice_type is 0, no OTA task is deployed on the server. If it is 1, an OTA task is pushed from the cloud. If it is 2, the device actively queries the server for an OTA task.
       if ota_notice_type > 0:
           # TODO: Check the version number to decide whether to upgrade and when to start the upgrade.
   
           # TODO: If the firmware download is slow, run it in a separate thread to avoid blocking the main process. 
           # If your device might receive multiple OTA messages in a short time, such as from multiple active requests or a mix of pushes and requests, you must manage concurrency. 
           # This prevents multiple threads from writing to the same file simultaneously.
   
           print("on_ota_message version:" + version + " size:" + str(size) + " url:" + url + " sign_method:" + sign_method)
           print("on_ota_message sign:" + sign + " module:" + module + " extra:" + extra)
           # TODO: Modify the firmware_path variable to store the firmware in a custom path.
           firmware_path = "demo_ota.py"
           ret = lk.download_ota_firmware(url, firmware_path, sign_method, sign)
   
           if lk.ErrorCode.SUCCESS == ret:
               # TODO: Deploy the new firmware, report the new version number, and confirm that the upgrade is complete.
               print("report version ")
               lk.ota_report_version(module, version)
               pass
           else:
               print("download error code %x" % ret.value)
       else:
           print("no firmware ")
   
   # TODO: Enter the device certificate information.
   lk = linkkit.LinkKit(
       host_name="cn-shanghai",
       product_key="${YourProductKey}",
       device_name="${YourDeviceName}",
       device_secret="${YourDeviceSecret}")
   # TODO: Enter the MQTT endpoint.
   lk.config_mqtt(endpoint="${YourInstanceId}")
   lk.on_ota_message_arrived = on_ota_message_arrived
   __log_format = '%(asctime)s-%(process)d-%(thread)d - %(name)s:%(module)s:%(funcName)s - %(levelname)s - %(message)s'
   logging.basicConfig(format=__log_format)
   lk.enable_logger(logging.DEBUG)
   lk.connect_async()
   
   while True:
       time.sleep(1)

3. After the OTA upgrade package is downloaded, you must upgrade the device using your own OTA method. After the upgrade is complete, call the ota_report_version function to report the new version number. IoT Platform receives the new version number and compares it with the target version number. If the version numbers match, the upgrade is considered successful.

Actively download an OTA upgrade package

By default, the SDK passively receives upgrade messages from the server. The SDK also allows a device to actively query the cloud for OTA upgrade messages.

def query_ota_firmware(self, module=None)