Criação de uma atualização do OTA com a AWS CLI

Ao usar a AWS CLI para criar uma atualização OTA, você:

Assinatura digital da atualização de firmware

Ao usar a AWS CLI para executar atualizações OTA, você pode usar o Code Signing para AWS IoT ou pode assinar a atualização de firmware por conta própria. Para obter uma lista dos algoritmos de hashing e assinatura criptográfica compatíveis com o Code Signing para AWS IoT, consulte SigningConfigurationOverrides. Se desejar usar um algoritmo de criptografia que não é compatível com o Code Signing para AWS IoT, você precisará assinar o binário de firmware antes de fazer upload dele para o Amazon S3.

Assinatura de imagem de firmware com o Code Signing para AWS IoT

Para assinar a imagem de firmware usando o Code Signing para AWS IoT, você pode usar um dos SDKs ou ferramentas da linha de comando da AWS. Para obter mais informações sobre o Code Signing para AWS IoT, consulte Code Signing para AWS IoT.

Depois de instalar e configurar as ferramentas de assinatura de código, copie a imagem de firmware não assinada no bucket do Amazon S3 e inicie um trabalho de assinatura de código com os seguintes comandos da AWS CLI. O comando put-signing-profile cria um perfil de assinatura de código reutilizável. O comando start-signing-job inicia o trabalho de assinatura.

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

Esses são os parâmetros para os comandos put-signing-profile e start-signing-job:

O trabalho de assinatura inicia e grava a imagem de firmware assinada no bucket de destino do Amazon S3. O nome do arquivo para a imagem de firmware assinada é um GUID. Você precisa desse nome de arquivo ao criar um fluxo. Você pode encontrar o nome do arquivo navegando até o console do Amazon S3 e escolhendo o bucket. Se você não vir um arquivo com um nome de arquivo GUID, atualize o navegador.

O comando exibe um ARN de trabalho e um ID de trabalho. Você precisará desses valores mais tarde. Para obter mais informações sobre o Code Signing para AWS IoT, consulte Code Signing para AWS IoT.

Assinatura de imagem de firmware manualmente

Assine digitalmente a imagem de firmware e faça upload da imagem de firmware assinada no bucket do Amazon S3.

Criação de um fluxo da atualização de firmware

Um fluxo é uma interface abstrata para dados que podem ser consumidos por um dispositivo. Um fluxo pode ocultar a complexidade de acessar dados armazenados em diferentes locais ou serviços baseados em nuvem diferentes. O serviço Gerenciador de atualizações OTA permite que você use vários dados armazenados em vários locais no Amazon S3 para realizar uma atualização OTA.

Ao criar uma atualização OTA em AWS IoT, você também pode criar um fluxo que contém a atualização de firmware assinada. Crie um arquivo JSON (stream.json) que identifique a imagem de firmware assinada. O arquivo JSON deve conter o seguinte:

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

Estes são os atributos no arquivo JSON:

Use o comando create-stream AWS CLI da para criar um fluxo.

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

Estes são os argumentos para o comando create-stream da AWS CLI:

Para encontrar a chave de objeto do Amazon S3 da imagem de firmware assinada, use o comando aws signer describe-signing-job --job-id my-job-id, em que my-job-id é o ID do trabalho exibido pelo comando create-signing-job da AWS CLI. A saída do comando describe-signing-job contém a chave da imagem de firmware assinada.

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

Criação de uma atualização do OTA

Use o comando create-ota-update da AWS CLI para criar um trabalho de atualização OTA.

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-jsonFormato de

{
  "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"
    }
  ]
}

Resultado

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

Veja a seguir um exemplo de um arquivo JSON transmitido para o comando create-ota-update que utiliza o Code Signing para AWS IoT.

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

Veja a seguir um exemplo de um arquivo JSON transmitido para o comando create-ota-update da AWS CLI que usa um arquivo em linha para fornecer material de assinatura de código personalizado.

[
  {
    "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"
      }
    }
  }
]

Veja a seguir um exemplo de um arquivo JSON transmitido para o comando create-ota-update da AWS CLI que permite que o FreeRTOS OTA inicie um trabalho de assinatura de código e crie um perfil de assinatura de código e fluxo.

