AWS CLI を使用した OTA 更新の作成

AWS CLI を使用して OTA 更新を作成するときは、以下の操作を行います。

ファームウェアの更新にデジタル署名する

AWS CLI を使用して OTA の更新を実行する場合は、Code Signing for AWS IoT を使用するか、ファームウェア更新に署名することができます。Code Signing for AWS IoT によってサポートされている暗号化署名およびハッシュアルゴリズムのリストについては、「SigningConfigurationOverrides」を参照してください。Code Signing for AWS IoT でサポートされていない暗号化アルゴリズムを使用する場合は、Amazon S3 にアップロードする前にファームウェアバイナリに署名する必要があります。

Code Signing for AWS IoT を使用したファームウェアイメージへの署名

Code Signing for AWS IoT を使用してファームウェアイメージに署名するには、AWS SDK またはコマンドラインツールのいずれかを使用できます。Code Signing for AWS IoT の詳細については、「Code Signing for AWS IoT」を参照してください。

コード署名ツールをインストールして設定したら、署名されていないファームウェアイメージを Amazon S3 バケットにコピーし、以下の AWS CLI コマンドを使用してコード署名ジョブを開始します。put-signing-profile コマンドは、再利用可能なコード署名プロファイルを作成します。start-signing-job コマンドは、署名ジョブを開始します。

aws signer put-signing-profile \
    --profile-name your_profile_name \
    --signing-material certificateArn=arn:aws:acm::your-region:your-aws-account-id:certificate/your-certificate-id \
    --platform your-hardware-platform \
    --signing-parameters certname=your_certificate_path_on_device

aws signer start-signing-job \
    --source 's3={bucketName=your_s3_bucket,key=your_s3_object_key,version=your_s3_object_version_id}' \
    --destination 's3={bucketName=your_destination_bucket}' \
    --profile-name your_profile_name

これらは put-signing-profile および start-signing-job コマンドのパラメータです。

署名ジョブが開始され、署名済みファームウェアイメージがコピー先の Amazon S3 バケットに書き込まれます。署名済みファームウェアイメージのファイル名は GUID です。ストリームを作成するときは、このファイル名が必要です。このファイル名は、Amazon S3 コンソールを参照し、バケットを選択すると表示されます。GUID ファイル名のファイルが表示されない場合は、ブラウザを更新してください。

このコマンドは、ジョブの ARN とジョブ ID を表示します。これらの値は後で必要になります。Code Signing for AWS IoT の詳細については、「Code Signing for AWS IoT」を参照してください。

手動でファームウェアイメージに署名する

ファームウェアイメージにデジタル署名し、署名済みファームウェアイメージを Amazon S3 バケットにアップロードします。

ファームウェアの更新のストリームを作成する

ストリームは、デバイスによって消費されるデータへの抽象インターフェイスです。ストリームは、異なる場所または異なるクラウドベースのサービスに保存されているデータにアクセスすることの複雑さを隠すことができます。OTA 更新マネージャーサービスを使用すると、Amazon S3 のさまざまな場所に保存されている複数のデータを使用して、OTA 更新を実行できます。

AWS IoT OTA 更新を作成するときに、署名済みのファームウェア更新を含むストリームを作成することもできます。署名済みファームウェアイメージを識別する JSON ファイル (stream.json) を作成します。JSON ファイルには次の内容が含まれています。

[
  {
    "fileId":"your_file_id",
    "s3Location":{
      "bucket":"your_bucket_name",
      "key":"your_s3_object_key"
    }
  }   
]

これらは JSON ファイル内の属性です。

create-stream AWS CLI コマンドを使用して、ストリームを作成します。

aws iot create-stream \
    --stream-id your_stream_id \
    --description your_description \
    --files file://stream.json \
    --role-arn your_role_arn

以下に示しているのは、create-stream AWS CLI コマンドの引数です。

署名済みファームウェアイメージの Amazon S3 オブジェクトキーを検索するには、aws signer describe-signing-job --job-id my-job-id コマンドを使用します。my-job-id は、create-signing-job AWS CLI コマンドで表示されるジョブ ID です。describe-signing-job コマンドの出力には、署名済ファームウェアイメージのキーが含まれています。

... text deleted for brevity ...
  "signedObject": {
    "s3": {
      "bucketName": "ota-bucket",
      "key": "7309da2c-9111-48ac-8ee4-5a4262af4429"
    }
  }
