Espressif ESP32-DevKitC と ESP-WROVER-KIT の開始方法

このチュートリアルでは、ESP32-WROOM-32、ESP32-SOLO-1、または ESP-WROVER モジュール、および ESP-WROVER-KIT-VB を搭載した Espressif ESP32-DevKitC の使用を開始するための手順について説明します。AWS Partner Device catalog のパートナーから購入するには、ESP32-WROOM-32 DevKitC、ESP32-SOLO-1、または ESP32-WROVER-KIT のリンクをご利用ください。開発ボードのこれらのバージョンが Amazon FreeRTOS でサポートされています。これらのボードの詳細については、Espressif ウェブサイトの「ESP32-DevKitC」または「ESP-WROVER-KIT」を参照してください。

概要

このチュートリアルには、使用開始のための以下の手順が含まれています。

前提条件

Espressif ボードで Amazon FreeRTOS を使い始める前に、AWS アカウントとアクセス許可を設定する必要があります。

AWS アカウントを作成するには、「AWS アカウントの作成とアクティベート」を参照してください。

IAM ユーザーを AWS アカウントに追加するには、「IAM ユーザーガイド」を参照してください。AWS IoT および Amazon FreeRTOS に IAM ユーザーアカウントのアクセスを付与するには、IAM ユーザーアカウントに以下の IAM ポリシーをアタッチします。

IAM およびユーザーアカウントの詳細については、IAM ユーザーガイド を参照してください。

ポリシーの詳細については、「IAM アクセス権限とポリシー」を参照してください。

Espressif ハードウェアの設定

ESP32-DevKitC 開発ボードハードウェアの設定の詳細については、ESP32-DevKitC 入門ガイドを参照してください。

ESP-WROVER-KIT 開発ボードハードウェアの設定の詳細については、ESP-WROVER-KIT 入門ガイドを参照してください。

開発環境の設定

ボードと通信するには、ツールチェーンをダウンロードしてインストールする必要があります。

ツールチェーンの設定

ツールチェーンを設定するには、ホストマシンのオペレーティングシステムの指示に従ってください。

CMake をインストールする

CMake ビルドシステムは、このデバイスの Amazon FreeRTOS デモとテストアプリケーションをビルドするために必要です。Amazon FreeRTOS では、バージョン 3.13 以降がサポートされています。

CMake.org から CMake の最新バージョンをダウンロードできます。ソースとバイナリ配布のいずれも利用可能です。

Amazon FreeRTOS で CMake の使用に関する詳細については、「Amazon FreeRTOS による CMake の使用」を参照してください。

シリアル接続の確立

ホストマシンと ESP32-DevKitC の間にシリアル接続を確立するには、CP210x USB を UART Bridge VCP ドライバーにインストールする必要があります。これらのドライバーは Silicon Labs からダウンロードできます。

ホストマシンと ESP32-WROVER-KIT の間にシリアル接続を確立するには、一部の FTDI 仮想 COM ポートドライバーをインストールする必要があります。これらのドライバーは FTDI からダウンロードできます。

詳細については、「ESP32 とのシリアル接続を確立する」を参照してください。シリアル接続を確立したら、ボードとの接続用のシリアルポートをメモしておきます。デモを構築する際に必要になります。

Amazon FreeRTOS をダウンロードして設定する

環境をセットアップすると、GitHub、または Amazon FreeRTOS コンソールから Amazon FreeRTOS をダウンロードできるようになります。手順については、README.md ファイルを参照してください。

Amazon FreeRTOS デモアプリケーションを設定する

Amazon FreeRTOS には、AWS IoT に接続するための Espressif ボードのセットアップを容易にする SetupAWS.py スクリプトが含まれています。このスクリプトを設定するには、<amazon-freertos>/tools/aws_config_quick_start/configure.json を開いて次の属性を設定します。

スクリプトでは次のことが実行されます。

SetupAWS.py の詳細については、<amazon-freertos>/tools/aws_config_quick_start ディレクトリにある README.md を参照してください。

Amazon FreeRTOS デモプロジェクトをビルド、フラッシュ、および実行する

CMake を使用してビルドファイルを生成し、Make を使用してアプリケーションバイナリをビルドし、Espressif の IDF ユーティリティを使用してボードをフラッシュできます。

Amazon FreeRTOS をビルドする

(Windows を使用している場合は、次のセクションを参照してください)

CMake を使用してビルドファイルを生成してから、Make を使用してアプリケーションをビルドします。

Windows で Amazon FreeRTOS をビルドする