[
  {
    "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"
          }
        }
      }
    }  
  }
]

Veja a seguir um exemplo de um arquivo JSON transmitido para o comando create-ota-update da AWS CLI que cria uma atualização OTA que inicia um trabalho de assinatura de código com um perfil existente e usa o fluxo especificado.

[
  {
    "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"
          }
        }
      }
    }  
  }
]

Veja a seguir um exemplo de um arquivo JSON transmitido para o comando create-ota-update da AWS CLI que permite que o FreeRTOS OTA crie um fluxo com um ID de trabalho de assinatura de código existente.

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

Veja a seguir um exemplo de um arquivo JSON transmitido para o comando create-ota-update da AWS CLI que cria uma atualização OTA. A atualização cria um fluxo a partir do objeto especificado do S3 e usa a assinatura de código personalizado.

[
  {
    "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"
      }
    }  
  }
]

Listagem de atualizações do OTA

Você pode usar o comando list-ota-updates da AWS CLI para obter uma lista de todas as atualizações OTA.

aws iot list-ota-updates

A saída do comando list-ota-updates parece com o exemplo a seguir.

{
  "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
    }
  ]
}

Obtenção de informações sobre uma atualização OTA

Você pode usar o comando get-ota-update da AWS CLI para obter o status da criação ou exclusão de uma atualização OTA.

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

A saída do comando get-ota-update é semelhante ao exemplo a seguir.

{ 
    "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" 
    } 
}

Os valores retornados para otaUpdateStatus incluem o seguinte:

Exclusão de dados relacionados ao OTA

No momento, não é possível usar o console da AWS IoT para excluir fluxos ou atualizações OTA. Você pode usar a AWS CLI para excluir fluxos, atualizações OTA e trabalhos da AWS IoT criados durante uma atualização OTA.

Exclusão de um fluxo do OTA

Quando você cria uma atualização OTA que usa MQTT, você pode usar a linha de comando ou o console da AWS IoT para criar um fluxo para dividir o firmware em pedaços para que ele possa ser enviado pelo MQTT. Você pode excluir esse fluxo com o comando delete-stream da AWS CLI, conforme mostrado no exemplo a seguir.

aws iot delete-stream --stream-id your_stream_id

Como excluir uma atualização do OTA

Quando você cria uma atualização OTA, são criados:

O comando delete-ota-update exclui a entrada somente no banco de dados de trabalhos de atualização OTA. É necessário usar o comando delete-job para excluir o trabalho da AWS IoT.

Use o comando delete-ota-update para excluir uma atualização OTA.

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

Exclusão de um trabalho da IoT criado para uma atualização do OTA

O FreeRTOS cria um trabalho do AWS IoT quando você cria uma atualização OTA. Uma execução de trabalho também é criada para cada dispositivo que processa o trabalho. Você pode usar o comando delete-job da AWS CLI para excluir um trabalho e as execuções de trabalho associadas.

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

O parâmetro no-force especifica que somente os trabalhos que estão em estado terminal (COMPLETED ou CANCELED) podem ser excluídos. Você pode excluir um trabalho que está em um estado não terminal, transmitindo o parâmetro force. Para obter mais informações, consulte API DeleteJob.

Dependendo do número de execuções de trabalho criadas para o trabalho e de outros fatores, pode levar alguns minutos para excluir um trabalho. Enquanto o trabalho estiver sendo excluído, seu status será DELETION_IN_PROGRESS. A tentativa de excluir ou cancelar um trabalho cujo status já seja DELETION_IN_PROGRESS resulta em um erro.

Você pode usar a delete-job-execution para excluir uma execução de trabalho. Você pode querer excluir uma execução de trabalho quando um pequeno número de dispositivos não puder processar um trabalho. Isso exclui a execução do trabalho de um único dispositivo, conforme mostrado no exemplo a seguir.

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

Assim como ocorre com o comando delete-job da AWS CLI, você pode transmitir o parâmetro --force ao delete-job-execution para forçar a exclusão de um trabalho de execução. Para obter mais informações, consulte API DeleteJobExecution.

Para obter mais informações sobre como usar a aplicação de demonstração de atualização OTA, consulte Aplicação de demonstração de atualizações remotas.