... text deleted for brevity ...

OTA 更新の作成

OTA 更新ジョブを作成するには、create-ota-update AWS CLI コマンドを使用します。

aws iot  create-ota-update \
    --ota-update-id value \
    [--description value] \
    --targets value \
    [--protocols value] \
    [--target-selection value] \
    [--aws-job-executions-rollout-config value] \
    [--aws-job-presigned-url-config value] \
    [--aws-job-abort-config value] \
    [--aws-job-timeout-config value] \
    --files value \
    --role-arn value \
    [--additional-parameters value] \
    [--tags value]  \
    [--cli-input-json value] \
    [--generate-cli-skeleton]

cli-input-json 形式

{
  "otaUpdateId": "string",
  "description": "string",
  "targets": [
    "string"
  ],
  "protocols": [
    "string"
  ],
  "targetSelection": "string",
  "awsJobExecutionsRolloutConfig": {
    "maximumPerMinute": "integer",
    "exponentialRate": {
      "baseRatePerMinute": "integer",
      "incrementFactor": "double",
      "rateIncreaseCriteria": {
        "numberOfNotifiedThings": "integer",
        "numberOfSucceededThings": "integer"
      }
    }
  },
  "awsJobPresignedUrlConfig": {
    "expiresInSec": "long"
  },
  "awsJobAbortConfig": {
    "abortCriteriaList": [
      {
        "failureType": "string",
        "action": "string",
        "thresholdPercentage": "double",
        "minNumberOfExecutedThings": "integer"
      }
    ]
  },
  "awsJobTimeoutConfig": {
    "inProgressTimeoutInMinutes": "long"
  },
  "files": [
    {
      "fileName": "string",
      "fileType": "integer",
      "fileVersion": "string",
      "fileLocation": {
        "stream": {
          "streamId": "string",
          "fileId": "integer"
        },
        "s3Location": {
          "bucket": "string",
          "key": "string",
          "version": "string"
        }
      },
      "codeSigning": {
        "awsSignerJobId": "string",
        "startSigningJobParameter": {
          "signingProfileParameter": {
            "certificateArn": "string",
            "platform": "string",
            "certificatePathOnDevice": "string"
          },
          "signingProfileName": "string",
          "destination": {
            "s3Destination": {
              "bucket": "string",
              "prefix": "string"
            }
          }
        },
        "customCodeSigning": {
          "signature": {
            "inlineDocument": "blob"
          },
          "certificateChain": {
            "certificateName": "string",
            "inlineDocument": "string"
          },
          "hashAlgorithm": "string",
          "signatureAlgorithm": "string"
        }
      },
      "attributes": {
        "string": "string"
      }
    }
  ],
  "roleArn": "string",
  "additionalParameters": {
    "string": "string"
  },
  "tags": [
    {
      "Key": "string",
      "Value": "string"
    }
  ]
}

Output

{
  "otaUpdateId": "string",
  "awsIotJobId": "string",
  "otaUpdateArn": "string",
  "awsIotJobArn": "string",
  "otaUpdateStatus": "string"
}

Code Signing for create-ota-update を使用する AWS IoT というコマンドに渡される JSON ファイルの例を次に示します。

[
  {
    "fileName": "firmware.bin",                
    "fileType": 1,
    "fileLocation": {
      "stream": {
        "streamId": "004",                         
        "fileId":123
      }                        
    },
    "codeSigning": {
      "awsSignerJobId": "48c67f3c-63bb-4f92-a98a-4ee0fbc2bef6"     
    }
  }
]

インラインファイルを使用してカスタムコード署名マテリアルを提供する create-ota-update AWS CLI コマンドに渡される JSON ファイルの例を次に示します。

[
  {
    "fileName": "firmware.bin",
    "fileType": 1,
    "fileLocation": {
      "stream": {
        "streamId": "004",
        "fileId": 123
      }
    },
    "codeSigning": {
      "customCodeSigning":{
        "signature":{
          "inlineDocument":"your_signature"
        },
        "certificateChain": {
          "certificateName": "your_certificate_name",
          "inlineDocument":"your_certificate_chain"
        },
        "hashAlgorithm":"your_hash_algorithm",
        "signatureAlgorithm":"your_signature_algorithm"
      }
    }
  }
]