Windows では、CMake に対してビルドジェネレータを指定する必要があります。指定しない場合、CMake はデフォルトを Visual Studio に使用します。Ninja ビルドシステムは Windows、Linux、および MacOS で機能するため、Expressif では Ninja ビルドシステムが公式に推奨されます。CMake コマンドは、cmd あるいは powershell などのネイティブの Windows 環境で実行する必要があります。MSYS2 や WSL などの仮想 Linux 環境で CMake コマンドを実行することはサポートされていません。

CMake を使用してビルドファイルを生成してから、Make を使用してアプリケーションをビルドします。

Amazon FreeRTOS をフラッシュおよび実行する

Espressif の IDF ユーティリティ (<amazon-freertos>/vendors/espressif/esp-idf/tools/idf.py) を使用して、ボードをフラッシュし、アプリケーションを実行し、ログを表示します。

ボードのフラッシュを消去するには、<amazon-freertos> ディレクトリに移動し、次のコマンドを使用します。

./vendors/espressif/esp-idf/tools/idf.py erase_flash -B build

アプリケーションバイナリをボードにフラッシュするには、make を使用します。

make flash

また、次のように IDF スクリプトを使用してボードをフラッシュすることもできます。

./vendors/espressif/esp-idf/tools/idf.py flash -B build

モニタリングするには、次のコマンドを使用します。

./vendors/espressif/esp-idf/tools/idf.py monitor -p /dev/ttyUSB1 -B build

./vendors/espressif/esp-idf/tools/idf.py erase_flash flash monitor -p /dev/ttyUSB1 -B build

クラウド上の MQTT メッセージのモニタリング

デバイスが AWS クラウドに送信するメッセージをモニタリングするには、AWS IoT コンソールで MQTT クライアントを使用します。

Bluetooth Low-Energy デモを実行する

Amazon FreeRTOS は、Bluetooth Low Energy 接続をサポートしています。

Bluetooth Low Energy で Amazon FreeRTOS デモプロジェクトを実行するには、iOS または Android のモバイルデバイスで Amazon FreeRTOS Bluetooth Low Energy Mobile SDK デモアプリケーションを実行する必要があります。

ボードで MQTT over Bluetooth Low Energy デモを実行する方法については、「MQTT over Bluetooth Low Energy デモアプリケーション」を参照してください。

ボードで Wi-Fi プロビジョニングデモを実行する方法については、「Wi-Fi プロビジョニングデモアプリケーション」を参照してください。

ESP32 用の独自の CMake プロジェクトで Amazon FreeRTOS を使用する

あなた自身の CMake プロジェクトで Amazon FreeRTOS を消費したい場合は、それをサブディレクトリとして設定し、アプリケーションと一緒にビルドすることができます。まず、GitHub、または Amazon FreeRTOS コンソールから Amazon FreeRTOS のコピーを取得します。git を使用している場合は、次のコマンドで git サブモジュールとして設定することもできます。これにより、将来更新が容易になります。

git submodule add -b release https://github.com/aws/amazon-freertos.git amazon-freertos

新しいバージョンがリリースされた場合、これらのコマンドを使用してローカルコピーを更新できます。

# Pull the latest changes from the remote tracking branch.
git submodule update --remote -- amazon-freertos
# Commit the submodule change because it is pointing to a different revision now.
git add amazon-freertos
git commit -m "Update Amazon FreeRTOS to a new release"

プロジェクトのディレクトリ構造が次のものであると仮定します。

- amazon-freertos (the copy that you obtained from GitHub or the AWS IoT console)
- src
  - main.c (your application code)
- CMakeLists.txt

以下に、Amazon FreeRTOS を使用してアプリケーションを構築するために使用できる最上位 CMakeLists.txt ファイルの例を示します。

cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

add_executable(my_app src/main.c)

# Tell IDF build to link against this target.
set(IDF_PROJECT_EXECUTABLE my_app)

# Add amazon freertos as a subdirectory. AFR_BOARD tells which board to target.
set(AFR_BOARD espressif.esp32_devkitc CACHE INTERNAL "")
add_subdirectory(amazon-freertos)

# Link against the mqtt library so that we can use it. Dependencies are transitively
# linked.
target_link_libraries(my_app PRIVATE AFR::mqtt)

プロジェクトをビルドするには、次の CMake コマンドを実行します。ESP32 コンパイラが PATH 環境変数にあることを確認してください。

cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=amazon-freertos/tools/cmake/toolchains/xtensa-esp32.cmake -GNinja
cmake --build build

アプリケーションをボードにフラッシュするには、

cmake --build build --target flash

