Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Migrasi dari versi 1 ke versi 3 untuk port OTA PAL
<a name="porting-migration-ota-pal"></a>

Perpustakaan Over-the-air Pembaruan memperkenalkan beberapa perubahan dalam struktur folder dan penempatan konfigurasi yang diperlukan oleh perpustakaan dan aplikasi demo. Untuk aplikasi OTA yang dirancang untuk bekerja dengan v1.2.0 untuk bermigrasi ke v3.0.0 pustaka, Anda harus memperbarui tanda tangan fungsi port PAL dan menyertakan file konfigurasi tambahan seperti yang dijelaskan dalam panduan migrasi ini.

## Perubahan OTA PAL
<a name="porting-migration-ota-pal-changes"></a>
+ Nama direktori port OTA PAL telah diperbarui dari `ota` ke`ota_pal_for_aws`. Folder ini harus berisi 2 file: `ota_pal.c` dan`ota_pal.h`. File header PAL `libraries/freertos_plus/aws/ota/src/aws_iot_ota_pal.h` telah dihapus dari perpustakaan OTA dan harus ditentukan di dalam port.
+ Kode pengembalian (`OTA_Err_t`) diterjemahkan ke dalam enum`OTAMainStatus_t`. Lihat [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) untuk kode pengembalian yang diterjemahkan. [ Makro pembantu](https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/666241d0f643b07d5146a3715b649d80f8135e0b/source/include/ota_platform_interface.h#L105-L111) juga disediakan untuk menggabungkan `OtaPalMainStatus` dan `OtaPalSubStatus` kode dan mengekstrak `OtaMainStatus` dari `OtaPalStatus` dan serupa.
+ Masuk ke PAL 
  + Menghapus `DEFINE_OTA_METHOD_NAME` makro.
  + Sebelumnya:`OTA_LOG_L1( "[%s] Receive file created.\r\n", OTA_METHOD_NAME );`.
  + Diperbarui: `LogInfo(( "Receive file created."));` Gunakan`LogDebug`, `LogWarn` dan `LogError` untuk log yang sesuai.
+ Variabel `cOTA_JSON_FileSignatureKey` berubah menjadi`OTA_JsonFileSignatureKey`.

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

Tanda tangan fungsi didefinisikan `ota_pal.h` dan dimulai dengan awalan, bukan`otaPal`. `prvPAL`

**catatan**  
Nama pasti PAL secara teknis terbuka, tetapi agar kompatibel dengan tes kualifikasi, nama tersebut harus sesuai dengan yang ditentukan di bawah ini.


****  

|  Versi 1   |  Versi 3   |  Catatan   | 
| --- | --- | --- | 
|  `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );`  |  `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );`  |  Buat file penerima baru untuk potongan data saat mereka masuk.  | 
|  `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 );`  |  Tulis blok data ke file yang ditentukan pada offset yang diberikan.   | 
|  `OTA_Err_t prvPAL_ActivateNewImage( void );`  |  `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );`  |  Aktifkan gambar MCU terbaru yang diterima melalui OTA.  | 
|  `OTA_Err_t prvPAL_ResetDevice( void );`  |  `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );`  |  Setel ulang perangkat.  | 
|  `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );`  |  `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );`  |  Otentikasi dan tutup file penerima yang mendasarinya dalam konteks OTA yang ditentukan.  | 
|  `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );`  |  `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );`  |  Hentikan transfer OTA.  | 
|  `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );`  |  `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );`  |  Mencoba untuk mengatur status gambar pembaruan OTA.  | 
|  `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );`  |  `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );`  |  Dapatkan status gambar pembaruan OTA.  | 
+ Versi 1: `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );`

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

  Catatan: Buat file penerimaan baru untuk potongan data saat masuk.
+ Versi 1: `int16_t prvPAL_WriteBlock( OTA_FileContext_t * const C, uint32_t ulOffset, uint8_t * const pcData, uint32_t ulBlockSize );`

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

  Catatan: Tulis blok data ke file yang ditentukan pada offset yang diberikan. 
+ Versi 1: `OTA_Err_t prvPAL_ActivateNewImage( void );`

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

  Catatan: Aktifkan gambar MCU terbaru yang diterima melalui OTA.
+ Versi 1: `OTA_Err_t prvPAL_ResetDevice( void );`

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

  Catatan: Setel ulang perangkat.
+ Versi 1: `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );`

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

  Catatan: Mengautentikasi dan menutup file penerima yang mendasarinya dalam konteks OTA yang ditentukan.
+ Versi 1: `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );`

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

  Catatan: Hentikan transfer OTA.
+ Versi 1: `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );`

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

  Catatan: Mencoba mengatur status gambar pembaruan OTA.
+ Versi 1: `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );`

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

  Catatan: Dapatkan status gambar pembaruan OTA.

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


****  

|  Versi 1   |  File  |  Versi 3   |  File  |  Catatan   | 
| --- | --- | --- | --- | --- | 
|  `OTA_PAL_ImageState_t`  |  `aws_iot_ota_agent.h`  |  `OtaPalImageState_t`  |  `ota_private.h`  |  *Status gambar diatur oleh implementasi platform.*  | 
|  `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: Ini adalah makro yang mendefinisikan 32 bilangan bulat yang tidak ditandatangani. v3: Enum khusus yang mewakili jenis kesalahan dan terkait dengan kode kesalahan.  | 
|  `OTA_FileContext_t`  |  `aws_iot_ota_agent.h`  |  `OtaFileContext_t`  |  `ota_private.h`  |  v1: Berisi enum dan buffer untuk data. v3: Berisi variabel panjang data tambahan.  | 
|  `OTA_ImageState_t`  |  `aws_iot_ota_agent.h`  |  `OtaImageState_t`  |  `ota_private.h`  |  *OTA Image menyatakan*  | 
+ Versi 1: `OTA_PAL_ImageState_t`

  Berkas: `aws_iot_ota_agent.h`

  Versi 3: `OtaPalImageState_t`

  Berkas: `ota_private.h`

  Catatan: *Status gambar yang ditetapkan oleh implementasi platform.*
+ Versi 1: `OTA_Err_t`

  Berkas: `aws_iot_ota_agent.h`

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

  Berkas:`ota.h`, `ota_platform_interface.h`

  Catatan: v1: Ini adalah makro yang mendefinisikan 32 bilangan bulat yang tidak ditandatangani. v3: Enum khusus yang mewakili jenis kesalahan dan terkait dengan kode kesalahan.
+ Versi 1: `OTA_FileContext_t`

  Berkas: `aws_iot_ota_agent.h`

  Versi 3: `OtaFileContext_t`

  Berkas: `ota_private.h`

  Catatan: v1: Berisi enum dan buffer untuk data. v3: Berisi variabel panjang data tambahan.
+ Versi 1: `OTA_ImageState_t`

  Berkas: `aws_iot_ota_agent.h`

  Versi 3: `OtaImageState_t`

  Berkas: `ota_private.h`

  Catatan: *Status gambar OTA*

### Perubahan konfigurasi
<a name="porting-migration-ota-pal-config-changes"></a>

File `aws_ota_agent_config.h` diubah namanya menjadi [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)yang mengubah penjaga include dari `_AWS_OTA_AGENT_CONFIG_H_` ke`OTA_CONFIG_H_`.
+ File `aws_ota_codesigner_certificate.h` telah dihapus.
+ Termasuk tumpukan logging baru untuk mencetak pesan 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 ****************/
  ```
+ Menambahkan konfigurasi konstan:

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

**File Baru: [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)**berisi konfigurasi yang diperlukan oleh demo OTA seperti sertifikat penandatanganan kode dan versi aplikasi.
+ `signingcredentialSIGNING_CERTIFICATE_PEM`yang didefinisikan dalam `demos/include/aws_ota_codesigner_certificate.h` telah dipindahkan ke `ota_demo_config.h` as `otapalconfigCODE_SIGNING_CERTIFICATE` dan dapat diakses dari file PAL sebagai: 

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

  File `aws_ota_codesigner_certificate.h` telah dihapus.
+ Makro`APP_VERSION_BUILD`,`APP_VERSION_MINOR`, `APP_VERSION_MAJOR` telah ditambahkan ke`ota_demo_config.h`. File lama yang berisi informasi versi telah dihapus, misalnya `tests/include/aws_application_version.h``libraries/c_sdk/standard/common/include/iot_appversion32.h`,`demos/demo_runner/aws_demo_version.c`.

## Perubahan pada tes OTA PAL
<a name="porting-migration-ota-pal-test-changes"></a>
+ Menghapus grup uji “Full\$1ota\$1agent” bersama dengan semua file terkait. Kelompok uji ini sebelumnya diperlukan untuk kualifikasi. Tes ini untuk perpustakaan OTA dan tidak khusus untuk port OTA PAL. Pustaka OTA sekarang memiliki cakupan pengujian lengkap yang di-host di repositori OTA sehingga grup pengujian ini tidak lagi diperlukan.
+ Menghapus grup uji “Full\$1OTA\$1CBOR” dan “Quarantine\$1OTA\$1CBOR” serta semua file terkait. Tes ini bukan bagian dari tes kualifikasi. Fungsionalitas yang dicakup tes ini sekarang sedang diuji di repositori OTA.
+ Memindahkan file pengujian dari direktori perpustakaan ke `tests/integration_tests/ota_pal` direktori.
+ Memperbarui tes kualifikasi OTA PAL untuk menggunakan v3.0.0 dari API perpustakaan OTA.
+ Memperbarui cara pengujian OTA PAL mengakses sertifikat penandatanganan kode untuk pengujian. Sebelumnya ada file header khusus untuk kredensi penandatanganan kode. Ini tidak lagi berlaku untuk versi baru perpustakaan. Kode pengujian mengharapkan variabel ini didefinisikan dalam`ota_pal.c`. Nilai ditetapkan ke makro yang didefinisikan dalam file konfigurasi OTA khusus platform.

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

Gunakan daftar periksa ini untuk memastikan Anda mengikuti langkah-langkah yang diperlukan untuk migrasi:
+ Perbarui nama folder port ota pal dari `ota` ke`ota_pal_for_aws`.
+ Tambahkan file `ota_pal.h` dengan fungsi yang disebutkan di atas. Untuk `ota_pal.h` file contoh, lihat [ GitHub](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/ports/ota_pal_for_aws/ota_pal.h).
+ Tambahkan file konfigurasi:
  + Ubah nama file dari `aws_ota_agent_config.h` menjadi (atau buat)`ota_config.h`.
    + Tambahkan:

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

      ```
      #include "ota_demo_config.h"
      ```
  + Salin file di atas ke `aws_test config` folder dan ganti semua termasuk `ota_demo_config.h` dengan`aws_test_ota_config.h`.
  + Tambahkan `ota_demo_config.h` file.
  + Tambahkan `aws_test_ota_config.h` file.
+ Buat perubahan berikut ke`ota_pal.c`: 
  + Perbarui sertakan dengan nama file pustaka OTA terbaru.
  + Hapus `DEFINE_OTA_METHOD_NAME` makro.
  + Perbarui tanda tangan fungsi OTA PAL.
  + Perbarui nama variabel konteks file dari `C` ke`pFileContext`.
  + Perbarui `OTA_FileContext_t` struct dan semua variabel terkait.
  + Perbarui `cOTA_JSON_FileSignatureKey` ke`OTA_JsonFileSignatureKey`.
  + Perbarui `OTA_PAL_ImageState_t` dan `Ota_ImageState_t` jenisnya.
  + Perbarui jenis kesalahan dan nilai.
  + Perbarui makro pencetakan untuk menggunakan tumpukan logging.
  + Perbarui `signingcredentialSIGNING_CERTIFICATE_PEM` yang akan menjadi`otapalconfigCODE_SIGNING_CERTIFICATE`.
  + Perbarui `otaPal_CheckFileSignature` dan `otaPal_ReadAndAssumeCertificate` fungsi komentar.
+ Perbarui [https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a](https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a)file.
+ Perbarui proyek IDE.