翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# OTA PAL 移植のバージョン 1 からバージョン 3 への移行
<a name="porting-migration-ota-pal"></a>

無線通信経由の更新ライブラリによって、フォルダ構造に加え、ライブラリとデモアプリケーションに必要な設定の配置にいくつかの変更が加えられました。v1.2.0 と連携するよう設計された OTA アプリケーションをライブラリの v3.0.0 に移行させるには、この移行ガイドに従って、PAL 移植機能の署名を更新し、複数の設定ファイルを追加する必要があります。

## OTA PAL への変更
<a name="porting-migration-ota-pal-changes"></a>
+ OTA PAL 移植のディレクトリ名は、`ota` から `ota_pal_for_aws` に更新されました。このフォルダには、`ota_pal.c` と `ota_pal.h` の 2 つのファイルが含まれている必要があります。PAL のヘッダーファイル `libraries/freertos_plus/aws/ota/src/aws_iot_ota_pal.h` は OTA ライブラリから削除されているため、ポート内で定義する必要があります。
+ リターンコード (`OTA_Err_t`) は、列挙型 `OTAMainStatus_t` に変換されます。変換後のリターンコードについては、[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) を参照してください。[また、ヘルパーマクロ](https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/666241d0f643b07d5146a3715b649d80f8135e0b/source/include/ota_platform_interface.h#L105-L111)も用意されているので、`OtaPalMainStatus` と `OtaPalSubStatus` のコードをマージしたり、`OtaMainStatus` を `OtaPalStatus` などから抽出したりする際に活用できます。
+ PAL でのログ記録 
  + `DEFINE_OTA_METHOD_NAME` マクロを削除。
  + 以前: `OTA_LOG_L1( "[%s] Receive file created.\r\n", OTA_METHOD_NAME );`
  + 更新後: `LogInfo(( "Receive file created."));` (目的のログを取得する際は、`LogDebug`、`LogWarn`、`LogError` を使用すること)
+ 変数 `cOTA_JSON_FileSignatureKey` を `OTA_JsonFileSignatureKey` に変更。

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

関数の署名は `ota_pal.h` で定義され、プレフィックスは `prvPAL` ではなく `otaPal` を使用します。

**注記**  
PAL の正確な名前は、技術的には自由に設定できますが、資格認定テストに対応させるためには、以下に示す名前と一致させる必要があります。


****  

|  バージョン 1   |  バージョン 3   |  注意事項   | 
| --- | --- | --- | 
| `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );` | まとまった受信データを格納する新しい受信ファイルを作成します。 | 
| `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 );` | 指定されたファイルに、指定されたオフセットでデータのブロックを書き込みます。 | 
| `OTA_Err_t prvPAL_ActivateNewImage( void );` | `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );` | OTA 経由で受信した最新の MCU イメージをアクティブ化します。 | 
| `OTA_Err_t prvPAL_ResetDevice( void );` | `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );` | デバイスをリセットします。 | 
| `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );` | 指定された OTA コンテキストの基盤となっている受信ファイルを認証し、閉じます。 | 
| `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );` | OTA 転送を停止します。 | 
| `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );` | `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );` | OTA 更新イメージの状態の設定を実施します。 | 
| `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );` | `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );` | OTA 更新イメージの状態を取得します。 | 
+ バージョン 1: `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );` 

  バージョン 3: `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );` 

  注: まとまった受信データを格納する新しい受信ファイルを作成します。
+ バージョン 1: `int16_t prvPAL_WriteBlock( OTA_FileContext_t * const C, uint32_t ulOffset, uint8_t * const pcData, uint32_t ulBlockSize );` 

  バージョン 3: `int16_t otaPal_WriteBlock( OtaFileContext_t * const pFileContext, uint32_t ulOffset, uint8_t * const pData, uint32_t ulBlockSize );` 

  注: 指定されたファイルに、指定されたオフセットでデータブロックを書き込みます。
+ バージョン 1: `OTA_Err_t prvPAL_ActivateNewImage( void );` 

  バージョン 3: `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );` 

  注: OTA 経由で受信した最新の MCU イメージをアクティブ化します。
+ バージョン 1: `OTA_Err_t prvPAL_ResetDevice( void );` 

  バージョン 3: `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );` 

  注: デバイスをリセットします。
+ バージョン 1: `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );` 

  バージョン 3: `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );` 

  注: 指定された OTA コンテキストの基盤となっている受信ファイルを認証し、閉じます。
+ バージョン 1: `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );` 

  バージョン 3: `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );` 

  注: OTA 転送を停止します。
+ バージョン 1: `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );` 

  バージョン 3: `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );` 

  注: OTA 更新イメージの状態の設定を実施します。
+ バージョン 1: `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );` 

  バージョン 3: `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );` 

  注: OTA 更新イメージの状態を取得します。

### データ型
<a name="porting-migration-ota-pal-data-types"></a>


****  

|  バージョン 1   |  システム  |  バージョン 3   |  システム  |  注意事項   | 
| --- | --- | --- | --- | --- | 
| `OTA_PAL_ImageState_t` | `aws_iot_ota_agent.h` | `OtaPalImageState_t` | `ota_private.h` | *プラットフォームの実装によって設定されたイメージの状態。* | 
| `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: 符号のない 32 個の整数を定義するマクロ。<br />v3: エラーの種類を表す特殊な列挙型であり、エラーコードに関連付けられた型。 | 
| `OTA_FileContext_t` | `aws_iot_ota_agent.h` | `OtaFileContext_t` | `ota_private.h` | v1: データの列挙型とバッファを含む。<br />v3: 追加のデータ長変数を含む。 | 
| `OTA_ImageState_t` | `aws_iot_ota_agent.h` | `OtaImageState_t` | `ota_private.h` | *OTA イメージの状態* | 
+ バージョン 1: `OTA_PAL_ImageState_t` 

  ファイル: `aws_iot_ota_agent.h`

  バージョン 3: `OtaPalImageState_t` 

  ファイル: `ota_private.h`

  注: *プラットフォームの実装によって設定されたイメージの状態。*
+ バージョン 1: `OTA_Err_t` 

  ファイル: `aws_iot_ota_agent.h`

  バージョン 3: `OtaErr_t OtaPalStatus_t (combination of OtaPalMainStatus_t and OtaPalSubStatus_t)` 

  ファイル: `ota.h`、`ota_platform_interface.h`

  注: v1: 符号のない 32 個の整数を定義するマクロ。v3: エラーの種類を表す特殊な列挙型であり、エラーコードに関連付けられた型。
+ バージョン 1: `OTA_FileContext_t` 

  ファイル: `aws_iot_ota_agent.h`

  バージョン 3: `OtaFileContext_t` 

  ファイル: `ota_private.h`

  注: v1: データの列挙型とバッファを含む。v3: 追加のデータ長変数を含む。
+ バージョン 1: `OTA_ImageState_t` 

  ファイル: `aws_iot_ota_agent.h`

  バージョン 3: `OtaImageState_t` 

  ファイル: `ota_private.h`

  注: *OTA イメージの状態*

### 設定変更
<a name="porting-migration-ota-pal-config-changes"></a>

ファイル `aws_ota_agent_config.h` の名前が [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) に変更されました。これにより、インクルードガードが `_AWS_OTA_AGENT_CONFIG_H_` から `OTA_CONFIG_H_` に変更されます。
+ ファイル `aws_ota_codesigner_certificate.h` は、削除されました。
+ デバッグメッセージを印刷するための新しいログ記録スタックが追加されました。

  ```
  /**************************************************/
  /******* 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 ****************/
  ```
+ 定数設定が追加されました。

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

**新規ファイル:** [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) には、コード署名の証明書やアプリケーションバージョンなど、OTA デモで必要な設定が含まれています。
+ `demos/include/aws_ota_codesigner_certificate.h` で定義された `signingcredentialSIGNING_CERTIFICATE_PEM` は、`otapalconfigCODE_SIGNING_CERTIFICATE` として `ota_demo_config.h` に移動しました。なお、次のように指定すると PAL ファイルからアクセスできます。

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

  ファイル `aws_ota_codesigner_certificate.h` は、削除されました。
+ `APP_VERSION_BUILD`、`APP_VERSION_MINOR`、`APP_VERSION_MAJOR` のマクロが `ota_demo_config.h` に追加されました。バージョン情報を含む `tests/include/aws_application_version.h`、`libraries/c_sdk/standard/common/include/iot_appversion32.h`、`demos/demo_runner/aws_demo_version.c` などの古いファイルは、削除されました。

## OTA PAL テストの変更点
<a name="porting-migration-ota-pal-test-changes"></a>
+ 「Full\_OTA\_AGENT」テストグループとそのすべての関連ファイルを削除しました。従来、このテストグループは資格に必要でした。これらのテストは OTA ライブラリ用であり、OTA PAL 移植に特有のものではありません。現在の OTA ライブラリは、OTA リポジトリでホストされるテストをすべて網羅しているため、このテストグループは不要となりました。
+ 「Full\_OTA\_CBOR」と「Quarantine\_OTA\_CBOR」テストグループを削除し、そのすべての関連ファイルも削除しました。これらのテストは、資格認定テストに含まれていませんでした。削除されたテストの対象だった機能については、OTA リポジトリでテストされています。
+ テストファイルをライブラリディレクトリから `tests/integration_tests/ota_pal` ディレクトリに移動させました。
+ OTA ライブラリ API の v3.0.0 を使用するよう、OTA PAL 資格認定テストを更新しました。
+ OTA PAL テストが、テスト用のコード署名の証明書にアクセスする方法を更新しました。以前は、コード署名の認証情報専用のヘッダーファイルが存在しましたが、新しいバージョンのライブラリは、その点が変更されています。テストコードでは、この変数が `ota_pal.c` で定義されることを想定しています。その値は、プラットフォーム固有の OTA 設定ファイルで定義されたマクロに割り当てられます。

## チェックリスト
<a name="porting-migration-ota-pal-test-checklist"></a>

このチェックリストを使用して、移行に必要な手順を実行していることを確認します。
+ OTA PAL 移植フォルダの名前を `ota` から `ota_pal_for_aws` に更新します。
+ 上記の機能を含んだファイル `ota_pal.h` を追加します。`ota_pal.h` ファイルの例については、[GitHub](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/ports/ota_pal_for_aws/ota_pal.h) を参照してください。
+ 設定ファイルを追加します。
  + ファイル名を `aws_ota_agent_config.h` から `ota_config.h` に変更するか、新しく という名前のファイルを作成します。
    + 追加:

      ```
      otaconfigFILE_BLOCK_SIZE ( 1UL << otaconfigLOG2_FILE_BLOCK_SIZE )
      ```
    + インクルード:

      ```
      #include "ota_demo_config.h"
      ```
  + 上記のファイルを `aws_test config` フォルダにコピーし、`ota_demo_config.h` に含まれているものをすべて `aws_test_ota_config.h` に置き換えます。
  + `ota_demo_config.h` ファイルを追加します。
  + `aws_test_ota_config.h` ファイルを追加します。
+ `ota_pal.c` に以下の変更を加えます。
  + インクルードを最新の OTA ライブラリファイル名に更新します。
  + `DEFINE_OTA_METHOD_NAME` マクロを削除します。
  + OTA PAL 関数の署名を更新します。
  + ファイルコンテキスト変数の名前を `C` から `pFileContext` に更新します。
  + `OTA_FileContext_t` 構造体とそれに関連するすべての変数を更新します。
  + `cOTA_JSON_FileSignatureKey` を `OTA_JsonFileSignatureKey` に更新します。
  + `OTA_PAL_ImageState_t` と `Ota_ImageState_t` のタイプを更新します。
  + エラータイプとエラー値を更新します。
  + 印刷マクロを更新し、ログ記録スタックを使用するようにします。
  + `otapalconfigCODE_SIGNING_CERTIFICATE` になるよう `signingcredentialSIGNING_CERTIFICATE_PEM` を更新します。
  + `otaPal_CheckFileSignature` と `otaPal_ReadAndAssumeCertificate` の関数のコメントを更新します。
+ [https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a](https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a) ファイルを更新します。
+ IDE プロジェクトを更新します。