Amazon FreeRTOS からコンポーネントを使用する

CMake を実行した後、サマリー出力で使用可能なすべてのコンポーネントを見つけることができます。次のように表示されます。

====================Configuration for Amazon FreeRTOS====================
  Version:                 201910.00
  Git version:             201910.00-388-gcb3612cb7

Target microcontroller:
  vendor:                  Espressif
  board:                   ESP32-DevKitC
  description:             Development board produced by Espressif that comes in two
                           variants either with ESP-WROOM-32 or ESP32-WROVER module
  family:                  ESP32
  data ram size:           520KB
  program memory size:     4MB

Host platform:
  OS:                      Linux-4.15.0-66-generic
  Toolchain:               xtensa-esp32
  Toolchain path:          /opt/xtensa-esp32-elf
  CMake generator:         Ninja

Amazon FreeRTOS modules:
  Modules to build:        ble, ble_hal, ble_wifi_provisioning, common, crypto, defender,
                           dev_mode_key_provisioning, freertos_plus_tcp, greengrass,
                           https, kernel, mqtt, ota, pkcs11, pkcs11_implementation,
                           platform, secure_sockets, serializer, shadow, tls, wifi
  Enabled by user:         ble, ble_hal, ble_wifi_provisioning, defender, greengrass,
                           https, mqtt, ota, pkcs11, pkcs11_implementation, platform,
                           secure_sockets, shadow, wifi
  Enabled by dependency:   common, crypto, demo_base, dev_mode_key_provisioning,
                           freertos, freertos_plus_tcp, kernel, pkcs11_mbedtls,
                           secure_sockets_freertos_plus_tcp, serializer, tls, utils
  3rdparty dependencies:   http_parser, jsmn, mbedtls, pkcs11, tinycbor
  Available demos:         demo_ble, demo_ble_numeric_comparison, demo_defender,
                           demo_greengrass_connectivity, demo_https, demo_mqtt, demo_ota,
                           demo_shadow, demo_tcp, demo_wifi_provisioning
  Available tests:
=========================================================================

「構築するモジュール」リストから任意のコンポーネントを参照できます。それらをアプリケーションにリンクするには、名前の前に AFR:: 名前空間を置きます。たとえば AFR::mqtt、AFR::ota などです。

ESP-IDF へのカスタムコンポーネントの追加

ESP-IDF ビルド環境にさらにコンポーネントを追加できます。たとえば、foo というコンポーネントを追加し、プロジェクトは次のようになります。

- amazon-freertos
- components
  - foo
    - include
      - foo.h
    - src
      - foo.c
    - CMakeLists.txt
- src
  - main.c
- CMakeLists.txt

次に、コンポーネントの CMakeLists.txt ファイルの例を示します。

# include paths of this components.
set(COMPONENT_ADD_INCLUDEDIRS include)

# source files of this components.
set(COMPONENT_SRCDIRS src)
# Alternatively, use COMPONENT_SRCS to specify source files explicitly
# set(COMPONENT_SRCS src/foo.c)

# add this components, this will define a CMake library target.
register_component()

標準の CMake 関数 target_link_libraries を使用して依存関係を指定することもできます。コンポーネントのターゲット名は、ESP-IDF で定義された変数 COMPONENT_TARGET に格納されていることに注意してください。

# add this component, this will define a CMake library target.
register_component()

# standard CMake function can be used to specify dependencies. ${COMPONENT_TARGET} is defined
# from esp-idf when you call register_component, by default it's idf_component_<folder_name>.
target_link_libraries(${COMPONENT_TARGET} PRIVATE AFR::mqtt)

ESP コンポーネントの場合、これは 2 つの変数 COMPONENT_REQUIRES と COMPONENT_PRIV_REQUIRES を設定することによって行われます。ESP-IDF Programming Guide の「When Writing a Component」を参照してください。

# If the dependencies are from ESP-IDF, use these 2 variables. Note these need to be
# set before calling register_component().
set(COMPONENT_REQUIRES log)
set(COMPONENT_PRIV_REQUIRES lwip)

次に、最上位レベルの CMakeLists.txt ファイルで、これらのコンポーネントを検索する場所を ESP-IDF に指示します。add_subdirectory(amazon-freertos) の前の任意の場所に次の行を挿入します。

# Add some extra components. IDF_EXTRA_COMPONENT_DIRS is an variable used by ESP-IDF
# to collect extra components.
get_filename_component(
    EXTRA_COMPONENT_DIRS
    "components/foo" ABSOLUTE
)
list(APPEND IDF_EXTRA_COMPONENT_DIRS ${EXTRA_COMPONENT_DIRS})

