Creación de una actualización OTA con la AWS CLI

Cuando utiliza la AWS CLI para crear una actualización OTA:

Firma digital de la actualización de firmware

Cuando utiliza la AWS CLI para realizar actualizaciones OTA, puede utilizar la firma de código para AWS IoT o firmar usted mismo la actualización de firmware. Para obtener una lista de los algoritmos de hash y firma criptográfica compatibles con la firma de código para AWS IoT, consulte SigningConfigurationOverrides. Si desea utilizar un algoritmo criptográfico que no sea compatible con la firma de código para AWS IoT, tiene que firmar los binarios de firmware antes de cargarlo en Amazon S3.

Firma de la imagen de firmware con la firma de código para AWS IoT

Para firmar la imagen de firmware mediante la firma de código para AWS IoT, puede utilizar uno de los SDK o herramientas de la línea de comandos de AWS. Para obtener más información sobre la firma de código para AWS IoT, consulte Firma de código para AWS IoT.

Después de instalar y configurar las herramientas de firma de código, copie su imagen de firmware sin firmar en el bucket de Amazon S3 e inicie un trabajo de firma de código con los siguientes comandos de la AWS CLI. El comando put-signing-profile crea un perfil reutilizable de firma de código. El comando start-signing-job inicia el trabajo de firma.

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

Esto son los parámetros de los comandos put-signing-profile y start-signing-job:

El trabajo de firma comienza y escribe la imagen de firmware firmada en el bucket de Amazon S3 de destino. El nombre del archivo de la imagen de firmware firmada es un GUID. Necesitará este nombre de archivo para crear una secuencia. Para encontrar el nombre del archivo, vaya a la consola de Amazon S3 y elija su bucket. Si no ve un archivo con un nombre de archivo GUID, actualice el navegador.

El comando muestra un ARN de trabajo y un ID de trabajo. Necesitará estos valores más adelante. Para obtener más información sobre la firma de código para AWS IoT, consulte Firma de código para AWS IoT.

Firma manual de la imagen de firmware

Firme digitalmente la imagen de firmware y cargue la imagen de firmware firmada en su bucket de Amazon S3.

Creación de una secuencia de actualización de firmware

Una secuencia es una interfaz abstracta a los datos que puede consumir un dispositivo. Una secuencia puede ocultar la complejidad de obtener acceso a los datos almacenados en diferentes ubicaciones o en diferentes servicios en la nube. El servicio de administrador de actualizaciones OTA le permite utilizar varios datos, almacenados en varias ubicaciones de Amazon S3, para realizar una actualización OTA.

Al crear una actualización OTA de AWS IoT, también puede crear una secuencia que contenga la actualización de firmware firmada. Cree un archivo JSON (stream.json) que identifique su imagen de firmware firmada. El archivo JSON debe contener lo siguiente.

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

Estos son los atributos del archivo JSON:

Utilice el comando create-stream de la AWS CLI para crear un flujo.

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

Estos son los argumentos del comando create-stream de la AWS CLI:

Para encontrar la clave del objeto de Amazon S3 de la imagen de firmware firmada, utilice el comando aws signer describe-signing-job --job-id my-job-id, donde my-job-id es el ID de trabajo que muestra el comando create-signing-job de la AWS CLI. La salida del comando describe-signing-job contiene la clave de la imagen de firmware firmada.

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

Creación de una actualización OTA

Utilice el comando create-ota-update de la AWS CLI para crear un trabajo de actualización 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

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

A continuación, se muestra un ejemplo de un archivo JSON que se pasa en el comando create-ota-update que utiliza la firma de código para AWS IoT.

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

A continuación, se muestra un ejemplo de un archivo JSON que se transfiere al comando create-ota-update de la AWS CLI que utiliza un archivo insertado para proporcionar material de firma de código personalizada.

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

A continuación, se muestra un ejemplo de un archivo JSON transferido al comando create-ota-update de la AWS CLIque permite a la OTA de FreeRTOS comenzar un trabajo de firma de código y crear una secuencia y un perfil de firma del código.

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

