Introdução ao Espressif ESP32- DevKit C e ao ESP-WROVER-KIT

Importante

Essa integração de referência está hospedada no repositório Amazon-FreeRTOS, que está preterido. Recomendamos começar aqui ao criar um novo projeto. Se você já tem um projeto FreeRTOS existente baseado no repositório Amazon-FreeRTOS que está preterido, consulte o Guia de migração do repositório Github do Amazon FreeRTOS.

nota

Para explorar como integrar bibliotecas modulares e demonstrações do FreeRTOS no seu projeto Espressif IDF, consulte nossa Integração de referência em destaque para a plataforma ESP32-C3.

Siga este tutorial para começar a usar o Espressif ESP32- DevKit C equipado com os módulos ESP32-WROOM-32, ESP32-SOLO-1 ou ESP-WROVER e o ESP-WROVER-KIT-VB. Para comprar um de nosso parceiro no catálogo do AWS Device Partner, use os links a seguir:

• ESP32-QUARTO-32 C DevKit

• ESP32-SOLO-1

• ESP32-WROVER-KIT

Essas versões das placas de desenvolvimento são compatíveis com o FreeRTOS.

Para obter mais informações sobre as versões mais recentes dessas placas, consulte ESP32- DevKit C V4 ou ESP-WROVER-KIT v4.1 no site da Espressif.

nota

Atualmente, a porta FreeRTOS para ESP32-WROVER-KIT e DevKit ESP C não suporta o recurso de multiprocessamento simétrico (SMP).

Visão geral

Este tutorial orienta você pelas seguintes etapas:

1. Conectar sua placa a uma máquina host.

2. Instalar software na máquina host para desenvolver e depurar aplicativos incorporados para seu microcontrolador.

3. Compilar um aplicativo de demonstração do FreeRTOS de forma cruzada para uma imagem binária.

4. Carregar a imagem binária do aplicativo em sua placa e executar o aplicativo.

5. Interagir com o aplicativo em execução na placa em uma conexão serial para fins de monitoramento e depuração.

Pré-requisitos

Antes de começar a usar o FreeRTOS na placa Espressif, é necessário configurar as permissões e a conta da AWS.

Cadastrar-se em uma Conta da AWS

Se você ainda não tem uma Conta da AWS, siga as etapas a seguir para criar uma.

Para se cadastrar em uma Conta da AWS

1. Abra https://portal.aws.amazon.com/billing/signup.

2. Siga as instruções on-line.

   Parte do procedimento de aplicação envolve receber uma chamada telefônica e digitar um código de verificação no teclado do telefone.

   Quando você se cadastra em uma Conta da AWS, um Usuário raiz da conta da AWS é criado. O usuário raiz tem acesso a todos os Serviços da AWS e atributos na conta. Como prática recomendada de segurança, atribua acesso administrativo a um usuário administrativo e use somente o usuário raiz para realizar as tarefas que exigem acesso do usuário raiz.

A AWS envia um e-mail de confirmação depois que o processo de cadastramento é concluído. A qualquer momento, é possível visualizar as atividades da conta atual e gerenciar sua conta acessando https://aws.amazon.com/ e selecionando Minha conta.

Criar um usuário administrativo

Depois de se inscrever em uma Conta da AWS, proteja seu Usuário raiz da conta da AWS, habilite o AWS IAM Identity Center e crie um usuário administrativo para não usar o usuário raiz em tarefas cotidianas.

Proteger seu Usuário raiz da conta da AWS

1. Faça login no AWS Management Console como o proprietário da conta ao escolher a opção Usuário raiz e inserir o endereço de e-mail da Conta da AWS. Na próxima página, digite sua senha.

   Para obter ajuda ao fazer login usando o usuário raiz, consulte Fazer login como usuário raiz no Guia do usuário do Início de Sessão da AWS.

2. Ative a autenticação multifator (MFA) para o usuário raiz.c

   Para obter instruções, consulte Habilitar um dispositivo MFA virtual para o usuário raiz de sua conta da Conta da AWS para seu (console) no Guia do usuário do IAM.

Criar um usuário administrativo

1. Habilitar o IAM Identity Center.

   Para obter instruções, consulte Enabling AWS IAM Identity Center no Manual do Usuário do AWS IAM Identity Center.

2. No Centro de Identidade do IAM, conceda acesso administrativo a um usuário administrativo.

   Para ver um tutorial sobre como usar o Diretório do Centro de Identidade do IAM como fonte de identidade, consulte Configure user access with the default Diretório do Centro de Identidade do IAM no Manual do Usuário do AWS IAM Identity Center.

Login como usuário administrativo

• Para fazer login com seu usuário do Centro de Identidade do IAM, use a URL de login que foi enviada ao seu endereço de e-mail quando você criou o usuário do Centro do Usuário do IAM.

  Para obter ajuda com o login utilizando um usuário do Centro de Identidade do IAM, consulte Fazer login no portal de acesso da AWS, no Guia do usuário do Início de Sessão da AWS.