このコンポーネントは、デフォルトでアプリケーションコードに自動的にリンクされるようになりました。ヘッダーファイルを含めて、定義する関数を呼び出すことができるはずです。

Amazon FreeRTOS の構成を上書きする

現在、Amazon FreeRTOS ソースツリーの外で構成を再定義するための明確なアプローチはありません。デフォルトでは、CMake は <amazon-freertos>/vendors/espressif/boards/esp32/aws_demos/config_files/ ディレクトリと <amazon-freertos>/demos/include/ ディレクトリを探します。ただし、回避策を使用して、最初に他のディレクトリを検索するようにコンパイラに指示できます。たとえば、Amazon FreeRTOS 構成用に別のフォルダを追加できます。

- amazon-freertos
- amazon-freertos-configs
  - aws_clientcredential.h
  - aws_clientcredential_keys.h
  - iot_mqtt_agent_config.h
  - iot_config.h
- components
- src
- CMakeLists.txt

amazon-freertos-configs の下にあるファイルは、<amazon-freertos>/vendors/espressif/boards/esp32/aws_demos/config_files/ ディレクトリと <amazon-freertos>/demos/include/i ディレクトリからコピーされます。次に、最上位レベルの CMakeLists.txt ファイルで、コンパイラがこのディレクトリを最初に検索するように、この行を add_subdirectory(amazon-freertos) の前に追加します。

include_directories(BEFORE amazon-freertos-configs)

ESP-IDF 用の独自の sdkconfig を提供する

独自の sdkconfig.default を提供したい場合は、コマンドラインから CMake 変数 IDF_SDKCONFIG_DEFAULTS を設定することができます。

cmake -S . -B build -DIDF_SDKCONFIG_DEFAULTS=<path_to_your_sdkconfig_defaults> -DCMAKE_TOOLCHAIN_FILE=amazon-freertos/tools/cmake/toolchains/xtensa-esp32.cmake -GNinja

独自の sdkconfig.default ファイルの場所を指定しない場合、Amazon FreeRTOS は <amazon-freertos>/vendors/espressif/boards/esp32/aws_demos/sdkconfig.defaults にあるデフォルトのファイルを使用します。

概要

foo という名前のコンポーネントを持つプロジェクトがあり、いくつかの設定を上書きする場合、最上位レベルの CMakeLists.txt ファイルの完全な例を次に示します。

cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

add_executable(my_app src/main.c)

# Tell IDF build to link against this target.
set(IDF_PROJECT_EXECUTABLE my_app)

# Add some extra components. IDF_EXTRA_COMPONENT_DIRS is an variable used by ESP-IDF
# to collect extra components.
get_filename_component(
    EXTRA_COMPONENT_DIRS
    "components/foo" ABSOLUTE
)
list(APPEND IDF_EXTRA_COMPONENT_DIRS ${EXTRA_COMPONENT_DIRS})

# Override the configurations for Amazon FreeRTOS.
include_directories(BEFORE amazon-freertos-configs)

# Add amazon freertos as a subdirectory. AFR_BOARD tells which board to target.
set(AFR_BOARD espressif.esp32_devkitc CACHE INTERNAL "")
add_subdirectory(amazon-freertos)

# Link against the mqtt library so that we can use it. Dependencies are transitively
# linked.
target_link_libraries(my_app PRIVATE AFR::mqtt)

トラブルシューティング

Amazon FreeRTOS の開始方法に関する一般的なトラブルシューティングについては、「トラブルシューティングの開始方法」を参照してください。

Espressif ESP32-DevKitC および ESP-WROVER-KIT のデバッグコード

JTAG to USB ケーブルが必要です。USB to MPSSE を使用します (例: FTDI C232HM-DDHSL-0)。

ESP-DevKitC JTAG セットアップ

FTDI C232HM-DDHSL-0 ケーブルの場合、これらは ESP32 DevkitC への接続です。

ESP-WROVER-KIT JTAG セットアップ

FTDI C232HM-DDHSL-0 ケーブルの場合、これらは ESP32-WROVER-KIT への接続です。

これらのテーブルは、FTDI C232HM-DDHSL-0 データシートから開発されました。詳細については、データシートの C232HM MPSSE Cable Connection and Mechanical Details を参照してください。

ESP-WROVER-KIT で JTAG を有効にするには、次に示すように TMS、TDO、TDI、TCK、S_TDI のピンにジャンパーを配置します。

Windows でのデバッグ

macOS でのデバッグ

Linux でのデバッグ