Introdução a ESP-IDF com VS Code

Introdução

Nesse post vamos aprender sobre a ESP-IDF, a framework nativa para desenvolvimento no ESP32, explicando seu uso, as diferenças entre a IDF e a Arduino, instalação no Visual Studio Code e a criação de projetos, antes de iniciar a leitura é importante ressaltar que a IDF é uma framework pensada no uso profissional, sendo recomendado ter conhecimento nos seguintes tópicos:

• Linguagens C e C++.
• FreeRTOS (temos vários artigos ensinando como utilizar o FreeRTOS, clique aqui e leia agora mesmo!)
• Conhecimentos básicos sobre ESP32 (Introdução ao ESP32)

Materiais Necessários

Nesse post vamos usar a placa DOIT ESP32 DevKit V1 e componentes discretos como LEDs e resistores, além de um display I2C. Vale lembrar que é possível usar qualquer placa baseada nos SoCs da família ESP32, ou seja, as linhas ESP32, ESP32-S, ESP32-C, ESP32-H e ESP32-P.

Apenas por curiosidade, as placas baseadas no ESP8266, como o ESP-01 e ESP-12 (NodeMCU) usam uma SDK diferente da ESP-IDF, a ESP8266 Non-OS SDK

• 1x Módulo WiFi ESP32 Bluetooth 30 pinos
• 1x Led Difuso 5mm Vermelho
• 1x Led Difuso 5mm Amarelo
• 1x Protoboard 830 Pontos
• 2x Resistor 1K 1/4W (10 Unidades)
• 1x Push Button (Chave Táctil) 6x6x5mm
• 1x Display LCD 16x2 com Backlight Azul
• 1x Módulo Serial I2C para Display LCD

O que é a ESP-IDF?

A Espressif IoT Development Framework ou simplesmente ESP-IDF, é a SDK nativa para a família ESP32, criada pela Espressif. Ela é um conjunto completo de ferramentas para todo o ciclo de desenvolvimento de uma Aplicação IoT, desde o protótipo até o produto final, contendo:

• Gerenciamento e configuração de projeto
• ferramentas de monitoramento e depuração
• gerenciamento de dependências
• API simplificada para acesso a todas as funcionalidades do hardware
• Sistema Operacional de tempo real (FreeRTOS)

ESP-IDF x Arduino IDE

Instalando a ESP-IDF no Visual Studio code

Agora que aprendemos o que é a ESP-IDF, vamos para a instalação.

Instalando o Visual Studio Code (VS Code)

Instalando extensões no VS Code

• C/C++ Extension Pack
• CMake
• ESP-IDF

Instalando a ESP-IDF

Pré-requisitos

Criando um projeto

Primeiros passos com a IDF

Com o projeto criado, vamos nos deparar com vários arquivos, no momento vamos alterar apenas o arquivo principal, localizado no diretório main/main.c.

Antes de escrevemos nosso primeiro código, vamos fazer uma pequena lista dos comandos básicos:

1. Alterar a versão da IDF
2. Alterar a porta de upload
3. Alterar o target do projeto (target = placa utilizada)
4. Abrir outro projeto
5. Configurar o funcionamento da IDF
6. Build, upload e monitor serial

Logs e Tratamentos de erros

Como já comentamos, a ESP-IDF tem como foco o uso profissional, e por isso uma das características mais importantes dela é o seu sistema de geração de logs e tratamento de erros, uma característica crucial na etapa de prototipação. Não precisamos dominar esse assunto por agora, mas é bom entender a base desse conceito, pois toda IDF faz uso desse sistema.

O que são Logs?

#include <stdio.h>

void app_main(void)
{
 printf("hello world\n\r");
}

Gerando Logs

1. ESP_LOGE para erros.
2. ESP_LOGW para avisos.
3. ESP_LOGI para informações gerais.
4. ESP_LOGD para informações de Debug.
5. ESP_LOGV para detalhes adicionais.

