Skip to content
IoT Service

Configure OTA for HTTP protocol

Configure OTA for HTTP protocol

  • Provision groups and devices.

  • Create a file object in Data Ocean, upload the firmware/software update file, get the download url of the uploaded file to create firmware in IoT.

    • Note that the maximum file size supported is only 1GB.

  • Create OTA firmware in IoT.

  • Device must subscribe to below topics for OTA job notifications and to start executing the next job which has been queued

    • $aws/things/[clientId]/jobs/start-next/accepted
    • $aws/things/[clientId]/jobs/start-next/rejected
    • $aws/things/[clientId]/jobs/notify-next
    • $aws/things/[clientId]/jobs/notify

  • Create signature by signing the firmware/software update file using a valid certificate key (we recommend using the device certificate key).

    • Sample OpenSSL command to sign a firmware update json file using a ECDSA device certificate key: openssl dgst -ecdsa-with-SHA1 -sign deviceCert.key firmwareUpdate.json > signature

  • Convert the signature as a base64 encoded value to create a OTA Job in IoT, using the below sample OpenSSL command

    • openssl enc -base64 -in signature -out signature.base64

  • Create OTA jobs in IoT. Make note of the jobId for the final step.

  • Get Notification about the Job

    • When device is online,

      • Notification for the created job will be received in the topic : $aws/things/{clientId}/jobs/notify-next

        Response sample ( for jobs created without download URL expiry)  {   "timestamp": 1675063905,   "execution": {       "jobId": "AFR_OTA-616e1526-d4d4-4359-bfe2-c33b5d34af7d",       "status": "QUEUED",       "queuedAt": 1675060063,       "lastUpdatedAt": 1675060063,       "versionNumber": 1,       "executionNumber": 1,       "jobDocument": {           "afr_ota": {               "protocols": [                   "HTTP"               ],           "files": {               "filepath": "device/firmware.exe",               "fileid": 0,               "filesize": 35,               "certfile": "device/certificate.pem",               "update_data_url": "https://iotng-dev-ota-us-west-2.s3.us-west-2.amazonaws.com/729c8199-fb8d-4e42-a14f-5cf543e5c225/2ce18c8c-c40b-42d1-91f7-d641d65dc15f?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEBAaCXVzLXdlc3QtMiJHMEUCIQCbgaux09JZjS7t%2BpfKb%2F3z%2Fc7kdmw53dpoZIjE%2B%2FBhL6q1tftLRf8Knmnjwk8aKvDHe8U%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230130T073145Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Credential=ASIAS4MLL5FYZJH267LY%2F20230130%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=15546e2e136bd4621a03f27065c2ecb3acc34881f333139ff04172e11275dc49",               "auth_scheme": "aws.s3.presigned",                   "firmware_version": "v1",               "sig-sha-1-ecdsa": "MGQCMAFowjm/7sr1+gfr/jem47yyjH+Wnb5Lqt/Zk7Tt2sOAitwa4m+odKyvEJ1W\nchN1GgIwVaZvui4pzMVEjm7h+V8Q05jdr407OImOQL42jeWjIU7T1UpGUJFSAwv2\nsE75eYaX\n"           }       }   }   }   }

        • Field details
          • update_data_url - S3 pre-signed url from where firmwareUpdate file can be downloaded.
          • filesize - Length of the file block received. It is useful when a file has to be downloaded as multiple blocks.

        Response sample ( for jobs created with download URL expiry) {   "timestamp": 1683003253,   "execution": {       "jobId": "AFR_OTA-c8744d73-39c6-47b4-8606-12bb4481eaf4",       "status": "QUEUED",       "queuedAt": 1683003253,       "lastUpdatedAt": 1683003253,       "versionNumber": 1,       "executionNumber": 1,       "jobDocument": {       "afr_ota": {           "protocols": [           "HTTP"           ],           "files": {           "filepath": "c:/testfirmware",           "fileid": 0,           "filesize": 1362757,           "certfile": "c:/testcert",           "update_data_url": "https://do-ro-us1.stage.dataocean.trimblecloud.com/s/d9f5a86c-c4d2-4abd-8919-e754b142897d.1?response-content-disposition=attachment%253B%2Bfilename%253D%2522b120a9bd-785b-49b2-93cb-4b6f48182b69%2522%253B%2Bfilename%252A%253Dutf-8%2527%2527b120a9bd-785b-49b2-93cb-4b6f48182b69&response-content-type=text%252Fplain&Policy=eyJTdG&Signature=oNDxKJTxay&Key-Pair-Id=APKAJJH2YHAR4EAJ5QPQ",           "firmware_version": " 2.O",           "sig-sha-1-rsa": "RlTJmtB3CJN3WGxb2t9ISqGqUUqTA/2AxLx9i8wpXyPM/BhQgT5SxZQCKi00gmNrYP5rUpgbpdGi3glSTf\neJaywOQmKLbGLqEnEjdpMw==",   "job_expiration_utc": "2023-05-06T07:48:00.000Z"           }       }       }   }   }

      • Notification for all the jobs queued at that moment will be received in the topic : $aws/things/{clientId}/jobs/notify

        {
             "timestamp": 1672730954,
             "jobs": {
                 "QUEUED": [
                 {
                     "jobId": "AFR_OTA-616e1526-d4d4-4359-bfe2-c33b5d34af7d",
                     "queuedAt": 1672730953,
                     "lastUpdatedAt": 1672730953,
                     "executionNumber": 1,
                     "versionNumber": 1
                 }
                 ]
             }
             }

      • Publish empty message to start the pending job in the topic : $aws/things/{clientId}/jobs/start-next

      • Receive the response in the topic : aws/things/{clientId}/jobs/start-next/accepted

        Response sample ( for jobs created without download url expiry) {     "timestamp": 1675064242,     "execution": {         "jobId": "AFR_OTA-616e1526-d4d4-4359-bfe2-c33b5d34af7d",         "status": "IN_PROGRESS",         "queuedAt": 1675060063,         "startedAt": 1675064242,         "lastUpdatedAt": 1675064242,         "versionNumber": 2,         "executionNumber": 1,         "jobDocument": {             "afr_ota": {                 "protocols": [                     "HTTP"                 ],             "files": {                 "filepath": "device/firmware.exe",                 "fileid": 0,                 "filesize": 35,                 "certfile": "device/certificate.pem",                 "update_data_url": "https://iotng-dev-ota-us-west-2.s3.us-west-2.amazonaws.com/729c8199-fb8d-4e42-a14f-5cf543e5c225/2ce18c8c-c40b-42d1-91f7-d641d65dc15f?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEBAaCXVzLXdlc3QtMiJIMEYCIQDgh%2FOkSxZhJvgb81yVrxFTzMFD5PCAotDrAe9bmWJ26QIhAIkKYMN0ZL4JNvrTT7tFJNfyrFPEC4FSj7ZE4Xg0siv1KuYCCIn%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQAxoMMTk4Mzk3NjUxMzEzIgyXRswBL7IL%2BkbkDAsqugIWcPgtusFMf65kpVHLDl8kemJ7Tl0t2RR8vrxBaZoVcwBIw2hS8OpAAfWs7KtjYQ3fs4Tp%2B5RXTV6cPPK3cYuz9ZM9m5yKVMpUj41Z4hZciBSKSCpow55DdanthCJLI8%2BuVPzf2tg0VSIMdpHA2MeDbs%2BC0rZ43n5EWLggfrQd%2BTccimhCedOj2FJcQIRZrwXyrfDKmvBgKHO8giRrQoRWwHoOdVPVfpOcaQJmjAQVIsszPEnBBEHeRKuaSDga%2BJfUMK37ALUi%2BLbOASOv2%2F7y%2FP2iQrPiuu1MVPwzhLixl%2FnErKDkIG%2BkunbKTuRYijRI2DNIgsBZGmW9zQGz58rpEElfLWQuCh%2Fvlewr4v180NPR5hZCM7rg2G0DdDtlq3jc8I75yzslyykLgWIgxinmDWst2Ma7y4%2B%2BTzCy592eBjq%2BAY%2B846XsnwDU2eyjt845BBsJZYrE4DPkXM%2FpaZOGI4mbCpS4IazYZH0sCBdEez7Z%2B4oBMjbBtA2gtH1slqzKyJ45YvEBSpF6c%2FeDmKVGzZJMtj%2F6z1vcHFG98UIRdYNKZlvh3mOTv4WcGqOzJw9MZ4csR2cya3xTMn66cCuu%2B5EY2TGQSkgTyEcl%2B88SdGvBFzDNDA5f20XwoW0%2BYSaP1RNaL4ukzhlkBCGkgzQItsoJudguy4T05SEerW05hII%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230130T073722Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Credential=ASIAS4MLL5FYQ4Z624M6%2F20230130%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=76464bfb4c6ce6f659109eb73d9e3e910cf1edf5114e11dd7e16f4718257a4de",                 "auth_scheme": "aws.s3.presigned",                 "firmware_version": "v1",                 "sig-sha-1-ecdsa": "MGQCMAFowjm/7sr1+gfr/jem47yyjH+Wnb5Lqt/Zk7Tt2sOAitwa4m+odKyvEJ1W\nchN1GgIwVaZvui4pzMVEjm7h+V8Q05jdr407OImOQL42jeWjIU7T1UpGUJFSAwv2\nsE75eYaX\n"             }         }     } } }

      • Make note of the update_data_url to download the firmware update file.

        • The above update_data_url is a S3 pre-signed URL that will expire in 3600 seconds(60 mins). To get new update_data_url publish empty message to the topic : $aws/things/{clientId}/jobs/{jobId}/get

        Response sample ( for jobs created with download URL expiry) { "timestamp": 1683003440, "execution": {     "jobId": "AFR_OTA-c8744d73-39c6-47b4-8606-12bb4481eaf4",     "status": "IN_PROGRESS",     "queuedAt": 1683003253,     "startedAt": 1683003440,     "lastUpdatedAt": 1683003440,     "versionNumber": 2,     "executionNumber": 1,     "jobDocument": {     "afr_ota": {         "protocols": [         "HTTP"         ],         "files": {         "filepath": "c:/testfirmware",         "fileid": 0,         "filesize": 1362757,         "certfile": "c:/testcert",         "update_data_url": "https://do-ro-us1.stage.dataocean.trimblecloud.com/s/d9f5a86c-c4d2-4abd-8919-e754b142897d.1?response-content-disposition=attachment%253B%2Bfilename%253D%2522b120a9bd-785b-49b2-93cb-4b6f48182b69%2522%253B%2Bfilename%252A%253Dutf-8%2527%2527b120a9bd-785b-49b2-93cb-4b6f48182b69&response-content-type=text%252Fplain&Policy=eyJTdG&Signature=oNDxKJTxay&Key-Pair-Id=APKAJJH2YHAR4EAJ5QPQ",         "firmware_version": " 2.O",         "sig-sha-1-rsa": "RlTJmtB3CJN3WGxb2t9ISqGqUUqTA/2AxLx9i8wpXyPM/BhQgT5SxZQCKi00gmNrYP5rUpgbpdGi3glSTf\neJaywOQmKLbGLqEnEjdpMw==", "job_expiration_utc": "2023-05-06T07:48:00.000Z"         }     }     } } }

      • Make note of the update_data_url to download the firmware update file

        • The above update_data_url is a Data Ocean download URL that will expire in the duration set in the download url expiry while creating the OTA update job. The job will be canceled after this duration.
        • The job expiration time will be mentioned in the field ‘job_expiration_utc’.

      • Note the status of the job changes from QUEUED to IN_PROGRESS.

    • When device is offline,

      • Connect the device to turn it online

      • Subscribe to all OTA jobs topics

      • Publish empty message to start the pending job in the topic : $aws/things/{clientId}/jobs/start-next

        !!!Note If the device needs to check if any jobs are available after coming online, publish empty message to this topic $aws/things/{clientId}/jobs/get to get the list of jobs created while the device was offline.

      • Receive the response in the topic : aws/things/{clientId}/jobs/start-next/accepted

      • Make note of the update_data_url to download the firmware update file

        • The above update_data_url will expire in 3600 seconds(60 mins). To get new update_data_url publish empty message to the topic : $aws/things/{clientId}/jobs/{jobId}/get

      • Note the status of the job changes from QUEUED to IN_PROGRESS.

  • Download the firmware update file

    • Using the update_data_url from the job document download the firmware update file
    • To download firmware file as blocks/chunks use the “Range” header when downloading the file. This supports both S3 and DO urls. Sample curl command with the “Range” header. 
        curl --location --request GET 'https://iotng-dev-ota-us-west-2.s3.us-west-2.amazonaws.com/729c8199-fb8d-4e42-a14f-5cf543e5c225/2ce18c8c-c40b-42d1-91f7-d641d65dc15f?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEBAaCXVzLXdlc3QtMiJIMEYCIQDgh%2FOkSxZhJvgb81yVrxFTzMFD5PCAotDrAe9bmWJ26QIhAIkKYMN0ZL4JNvrTT7tFJNfyrFPEC4FSj7ZE4Xg0siv1KuYCCIn%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQAxoMMTk4Mzk3NjUxMzEzIgyXRswBL7IL%2BkbkDAsqugIWcPgtusFMf65kpVHLDl8kemJ7Tl0t2RR8vrxBaZoVcwBIw2hS8OpAAfWs7KtjYQ3fs4Tp%2B5RXTV6cPPK3cYuz9ZM9m5yKVMpUj41Z4hZciBSKSCpow55DdanthCJLI8%2BuVPzf2tg0VSIMdpHA2MeDbs%2BC0rZ43n5EWLggfrQd%2BTccimhCedOj2FJcQIRZrwXyrfDKmvBgKHO8giRrQoRWwHoOdVPVfpOcaQJmjAQVIsszPEnBBEHeRKuaSDga%2BJfUMK37ALUi%2BLbOASOv2%2F7y%2FP2iQrPiuu1MVPwzhLixl%2FnErKDkIG%2BkunbKTuRYijRI2DNIgsBZGmW9zQGz58rpEElfLWQuCh%2Fvlewr4v180NPR5hZCM7rg2G0DdDtlq3jc8I75yzslyykLgWIgxinmDWst2Ma7y4%2B%2BTzCy592eBjq%2BAY%2B846XsnwDU2eyjt845BBsJZYrE4DPkXM%2FpaZOGI4mbCpS4IazYZH0sCBdEez7Z%2B4oBMjbBtA2gtH1slqzKyJ45YvEBSpF6c%2FeDmKVGzZJMtj%2F6z1vcHFG98UIRdYNKZlvh3mOTv4WcGqOzJw9MZ4csR2cya3xTMn66cCuu%2B5EY2TGQSkgTyEcl%2B88SdGvBFzDNDA5f20XwoW0%2BYSaP1RNaL4ukzhlkBCGkgzQItsoJudguy4T05SEerW05hII%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230130T073722Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Credential=ASIAS4MLL5FYQ4Z624M6%2F20230130%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=76464bfb4c6ce6f659109eb73d9e3e910cf1edf5114e11dd7e16f4718257a4de' \
        --header 'Range: bytes=0-250'

  • Validate signature.

    • Extract the public key of the certificate used for signing the firmware/software update file using the below sample OpenSSL command: openssl x509 -pubkey -noout -in deviceCert.pem > pubkey.pem

    • Verify the downloaded firmware/software update file using the below sample OpenSSL command: openssl dgst -ecdsa-with-SHA1 -verify pubkey.pem -signature signature firmwareUpdate.json

  • Publish job status from device. Possible job execution status values are FAILED, SUCCEEDED, REJECTED, and IN_PROGRESS.

    • Device must subscribe to below topics to receive job update status
      • $aws/things/[clientId]/jobs/{jobId}/update/accepted
      • $aws/things/[clientId]/jobs/{jobId}/update/rejected
    • Publish below message to update the job status to the topic : $aws/things/[clientId]/jobs/{jobId}/update 
      {
          "status":"SUCCEEDED"
      }

Delete Job Update

Ota Job Update can be deleted only when all the executions of the job is in queued state or job is in terminal state. The Ota Update Job in which any execution’s status is QUEUED or IN_PROGRESS cannot be deleted. Those Job Executions can be cancelled. After cancellation, the job can be deleted.