MinervaBots ESC ESP32 Library 🤖🚁

📖 Sobre

Biblioteca desenvolvida pela equipe de competição de robótica MinervaBots da Universidade Federal do Rio de Janeiro (UFRJ) para o controle de precisão e alta performance de motores brushless via ESC (Electronic Speed Controller) utilizando microcontroladores da família ESP32.

Assim como nossa biblioteca de Servos, esta biblioteca de ESC é do tipo Header-Only e acessa diretamente a API nativa ledc (LED Control) do ESP-IDF. Isso garante sinais PWM extremamente estáveis, integração perfeita com o FreeRTOS e resposta instantânea para malhas de controle (como PID).

---

✨ Principais Características

• Controle Universal: Suporte nativo tanto para ESCs Bidirecionais (com ré, como robôs de Trekking) quanto Unidirecionais (como usamos em ventoinhas e sucção em seguidores de linha).
• Zero-Overhead Math: Os fatores de conversão de velocidade para PWM são resolvidos em tempo de compilação via constexpr. A função de aceleração executa zero divisões, garantindo economia massiva de ciclos de CPU.
• Two-Stage Initialization: A alocação de timers e a configuração do hardware foram isoladas no método begin(), garantindo segurança absoluta contra instabilidades de boot do RTOS ao instanciar objetos globais.
• Smart Timer Allocation: Varredura dinâmica de canais. Se houver múltiplos motores na mesma frequência (50Hz), a biblioteca reaproveita os timers do ESP32 automaticamente, economizando recursos físicos.
• Proteção de Tipagem: O código utiliza int16_t para evitar Underflows na hora de reverter o motor e aplica clamping automático de velocidade.
• Frameworks Suportados: Funciona perfeitamente tanto em projetos baseados em ESP-IDF puro quanto em Arduino Core.

---

📦 Instalação

A biblioteca está disponível oficialmente no Registry do PlatformIO. Para instalar, basta adicionar o nome da biblioteca ao seu arquivo platformio.ini:

[env:esp32dev]
platform = espressif32
framework = espidf  ; ou arduino
monitor_speed = 115200
lib_deps =
    minervabots/MinervaBots-ESC-ESP32-Library @ ^1.0.0

---

📖 Referência da API

A documentação oficial e completa da biblioteca se encontra no site MinervaCore!

EscMB(uint8_t canal, uint8_t pino, bool bidirecional = true)

Construtor da classe.

• canal: O canal PWM do LEDC a ser utilizado (0 a 15 no ESP32 clássico, 0 a 7 nos S2/S3/C3).
• pino: O pino GPIO físico conectado ao sinal (S) do ESC.
• bidirecional: Define o comportamento do ESC. true (padrão) para controle de frente/ré, ou false para apenas uma direção.

void begin()

Inicializa o hardware, aloca os timers do ESP32 e envia o sinal de Ponto Morto para armar o ESC. Deve ser chamado dentro da função de setup() ou app_main().

void setVelocidade(int16_t velocidade)

Acelera, desacelera ou inverte o motor.

• ESC Bidirecional: Aceita valores de -127 (ré máxima) a 128 (frente máxima). O zero é o ponto morto.
• ESC Unidirecional: Aceita valores de 0 (parado) a 255 (velocidade máxima).

int16_t getVelocidade() const

Retorna a última velocidade enviada ao motor.

void parar()

Atalho de segurança que chama setVelocidade(0), enviando imediatamente o sinal de ponto morto ao ESC para parar a rotação livremente sem desarmar o controlador.

---

🚀 Como Usar (Quick Start)

A inicialização correta de um ESC requer um sinal de "ponto morto" por algum instante de tempo para que ele seja armado com sucesso e emita o bipe de confirmação.

Com Arduino

#include <Arduino.h>
#include <EscMB.hpp>

// Instancia um ESC bidirecional no pino 18, canal 0
EscMB motorEsquerdo(0, 18, true);

void setup() {
    // Inicializa os timers e envia o sinal 0 (ponto morto) para armar o ESC
    motorEsquerdo.begin();
    
    // Aguarda 500 milisegundos para o ESC emitir o som de inicialização
    delay(500); 
}

void loop() {
    // Acelera gradativamente para frente
    for (int16_t vel = 0; vel <= 128; vel++) {
        motorEsquerdo.setVelocidade(vel);
        delay(15);
    }

    motorEsquerdo.parar();
    delay(1000);

    // Acelera gradativamente para trás (ré)
    for (int16_t vel = 0; vel >= -127; vel--) {
        motorEsquerdo.setVelocidade(vel);
        delay(15);
    }
    
    motorEsquerdo.parar();
    delay(2000);
}

Com ESP-IDF

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include <EscMB.hpp>

// Instancia um ESC unidirecional no pino 18, canal 0
EscMB motorArma(0, 18, false);

extern "C" void app_main() {
    // Inicializa o hardware de forma segura após o boot do RTOS
    motorArma.begin();
    vTaskDelay(500 / portTICK_PERIOD_MS); // Tempo para armar o ESC

    while (true) {
        // Spin-up da arma (0 a 255)
        for (int16_t vel = 0; vel <= 255; vel += 5) {
            motorArma.setVelocidade(vel);
            vTaskDelay(50 / portTICK_PERIOD_MS);
        }

        vTaskDelay(5000 / portTICK_PERIOD_MS); // Mantém ligado por 5s
        
        // Desliga a arma
        motorArma.parar();
        vTaskDelay(5000 / portTICK_PERIOD_MS);
    }
}

Outros exemplos de uso aqui

---

🦉 Sobre a MinervaBots

A MinervaBots é a equipe de competição de robótica da Universidade Federal do Rio de Janeiro (UFRJ). Desenvolvemos tecnologias, robôs autônomos e de combate em diversas categorias, além de fomentar a pesquisa e o ensino de engenharia no Brasil.

---

Licença: MIT