FreeRTOS OTA がコード署名ジョブを開始し、コード署名のプロファイルとストリームを作成できるようにする create-ota-update AWS CLI コマンドに渡される JSON ファイルの例を以下に示します。

[
  {
    "fileName": "your_firmware_path_on_device",
    "fileType": 1,
    "fileVersion": "1",
    "fileLocation": {
      "s3Location": {
        "bucket": "your_bucket_name",
        "key": "your_object_key",
        "version": "your_S3_object_version"
      }
    },
    "codeSigning":{
      "startSigningJobParameter":{
        "signingProfileName": "myTestProfile",
        "signingProfileParameter": {
          "certificateArn": "your_certificate_arn",
          "platform": "your_platform_id",
          "certificatePathOnDevice": "certificate_path"
        },
        "destination": {
          "s3Destination": {
            "bucket": "your_destination_bucket"
          }
        }
      }
    }  
  }
]

既存のプロファイルを使用してコード署名ジョブを開始し、指定されたストリームを使用する OTA 更新を作成する create-ota-update AWS CLI コマンドに渡される JSON ファイルの例を以下に示します。

[
  {
    "fileName": "your_firmware_path_on_device",
    "fileType": 1,
    "fileVersion": "1",
    "fileLocation": {
      "s3Location": {
        "bucket": "your_s3_bucket_name",
        "key": "your_object_key",
        "version": "your_S3_object_version"
      }
    },
    "codeSigning":{
      "startSigningJobParameter":{
        "signingProfileName": "your_unique_profile_name",
        "destination": {
          "s3Destination": {
            "bucket": "your_destination_bucket"
          }
        }
      }
    }  
  }
]

FreeRTOS OTA が既存のコード署名ジョブ ID でストリームを作成できるようにする create-ota-update AWS CLI コマンドに渡される JSON ファイルの例を以下に示します。

[
  {
    "fileName": "your_firmware_path_on_device",
    "fileType": 1,
    "fileVersion": "1",
    "codeSigning":{
      "awsSignerJobId": "your_signer_job_id"
    }  
  }
]

OTA 更新を作成する create-ota-update AWS CLI コマンドに渡される JSON ファイルの例を次に示します。この更新では、指定された S3 オブジェクトからストリームが作成され、カスタムコード署名が使用されます。

[
  {
    "fileName": "your_firmware_path_on_device",
    "fileType": 1,
    "fileVersion": "1",
    "fileLocation": {
      "s3Location": {
        "bucket": "your_bucket_name",
        "key": "your_object_key",
        "version": "your_S3_object_version"
      }
    },
    "codeSigning":{
      "customCodeSigning": {
        "signature":{
          "inlineDocument":"your_signature"
        },
        "certificateChain": {
          "inlineDocument":"your_certificate_chain",
          "certificateName": "your_certificate_path_on_device"
        },
        "hashAlgorithm":"your_hash_algorithm",
        "signatureAlgorithm":"your_sig_algorithm"
      }
    }  
  }
]

OTA 更新を一覧表示する

すべての OTA 更新のリストを取得するには、list-ota-updates AWS CLI コマンドを使用できます。

aws iot list-ota-updates

コマンド list-ota-updates の出力は次のようになります。

{
  "otaUpdates": [
     
    {
      "otaUpdateId": "my_ota_update2",
      "otaUpdateArn": "arn:aws:iot:us-west-2:123456789012:otaupdate/my_ota_update2",
      "creationDate": 1522778769.042
    },
    {
      "otaUpdateId": "my_ota_update1",
      "otaUpdateArn": "arn:aws:iot:us-west-2:123456789012:otaupdate/my_ota_update1",
      "creationDate": 1522775938.956
    },
    {
      "otaUpdateId": "my_ota_update",
      "otaUpdateArn": "arn:aws:iot:us-west-2:123456789012:otaupdate/my_ota_update",
      "creationDate": 1522775151.031
    }
  ]
}

OTA 更新に関する情報の取得

get-ota-update AWS CLI コマンドを使用して、OTA 更新の作成または削除のステータスを取得できます。

aws iot get-ota-update --ota-update-id your-ota-update-id

get-ota-update コマンドからの出力は以下のようになります。