Para conceder acesso, adicione as permissões aos seus usuários, grupos ou perfis:

• Usuários e grupos no AWS IAM Identity Center:

  Crie um conjunto de permissões. Siga as instruções em Create a permission set (Criação de um conjunto de permissões) no Guia do usuário do AWS IAM Identity Center.

• Usuários gerenciados no IAM com provedor de identidades:

  Crie um perfil para a federação de identidades. Siga as instruções em Criar um perfil para um provedor de identidades de terceiros (federação) no Guia do usuário do IAM.

• Usuários do IAM:

  • Crie um perfil que seu usuário possa assumir. Siga as instruções em Creating a role for an IAM user (Criação de um perfil para um usuário do IAM) no Guia do usuário do IAM.

  • (Não recomendado) Vincule uma política diretamente a um usuário ou adicione um usuário a um grupo de usuários. Siga as instruções em Adição de permissões a um usuário (console) no Guia do usuário do IAM.

Conceitos básicos

nota

Os comandos do Linux neste tutorial exigem o uso do shell Bash.

1. Configuração do hardware Espressif.

   • Para obter informações sobre como configurar o hardware da placa de desenvolvimento ESP32- DevKit C, consulte o Guia de introdução do ESP32- DevKit C V4.

   • Para obter informações sobre como configurar o hardware da placa de desenvolvimento ESP-WROVER-KIT, consulte o Guia de conceitos básicos do ESP-WROVER-KIT V4.1.

   Importante

   Ao chegar na seção Começar a usar dos guias do Espressif, pare e retorne para as instruções desta página.

2. Faça o download dos Amazon GitHubFreeRTOS em. (Para obter instruções, consulte o arquivo README.md.)

3. Configure o ambiente de desenvolvimento.

   Para se comunicar com sua placa, você deve instalar uma cadeia de ferramentas. A Espressif fornece o ESP-IDF para desenvolver software para suas placas. Como o ESP-IDF tem a própria versão do kernel do FreeRTOS integrada como um componente, o Amazon FreeRTOS inclui uma versão personalizada do ESP-IDF v4.2 que tem o kernel do FreeRTOS removido. Isso corrige problemas com arquivos duplicados durante a compilação. Para usar a versão personalizada do ESP-IDF v4.2 incluída no Amazon FreeRTOS, siga as instruções abaixo para o sistema operacional da sua máquina host.

   Windows

   1. Faça download do Instalador online universal do ESP-IDF para Windows.

   2. Execute o Instalador online universal.

   3. Ao chegar à etapa Fazer download ou usar ESP-IDF, selecione Usar um diretório ESP-IDF existente e defina Escolher diretório ESP-IDF existente como freertos/vendors/espressif/esp-idf.

   4. Conclusão da instalação

   macOS

   1. Siga as instruções nos Pré-requisitos de configuração padrão da cadeia de ferramentas (ESP-IDF v4.2) para macOS.

      Importante

      Quando você chegar nas instruções de "Obter ESP-IDF" em Próximas etapas, pare e retorne para as instruções desta página.

   2. Abra a janela de linha de comando.

   3. Navegue até o diretório de download do FreeRTOS e, em seguida, execute o script a seguir para baixar e instalar a cadeia de ferramentas do espressif em sua plataforma.

      vendors/espressif/esp-idf/install.sh

   4. Adicione as ferramentas da cadeia de ferramentas ESP-IDF ao caminho do seu terminal com o comando a seguir.

      source vendors/espressif/esp-idf/export.sh

   Linux

   1. Siga as instruções nos Pré-requisitos da configuração padrão da cadeia de ferramentas (ESP-IDF v4.2) para Linux.

      Importante

      Quando você chegar nas instruções de "Obter ESP-IDF" em Próximas etapas, pare e retorne para as instruções desta página.

   2. Abra a janela de linha de comando.

   3. Navegue até o diretório de download do FreeRTOS e execute o script a seguir para baixar e instalar a cadeia de ferramentas do Espressif em sua plataforma.

      vendors/espressif/esp-idf/install.sh

   4. Adicione as ferramentas da cadeia de ferramentas ESP-IDF ao caminho do seu terminal com o comando a seguir.

      source vendors/espressif/esp-idf/export.sh

4. Estabelecimento de uma conexão serial.

   1. Para estabelecer uma conexão serial entre sua máquina host e o ESP32- DevKit C, você deve instalar os drivers CP210x USB para UART Bridge VCP. Você pode fazer download desses drivers no Silicon Labs.

      Para estabelecer uma conexão serial entre sua máquina host e o ESP32-WROVER-KIT, é necessário instalar o driver de porta COM virtual FTDI. Você pode fazer download desse driver no FTDI.

   2. Siga as etapas para Estabelecer conexão serial com ESP32.

   3. Depois de estabelecer uma conexão serial, anote a porta serial da conexão de sua placa. Você precisa disso para exibir a demonstração.