1. Clique na opção menuconfig.
2. Na barra de pesquisa, procure por "Log output".
3. Em "Default log verbosity" podemos alterar quais logs aparecem ou até mesmo desligá-los por completo.
4. Clique em "Save".

Tratamento de Erros

Projeto: configurando log

Esse projeto é apenas um exercício de fixação dos tópicos recém-abordados. Nesse código vamos criar duas task que exibem mensagens de logs a cada 5 segundos e configurar a exibição deles.

//libC includes
#include <stdio.h>

//FreeRTOS includes
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>

//ESP-IDF includes
#include <esp_log.h>

//task para teste
void task1(void*);
void task2(void*);

void app_main(void){
    static const  char *TAG = "app_main"; //tag da main

    
    if(xTaskCreatePinnedToCore(task1,"task1",2048,NULL, 1,NULL, 0) != pdPASS){
        ESP_LOGE(TAG, "ERRO A iniciar a task1");
    }else{
        ESP_LOGI(TAG, "task1 criada com sucesso");
    }

    if(xTaskCreatePinnedToCore(task2,"task2",2048,NULL, 1,NULL, 0) != pdPASS){
        ESP_LOGE(TAG, "ERRO A iniciar a task2");
    }else{
        ESP_LOGI(TAG, "task2 criada com sucesso");
    }
    while(true){ 
        vTaskDelay(pdMS_TO_TICKS(10000)); //10Seg de delay
        printf("hello world\n\r");
    }
}

void task1(void *args){
    static const char *TAG = "Task1"; //tag da task1

    while(true){ 
        vTaskDelay(pdMS_TO_TICKS(5000)); //5Seg de delay
        ESP_LOGE(TAG,"Logs de ERRO tem a cor vermelha!");
        ESP_LOGW(TAG,"Logs de AVISO tem a cor amarela!");
        ESP_LOGI(TAG,"Logs de INFO tem a cor verde!");
    }
}

void task2(void *args){
    static const char *TAG = "Task2";//tag da task2
    while(true){ 
        vTaskDelay(pdMS_TO_TICKS(5000)); //5Seg de delay
        ESP_LOGD(TAG,"Logs de DEBUG tem a cor Branca e alta verbosidade");
        ESP_LOGV(TAG,"Logs VERBOSOS tem a cor Branca e a maior verbosidade, são usadas para mensagens grandes e detalhadas sobre o funcionamento do aplicação \
        assim como essa mensagem, por padrão Logs verbosos e debug estão desabilitados");
    }
}

Controlando periféricos

Agora que já temos uma noção básica de como a ESP-IDF funciona, vamos para próxima etapa: controlar os periféricos da placa!

Drivers

GPIO Driver

Configurando GPIOs

• gpio_num_t é o número da GPIO que queremos configurar. Recebe um valor no formato GPIO_NUM_x, onde "x" é o número da GPIO (Ex: num. GPIO10 = GPIO_NUM_10).
• gpio_mode_t é a direção que queremos configurar a GPIO. Esta pode receber 6 valores:
  • GPIO_MODE_DISABLE (GPIO desligada);
  • GPIO_MODE_INPUT;
  • GPIO_MODE_OUTPUT;
  • GPIO_MODE_OUTPUT_OD (open-drain);
  • GPIO_MODE_INPUT_OUTPUT_OD (INPUT e OUTPUT em open-drain);
  • GPIO_MODE_INPUT_OUTPUT (INPUT e OUTPUT).

• GPIO_PULLUP_ONLY.
• GPIO_PULLDOWN_ONLY.
• GPIO_PULLUP_PULLDOWN.
• GPIO_FLOATING (sem resistor de pull)

Configurando múltiplos GPIOs

• gpio_set_level(gpio_num_t gpio_num, uint32_t level), que é semelhante ao "digitalWrite()" e recebe o número da GPIO juntamente com o nível lógico da porta (1 = HIGH e 0 = LOW).
• int gpio_get_level(gpio_num_t gpio_num), semelhante ao "digitalRead()" e recebe o número da GPIO, retornando o nível lógico da porta (1 = HIGH e 0 = LOW).