{ 
    "otaUpdateInfo": { 
        "otaUpdateId": "ota-update-001", 
        "otaUpdateArn": "arn:aws:iot:region:123456789012:otaupdate/ota-update-001", 
        "creationDate": 1575414146.286, 
        "lastModifiedDate": 1575414149.091, 
        "targets": [ 
            "arn:aws:iot:region:123456789012:thing/myDevice" 
        ], 
        "protocols": [ "HTTP" ], 
        "awsJobExecutionsRolloutConfig": { 
            "maximumPerMinute": 0 
        }, 
        "awsJobPresignedUrlConfig": { 
            "expiresInSec": 1800 
        }, 
        "targetSelection": "SNAPSHOT", 
        "otaUpdateFiles": [ 
            { 
                "fileName": "my_firmware.bin", 
                "fileType": 1,
                "fileLocation": { 
                    "s3Location": { 
                        "bucket": "my-bucket", 
                        "key": "my_firmware.bin", 
                        "version": "AvP3bfJC9gyqnwoxPHuTqM5GWENt4iii" 
                    } 
                }, 
                "codeSigning": { 
                    "awsSignerJobId": "b7a55a54-fae5-4d3a-b589-97ed103737c2", 
                    "startSigningJobParameter": { 
                        "signingProfileParameter": {}, 
                        "signingProfileName": "my-profile-name", 
                        "destination": { 
                            "s3Destination": { 
                                "bucket": "some-ota-bucket", 
                                "prefix": "SignedImages/" 
                            } 
                        } 
                    }, 
                    "customCodeSigning": {} 
                } 
            } 
        ], 
        "otaUpdateStatus": "CREATE_COMPLETE", 
        "awsIotJobId": "AFR_OTA-ota-update-001", 
        "awsIotJobArn": "arn:aws:iot:region:123456789012:job/AFR_OTA-ota-update-001" 
    } 
}

otaUpdateStatus に戻される値には次のものがあります。

OTA 関連データの削除

現時点では、AWS IoT コンソールを使用してストリームまたは OTA 更新を削除することはできません。AWS CLI を使用して、OTA 更新中に作成されたストリーム、OTA 更新、AWS IoT ジョブを削除できます。

OTA ストリームを削除する

MQTT を使用する OTA 更新を作成する場合、コマンドラインまたは AWS IoT コンソールを使用して、ファームウェアをチャンクに分割して MQTT 経由で送信できるようにストリームを作成できます。次の例に示すように、delete-stream AWS CLI コマンドを使用してこのストリームを削除できます。

aws iot delete-stream --stream-id your_stream_id

OTA ストリームの削除

OTA 更新の作成時、以下が作成されます。

delete-ota-update コマンドは、OTA 更新ジョブデータベース内のエントリのみを削除します。delete-job ジョブを削除するには、AWS IoT コマンドを使用する必要があります。

delete-ota-update コマンドを使用して、OTA 更新を削除します。

aws iot delete-ota-update --ota-update-id your_ota_update_id

OTA 更新用に作成された IoT ジョブを削除する

FreeRTOS は、OTA 更新を作成するときに AWS IoT ジョブを作成します。ジョブの実行は、ジョブを処理するデバイスごとにも作成されます。delete-job AWS CLI コマンドを使用して、ジョブおよび関連するジョブの実行を削除できます。

aws iot delete-job --job-id your-job-id --no-force

no-force パラメータは、終了状態のジョブ (COMPLETED または CANCELLED) のみを削除できるように指定します。force パラメータを渡すことによって、非ターミナルステータスにあるジョブを削除することができます。詳細については、DeleteJob API を参照してください。

ジョブ用に作成されたジョブ実行の数およびその他の要素に応じて、ジョブの削除に時間がかかる場合があります。ジョブが削除されている間、そのステータスは DELETION_IN_PROGRESS です。ステータスがすでに DELETION_IN_PROGRESS のジョブを削除あるいはキャンセルしようとすると、エラーになります。

delete-job-execution を使用してジョブの実行を削除できます。いくらかのデバイスがジョブを処理できない場合、ジョブの実行を削除することをお勧めします。これにより、次の例に示すように、単一のデバイスのジョブ実行が削除されます。

aws iot delete-job-execution --job-id your-job-id --thing-name
                    your-thing-name --execution-number your-job-execution-number --no-force

delete-job AWS CLI コマンドの場合と同様に、delete-job-execution に --force パラメータを渡して強制的にジョブの実行を削除できます。詳細については、DeleteJobExecution API を参照してください。

OTA 更新デモアプリケーションを使用する方法の詳細については、「無線通信経由更新デモアプリケーション」を参照してください。