Configuração dos aplicativos de demonstração do FreeRTOS

Para este tutorial, o arquivo de configuração do FreeRTOS está localizado em freertos/vendors/espressif/boards/board-name/aws_demos/config_files/FreeRTOSConfig.h. (Por exemplo, se AFR_BOARD espressif.esp32_devkitc for escolhido, o arquivo de configuração estará localizado em freertos/vendors/espressif/boards/esp32/aws_demos/config_files/FreeRTOSConfig.h.)

1. Se você estiver executando macOS ou Linux, abra um prompt de terminal. Se você estiver executando o Windows, abra o aplicativo "ESP-IDF 4.x CMD" (se você incluiu essa opção ao instalar a cadeia de ferramentas ESP-IDF) ou, caso contrário, o aplicativo "Prompt de comando".

2. Para verificar se você tem o Python3 instalado, execute

   python --version

   A versão instalada é exibida. Se você não tiver o Python 3.0.1 ou posterior instalado, poderá instalá-lo a partir do site do Python.

3. É necessária a Interface de linha de comandos (CLI) da AWS para executar os comandos AWS IoT. Se você estiver executando o Windows, use o comando easy_install awscli para instalar a CLI da AWS no aplicativo "Comando" ou "ESP-IDF 4.x CMD".

   Se você estiver executando o macOS ou o Linux, consulte Instalação da CLI AWS.

4. Executar

   aws configure

   e configure a CLI da AWS com o ID da chave de acesso da AWS, a chave de acesso secreta e o nome de região da AWS padrão. Para obter mais informações, consulte Configurar a CLI AWS.

5. Use o comando a seguir para instalar o SDK da AWS para Python (boto3):

   • No Windows, no aplicativo "Comando" ou "ESP-IDF 4.x CMD", execute

     pip install boto3 --user

     nota

     Consulte os detalhes na documentação do boto3.

   • No macOS ou Linux, execute

     pip install tornado nose --user

     e depois execute

     pip install boto3 --user

   O FreeRTOS inclui o script SetupAWS.py para facilitar a configuração da placa Espressif para conectar-se ao AWS IoT. Para configurar o script, abra freertos/tools/aws_config_quick_start/configure.json e defina os seguintes atributos:

   afr_source_dir

   O caminho completo para o diretório freertos no computador. Certifique-se de usar barras para especificar esse caminho.

   thing_name

   O nome que você deseja atribuir à coisa da AWS IoT que representa sua placa.

   wifi_ssid

   O SSID da rede Wi-Fi.

   wifi_password

   A senha da rede Wi-Fi.

   wifi_security

   O tipo de segurança da rede Wi-Fi.

   Os tipos de segurança válidos estão a seguir:

   • eWiFiSecurityOpen (Aberto, sem segurança)

   • eWiFiSecurityWEP (segurança WEP)

   • eWiFiSecurityWPA (segurança WPA)

   • eWiFiSecurityWPA2 (segurança WPA2)

6. Executar o script de configuração.

   1. Se você estiver executando macOS ou Linux, abra um prompt de terminal. Se você estiver executando o Windows, abra o aplicativo "ESP-IDF 4.x CMD" ou "Comando".

   2. Navegue até o diretório freertos/tools/aws_config_quick_start e execute

      python SetupAWS.py setup

      O script faz o seguinte:

      • Cria uma coisa, um certificado e uma política de IoT.

      • Anexa a política de IoT ao certificado e o certificado à coisa do AWS IoT.

      • Preenche o arquivo aws_clientcredential.h com o endpoint, o SSID Wi-Fi e as credenciais da AWS IoT.

      • Formata o certificado e a chave privada e os grava no arquivo de cabeçalho aws_clientcredential_keys.h.

      nota

      O certificado é codificado apenas para fins de demonstração. Por este motivo, os aplicativos devem armazenar esses arquivos em um local seguro.

      Para obter mais informações sobre SetupAWS.py, consulte README.md no diretório freertos/tools/aws_config_quick_start.

Monitoramento de mensagens MQTT na nuvem

Antes de executar o projeto de demonstração do FreeRTOS, você pode configurar o cliente MQTT no console do AWS IoT para monitorar as mensagens enviadas pelo dispositivo para a nuvem da AWS.

Para assinar o tópico MQTT com o cliente MQTT do AWS IoT

1. Navegue até o console do AWS IoT.

2. No painel de navegação, escolha Teste e, em seguida, escolha Cliente de teste MQTT.

3. Em Tópico de inscrição, insira your-thing-name/example/topic e selecione Inscreva-se no tópico.

Quando o projeto de demonstração for executado com êxito em seu dispositivo, você verá "Olá, mundo!". enviado várias vezes para o tópico em que você assinou.

Compilação, atualização e execução do projeto de demonstração do FreeRTOS usando o script idf.py

Você pode usar o utilitário IDF (idf.py) do Espressif para criar o projeto e instalar os binários em seu dispositivo.

nota