Projeto: Blink

Nesse projeto, vamos configurar as GPIOs das duas formas que aprendemos para implementar um botão que seleciona qual LED irá piscar.

Esquema:

Código:

// C includes
#include <stdio.h>

//FreeRTOS includes
#include <freertos/FreeRTOS.h>

//esp-idf includes
#include <esp_log.h>
#include <esp_err.h>
#include <driver/gpio.h>

//defines
#define BTN GPIO_NUM_21
#define LED_V GPIO_NUM_22
#define LED_A GPIO_NUM_23

//função que configura os GPIOs
void GPIO_init();




void app_main(void){
    const static char TAG[] = "main task"; //tag main
    GPIO_init(); //inicia as GPIOS
    gpio_num_t leds[] = {LED_A, LED_V};
    int led_atual = 0;
    int input = 0;
    int input_anterior = 1;

    while(true){
        input = gpio_get_level(BTN);
        if(input == 0 && input != input_anterior){
            led_atual = (led_atual + 1)%2;// muda o led atual
            ESP_LOGI(TAG, "botão pressionado!");
        }
        input_anterior = input;

        //pisca led atual
        gpio_set_level(leds[led_atual], 1);
        vTaskDelay(pdMS_TO_TICKS(100));
        gpio_set_level(leds[led_atual], 0);
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

void GPIO_init(){
    const static char TAG[] = "GPIO_init";

    //configura GPIOS com a struct gpio_config
    gpio_config_t leds = {
        .pin_bit_mask = (1<<LED_A) | (1<<LED_V), //BITMASK das portas 23 e 22
        .mode = GPIO_MODE_DEF_OUTPUT, //modo output only
        .pull_up_en = GPIO_PULLUP_DISABLE, //sem pullup
        .pull_down_en = GPIO_PULLDOWN_DISABLE,// sem pulldown
        .intr_type = GPIO_INTR_DISABLE, //interrupções desligadas 
    };

    ESP_ERROR_CHECK(gpio_config(&leds)); //inicia a configuração e verifica erros

    //configura GPIO com funções 
    gpio_set_direction(BTN, GPIO_MODE_DEF_INPUT); // configura a porta 21 como input
    gpio_set_pull_mode(BTN, GPIO_PULLUP_ONLY); //configura pull_up na porta 21

    ESP_LOGI(TAG, "GPIOs configuradas!!!");
}

Resultado:

Desafio:

UART Driver

Agora vamos aprender a configurar a UART na ESP-IDF. Assim como as GPIOS, a UART também tem seu driver, sendo incluída pelo header: <driver/uart.h>.O processo para usar a UART na ESP-IDF é dividido em 3 etapas:

• Configuração dos parâmetros de comunicação;
• Configuração dos pinos;
• Inicialização do driver.

Configurando parâmetros de comunicação

Inicializando o driver

1. Barramento UART a ser inicializado;
2. Tamanho do buffer do TX;
3. Tamanho do buffer do RX;
4. Tamanho da fila de eventos;
5. Handler de uma Queue do FreeRTOS;
6. Flags de interrupção.

Projeto: UART ECHO

Nesse projeto vamos fazer um simples ECHO via UART (echo significa que vamos apenas repetir a informação recebida), passando por todas as etapas de configuração da UART, leitura e escrita de informação.Nesse código vamos usar a UART0, então é recomendado desligar todos os Logs, como já vimos início desse post.

Código:

//C includes
#include <stdio.h>


//freeRTOS includes
#include <freertos/FreeRTOS.h>
#include <freertos/queue.h>

//esp-idf includes
#include <esp_log.h>
#include <esp_err.h>
#include <driver/uart.h>

//UART defines 
#define UART UART_NUM_0
#define BAUDRATE 115200
#define UART_BUF_LEN 2048
#define UART_EVENT_BUF_LEN 10 

//UART tipes
QueueHandle_t uart_event_queue;


//função que inicia o driver de UART
void UART_init();

void app_main(void){
    size_t RX_len = 0; //contador de Bytes no RX buffer
    char Recive_buf[UART_BUF_LEN] = {0};//inicializa o array com 0

    //inicializa a UART
    UART_init();
    while(true){
        //verifica se há informações para ler
        uart_get_buffered_data_len(UART,&RX_len);
        if(RX_len != 0){
            uart_read_bytes(UART,Recive_buf,RX_len, pdMS_TO_TICKS(1000)); //le as informações do RX
            uart_write_bytes(UART, Recive_buf, RX_len); // envia as informações para TX
            RX_len = 0; // reseta o contadotor de Bytes 
        }
        vTaskDelay(pdMS_TO_TICKS(100)); //espera 100MS a cada leitura
    }

}

void UART_init() {
    //configuração basica de UART
    uart_config_t uart_params = {
        .baud_rate = BAUDRATE,
        .data_bits = UART_DATA_8_BITS, //pacotes de 8bits
        .parity = UART_PARITY_DISABLE, //sem paridade
        .stop_bits = UART_STOP_BITS_1, //apenas 1Bit de stop
        .flow_ctrl = UART_HW_FLOWCTRL_DISABLE, //sem pino de CTS, função desabilitada
        .rx_flow_ctrl_thresh = 0,// sem pino RTS, função desabilitada
        .source_clk = UART_SCLK_DEFAULT, //clock padrão da UART
    };

    //aplicando as configuraçõe
    ESP_ERROR_CHECK(uart_param_config(UART, &uart_params));

    //configuração dos pinos
    ESP_ERROR_CHECK(uart_set_pin(UART, 1, 3, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE));
    //----------------TXD, RXD, CTS(sem pino),RTS(sem pino)

    //inicilizando Driver de UART
    ESP_ERROR_CHECK(uart_driver_install(UART, UART_BUF_LEN, UART_BUF_LEN, UART_EVENT_BUF_LEN, &uart_event_queue, 0));
}

Resultado:

I2C Driver

Para o último tópico desse post vamos falar como configurar e usar o driver I₂C. Vamos começar incluindo o header <driver/i2c.h>, que tem as etapas bem parecidas com a configuração do driver da UART (até um pouco mais fácil, eu diria). Assim como na UART, esse processo segue algumas etapas, nesse caso são apenas duas, sendo a primeira a configuração dos parâmetros, tanto I₂C master quanto slave são configurados pela struct: i2c_config_t. Essa struct tem os seguintes campos:

Projeto: Display LCD

Nesse projeto vamos fazer algo um pouco diferente. Como comentamos no início do artigo, a ESP-IDF também suporta o uso da linguagem C++, então vamos fazer uso disso: nesse projeto vamos aprender como instalar bibliotecas de terceiros (fora da lista de componentes).

Baixando a biblioteca do LCD

idf_component_register(SRCS "main.cpp" "./UniversalLCD-main/universallcd.cpp"
INCLUDE_DIRS "." "UniversalLCD-main")

Esquema:

Código:

//Lib C includes
#include <stdio.h>

//FreeRTOS includes
#include <freertos/FreeRTOS.h>

//ESP-IDF includes
#include <driver/i2c.h>
#include <driver/gptimer.h>
#include <esp_err.h>
#include <esp_log.h>

//extra includes
#include <UniversalLCD-main/universallcd.hpp>

//DEFINES
#define LCD_ADDR 0x27
#define I2C_MASTER I2C_NUM_0
#define TIMER_HZ (1000*1000)

//lcd types -------------------------------------------------------------------------------------------------
struct LcdDrive : public universalLCD::BusInterface{
    void send(uint8_t config, uint8_t data){
        uint8_t package = (config & 0b00000111) | (data & 0xF0) | 0x08;
        i2c_master_write_to_device(I2C_MASTER, LCD_ADDR,&package,1,pdMS_TO_TICKS(100));
    }
};

//lcd driver delay (This code runs at a frequency of 1Khz, so it is not necessary to block the task for a microsecond delay)
static bool timer_delay_callback(gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_ctx);
void delay(uint32_t us);
void lcd_timer_init(void);


//lcd drive handler
gptimer_handle_t lcd_driver_delay;
gptimer_config_t timer_config;
gptimer_alarm_config_t delay_config;
gptimer_event_callbacks_t delay_callback;
volatile bool timer_flag;
//--------------------------------------------------------------------------------------------------------------------------------------

void I2C_init();

extern "C" void app_main(){
    I2C_init();
    lcd_timer_init();

    LcdDrive drive;
    universalLCD::UniversalLCD lcd(drive,universalLCD::Bus4Bits,delay);
    lcd.begin()
        .write("Hello world")
        .cursorOn()
        .cursorBlinkOn();
    while(true) vTaskDelay(portMAX_DELAY);

}

void I2C_init(){
    //configura I2C
    i2c_config_t conf = {
        .mode = I2C_MODE_MASTER, //modo master
        .sda_io_num = GPIO_NUM_21,
        .scl_io_num = GPIO_NUM_22,
        .sda_pullup_en = GPIO_PULLUP_ENABLE, //pull-ups habilitados
        .scl_pullup_en = GPIO_PULLUP_ENABLE,
        .master = 100000, //100Khz de clock
        .clk_flags = I2C_SCLK_SRC_FLAG_FOR_NOMAL, //clock padrão
    };

    //aplica as configuraçoes 
    ESP_ERROR_CHECK(i2c_param_config(I2C_MASTER, &conf));

    //inicia o driver I2C
    ESP_ERROR_CHECK(i2c_driver_install(I2C_MASTER, conf.mode, 0, 0, 0));
}



//LCD Functions
void lcd_timer_init(void){
    timer_config = {
        .clk_src = GPTIMER_CLK_SRC_DEFAULT,
        .direction = GPTIMER_COUNT_UP,
        .resolution_hz = TIMER_HZ,
        .intr_priority = 0,
        .flags = 0,
    };

    ESP_ERROR_CHECK(gptimer_new_timer(&timer_config, &lcd_driver_delay));
    delay_callback = {
        .on_alarm = timer_delay_callback,
    };
    delay_config = {
        .alarm_count = 0,
        .reload_count = 0,
        .flags = 0,
    };
    ESP_ERROR_CHECK(gptimer_register_event_callbacks(lcd_driver_delay,&delay_callback,NULL));
    ESP_ERROR_CHECK(gptimer_enable(lcd_driver_delay));
    ESP_ERROR_CHECK(gptimer_start(lcd_driver_delay));
}

static bool timer_delay_callback(gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_ctx){
    timer_flag = true;
    return true;
}

void delay(uint32_t us){
    uint64_t count;
    gptimer_stop(lcd_driver_delay);
    gptimer_get_raw_count(lcd_driver_delay, &count);
    delay_config = {
        .alarm_count = (uint64_t)(us+count),
        .reload_count = 0,
        .flags = 0,
    };
    timer_flag = false;
    ESP_ERROR_CHECK(gptimer_set_alarm_action(lcd_driver_delay, &delay_config));
    gptimer_start(lcd_driver_delay);
    while(!timer_flag);
}

Resultado:

Conclusão

Finalizamos aqui essa introdução. Esperamos que esse post tenha contribuído para seu aprendizado e desenvolvimento de novas habilidades, é sempre bom aprender novas ferramentas e funcionalidades para implementar em nossos projetos.Sinta-se a vontade para nos enviar dúvidas e/ou sugestões nos comentários e fique atento às novidades, traremos outros artigos sobre a ESP-IDF no futuro.Obrigado por ler até aqui, e até mais!

Sobre o autor

Guilherme Schultz LinkedIn Apaixonado por tecnologia, Autodidata em eletrônica e desenvolvimento embarcado.