Configure OTA for MQTT

Provision groups and devices.
- Registering a group
- Registering a device
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 16MB
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

{
  "timestamp": 1672730954,
  "execution": {
      "jobId": "AFR_OTA-3a803ea4-7201-449e-9a62-9fcdd1ea7b65",
      "status": "QUEUED",
      "queuedAt": 1672730953,
      "lastUpdatedAt": 1672730953,
      "versionNumber": 1,
      "executionNumber": 1,
      "jobDocument": {
      "afr_ota": {
          "protocols": [
          "MQTT"
          ],
          "streamname": "AFR_OTA-3027a394-e583-4080-992d-04e450f38a9b-uDhetChNyu",
          "files": [
          {
              "filepath": "device/firmware.exe",
              "filesize": 35,
              "fileid": 0,
              "certfile": "device/certificate.pem",
              "sig-sha-1-ecdsa": "MGQCMH0CpLZk16TeTRteBUuu4N8P8yDVGocDd80kgoVCgo1Q0mOUkdatfNWRAgmP\nT6U8EgIwO73iuWg8FiBGHNxMNFHNVSf2NHMXeeH0rfwoDKsCX7l7+ELDE5sSGZ6Q\nKb5N0i5a\n"
          }
          ]
      }
      }
  }
  }

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-3a803ea4-7201-449e-9a62-9fcdd1ea7b65",
          "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.

{
  "timestamp": 1672731078,
  "execution": {
      "jobId": "AFR_OTA-3a803ea4-7201-449e-9a62-9fcdd1ea7b65",
      "status": "IN_PROGRESS",
      "queuedAt": 1672730953,
      "startedAt": 1672731078,
      "lastUpdatedAt": 1672731078,
      "versionNumber": 2,
      "executionNumber": 1,
      "jobDocument": {
      "afr_ota": {
          "protocols": [
          "MQTT"
          ],
          "streamname": "AFR_OTA-3027a394-e583-4080-992d-04e450f38a9b-uDhetChNyu",
          "files": [
          {
              "filepath": "device/firmware.exe",
              "filesize": 35,
              "fileid": 0,
              "certfile": "device/certificate.pem",
              "firmware_version": "v1",
              "sig-sha-1-ecdsa": "MGQCMH0CpLZk16TeTRteBUuu4N8P8yDVGocDd80kgoVCgo1Q0mOUkdatfNWRAgmP\nT6U8EgIwO73iuWg8FiBGHNxMNFHNVSf2NHMXeeH0rfwoDKsCX7l7+ELDE5sSGZ6Q\nKb5N0i5a\n"
          }
          ]
      }
      }
  }
  }

Make note of the stream name received in the above job document response for further steps.
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 and streams 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 stream name received in the above job document response for further steps.
- Note the status of the job changes from QUEUED to IN_PROGRESS

Receive description of the stream
- Device must subscribe to below topic to receive stream descriptions
  - $aws/things/{clientId}/streams/{streamName}/description/json
  - $aws/things/{clientId}/streams/{streamName}/rejected/json
- Publish empty message to topic : $aws/things/{clientId}/streams/{streamName}/describe/json
- Receive the stream description in the topic : $aws/things/{clientId}/streams/{streamName}/description/json
```
 {
      "s": 1,
      "d": "Stream for OTAUpdate 3a803ea4-7201-449e-9a62-9fcdd1ea7b65",
      "r": [
          {
          "f": 0,
          "z": 35
          }
      ]
  }
```
  - Field details:
    - s - Stream version as an integer
    - d - Description of the stream
    - r - List of the files in the stream
    - f - Stream file ID as an integer
    - z - Stream file size in number of bytes
Get base64 encoded stream object(firmware/software update file)
- Device must subscribe to below topic to receive file data
  - $aws/things/{clientId}/streams/{streamName}/data/json
  - $aws/things/{clientId}/streams/{streamName}/rejected/json
- Publish below message to topic:
  - $aws/things/{clientId}/streams/{streamName}/get/json
    { "s": 1, "f": 0, "l":256, "n": 1 }
    - Field details:
      - s - Stream version as an integer.
      - f - Stream file ID as an integer.
      - l - Length of file blocks to be downloaded in bytes. Minimum length - 256 bytes; Maximum length - 131072 bytes.
      - n - Number of file blocks to be downloaded.
- Receive the data in the topic : $aws/things/{clientId}/streams/{streamName}/data/json { "f": 0, "i": 0, "l": 35, "p": "ew0KCSJ0ZXN0IiA6ICJPVEEiLA0KCSJpZCIgOiAiMSINCn0=" }
  - Field details
    - f - Stream file ID as an integer
    - i - n-th number of the file blocks received
    - l - Length of the file block received
    - p - Base64 encoded file(firmware/software update) to be downloaded
- Decode the base64 encoded file data to get original file
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.