Algumas configurações podem exigir que você use a opção de porta "-p port-name" comidf.py para especificar a porta correta, como no exemplo a seguir.

idf.py -p /dev/cu.usbserial-00101301B flash

Compilação e instalação do FreeRTOS no Windows, Linux e macOS (ESP-IDF v4.2)

1. Navegue até a raiz do diretório de downloads do FreeRTOS.

2. Na janela da linha de comando, insira o comando a seguir para adicionar as ferramentas de ESP-IDF ao PATH do seu terminal.

   Windows (aplicativo "Comando")

   vendors\espressif\esp-idf\export.bat

   Windows (aplicativo "ESP-IDF 4.x CMD")

   (Isso já foi feito quando você abriu o aplicativo.)

   Linux / macOS

   source vendors/espressif/esp-idf/export.sh

3. Configure o cmake no diretório build e compile a imagem do firmware com o comando a seguir.

   idf.py -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 build

   O resultado deverá ser parecido com o que segue.

      Running cmake in directory /path/to/hello_world/build
      Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
      Warn about uninitialized values.
      -- Found Git: /usr/bin/git (found version "2.17.0")
      -- Building empty aws_iot component due to configuration
      -- Component names: ...
      -- Component paths: ...
   
      ... (more lines of build system output)
   
      [527/527] Generating hello-world.bin
      esptool.py v2.3.1
   
      Project build complete. To flash, run this command:
      ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
      or run 'idf.py -p PORT flash' 

   Se não houver erros, a compilação gerará os arquivos .bin binários do firmware.

4. Apague a memória instalada da placa de desenvolvimento com o comando a seguir.

   idf.py erase_flash

5. Use o script idf.py para instalar o binário do aplicativo na placa.

   idf.py flash

6. Monitore a saída da porta serial da placa com o comando a seguir.

   idf.py monitor

   nota

   Você pode combinar esses comandos, como no exemplo a seguir.

   idf.py erase_flash flash monitor

   Para determinadas configurações da máquina host, você deve especificar a porta ao instalar a placa, como no exemplo a seguir.

   idf.py erase_flash flash monitor -p /dev/ttyUSB1

Compilação e instalação do FreeRTOS com o CMake

Além de usar o script idf.py fornecido pelo SDK do IDF para criar e executar seu código, você também pode compilar o projeto com o CMake. Atualmente, ele é compatível com o Makefile da Unix ou sistema de compilação Ninja.

Como compilar e instalar o projeto

1. Em uma janela da linha de comando, navegue até o diretório raiz de downloads do FreeRTOS.

2. Execute o script a seguir para adicionar as ferramentas ESP-IDF ao PATH do shell.

   Windows

   vendors\espressif\esp-idf\export.bat

   Linux / macOS

   source vendors/espressif/esp-idf/export.sh

3. Insira o comando a seguir para gerar os arquivos de compilação.

   Com Makefiles da Unix

   cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0

   Com Ninja

   cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0 -GNinja

4. Crie o projeto.

   Com Makefiles da Unix

   make -C ./YOUR_BUILD_DIRECTORY -j8 

   Com Ninja

   ninja -C ./YOUR_BUILD_DIRECTORY -j8

5. Apague a memória instalada e depois instale a placa.

   Com Makefiles da Unix

   make -C ./YOUR_BUILD_DIRECTORY erase_flash

   make -C ./YOUR_BUILD_DIRECTORY flash

   Com Ninja

   ninja -C ./YOUR_BUILD_DIRECTORY erase_flash

   ninja -C ./YOUR_BUILD_DIRECTORY flash

Execução das demonstrações de Bluetooth Low-Energy

O FreeRTOS oferece suporte à conectividade Biblioteca de Bluetooth Low Energy.

Para executar o projeto de demonstração do FreeRTOS no Bluetooth Low Energy, você precisa executar o aplicativo de demonstração do SDK móvel de Bluetooth Low Energy do FreeRTOS em um dispositivo móvel Android ou iOS.

Como configurar o aplicativo de demonstração do SDK móvel de Bluetooth Low Energy do FreeRTOS

1. Siga as instruções em SDKs móveis para dispositivos Bluetooth do FreeRTOS para fazer download e instalar o SDK para sua plataforma móvel em seu computador host.

2. Siga as instruções em Aplicativo de demonstração do SDK móvel de Bluetooth Low Energy do FreeRTOS para configurar o aplicativo móvel de demonstração no dispositivo móvel.

Para obter instruções sobre como executar a demonstração do MQTT por Bluetooth Low Energy na sua placa, consulte MQTT por Bluetooth Low Energy.

Para obter instruções sobre como executar a demonstração do provisionamento de Wi-Fi na sua placa, consulte Provisionamento de Wi-Fi.

Uso do FreeRTOS em seu próprio projeto CMake para ESP32

Se desejar usar o FreeRTOS em seu próprio projeto CMake, você pode configurá-lo como um subdiretório e compilá-lo junto com seu aplicativo. Primeiro, obtenha uma cópia dos FreeRTOS em. GitHub Você também pode configurá-lo como um submódulo Git com o comando a seguir para que seja mais fácil atualizar no futuro.

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

