Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

# Migration von Version 1 zu Version 3 für den OTA-PAL-Port
<a name="porting-migration-ota-pal"></a>

Mit der Over-the-air Updates-Bibliothek wurden einige Änderungen an der Ordnerstruktur und der Platzierung der Konfigurationen vorgenommen, die für die Bibliothek und die Demo-Anwendungen erforderlich sind. Damit OTA-Anwendungen, die für die Verwendung mit Version 1.2.0 entwickelt wurden, auf Version 3.0.0 der Bibliothek migrieren können, müssen Sie die Funktionssignaturen des PAL-Ports aktualisieren und zusätzliche Konfigurationsdateien hinzufügen, wie in diesem Migrationshandbuch beschrieben.

## Änderungen an OTA PAL
<a name="porting-migration-ota-pal-changes"></a>
+ Der Name des OTA-PAL-Port-Verzeichnisses wurde von `ota` bis aktualisiert`ota_pal_for_aws`. Dieser Ordner muss 2 Dateien enthalten: `ota_pal.c` und`ota_pal.h`. Die PAL-Header-Datei `libraries/freertos_plus/aws/ota/src/aws_iot_ota_pal.h` wurde aus der OTA-Bibliothek gelöscht und muss innerhalb des Ports definiert werden.
+ Die Rückgabecodes (`OTA_Err_t`) werden in eine `OTAMainStatus_t` Aufzählung übersetzt. Übersetzte Rückgabecodes finden Sie auf [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). [ Es stehen auch Hilfsmakros](https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/666241d0f643b07d5146a3715b649d80f8135e0b/source/include/ota_platform_interface.h#L105-L111) zum Kombinieren `OtaPalMainStatus` und `OtaPalSubStatus` Codieren sowie `OtaMainStatus` Extrahieren `OtaPalStatus` und Ähnlichem zur Verfügung.
+ Im PAL einloggen 
  + Das `DEFINE_OTA_METHOD_NAME` Makro wurde entfernt.
  + Vorhin:`OTA_LOG_L1( "[%s] Receive file created.\r\n", OTA_METHOD_NAME );`.
  + Aktualisiert: `LogInfo(( "Receive file created."));` Verwenden Sie`LogDebug`, `LogWarn` und `LogError` für das entsprechende Protokoll.
+ Die Variable `cOTA_JSON_FileSignatureKey` wurde geändert in`OTA_JsonFileSignatureKey`.

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

Die Funktionssignaturen sind in definiert `ota_pal.h` und beginnen mit dem Präfix `otaPal` anstelle von`prvPAL`.

**Anmerkung**  
Der genaue Name des PAL ist technisch gesehen offen, aber um mit den Qualifikationstests kompatibel zu sein, sollte der Name den unten angegebenen entsprechen.


****  

|  Version 1   |  Version 3   |  Hinweise   | 
| --- | --- | --- | 
| `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );` | Erstellen Sie eine neue Empfangsdatei für die eingehenden Datenblöcke. | 
| `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 );` | Schreibt einen Datenblock am angegebenen Offset in die angegebene Datei.  | 
| `OTA_Err_t prvPAL_ActivateNewImage( void );` | `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );` | Aktiviert das neueste MCU-Image, das über OTA empfangen wurde. | 
| `OTA_Err_t prvPAL_ResetDevice( void );` | `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );` | Setzen Sie das Gerät zurück. | 
| `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );` | Authentifizieren und schließen Sie die zugrunde liegende Empfangsdatei im angegebenen OTA-Kontext. | 
| `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );` | Stoppt eine OTA-Übertragung. | 
| `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );` | `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );` | Versuchen Sie, den Status des OTA-Update-Images festzulegen. | 
| `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );` | `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );` | Rufen Sie den Status des OTA-Update-Images ab. | 
+ Version 1: `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );`

  Ausführung 3: `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );`

  Hinweise: Erstellen Sie eine neue Empfangsdatei für die eingehenden Datenblöcke.
+ Version 1: `int16_t prvPAL_WriteBlock( OTA_FileContext_t * const C, uint32_t ulOffset, uint8_t * const pcData, uint32_t ulBlockSize );`

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

  Hinweise: Schreibt einen Datenblock am angegebenen Offset in die angegebene Datei. 
+ Version 1: `OTA_Err_t prvPAL_ActivateNewImage( void );`

  Ausführung 3: `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );`

  Hinweise: Aktiviert das neueste MCU-Image, das über OTA empfangen wurde.
+ Version 1: `OTA_Err_t prvPAL_ResetDevice( void );`

  Ausführung 3: `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );`

  Hinweise: Setzen Sie das Gerät zurück.
+ Version 1: `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );`

  Ausführung 3: `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );`

  Hinweise: Authentifizieren und schließen Sie die zugrunde liegende Empfangsdatei im angegebenen OTA-Kontext.
+ Version 1: `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );`

  Ausführung 3: `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );`

  Hinweise: Stoppen Sie eine OTA-Übertragung.
+ Version 1: `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );`

  Ausführung 3: `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );`

  Hinweise: Versuch, den Status des OTA-Update-Images festzulegen.
+ Version 1: `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );`

  Ausführung 3: `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );`

  Hinweise: Rufen Sie den Status des OTA-Update-Images ab.

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


****  

|  Version 1   |  Datei  |  Version 3   |  Datei  |  Hinweise   | 
| --- | --- | --- | --- | --- | 
| `OTA_PAL_ImageState_t` | `aws_iot_ota_agent.h` | `OtaPalImageState_t` | `ota_private.h` | *Der durch die Plattformimplementierung festgelegte Image-Status.* | 
| `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: Dies waren Makros, die eine 32-Ganzzahl ohne Vorzeichen definierten.<br />v3: Spezialisierte Aufzählung, die die Art des Fehlers darstellt und einem Fehlercode zugeordnet ist. | 
| `OTA_FileContext_t` | `aws_iot_ota_agent.h` | `OtaFileContext_t` | `ota_private.h` | v1: Enthält eine Aufzählung und Puffer für die Daten.<br />v3: Enthält zusätzliche Variablen mit Datenlänge. | 
| `OTA_ImageState_t` | `aws_iot_ota_agent.h` | `OtaImageState_t` | `ota_private.h` | *OTA-Bildstatus* | 
+ Version 1: `OTA_PAL_ImageState_t`

  Datei: `aws_iot_ota_agent.h`

  Version 3: `OtaPalImageState_t`

  Datei: `ota_private.h`

  Hinweise: *Der durch die Plattformimplementierung festgelegte Image-Status.*
+ Version 1: `OTA_Err_t`

  Datei: `aws_iot_ota_agent.h`

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

  Datei:`ota.h`, `ota_platform_interface.h`

  Hinweise: v1: Dies waren Makros, die eine 32-Ganzzahl ohne Vorzeichen definierten. v3: Spezialisierte Aufzählung, die den Fehlertyp darstellt und mit einem Fehlercode verknüpft ist.
+ Version 1: `OTA_FileContext_t`

  Datei: `aws_iot_ota_agent.h`

  Version 3: `OtaFileContext_t`

  Datei: `ota_private.h`

  Hinweise: v1: Enthält eine Aufzählung und Puffer für die Daten. v3: Enthält zusätzliche Variablen mit Datenlänge.
+ Version 1: `OTA_ImageState_t`

  Datei: `aws_iot_ota_agent.h`

  Version 3: `OtaImageState_t`

  Datei: `ota_private.h`

  Hinweise: Status des *OTA-Images*

### Konfigurationsänderungen
<a name="porting-migration-ota-pal-config-changes"></a>

Die Datei `aws_ota_agent_config.h` wurde umbenannt, [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)wodurch sich der Include-Schutz von `_AWS_OTA_AGENT_CONFIG_H_` zu ändert`OTA_CONFIG_H_`.
+ Die Datei `aws_ota_codesigner_certificate.h` wurde gelöscht.
+ Der neue Logging-Stack zum Drucken von Debug-Nachrichten wurde hinzugefügt:

  ```
  /**************************************************/
  /******* 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 ****************/
  ```
+ Die konstante Konfiguration wurde hinzugefügt:

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

**Neue Datei: [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)**enthält die Konfigurationen, die für die OTA-Demo erforderlich sind, z. B. das Codesignaturzertifikat und die Anwendungsversion.
+ `signingcredentialSIGNING_CERTIFICATE_PEM`was in definiert wurde, `demos/include/aws_ota_codesigner_certificate.h` wurde nach `ota_demo_config.h` as verschoben `otapalconfigCODE_SIGNING_CERTIFICATE` und kann über die PAL-Dateien wie folgt abgerufen werden: 

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

  Die Datei `aws_ota_codesigner_certificate.h` wurde gelöscht.
+ Die Makros `APP_VERSION_BUILD``APP_VERSION_MINOR`,, `APP_VERSION_MAJOR` wurden hinzugefügt`ota_demo_config.h`. Die alten Dateien, die die Versionsinformationen enthielten, wurden entfernt, zum Beispiel `tests/include/aws_application_version.h``libraries/c_sdk/standard/common/include/iot_appversion32.h`,`demos/demo_runner/aws_demo_version.c`.

## Änderungen an den OTA-PAL-Tests
<a name="porting-migration-ota-pal-test-changes"></a>
+ Die Testgruppe „Full\_OTA\_Agent“ wurde zusammen mit allen zugehörigen Dateien entfernt. Diese Testgruppe war zuvor für die Qualifizierung erforderlich. Diese Tests betrafen die OTA-Bibliothek und waren nicht spezifisch für den OTA-PAL-Port. Die OTA-Bibliothek verfügt jetzt über eine vollständige Testabdeckung, die im OTA-Repository gehostet wird, sodass diese Testgruppe nicht mehr erforderlich ist.
+ Die Testgruppen „Full\_OTA\_CBOR“ und „Quarantine\_OTA\_CBOR“ sowie alle zugehörigen Dateien wurden entfernt. Diese Tests waren nicht Teil der Qualifikationstests. Die Funktionen, die diese Tests abdeckten, werden jetzt im OTA-Repository getestet.
+ Die Testdateien wurden aus dem Bibliotheksverzeichnis in das `tests/integration_tests/ota_pal` Verzeichnis verschoben.
+ Die OTA-PAL-Qualifikationstests wurden aktualisiert, sodass sie Version 3.0.0 der OTA-Bibliotheks-API verwenden.
+ Die Art und Weise, wie die OTA-PAL-Tests auf das Codesignaturzertifikat für Tests zugreifen, wurde aktualisiert. Bisher gab es eine spezielle Header-Datei für die Codesignatur-Anmeldeinformationen. Dies ist bei der neuen Version der Bibliothek nicht mehr der Fall. Der Testcode erwartet, dass diese Variable in definiert ist`ota_pal.c`. Der Wert wird einem Makro zugewiesen, das in der plattformspezifischen OTA-Konfigurationsdatei definiert ist.

## Checkliste
<a name="porting-migration-ota-pal-test-checklist"></a>

Verwenden Sie diese Checkliste, um sicherzustellen, dass Sie die für die Migration erforderlichen Schritte befolgen:
+ Aktualisieren Sie den Namen des Ota-Pal-Port-Ordners von `ota` bis`ota_pal_for_aws`.
+ Fügen Sie die Datei `ota_pal.h` mit den oben genannten Funktionen hinzu. Eine `ota_pal.h` Beispieldatei finden Sie unter [ GitHub](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/ports/ota_pal_for_aws/ota_pal.h).
+ Fügen Sie die Konfigurationsdateien hinzu:
  + Ändern Sie den Namen der Datei von `aws_ota_agent_config.h` zu (oder erstellen)`ota_config.h`.
    + Fügen Sie hinzu:

      ```
      otaconfigFILE_BLOCK_SIZE ( 1UL << otaconfigLOG2_FILE_BLOCK_SIZE )
      ```
    + Einschließen:

      ```
      #include "ota_demo_config.h"
      ```
  + Kopieren Sie die obigen Dateien in den `aws_test config` Ordner und ersetzen Sie alle Includes von `ota_demo_config.h` durch`aws_test_ota_config.h`.
  + Fügt eine `ota_demo_config.h` Datei hinzu.
  + Fügt eine `aws_test_ota_config.h` Datei hinzu.
+ Nehmen Sie die folgenden Änderungen an `ota_pal.c` vor: 
  + Aktualisieren Sie die Includes mit den neuesten OTA-Bibliotheksdateinamen.
  + Entfernen Sie das `DEFINE_OTA_METHOD_NAME`-Makro.
  + Aktualisieren Sie die Signaturen der OTA-PAL-Funktionen.
  + Aktualisieren Sie den Namen der Dateikontextvariablen von `C` bis`pFileContext`.
  + Aktualisieren Sie die `OTA_FileContext_t` Struktur und alle zugehörigen Variablen.
  + Aktualisieren `cOTA_JSON_FileSignatureKey` auf`OTA_JsonFileSignatureKey`.
  + Aktualisieren Sie die `Ota_ImageState_t` Typen `OTA_PAL_ImageState_t` und.
  + Aktualisieren Sie den Fehlertyp und die Fehlerwerte.
  + Aktualisieren Sie die Druckmakros, um den Protokollierungsstapel zu verwenden.
  + Aktualisieren Sie das `signingcredentialSIGNING_CERTIFICATE_PEM` zu sein. `otapalconfigCODE_SIGNING_CERTIFICATE`
  + Kommentare zum Update `otaPal_CheckFileSignature` und zur `otaPal_ReadAndAssumeCertificate` Funktion.
+ Aktualisiere die [https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a](https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a)Datei.
+ Aktualisieren Sie die IDE-Projekte.