As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Migrando da versão 1 para a versão 3 para a porta OTA PAL
<a name="porting-migration-ota-pal"></a>

A Biblioteca de atualizações sem fios introduziu algumas mudanças na estrutura de pastas e no posicionamento das configurações exigidas pela biblioteca e pelas aplicações de demonstração. Para que aplicações OTA projetadas para funcionar com a v1.2.0 migrem para a v3.0.0 da biblioteca, você deve atualizar as assinaturas da função da porta PAL e incluir arquivos de configuração adicionais, conforme descrito neste guia de migração.

## Alterações em OTA PAL
<a name="porting-migration-ota-pal-changes"></a>
+ O nome do diretório da porta OTA PAL foi atualizado de `ota` para `ota_pal_for_aws`. Essa pasta deve conter dois arquivos: `ota_pal.c` e `ota_pal.h`. O arquivo de cabeçalho PAL `libraries/freertos_plus/aws/ota/src/aws_iot_ota_pal.h` foi excluído da biblioteca OTA e deve ser definido dentro da porta.
+ Os códigos de retorno (`OTA_Err_t`) são convertidos em uma enumeração `OTAMainStatus_t`. Consulte [ota\$1platform\$1interface.h](https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/v3.0.0/source/include/ota_platform_interface.h#L68-L90) para obter os códigos de retorno convertidos. [ Macros auxiliares](https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/666241d0f643b07d5146a3715b649d80f8135e0b/source/include/ota_platform_interface.h#L105-L111) também são fornecidas para combinar os códigos `OtaPalMainStatus` e `OtaPalSubStatus`. e extrair `OtaMainStatus` de `OtaPalStatus` e similares.
+ Registro em log na PAL 
  + Remova a macro `DEFINE_OTA_METHOD_NAME`.
  + Anteriormente: `OTA_LOG_L1( "[%s] Receive file created.\r\n", OTA_METHOD_NAME );`.
  + Atualizado: use `LogInfo(( "Receive file created."));`, `LogDebug`, `LogWarn` e `LogError` para o log apropriado.
+ Variável `cOTA_JSON_FileSignatureKey` alterada para `OTA_JsonFileSignatureKey`.

### Funções
<a name="porting-migration-ota-pal-functions"></a>

As assinaturas da função são definidas em `ota_pal.h` e começam com o prefixo `otaPal` em vez de `prvPAL`.

**nota**  
O nome exato do PAL é tecnicamente aberto, mas para ser compatível com os testes de qualificação, o nome deve estar de acordo com os especificados abaixo.


****  

|  Versão 1   |  Versão 3   |  Observações   | 
| --- | --- | --- | 
|  `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );`  |  `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );`  |  Cria um novo arquivo de recebimento para os blocos de dados à medida que eles chegam.  | 
|  `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 );`  |  Grava um bloco de dados no arquivo especificado no deslocamento determinado.   | 
|  `OTA_Err_t prvPAL_ActivateNewImage( void );`  |  `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );`  |  Ativa a imagem MCU mais recente recebida via OTA.  | 
|  `OTA_Err_t prvPAL_ResetDevice( void );`  |  `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );`  |  Redefinir o dispositivo.  | 
|  `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );`  |  `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );`  |  Autentica e fecha o arquivo de recebimento subjacente no contexto OTA especificado.  | 
|  `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );`  |  `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );`  |  Interrompe uma transferência OTA.  | 
|  `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );`  |  `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );`  |  Tenta definir o estado da imagem de atualização OTA.  | 
|  `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );`  |  `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );`  |  Obtém o estado da imagem de atualização OTA.  | 
+ Versão 1: `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );`

  Versão 3: `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );`

  Observações: cria um novo arquivo de recebimento para os blocos de dados à medida que eles chegam.
+ Versão 1: `int16_t prvPAL_WriteBlock( OTA_FileContext_t * const C, uint32_t ulOffset, uint8_t * const pcData, uint32_t ulBlockSize );`

  Versão 3: `int16_t otaPal_WriteBlock( OtaFileContext_t * const pFileContext, uint32_t ulOffset, uint8_t * const pData, uint32_t ulBlockSize );`

  Grava um bloco de dados no arquivo especificado no deslocamento determinado. 
+ Versão 1: `OTA_Err_t prvPAL_ActivateNewImage( void );`

  Versão 3: `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );`

  Observações: ativa a imagem MCU mais recente recebida via OTA.
+ Versão 1: `OTA_Err_t prvPAL_ResetDevice( void );`

  Versão 3: `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );`

  Observações: reinicia o dispositivo.
+ Versão 1: `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );`

  Versão 3: `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );`

  Observações: autentica e fecha o arquivo de recebimento subjacente no contexto OTA especificado.
+ Versão 1: `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );`

  Versão 3: `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );`

  Observações: interrompe uma transferência OTA.
+ Versão 1: `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );`

  Versão 3: `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );`

  Observações: tenta definir o estado da imagem de atualização OTA.
+ Versão 1: `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );`

  Versão 3: `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );`

  Observações: obtém o estado da imagem de atualização OTA.

### Tipos de dados
<a name="porting-migration-ota-pal-data-types"></a>


****  

|  Versão 1   |  Arquivo  |  Versão 3   |  Arquivo  |  Observações   | 
| --- | --- | --- | --- | --- | 
|  `OTA_PAL_ImageState_t`  |  `aws_iot_ota_agent.h`  |  `OtaPalImageState_t`  |  `ota_private.h`  |  *O estado da imagem definido pela implementação da 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: essas eram macros definindo um número inteiro de 32 não assinado. v3: enumeração especializada representando o tipo de erro e associada a um código de erro.  | 
|  `OTA_FileContext_t`  |  `aws_iot_ota_agent.h`  |  `OtaFileContext_t`  |  `ota_private.h`  |  v1: contém uma enumeração e buffers para os dados. v3: contém variáveis adicionais de comprimento de dados.  | 
|  `OTA_ImageState_t`  |  `aws_iot_ota_agent.h`  |  `OtaImageState_t`  |  `ota_private.h`  |  *Estados da imagem OTA*  | 
+ Versão 1: `OTA_PAL_ImageState_t`

  Arquivo , : `aws_iot_ota_agent.h`

  Versão 3: `OtaPalImageState_t`

  Arquivo , : `ota_private.h`

  Observações: *o estado da imagem definido pela implementação da plataforma.*
+ Versão 1: `OTA_Err_t`

  Arquivo , : `aws_iot_ota_agent.h`

  Versão 3: `OtaErr_t OtaPalStatus_t (combination of OtaPalMainStatus_t and OtaPalSubStatus_t)`

  Arquivo `ota.h`, `ota_platform_interface.h`

  Observações: v1: esses macros definiam um número inteiro de 32 não assinado. v3: enumeração especializada representando o tipo de erro e associada a um código de erro.
+ Versão 1: `OTA_FileContext_t`

  Arquivo , : `aws_iot_ota_agent.h`

  Versão 3: `OtaFileContext_t`

  Arquivo , : `ota_private.h`

  Observações: v1: contém uma enumeração e buffers para os dados. v3: contém variáveis adicionais de comprimento de dados.
+ Versão 1: `OTA_ImageState_t`

  Arquivo , : `aws_iot_ota_agent.h`

  Versão 3: `OtaImageState_t`

  Arquivo , : `ota_private.h`

  *Observações: estados de imagem OTA*

### Alterações de configuração
<a name="porting-migration-ota-pal-config-changes"></a>

O arquivo `aws_ota_agent_config.h` foi renomeado para [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), o que altera as guards incluídos de `_AWS_OTA_AGENT_CONFIG_H_` para `OTA_CONFIG_H_`.
+ O arquivo `aws_ota_codesigner_certificate.h` foi excluído.
+ Incluiu a nova pilha de registro em log para imprimir mensagens de depuração:

  ```
  /**************************************************/
  /******* 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 ****************/
  ```
+ Configuração constante adicionada:

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

**Novo arquivo:** [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) contém as configurações exigidas pela demonstração OTA, como o certificado de assinatura de código e a versão da aplicação.
+ `signingcredentialSIGNING_CERTIFICATE_PEM` que foi definido em `demos/include/aws_ota_codesigner_certificate.h` foi movido para `ota_demo_config.h` as `otapalconfigCODE_SIGNING_CERTIFICATE` e pode ser acessado a partir dos arquivos PAL como: 

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

  O arquivo `aws_ota_codesigner_certificate.h` foi excluído.
+ As macros`APP_VERSION_BUILD`, `APP_VERSION_MINOR`, `APP_VERSION_MAJOR` foram adicionadas a `ota_demo_config.h`. Os arquivos antigos contendo as informações da versão foram removidos, por exemplo `tests/include/aws_application_version.h`, `libraries/c_sdk/standard/common/include/iot_appversion32.h`, `demos/demo_runner/aws_demo_version.c`.

## Alterações nos testes OTA PAL
<a name="porting-migration-ota-pal-test-changes"></a>
+ O grupo de teste "FULL\$1OTA\$1Agent" foi removido junto com todos os arquivos relacionados. Esse grupo de teste era exigido anteriormente para qualificação. Esses testes foram para a biblioteca OTA e não específicos para a porta OTA PAL. A biblioteca OTA agora tem cobertura de teste completa hospedada no repositório OTA, portanto, esse grupo de teste não é mais necessário.
+ Os grupos de teste "Full\$1OTA\$1CBOR" e "Quarantine\$1OTA\$1CBOR" fora removidos, bem como todos os arquivos relacionados. Esses testes não faziam parte dos testes de qualificação. As funcionalidades abordadas por esses testes agora estão sendo testadas no repositório OTA.
+ Os arquivos de teste foram movidos do diretório da biblioteca para o diretório `tests/integration_tests/ota_pal`.
+ Os testes de qualificação OTA PAL foram atualizados para usar a versão 3.0.0 da API da biblioteca OTA.
+ A forma como os testes OTA PAL acessam o certificado de assinatura de código para testes foi atualizada. Anteriormente, havia um arquivo de cabeçalho dedicado para a credencial de assinatura de código. Esse não é mais o caso da nova versão da biblioteca. O código de teste espera que essa variável seja definida em `ota_pal.c`. O valor é atribuído a uma macro definida no arquivo de configuração OTA específico da plataforma.

## Lista de verificação
<a name="porting-migration-ota-pal-test-checklist"></a>

Use essa lista de verificação para seguir as etapas necessárias para a migração:
+ Atualize o nome da pasta da porta OTA PAL de `ota` para `ota_pal_for_aws`.
+ Adicione o arquivo `ota_pal.h` com as funções mencionadas acima. Para ver um exemplo de arquivo `ota_pal.h`, consulte [ GitHub](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/ports/ota_pal_for_aws/ota_pal.h).
+ Adicione os arquivos de configuração:
  + Altere o nome do arquivo de `aws_ota_agent_config.h` para (ou crie) `ota_config.h`.
    + Adicionar:

      ```
      otaconfigFILE_BLOCK_SIZE ( 1UL << otaconfigLOG2_FILE_BLOCK_SIZE )
      ```
    + Inclusão:

      ```
      #include "ota_demo_config.h"
      ```
  + Copie os arquivos acima para a pasta `aws_test config` e substitua as inclusões de `ota_demo_config.h` por `aws_test_ota_config.h`.
  + Adicione um arquivo `ota_demo_config.h`.
  + Adicione um arquivo `aws_test_ota_config.h`.
+ Faça as seguintes alterações em `ota_pal.c`: 
  + Atualize as inclusões com os nomes mais recentes dos arquivos da biblioteca OTA.
  + Remova a macro `DEFINE_OTA_METHOD_NAME`.
  + Atualize as assinaturas das funções OTA PAL.
  + Atualize o nome da variável de contexto do arquivo de `C` para `pFileContext`.
  + Atualize a estrutura `OTA_FileContext_t` e todas as variáveis relacionadas.
  + Atualize `cOTA_JSON_FileSignatureKey` para `OTA_JsonFileSignatureKey`.
  + Atualize os tipos `OTA_PAL_ImageState_t` e `Ota_ImageState_t`.
  + Atualize o tipo de erro e os valores.
  + Atualize as macros de impressão para usar a pilha de registro em log.
  + Atualize o `signingcredentialSIGNING_CERTIFICATE_PEM` para ser `otapalconfigCODE_SIGNING_CERTIFICATE`.
  + Atualize os comentários de função `otaPal_CheckFileSignature` e `otaPal_ReadAndAssumeCertificate`.
+ Para atualizar o arquivo [https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a](https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a).
+ Atualize os projetos do IDE.