Se uma versão mais recente for lançada, você poderá atualizar sua cópia local com esses comandos.

# Pull the latest changes from the remote tracking branch.
git submodule update --remote -- freertos 

# Commit the submodule change because it is pointing to a different revision now.
git add freertos 

git commit -m "Update FreeRTOS to a new release"

Se o seu projeto tem a seguinte estrutura de diretórios:

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

A seguir há um exemplo do arquivo CMakeLists.txt de nível superior que pode ser usado para compilar seu aplicativo junto com o FreeRTOS.

cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

# Tell IDF build to link against this target.
set(IDF_EXECUTABLE_SRCS "<complete_path>/src/main.c")
set(IDF_PROJECT_EXECUTABLE my_app)

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

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

Para criar o projeto, execute os seguintes comandos CMake. Certifique-se de que o compilador ESP32 está na variável de ambiente PATH.

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

cmake --build build-directory 

Para instalar a aplicação na sua placa, execute o comando a seguir.

cmake --build build-directory --target flash 

Uso de componentes do FreeRTOS

Depois de executar o CMake, você pode encontrar todos os componentes disponíveis na saída de resumo. Isso deve ser parecido com a seguinte exemplo.

====================Configuration for FreeRTOS====================
  Version:                 202107.00
  Git version:             202107.00-g79ad6defb

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

FreeRTOS modules:
  Modules to build:        backoff_algorithm, common, common_io, core_http,
                           core_http_demo_dependencies, core_json, core_mqtt,
                           core_mqtt_agent, core_mqtt_agent_demo_dependencies,
                           core_mqtt_demo_dependencies, crypto, defender, dev_mode_key_
                           provisioning, device_defender, device_defender_demo_
                           dependencies, device_shadow, device_shadow_demo_dependencies,
                           freertos_cli_plus_uart, freertos_plus_cli, greengrass,
                           http_demo_helpers, https, jobs, jobs_demo_dependencies,
                           kernel, logging, mqtt, mqtt_agent_interface, mqtt_demo_
                           helpers, mqtt_subscription_manager, ota, ota_demo_
                           dependencies, ota_demo_version, pkcs11, pkcs11_helpers,
                           pkcs11_implementation, pkcs11_utils, platform, secure_sockets,
                           serializer, shadow, tls, transport_interface_secure_sockets,
                           wifi
  Enabled by user:         common_io, core_http_demo_dependencies, core_json,
                           core_mqtt_agent_demo_dependencies, core_mqtt_demo_
                           dependencies, defender, device_defender, device_defender_demo_
                           dependencies, device_shadow, device_shadow_demo_dependencies,
                           freertos_cli_plus_uart, freertos_plus_cli, greengrass, https,
                           jobs, jobs_demo_dependencies, logging, ota_demo_dependencies,
                           pkcs11, pkcs11_helpers, pkcs11_implementation, pkcs11_utils,
                           platform, secure_sockets, shadow, wifi
  Enabled by dependency:   backoff_algorithm, common, core_http, core_mqtt,
                           core_mqtt_agent, crypto, demo_base, dev_mode_key_provisioning,
                           freertos, http_demo_helpers, kernel, mqtt, mqtt_agent_
                           interface, mqtt_demo_helpers, mqtt_subscription_manager, ota,
                           ota_demo_version, pkcs11_mbedtls, serializer, tls,
                           transport_interface_secure_sockets, utils
  3rdparty dependencies:   jsmn, mbedtls, pkcs11, tinycbor
  Available demos:         demo_cli_uart, demo_core_http, demo_core_mqtt, demo_core_mqtt_
                           agent, demo_device_defender, demo_device_shadow,
                           demo_greengrass_connectivity, demo_jobs, demo_ota_core_http,
                           demo_ota_core_mqtt, demo_tcp
  Available tests:
========================================================================= 

Você pode fazer referência a qualquer componente da lista Modules to build. Para vinculá-los ao seu aplicativo, coloque o namespace AFR:: na frente do nome, por exemplo, AFR::core_mqtt, AFR::ota e assim por diante.

Adição de componentes personalizados usando o ESP-IDF

Você pode adicionar mais componentes ao usar o ESP-IDF. Por exemplo, supondo que você deseja adicionar um componente chamado example_component e seu projeto tenha a seguinte aparência:

- freertos
- components
  - example_component
    - include
      - example_component.h
    - src
      - example_component.c
    - CMakeLists.txt
- src
  - main.c
- CMakeLists.txt 

Veja a seguir um exemplo do arquivo CMakeLists.txt do seu componente.

add_library(example_component src/example_component.c)
target_include_directories(example_component PUBLIC include) 

Em seguida, no arquivo CMakeLists.txt de nível superior, adicione o componente inserindo a linha a seguir logo depois de add_subdirectory(freertos).

add_subdirectory(component/example_component) 

