Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Migrazione dalla versione 1 alla versione 3 per la porta OTA PAL
<a name="porting-migration-ota-pal"></a>

La libreria Over-the-air degli aggiornamenti ha introdotto alcune modifiche nella struttura delle cartelle e nel posizionamento delle configurazioni richieste dalla libreria e dalle applicazioni demo. Affinché le applicazioni OTA progettate per funzionare con la v1.2.0 possano migrare alla versione 3.0.0 della libreria, è necessario aggiornare le firme delle funzioni della porta PAL e includere file di configurazione aggiuntivi come descritto in questa guida alla migrazione.

## Modifiche a OTA PAL
<a name="porting-migration-ota-pal-changes"></a>
+ Il nome della directory delle porte OTA PAL è stato aggiornato dal `ota` al`ota_pal_for_aws`. Questa cartella deve contenere 2 file: `ota_pal.c` e`ota_pal.h`. Il file di intestazione PAL è `libraries/freertos_plus/aws/ota/src/aws_iot_ota_pal.h` stato eliminato dalla libreria OTA e deve essere definito all'interno della porta.
+ I codici restituiti (`OTA_Err_t`) vengono tradotti in un `OTAMainStatus_t` enum. Fai riferimento a [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) per i codici restituiti tradotti. [ Sono inoltre disponibili macro di supporto per](https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/666241d0f643b07d5146a3715b649d80f8135e0b/source/include/ota_platform_interface.h#L105-L111) combinare `OtaPalMainStatus` e `OtaPalSubStatus` codificare ed estrarre `OtaMainStatus` da `OtaPalStatus` e simili.
+ Accesso al PAL 
  + Rimossa la `DEFINE_OTA_METHOD_NAME` macro.
  + In precedenza:`OTA_LOG_L1( "[%s] Receive file created.\r\n", OTA_METHOD_NAME );`.
  + Aggiornato: `LogInfo(( "Receive file created."));` usa`LogDebug`, `LogWarn` e `LogError` per il registro appropriato.
+ Variabile `cOTA_JSON_FileSignatureKey` modificata in`OTA_JsonFileSignatureKey`.

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

Le firme delle funzioni sono definite in `ota_pal.h` e iniziano con il prefisso `otaPal` anziché. `prvPAL`

**Nota**  
Il nome esatto del PAL è tecnicamente aperto, ma per essere compatibile con i test di qualificazione, il nome deve essere conforme a quelli specificati di seguito.


****  

|  Versione 1   |  Versione 3   |  Note   | 
| --- | --- | --- | 
| `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );` | Crea un nuovo file di ricezione per i blocchi di dati non appena arrivano. | 
| `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 );` | Scrive un blocco di dati nel file specificato all'offset specificato.  | 
| `OTA_Err_t prvPAL_ActivateNewImage( void );` | `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );` | Attiva l'immagine MCU più recente ricevuta tramite OTA. | 
| `OTA_Err_t prvPAL_ResetDevice( void );` | `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );` | Reimposta il dispositivo. | 
| `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );` | Autentica e chiudi il file di ricezione sottostante nel contesto OTA specificato. | 
| `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );` | Interrompi un trasferimento OTA. | 
| `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );` | `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );` | Tentativo di impostare lo stato dell'immagine di aggiornamento OTA. | 
| `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );` | `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );` | Ottieni lo stato dell'immagine di aggiornamento OTA. | 
+ Versione 1: `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );`

  Versione 3: `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );`

  Note: crea un nuovo file di ricezione per i blocchi di dati non appena arrivano.
+ Versione 1: `int16_t prvPAL_WriteBlock( OTA_FileContext_t * const C, uint32_t ulOffset, uint8_t * const pcData, uint32_t ulBlockSize );`

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

  Note: scrive un blocco di dati nel file specificato all'offset specificato. 
+ Versione 1: `OTA_Err_t prvPAL_ActivateNewImage( void );`

  Versione 3: `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );`

  Note: attiva l'immagine MCU più recente ricevuta tramite OTA.
+ Versione 1: `OTA_Err_t prvPAL_ResetDevice( void );`

  Versione 3: `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );`

  Note: ripristina il dispositivo.
+ Versione 1: `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );`

  Versione 3: `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );`

  Note: autentica e chiude il file di ricezione sottostante nel contesto OTA specificato.
+ Versione 1: `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );`

  Versione 3: `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );`

  Note: interrompi un trasferimento OTA.
+ Versione 1: `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );`

  Versione 3: `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );`

  Note: tentativo di impostare lo stato dell'immagine di aggiornamento OTA.
+ Versione 1: `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );`

  Versione 3: `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );`

  Note: ottieni lo stato dell'immagine di aggiornamento OTA.

### Tipi di dati
<a name="porting-migration-ota-pal-data-types"></a>


****  

|  Versione 1   |  File  |  Versione 3   |  File  |  Note   | 
| --- | --- | --- | --- | --- | 
| `OTA_PAL_ImageState_t` | `aws_iot_ota_agent.h` | `OtaPalImageState_t` | `ota_private.h` | *Lo stato dell'immagine impostato dall'implementazione della piattaforma.* | 
| `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: Si trattava di macro che definivano un numero intero senza segno 32.<br />v3: enum specializzato che rappresenta il tipo di errore e associato a un codice di errore. | 
| `OTA_FileContext_t` | `aws_iot_ota_agent.h` | `OtaFileContext_t` | `ota_private.h` | v1: contiene un enum e dei buffer per i dati.<br />v3: contiene variabili aggiuntive per la lunghezza dei dati. | 
| `OTA_ImageState_t` | `aws_iot_ota_agent.h` | `OtaImageState_t` | `ota_private.h` | *Stati dell'immagine OTA* | 
+ Versione 1: `OTA_PAL_ImageState_t`

  File: `aws_iot_ota_agent.h`

  Versione 3: `OtaPalImageState_t`

  File: `ota_private.h`

  Note: *lo stato dell'immagine impostato dall'implementazione della piattaforma.*
+ Versione 1: `OTA_Err_t`

  File: `aws_iot_ota_agent.h`

  Versione 3: `OtaErr_t OtaPalStatus_t (combination of OtaPalMainStatus_t and OtaPalSubStatus_t)`

  File:`ota.h`, `ota_platform_interface.h`

  Note: v1: si trattava di macro che definivano un numero intero senza segno 32. v3: enum specializzato che rappresenta il tipo di errore e associato a un codice di errore.
+ Versione 1: `OTA_FileContext_t`

  File: `aws_iot_ota_agent.h`

  Versione 3: `OtaFileContext_t`

  File: `ota_private.h`

  Note: v1: contiene un enum e dei buffer per i dati. v3: contiene variabili aggiuntive per la lunghezza dei dati.
+ Versione 1: `OTA_ImageState_t`

  File: `aws_iot_ota_agent.h`

  Versione 3: `OtaImageState_t`

  File: `ota_private.h`

  Note: *stati dell'immagine OTA*

### Modifiche di configurazione
<a name="porting-migration-ota-pal-config-changes"></a>

Il file `aws_ota_agent_config.h` è stato rinominato in base al [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)quale vengono modificate le guardie di inclusione da a`_AWS_OTA_AGENT_CONFIG_H_`. `OTA_CONFIG_H_`
+ Il file `aws_ota_codesigner_certificate.h` è stato eliminato.
+ Incluso il nuovo stack di registrazione per stampare i messaggi di debug:

  ```
  /**************************************************/
  /******* 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 ****************/
  ```
+ Aggiunta la configurazione costante:

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

**Nuovo file: [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 le configurazioni richieste dalla demo OTA, come il certificato di firma del codice e la versione dell'applicazione.
+ `signingcredentialSIGNING_CERTIFICATE_PEM`che è stato definito in `demos/include/aws_ota_codesigner_certificate.h` è stato spostato in `otapalconfigCODE_SIGNING_CERTIFICATE` ed è possibile accedervi dai file PAL come: `ota_demo_config.h` 

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

  Il file `aws_ota_codesigner_certificate.h` è stato eliminato.
+ Le macro `APP_VERSION_BUILD` `APP_VERSION_MAJOR` sono state aggiunte a`ota_demo_config.h`. `APP_VERSION_MINOR` I vecchi file contenenti le informazioni sulla versione sono stati rimossi, ad esempio `tests/include/aws_application_version.h``libraries/c_sdk/standard/common/include/iot_appversion32.h`,`demos/demo_runner/aws_demo_version.c`.

## Modifiche ai test OTA PAL
<a name="porting-migration-ota-pal-test-changes"></a>
+ Rimosso il gruppo di test «Full\_OTA\_Agent» insieme a tutti i file correlati. Questo gruppo di test era precedentemente richiesto per la qualificazione. Questi test erano per la libreria OTA e non erano specifici per la porta OTA PAL. La libreria OTA ora ha una copertura completa dei test ospitata nel repository OTA, quindi questo gruppo di test non è più necessario.
+ Rimossi i gruppi di test «Full\_OTA\_CBOR» e «Quarantine\_OTA\_CBOR» e tutti i file correlati. Questi test non facevano parte dei test di qualificazione. Le funzionalità coperte da questi test vengono ora testate nell'archivio OTA.
+ I file di test sono stati spostati dalla directory della libreria alla `tests/integration_tests/ota_pal` directory.
+ Aggiornati i test di qualificazione OTA PAL per utilizzare la v3.0.0 dell'API della libreria OTA.
+ È stato aggiornato il modo in cui i test OTA PAL accedono al certificato di firma del codice per i test. In precedenza esisteva un file di intestazione dedicato per la credenziale di firma del codice. Questo non è più il caso della nuova versione della libreria. Il codice di test prevede che questa variabile venga definita in`ota_pal.c`. Il valore viene assegnato a una macro definita nel file di configurazione OTA specifico della piattaforma.

## Lista di controllo
<a name="porting-migration-ota-pal-test-checklist"></a>

Utilizza questa lista di controllo per assicurarti di seguire i passaggi richiesti per la migrazione:
+ Aggiorna il nome della cartella della porta ota pal da `ota` a`ota_pal_for_aws`.
+ Aggiungi il file `ota_pal.h` con le funzioni sopra menzionate. Per un `ota_pal.h` file di esempio, vedere [ GitHub](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/ports/ota_pal_for_aws/ota_pal.h).
+ Aggiungi i file di configurazione:
  + Cambia il nome del file da `aws_ota_agent_config.h` a (o crea)`ota_config.h`.
    + Aggiungi:

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

      ```
      #include "ota_demo_config.h"
      ```
  + Copia i file di cui sopra nella `aws_test config` cartella e sostituisci le eventuali inclusioni `ota_demo_config.h` con`aws_test_ota_config.h`.
  + Aggiungi un `ota_demo_config.h` file.
  + Aggiungere un `aws_test_ota_config.h` file.
+ Apportare le modifiche seguenti a `ota_pal.c`: 
  + Aggiorna gli include con i nomi di file della libreria OTA più recenti.
  + Rimuovere la macro `DEFINE_OTA_METHOD_NAME`.
  + Aggiorna le firme delle funzioni OTA PAL.
  + Aggiorna il nome della variabile di contesto del file da `C` a`pFileContext`.
  + Aggiorna la `OTA_FileContext_t` struttura e tutte le variabili correlate.
  + Aggiorna `cOTA_JSON_FileSignatureKey` a`OTA_JsonFileSignatureKey`.
  + Aggiorna i `Ota_ImageState_t` tipi `OTA_PAL_ImageState_t` e.
  + Aggiorna il tipo e i valori di errore.
  + Aggiorna le macro di stampa per utilizzare lo stack di registrazione.
  + Aggiorna il file to be`signingcredentialSIGNING_CERTIFICATE_PEM`. `otapalconfigCODE_SIGNING_CERTIFICATE`
  + Commenti sull'aggiornamento `otaPal_CheckFileSignature` e sulle `otaPal_ReadAndAssumeCertificate` funzioni.
+ Aggiorna il [https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a](https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a)file.
+ Aggiorna i progetti IDE.