Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

# Migración de la versión 1 a la versión 3 para el puerto PAL OTA
<a name="porting-migration-ota-pal"></a>

La biblioteca de Over-the-air actualizaciones introdujo algunos cambios en la estructura de carpetas y en la ubicación de las configuraciones requeridas por la biblioteca y las aplicaciones de demostración. En el caso de las aplicaciones OTA diseñadas para funcionar con la versión 1.2.0 para migrar a la versión 3.0.0 de la biblioteca, debe actualizar las firmas de las funciones del puerto PAL e incluir archivos de configuración adicionales, tal y como se describe en esta guía de migración.

## Modificaciones en PAL OTA
<a name="porting-migration-ota-pal-changes"></a>
+ El nombre del directorio de puertos PAL OTA se ha actualizado de `ota` a `ota_pal_for_aws`. Esta carpeta debe contener 2 archivos: `ota_pal.c` y `ota_pal.h`. El archivo de cabecera PAL `libraries/freertos_plus/aws/ota/src/aws_iot_ota_pal.h` se ha eliminado de la biblioteca OTA y debe definirse dentro del puerto.
+ Los códigos de devolución (`OTA_Err_t`) se traducen en una enumeración `OTAMainStatus_t`. Consulte [ota\_platform\_interface.h](https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/v3.0.0/source/include/ota_platform_interface.h#L68-L90) para ver los códigos de devolución traducidos. [ También se proporcionan macros auxiliares](https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/666241d0f643b07d5146a3715b649d80f8135e0b/source/include/ota_platform_interface.h#L105-L111) para combinar los códigos `OtaPalMainStatus` y `OtaPalSubStatus`, y extraer `OtaMainStatus` de `OtaPalStatus` y similares.
+ Inicio de sesión en PAL 
  + Se ha eliminado la macro `DEFINE_OTA_METHOD_NAME`.
  + Anterior: `OTA_LOG_L1( "[%s] Receive file created.\r\n", OTA_METHOD_NAME );`.
  + Actualizada: `LogInfo(( "Receive file created."));` utilice`LogDebug`, `LogWarn` y `LogError` para el registro correspondiente.
+ Variable `cOTA_JSON_FileSignatureKey` cambiada a `OTA_JsonFileSignatureKey`.

### Funciones
<a name="porting-migration-ota-pal-functions"></a>

Las firmas de las funciones se definen en `ota_pal.h` y comienzan por el prefijo `otaPal` en lugar de `prvPAL`.

**nota**  
El nombre exacto del PAL es técnicamente abierto, pero para que sea compatible con las pruebas de calificación, el nombre debe ajustarse a los que se especifican a continuación.


****  

|  Versión 1   |  Versión 3   |  Notas   | 
| --- | --- | --- | 
| `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );` | Cree un nuevo archivo de recepción para los fragmentos de datos a medida que van llegando. | 
| `int16_t prvPAL_WriteBlock( OTA_FileContext_t * const C, uint32_t ulOffset, uint8_t * const pcData, uint32_t ulBlockSize );` | `int16_t otaPal_WriteBlock( OtaFileContext_t * const pFileContext, uint32_t ulOffset, uint8_t * const pData, uint32_t ulBlockSize );` | Escribe un bloque de datos en el archivo especificado en el desplazamiento dado.  | 
| `OTA_Err_t prvPAL_ActivateNewImage( void );` | `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );` | Active la imagen de MCU más reciente recibida a través de OTA. | 
| `OTA_Err_t prvPAL_ResetDevice( void );` | `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );` | Restablece el dispositivo. | 
| `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );` | Autentica y cierra el archivo de recepción subyacente en el contexto OTA especificado. | 
| `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );` | Detiene una transferencia OTA. | 
| `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );` | `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );` | Intenta obtener el estado de la imagen de actualización OTA. | 
| `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );` | `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );` | Obtiene el estado de la imagen de actualización OTA. | 
+ Versión 1: `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );`

  Versión 3: `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );`

  Notas: Cree un nuevo archivo de recepción para los fragmentos de datos a medida que van llegando.
+ Versión 1: `int16_t prvPAL_WriteBlock( OTA_FileContext_t * const C, uint32_t ulOffset, uint8_t * const pcData, uint32_t ulBlockSize );`

  Versión 3: `int16_t otaPal_WriteBlock( OtaFileContext_t * const pFileContext, uint32_t ulOffset, uint8_t * const pData, uint32_t ulBlockSize );`

  Escribe un bloque de datos en el archivo especificado en el desplazamiento dado. 
+ Versión 1: `OTA_Err_t prvPAL_ActivateNewImage( void );`

  Versión 3: `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );`

  Notas: Active la imagen de MCU más reciente recibida a través de OTA.
+ Versión 1: `OTA_Err_t prvPAL_ResetDevice( void );`

  Versión 3: `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );`

  Notas: Restablece el dispositivo.
+ Versión 1: `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );`

  Versión 3: `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );`

  Notas: Autentica y cierra el archivo de recepción subyacente en el contexto OTA especificado.
+ Versión 1: `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );`

  Versión 3: `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );`

  Notas: Detiene una transferencia OTA.
+ Versión 1: `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );`

  Versión 3: `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );`

  Notas: Intenta establecer el estado de la imagen de actualización de la OTA.
+ Versión 1: `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );`

  Versión 3: `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );`

  Notas: Obtiene el estado de la imagen de actualización OTA.

### Data Types
<a name="porting-migration-ota-pal-data-types"></a>


****  

|  Versión 1   |  Archivos  |  Versión 3   |  Archivos  |  Notas   | 
| --- | --- | --- | --- | --- | 
| `OTA_PAL_ImageState_t` | `aws_iot_ota_agent.h` | `OtaPalImageState_t` | `ota_private.h` | *El estado de la imagen establecido por la implementación de la plataforma.* | 
| `OTA_Err_t` | `aws_iot_ota_agent.h` | `OtaErr_t OtaPalStatus_t (combination of OtaPalMainStatus_t and OtaPalSubStatus_t)` | `ota.h`, `ota_platform_interface.h` | v1: eran macros que definían un entero de 32 sin signo.<br />v3: enumeración especializada que representa el tipo de error y está asociada a un código de error. | 
| `OTA_FileContext_t` | `aws_iot_ota_agent.h` | `OtaFileContext_t` | `ota_private.h` | v1: contiene una enumeración y búferes para los datos.<br />v3: contiene variables de longitud de datos adicionales. | 
| `OTA_ImageState_t` | `aws_iot_ota_agent.h` | `OtaImageState_t` | `ota_private.h` | *Estados de imagen OTA* | 
+ Versión 1: `OTA_PAL_ImageState_t`

  Archivo: `aws_iot_ota_agent.h`

  Versión 3: `OtaPalImageState_t`

  Archivo: `ota_private.h`

  Notas: *El estado de la imagen establecido por la implementación de la plataforma.*
+ Versión 1: `OTA_Err_t`

  Archivo: `aws_iot_ota_agent.h`

  Versión 3: `OtaErr_t OtaPalStatus_t (combination of OtaPalMainStatus_t and OtaPalSubStatus_t)`

  Archivo: `ota.h`, `ota_platform_interface.h`

  Notas: v1: eran macros que definían un entero de 32 sin signo. v3: enumeración especializada que representa el tipo de error y está asociada a un código de error.
+ Versión 1: `OTA_FileContext_t`

  Archivo: `aws_iot_ota_agent.h`

  Versión 3: `OtaFileContext_t`

  Archivo: `ota_private.h`

  Notas: v1: contiene una enumeración y búferes para los datos. v3: contiene variables de longitud de datos adicionales.
+ Versión 1: `OTA_ImageState_t`

  Archivo: `aws_iot_ota_agent.h`

  Versión 3: `OtaImageState_t`

  Archivo: `ota_private.h`

  Notas: *Estados de la imagen OTA*

### Cambios de configuración
<a name="porting-migration-ota-pal-config-changes"></a>

Se cambió el nombre del archivo `aws_ota_agent_config.h` a [https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/aws_demos/config_files/ota_config.h](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/aws_demos/config_files/ota_config.h), lo que cambia las protecciones de inclusión de `_AWS_OTA_AGENT_CONFIG_H_` a `OTA_CONFIG_H_`.
+ El archivo `aws_ota_codesigner_certificate.h` se ha eliminado.
+ Se ha incluido la nueva pila de registro para imprimir los mensajes de depuración:

  ```
  /**************************************************/
  /******* DO NOT CHANGE the following order ********/
  /**************************************************/
  
  /* Logging related header files are required to be included in the following order:
   * 1. Include the header file "logging_levels.h".
   * 2. Define LIBRARY_LOG_NAME and  LIBRARY_LOG_LEVEL.
   * 3. Include the header file "logging_stack.h".
   */
  
  /* Include header that defines log levels. */
  #include "logging_levels.h"
  
  /* Configure name and log level for the OTA library. */
  #ifndef LIBRARY_LOG_NAME
      #define LIBRARY_LOG_NAME     "OTA"
  #endif
  #ifndef LIBRARY_LOG_LEVEL
      #define LIBRARY_LOG_LEVEL    LOG_INFO
  #endif
  
  #include "logging_stack.h"
  
  /************ End of logging configuration ****************/
  ```
+ Se ha añadido la configuración de constantes:

  ```
  /** * @brief Size of the file data block message (excluding the header). */   
  #define otaconfigFILE_BLOCK_SIZE ( 1UL << otaconfigLOG2_FILE_BLOCK_SIZE )
  ```

**Archivo nuevo:** [https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/aws_demos/config_files/ota_demo_config.h](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/aws_demos/config_files/ota_demo_config.h) contiene las configuraciones que requiere la demostración de OTA, como el certificado de firma de código y la versión de la aplicación.
+ `signingcredentialSIGNING_CERTIFICATE_PEM`, que se definió en `demos/include/aws_ota_codesigner_certificate.h`, se ha trasladado a `ota_demo_config.h` como `otapalconfigCODE_SIGNING_CERTIFICATE` y se puede acceder a él desde los archivos PAL de la siguiente manera: 

  ```
  static const char codeSigningCertificatePEM[] = otapalconfigCODE_SIGNING_CERTIFICATE;
  ```

  El archivo `aws_ota_codesigner_certificate.h` se ha eliminado.
+ Las macros `APP_VERSION_BUILD`, `APP_VERSION_MINOR` y `APP_VERSION_MAJOR` se han agregado a `ota_demo_config.h`. Se han eliminado los archivos antiguos que contenían la información de la versión, por ejemplo`tests/include/aws_application_version.h`, `libraries/c_sdk/standard/common/include/iot_appversion32.h`, `demos/demo_runner/aws_demo_version.c`.

## Cambios en las pruebas de PAL OTA
<a name="porting-migration-ota-pal-test-changes"></a>
+ Se ha eliminado el grupo de pruebas Full\_OTA\_AGENT «» junto con todos los archivos relacionados. Anteriormente, este grupo de pruebas era obligatorio para la calificación. Estas pruebas eran para la biblioteca OTA y no específicas para el puerto PAL OTA. La biblioteca OTA ahora tiene una cobertura de pruebas completa alojada en el repositorio OTA, por lo que este grupo de pruebas ya no es necesario.
+ Se han eliminado los grupos de prueba «Quarantine\_OTA\_CBOR» y «», así como todos los archivos relacionados. Full\_OTA\_CBOR Estas pruebas no formaban parte de las pruebas de calificación. Las funcionalidades que cubrían estas pruebas se están probando ahora en el repositorio OTA.
+ Se han trasladado los archivos de prueba del directorio de la biblioteca al directorio `tests/integration_tests/ota_pal`.
+ Se han actualizado las pruebas de calificación PAL OTA para utilizar la versión 3.0.0 de la API de la biblioteca OTA.
+ Se ha actualizado la forma en que las pruebas PAL OTA acceden al certificado de firma de código para las pruebas. Anteriormente, había un archivo de encabezado dedicado a la credencial de firma de código. Este ya no es el caso de la nueva versión de la biblioteca. El código de prueba espera que esta variable esté definida en `ota_pal.c`. El valor se asigna a una macro que se define en el archivo de configuración OTA específico de la plataforma.

## Lista de comprobación
<a name="porting-migration-ota-pal-test-checklist"></a>

Utilice esta lista de verificación para asegurarse de seguir los pasos necesarios para la migración:
+ Actualice el nombre de la carpeta del puerto PAL OTA de `ota` a`ota_pal_for_aws`.
+ Añada el archivo `ota_pal.h` con las funciones mencionadas anteriormente. Para ver un `ota_pal.h` archivo de ejemplo, consulte [ GitHub](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/ports/ota_pal_for_aws/ota_pal.h).
+ Añada los archivos de configuración:
  + Cambie el nombre del archivo de `aws_ota_agent_config.h` a (o cree) `ota_config.h`.
    + Añada:

      ```
      otaconfigFILE_BLOCK_SIZE ( 1UL << otaconfigLOG2_FILE_BLOCK_SIZE )
      ```
    + Incluya:

      ```
      #include "ota_demo_config.h"
      ```
  + Copie los archivos anteriores a la carpeta `aws_test config` y sustituya los que se incluyen en `ota_demo_config.h` por `aws_test_ota_config.h`.
  + Añada un archivo `ota_demo_config.h`.
  + Añada un archivo `aws_test_ota_config.h`.
+ Realice los siguientes cambios en `ota_pal.c`: 
  + Actualice las inclusiones con los nombres de archivo de la biblioteca OTA más recientes.
  + Elimine la macro `DEFINE_OTA_METHOD_NAME`.
  + Actualice las firmas de las funciones PAL OTA.
  + Actualice el nombre de la variable de contexto del archivo de `C` a `pFileContext`.
  + Actualice la estructura `OTA_FileContext_t` y todas las variables relacionadas.
  + Actualice `cOTA_JSON_FileSignatureKey` a `OTA_JsonFileSignatureKey`.
  + Actualice los tipos `OTA_PAL_ImageState_t` y `Ota_ImageState_t`.
  + Actualice el tipo y los valores de error.
  + Actualice las macros de impresión para usar la pila de registro.
  + Actualice `signingcredentialSIGNING_CERTIFICATE_PEM` para que sea `otapalconfigCODE_SIGNING_CERTIFICATE`.
  + Actualice los comentarios de las funciones `otaPal_CheckFileSignature` y `otaPal_ReadAndAssumeCertificate`.
+ Actualice el archivo [https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a](https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a).
+ Actualice los proyectos del IDE.