Em seguida, modifique target_link_libraries para incluir seu componente.

target_link_libraries(my_app PRIVATE AFR::core_mqtt PRIVATE example_component) 

Esse componente agora é vinculado automaticamente ao código do aplicativo por padrão. Você deve poder incluir seus arquivos de cabeçalho e chamar as funções que eles definem.

Substituição de configurações do FreeRTOS

Atualmente, não há uma abordagem bem definida para redefinir as configurações fora da árvore de origem do FreeRTOS. Por padrão, o CMake procurará os diretórios freertos/vendors/espressif/boards/esp32/aws_demos/config_files/ e freertos/demos/include/. No entanto, você pode usar uma solução alternativa para dizer ao compilador para procurar outros diretórios primeiro. Por exemplo, você pode adicionar outra pasta para configurações do FreeRTOS.

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

Os arquivos em freertos-configs são copiados dos diretórios freertos/vendors/espressif/boards/esp32/aws_demos/config_files/ e freertos/demos/include/. No seu arquivo CMakeLists.txt de nível superior, adicione esta linha antes de add_subdirectory(freertos) para que o compilador pesquise este diretório primeiro.

include_directories(BEFORE freertos-configs)

Fornecimento de seu próprio sdkconfig para ESP-IDF

No caso de você querer fornecer o seu próprio sdkconfig.default, você pode definir a variável CMake IDF_SDKCONFIG_DEFAULTS na linha de comando:

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

Se não for especificado um local para seu próprio arquivo sdkconfig.default, o FreeRTOS usará o arquivo padrão localizado em freertos/vendors/espressif/boards/esp32/aws_demos/sdkconfig.defaults.

Para obter mais informações, consulte Configuração do projeto na Referência da API do Espressif e, se você encontrar problemas após compilar com êxito, consulte a seção sobre Opções obsoletas e suas substituições nessa página.

Resumo

Se você tem um projeto com um componente chamado example_component e desejar substituir algumas configurações, aqui está um exemplo completo do arquivo CMakeLists.txt de nível superior.

cmake_minimum_required(VERSION 3.13)

project(freertos_examples)