A continuación, se muestra un ejemplo de un archivo JSON transferido al comando create-ota-update de la AWS CLI y que crea una actualización OTA que comienza un trabajo de firma de código con un perfil existente y utiliza la secuencia especificada.

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

A continuación, se muestra un ejemplo de un archivo JSON transferido al comando create-ota-update de la AWS CLI que permite a la OTA de FreeRTOS crear una secuencia con un ID de trabajo de firma de código existente.

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

A continuación, se muestra un ejemplo de un archivo JSON transferido al comando create-ota-update de la AWS CLI que crea una actualización OTA. La actualización crea una secuencia desde el objeto de S3 especificado y utiliza firma de código personalizada.

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

Listado de actualizaciones OTA

Puede utilizar el comando list-ota-updates de la AWS CLI para obtener una lista de todas las actualizaciones OTA.

aws iot list-ota-updates

La salida del comando list-ota-updates es como se muestra a continuación.

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

Obtener información sobre una actualización OTA

Puede utilizar el comando get-ota-update de la AWS CLI para obtener el estado de creación o eliminación de una actualización OTA.

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

El resultado del comando get-ota-update tendrá un aspecto similar al siguiente.

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

Los valores devueltos para otaUpdateStatus incluyen lo siguiente:

Eliminación de datos relacionados con OTA

En estos momentos, no puede usar la consola de AWS IoT para eliminar secuencias o actualizaciones OTA. Puede utilizar la AWS CLI para eliminar secuencias, actualizaciones OTA y trabajos de AWS IoT creados durante una actualización OTA.

Eliminar una secuencia OTA

Cuando crea una actualización OTA que utiliza MQTT, puede utilizar la línea de comandos o la consola de AWS IoT para crear una secuencia que divida el firmware en fragmentos para que se pueda enviar a través de MQTT. Puede eliminar esta secuencia con el comando delete-stream de la AWS CLI, como se muestra en el siguiente ejemplo.

aws iot delete-stream --stream-id your_stream_id

Eliminar una actualización OTA

Al crear una actualización OTA, se crean los siguientes elementos:

El comando delete-ota-update elimina la entrada en la base de datos del trabajo de actualización OTA únicamente. Debe utilizar el comando delete-job para eliminar el trabajo de AWS IoT.

Utilice el comando delete-ota-update para eliminar una actualización OTA.

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

Eliminar un trabajo de IoT creado para una actualización OTA

FreeRTOS crea un trabajo de AWS IoT al crear una actualización OTA. También se crea una ejecución de trabajo para cada dispositivo que procesa el trabajo. Puede utilizar el comando delete-job de la AWS CLI para eliminar un trabajo y sus ejecuciones de trabajo asociadas.

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

El parámetro no-force especifica que solo se pueden eliminar los trabajos que están en estado terminal (COMPLETED o CANCELLED). Puede eliminar un trabajo que se encuentra en un estado no terminal pasando el parámetro force. Para obtener más información, consulte API DeleteJob.

Según el número de ejecuciones de trabajo creadas para el trabajo y otros factores, se podría tardar unos minutos en borrar un trabajo. Mientras el trabajo se está eliminando, su estado es DELETION_IN_PROGRESS. Al intentar eliminar o cancelar un trabajo cuyo estado ya es DELETION_IN_PROGRESS, se producirá un error.

Puede utilizar delete-job-execution para eliminar una ejecución de trabajo. Es posible que desee eliminar una ejecución de trabajo cuando un pequeño número de dispositivos no sea capaz de procesar un trabajo. Este elimina la ejecución de trabajo para un único dispositivo, como se muestra en el siguiente ejemplo.

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

Al igual que con el comando delete-job de la AWS CLI, puede transferir el parámetro --force a delete-job-execution para forzar la eliminación de una ejecución de trabajo. Para obtener más información, consulte API DeleteJobExecution.

Para obtener más información sobre el uso de la aplicación de demostración de actualizaciones OTA, consulte Aplicación de demostración de actualizaciones transparentes.