set(IDF_PROJECT_EXECUTABLE my_app)
set(IDF_EXECUTABLE_SRCS "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 a variable used by ESP-IDF
# to collect extra components.
get_filename_component(
    EXTRA_COMPONENT_DIRS
    "components/example_component" ABSOLUTE
)
list(APPEND IDF_EXTRA_COMPONENT_DIRS ${EXTRA_COMPONENT_DIRS})

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

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

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

Solução de problemas

• Se você estiver executando o macOS e o sistema operacional não reconhece o ESP-WROVER-KIT, verifique se os drivers D2XX não estão instalados. Para desinstalá-los, siga as instruções em FTDI Drivers Installation Guide for macOS X.

• O utilitário de monitor fornecido pelo ESP-IDF (e invocado usando o monitor make) ajuda a decodificar endereços. Por esse motivo, ele pode ajudar você a obter alguns backtraces significativos caso o aplicativo falhe. Para obter mais informações, consulte Decodificação de endereços automática no site da Espressif.

• Também é possível habilitar GDBstub para comunicação com gdb sem a necessidade de nenhum hardware JTAG especial. Para obter mais informações, consulte Inicialização do GDB para GDBStub no site da Espressif.

• Para obter informações sobre a configuração de um ambiente com base em OpenOCD se a depuração com base em hardware JTAG for necessária, consulte Depuração JTAG no site da Espressif.

• Se não for possível instalar pyserial usando pip no macOS, faça download no site do pyserial.

• Se a placa for reiniciada continuamente, tente apagar a instalação digitando o seguinte comando no terminal.

  make erase_flash

• Se você vir erros ao executar idf_monitor.py, use Python 2.7.

• As bibliotecas necessárias de ESP-IDF estão incluídas no FreeRTOS, portanto, não é necessário baixá-las externamente. Se a variável de ambiente IDF_PATH estiver definida, recomendamos que faça a limpeza dela antes de compilar o FreeRTOS.

• No Windows, pode levar de 3 a 4 minutos para o projeto ser criado. Para reduzir o tempo de compilação, você pode usar o comutador -j4 no comando make.

  make flash monitor -j4

• Se o dispositivo tiver problemas para se conectar ao AWS IoT, abra o arquivo aws_clientcredential.h e verifique se as variáveis de configuração estão corretamente definidas no arquivo. clientcredentialMQTT_BROKER_ENDPOINT[] deve ser semelhante a 1234567890123-ats.iot.us-east-1.amazonaws.com.

• Se você estiver seguindo as etapas em Uso do FreeRTOS em seu próprio projeto CMake para ESP32 e vir erros de referência indefinidos no vinculador, em geral, a causa é a falta de bibliotecas dependentes ou demonstrações. Para adicioná-los, atualize o arquivo CMakeLists.txt (no diretório raiz) usando a função padrão CMake target_link_libraries.

• O ESP-IDF v4.2 é compatível com o uso da cadeia de ferramentas xtensa\ -esp32\ -elf\ -gcc 8\ .2\ .0\. Se você estiver usando uma versão anterior da cadeia de ferramentas Xtensa, baixe a versão necessária.

• Se você ver um log de erros como o seguinte sobre dependências de python que não estão sendo atendidas no ESP-IDF v4.2:

  The following Python requirements are not satisfied:
    click>=5.0
    pyserial>=3.0
    future>=0.15.2
    pyparsing>=2.0.3,<2.4.0
    pyelftools>=0.22
    gdbgui==0.13.2.0
    pygdbmi<=0.9.0.2
    reedsolo>=1.5.3,<=1.5.4
    bitstring>=3.1.6
    ecdsa>=0.16.0
    Please follow the instructions found in the "Set up the tools" section of ESP-IDF Getting Started Guide 

  Instale as dependências do Python na sua plataforma usando o seguinte comando do Python:

  root/vendors/espressif/esp-idf/requirements.txt

Para obter mais informações sobre solução de problemas, consulte Solução de problemas de conceitos básicos.

Depuração

Código de depuração no Espressif ESP32- DevKit C e no ESP-WROVER-KIT (ESP-IDF v4.2)

Esta seção mostra como depurar o hardware da Espressif usando o ESP-IDF v4.2. Você precisa de um cabo JTAG para USB. Usamos um cabo USB para MPSSE (por exemplo, o FTDI C232HM-DDHSL-0).

Configuração do ESP- DevKit C JTAG

Para o cabo FTDI C232HM-DDHSL-0, estas são as conexões com o ESP32 DevkitC.

| C232HM-DDHSL-0 Wire Color | ESP32 GPIO Pin | JTAG Signal Name |
| ------------------------- | -------------- | ---------------- |
|  Brown (pin 5)            |  IO14          |  TMS             |
|  Yellow (pin 3)           |  IO12          |  TDI             |
|  Black (pin 10)           |  GND           |  GND             |
|  Orange (pin 2)           |  IO13          |  TCK             |
|  Green (pin 4)            |  IO15          |  TDO             | 

Configuração de ESP-WROVER-KIT JTAG

Para o cabo FTDI C232HM-DDHSL-0, estas são as conexões com o ESP32-WROVER-KIT.

| C232HM-DDHSL-0 Wire Color | ESP32 GPIO Pin | JTAG Signal Name |
| ------------------------- | -------------- | ---------------- |
|  Brown (pin 5)            |  IO14          |  TMS             |
|  Yellow (pin 3)           |  IO12          |  TDI             |
|  Orange (pin 2)           |  IO13          |  TCK             |
|  Green (pin 4)            |  IO15          |  TDO             |

Essas tabelas foram desenvolvidas na planilha FTDI C232HM-DDHSL-0. Para obter mais informações, consulte "Detalhes mecânicos e conexão de cabos C232HM MPSSE" na planilha.

Para habilitar a JTAG no ESP-WROVER-KIT, coloque jumpers nos pinos TMS, TDO, TDI, TCK e S_TDI, conforme mostrado aqui.

Depuração no Windows (ESP-IDF v4.2)

Para configurar para depuração no Windows

1. Conecte o lado USB do FTDI C232HM-DDHSL-0 ao computador e o outro lado como descrito em Código de depuração no Espressif ESP32- DevKit C e no ESP-WROVER-KIT (ESP-IDF v4.2). O dispositivo FTDI C232HM-DDHSL-0 deve aparecer no Device Manager (Gerenciador de dispositivos) em Universal Serial Bus Controllers (Controladores USB).

2. Na lista de dispositivos USB, clique com o botão direito do mouse no dispositivo C232HM-DDHSL-0 dispositivo e selecione Propriedades.

   nota

   O dispositivo pode estar listado como USB Serial Port (Porta serial USB).

   Para ver as propriedades do dispositivo, na janela de propriedades, escolha a guia Detalhes. Se o dispositivo não estiver listado, instale o driver do Windows para FTDI C232HM-DDHSL-0.

3. Na guia Details (Detalhes), selecione Property (Propriedade) e selecione Hardware IDs (IDs de hardware). Você deve ver algo parecido com isto no campo Valor.

   FTDIBUS\COMPORT&VID_0403&PID_6014

   Neste exemplo, o ID do fornecedor é 0403 e o ID do produto é 6014.

   Verifique se esses IDs correspondem os IDs em projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg. Os IDs são especificados em uma linha que começa com ftdi_vid_pid seguidos por um ID de fornecedor e um ID do produto.

   ftdi_vid_pid 0x0403 0x6014

4. Faça download do OpenOCD para Windows.

5. Descompacte o arquivo C:\ e adicione C:\openocd-esp32\bin ao caminho do sistema.

6. O OpenOCD requer libusb, que não é instalado por padrão no Windows. Para instalar o libusb:

   1. Faça download de zadig.exe.

   2. Executar zadig.exe. No menu Options (Opções), escolha List All Devices (Listar todos os dispositivos).

   3. No menu suspenso, escolha C232HM-DDHSL-0.

   4. No campo de driver de destino, à direita da seta verde, selecione WinUSB.

   5. Na caixa vertical no campo de driver de destino, escolha a seta e selecione Instalar driver. Escolha Replace Driver (Substituir driver).

7. Abra outro terminal, navegue até a raiz do diretório de download do FreeRTOS e execute o seguinte comando.

   idf.py openocd

   Deixe o prompt de comando aberto.

8. Abra outro terminal, navegue até a raiz do diretório de download do FreeRTOS e execute

   idf.py flash monitor

9. Abra outro prompt de comando, navegue até a raiz do diretório de download do FreeRTOS e espere até que a demonstração comece a ser executada na placa. Quando isso ocorrer, execute

   idf.py gdb

   O programa deve parar na função main.

   nota

   O ESP32 oferece suporte a, no máximo, dois pontos de interrupção.

Depuração no macOS (ESP-IDF v4.2)

1. Faça download do driver FTDI para macOS.

2. Faça download do OpenOCD.

3. Extraia o arquivo .tar baixado e defina o caminho em .bash_profile como OCD_INSTALL_DIR/openocd-esp32/bin.

4. Use o comando a seguir para instalar o libusb no macOS.

   brew install libusb

5. Use o comando a seguir para fazer download do driver da porta serial.

   sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver

6. Use o comando a seguir para fazer download do driver da porta serial.

   sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver

7. Se você estiver executando uma versão posterior a 10.9 do macOS, use o comando a seguir para descarregar o driver FTDI da Apple.

   sudo kextunload -b com.apple.driver.AppleUSBFTDI

8. Use o seguinte comando para obter o ID do produto e o ID do fornecedor do cabo FTDI. Ele lista os dispositivos USB conectados.

   system_profiler SPUSBDataType

   A saída de system_profiler deve ser a seguinte.

      DEVICE:
   
      Product ID: product-ID
      Vendor ID: vendor-ID (Future Technology Devices International Limited) 

9. Abra o arquivo projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg. Os IDs do fornecedor e do produto do seu dispositivo são especificados em uma linha que começa com ftdi_vid_pid. Altere os IDs de acordo com os IDs da saída system_profiler na etapa anterior.

10. Abra uma janela do terminal, navegue até a raiz do diretório de download do FreeRTOS e use o seguinte comando para execurar o OpenOCD.

    idf.py openocd

    Deixe essa janela do terminal aberta.

11. Abra um novo terminal e use o seguinte comando para carregar o driver de porta serial FTDI.

    sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver

12. Navegue até a raiz do diretório de downloads do FreeRTOS e execute

    idf.py flash monitor

13. Abra outro terminal, navegue até a raiz do diretório de download do FreeRTOS e execute

    idf.py gdb

    O programa deve parar em main.

Depuração no Linux (ESP-IDF v4.2)

1. Faça download do OpenOCD. Extraia o tarball e siga as instruções de instalação no arquivo readme.

2. Use o seguinte comando para instalar libusb em Linux.

   sudo apt-get install libusb-1.0

3. Abra um terminal e digite ls -l /dev/ttyUSB* para listar todos os dispositivos USB conectados ao computador. Isso ajuda você a verificar se as portas USB da placa são reconhecidas pelo sistema operacional. O resultado deverá ser parecido com o que segue.

      $ls -l /dev/ttyUSB*
      crw-rw----    1    root    dialout    188,    0    Jul    10    19:04    /dev/ttyUSB0
      crw-rw----    1    root    dialout    188,    1    Jul    10    19:04    /dev/ttyUSB1 

4. Saia e, em seguida, faça login e desligue e ligue a alimentação da placa para que as alterações entrem em vigor. Em um prompt de terminal, liste os dispositivos USB. Certifique-se de que o proprietário do grupo tenha sido alterado de dialout para plugdev.

      $ls -l /dev/ttyUSB*
      crw-rw----    1    root    plugdev    188,    0    Jul    10    19:04    /dev/ttyUSB0
      crw-rw----    1    root    plugdev    188,    1    Jul    10    19:04    /dev/ttyUSB1 

   A interface /dev/ttyUSBn com o menor número é usada para comunicação JTAG. A outra interface é roteada para a porta serial do ESP32 (UART) e é usada para fazer upload de código na memória flash do ESP32.

5. Na janela do terminal, navegue até a raiz do diretório de download do FreeRTOS e use o seguinte comando para execurar o OpenOCD.

   idf.py openocd 

6. Abra outro terminal, navegue até a raiz do diretório de download do FreeRTOS e execute o seguinte comando.

   idf.py flash monitor 

7. Abra outro terminal, navegue até a raiz do diretório de download do FreeRTOS e execute o seguinte comando.

   idf.py gdb

   O programa deve parar em main().