DEV Community: Pedro Fonseca

Como criei uma biblioteca HTTP de baixa alocação para ESP32 e o que aprendi com usuários globais

Pedro Fonseca — Thu, 06 Aug 2026 19:40:36 +0000

Desenvolver aplicações conectadas em sistemas embarcados como o ESP32 frequentemente esbarra em um problema clássico: gerenciamento de memória RAM e fragmentação de heap.

Ao consumir APIs REST tradicionais no ecossistema Arduino/ESP-IDF, o fluxo padrão quase sempre envolve:

Instanciar o HTTPClient nativo;
Realizar a requisição e baixar o payload inteiro em uma String dinâmica via http.getString();
Alocar um documento na heap via DynamicJsonDocument (ArduinoJson);
Desserializar a árvore JSON completa na memória;
Extrair manualmente campo por campo;
Torcer para o heap não fragmentar após centenas de requisições.

Em projetos maiores com Bluetooth, Wi-Fi, displays e múltiplos sensores concorrentes, essa abordagem facilmente causa crashes silenciosos ou reinicializações por falta de memória livre.

Pensando em resolver esse gargalo no meu próprio fluxo de trabalho, decidi construir o ESP32-HTTP-Client. O objetivo inicial era puramente técnico: eliminar intermediários de memória e simplificar a ergonomia do código em C++.

Hoje, a biblioteca já conta com usuários de vários lugares do mundo usando em projetos reais, e quero compartilhar aqui as decisões de arquitetura que tornaram isso possível e os aprendizados desse processo.

1. O gargalo do modelo tradicional (DOM vs Stream)

A maioria das soluções populares consome APIs via modelo baseado em DOM (Document Object Model): elas lêem a resposta completa da rede, guardam em buffer na memória e depois montam uma árvore de objetos em memória para você consultar.

Em um microcontrolador com poucas dezenas de kilobytes livres, isso é um desperdício crítico.

O que mudamos na arquitetura:

Parsing em Streaming direto do Socket: Em vez de armazenar o corpo da resposta em um buffer intermediário, o parser processa os bytes conforme eles chegam do socket de rede (com suporte nativo a Transfer-Encoding: chunked).
Direct Memory Binding (Injeção Direta): O valor do JSON é escrito diretamente no endereço de memória da variável C/C++ de destino (int, float, char[], ou struct), sem alocar árvores nem nós temporários.
Conexão Persistente (Keep-Alive TLS): Reutiliza a sessão e o socket TLS aberto, evitando o custo computacional e de latência do handshake TLS a cada requisição.

O resultado no código final fica em uma única linha fluente:

#include <WiFi.h>
#include "ESP32HTTPClient.h"

ESP32HTTPClient client("https://jsonplaceholder.typicode.com");

void setup() {
    Serial.begin(115200);
    WiFi.begin("SSID", "SENHA");
    while (WiFi.status() != WL_CONNECTED) delay(100);

    int userId = 0;
    // O valor vai direto para o endereço de userId sem buffer intermediário
    client.get("/todos/1").getBody("userId", &userId);

    Serial.printf("User ID obtido: %d\n", userId);
}

2. Benchmark de Performance e Uso de Heap

Para testar a hipótese na prática, executei um benchmark de 100 requisições consecutivas (GET /users do JSONPlaceholder) em um ESP32 padrão, comparando a abordagem padrão (HTTPClient + ArduinoJson) contra o ESP32-HTTP-Client:

Métrica	Padrão (HTTPClient + ArduinoJson)	ESP32-HTTP-Client	Diferença
Heap alocada por req	~58.2 KB	~15 bytes	-99.9% de RAM temporária
Heap Livre Mínimo	114.3 KB	128.6 KB	Mais margem de segurança
Tempo Médio por Request	~750 ms	~59 ms	~12x mais rápido (Keep-Alive)
Linhas de Boilerplate	~15 linhas	1 linha fluente	Alta manutenibilidade

Além de evitar a fragmentação do heap, o tempo de resposta caiu drasticamente porque o ESP32 não precisa renegociar certificados criptográficos TLS em toda chamada.

3. Ergonomia da API: Fluent Interface em C++ Embarcado

Uma das prioridades era garantir que a sintaxe fosse natural para quem vem tanto do C++ quanto de linguagens modernas como TypeScript/Python:

Query e Path Parameters

client.get("/users/{id}")
      .path("id", 42)
      .query("filter", "active");

POST com múltiplos tipos de payload

int novoId = 0;

client.post("/dispositivos")
      .body("nome", "Sensor-01")
      .body("temperatura", 24.5)
      .body("ativo", true)
      .getBody("id", &novoId);

Navegação em objetos aninhados e arrays

char cidade[32];

// Navega no caminho "address.city" direto para o buffer
client.get("/users/1").getBody("address.city", cidade, sizeof(cidade));

4. A experiência com usuários reais pelo mundo

Quando publicamos um projeto open source, muitas vezes esperamos que ele resolva apenas o nosso problema isolado.

Porém, conforme a lib foi catalogada no PlatformIO Registry e no Arduino Library Manager, começaram a surgir issues, dúvidas e discussões no GitHub vindas de desenvolvedores de vários países (EUA, Belorrusia, Belgica, França, e claro o Brasil).

Alguns aprendizados marcantes dessa troca:

Casos de borda em redes industriais: Desenvolvedores usando roteadores com MTU customizada ou servidores corporativos com headers HTTP fora do padrão convencional me forçaram a refinar o parser de stream para ser ainda mais resiliente a timeouts parciais.
Ambientes com pouquíssima RAM: Projetos rodando ESP32-CAM ou stacks pesadas de BLE relataram que a lib foi o que permitiu manter a conectividade HTTP sem causar estouro de pilha (stack overflow) no FreeRTOS.
Importância de documentação viva: Manter uma documentação clara em inglês e português com exemplos práticos reduziu o número de dúvidas básicas e aumentou o nível das contribuições técnicas.

5. Código e Documentação

O projeto é 100% open source (MIT) e está disponível nos gerenciadores de pacote:

Repositório no GitHub: PedroFnseca/esp32-http-client
Documentação Oficial: pedrofnseca.github.io/esp32-http-client
Instalação via PlatformIO: lib_deps = PedroFnseca/ESP32-HTTP-Client@^1.4.0
Instalação via Arduino IDE: Buscar por ESP32-HTTP-Client no Library Manager.

Gostaria de abrir espaço para feedbacks de quem trabalha com sistemas embarcados e IoT aqui na comunidade: que estratégias vocês têm adotado para gerenciar payloads JSON e conexões seguras em microcontroladores com recursos escassos?

ESP32 HTTP Client Without the Headache: Consuming REST APIs with Zero Memory Allocation

Pedro Fonseca — Thu, 06 Aug 2026 18:53:12 +0000

Consuming REST APIs on ESP32 Without Heap Crashes: Meet ESP32-HTTP-Client

If you have ever developed IoT projects on the ESP32 that interact with REST APIs (pushing sensor telemetry, querying cloud services, or integrating with Firebase and AWS), you have likely run into these classic bottlenecks:

Heap Fragmentation & Out-of-Memory Crashes: The standard HTTPClient + ArduinoJson workflow loads the entire HTTP payload into RAM as a String before parsing. With medium to large JSON payloads, this often leads to heap fragmentation and unpredictable crashes.
High Latency on Consecutive Requests: The default Arduino HTTPClient tears down and re-establishes TCP/TLS handshakes on every request, adding hundreds of milliseconds of overhead to every telemetry cycle.
Excessive Boilerplate: Writing 15 to 20 lines of repetitive code just to initialize clients, handle buffers, verify error status codes, and extract individual JSON nodes.

To solve these pain points with a clean, modern architecture, ESP32-HTTP-Client was created.

What is ESP32-HTTP-Client?

ESP32-HTTP-Client is a lightweight, fluent, and object-oriented HTTP/REST client for ESP32, designed specifically for memory-constrained embedded systems.

Rather than "buffering the entire response into RAM and then parsing", it leverages Direct Memory Binding and Stream-Based Parsing: JSON values are parsed directly from the incoming network stream and injected straight into your C++ variables or structs, never buffering the full payload in RAM.

// One line. Zero intermediate string buffers. Direct memory binding.
client.get("/sensor").getBody("temperature", &myFloatVariable);

Performance Benchmark: ESP32-HTTP-Client vs Standard Approach

In benchmark tests running 100 consecutive HTTP GET requests with JSON payloads (using the public JSONPlaceholder /users endpoint), the results highlight significant resource savings:

Metric / Feature	HTTPClient + ArduinoJson (Standard)	ESP32-HTTP-Client	Comparison
Heap Allocated per Request	~58.2 KB	~0.0 KB (15 bytes)	~99.9% less RAM per request
Average System RAM Used	~34.2%	~24.3%	~29% less overall RAM consumed
Absolute Min Free Heap	114.3 KB	128.6 KB	Much safer for complex IoT apps
Average Execution Time	~750 ms	~59 ms	~12x faster (Native Keep-Alive)
Lines of Code	~15-20 lines	1 fluent chain	Clean, readable, maintainable
JSON Parsing Model	Requires `DynamicJsonDocument`	Streaming directly to variables	Zero buffer allocation

Why is it so much faster?

ESP32-HTTP-Client maintains the underlying TCP/TLS connection open across calls (HTTP Keep-Alive) and decodes Transfer-Encoding: chunked on the fly. This eliminates the heavy overhead of re-running TLS cryptographic handshakes on every reading.

Quick Start: Your First Request in 2 Minutes

Installation

PlatformIO (add to your platformio.ini):

  lib_deps =
      PedroFnseca/ESP32-HTTP-Client@^1.4.0

Arduino IDE: Navigate to Sketch → Include Library → Manage Libraries..., search for ESP32-HTTP-Client, and click Install.

Basic Example: GET Request with Direct Binding

#include <Arduino.h>
#include <WiFi.h>
#include "ESP32HTTPClient.h"

const char* ssid     = "YOUR_SSID";
const char* password = "YOUR_PASSWORD";

// Initialize client with base URL
ESP32HTTPClient client("https://jsonplaceholder.typicode.com");

void setup() {
    Serial.begin(115200);
    WiFi.begin(ssid, password);
    while (WiFi.status() != WL_CONNECTED) delay(100);

    int userId = 0;
    char title[64] = {0};
    bool completed = false;

    // Expected JSON: { "userId": 1, "id": 1, "title": "delectus aut autem", "completed": false }
    client.get("/todos/1")
          .getBody("userId", &userId)
          .getBody("title", title, sizeof(title))
          .getBody("completed", &completed);

    Serial.printf("User ID: %d | Title: %s | Completed: %s\n", 
                  userId, title, completed ? "true" : "false");
}

void loop() {}

Advanced Features for Production IoT

ESP32-HTTP-Client provides a complete toolset for real-world IoT applications:

1. Bidirectional Struct <-> JSON Mapping

Map entire C++ structures using the REST_JSON_MAP macro. You can send and receive typed objects without manual serialization logic:

// 1. Declare struct with mapped fields
struct DeviceTelemetry {
    int deviceId = 101;
    float temperature = 26.4;
    float humidity = 58.0;
    bool statusOk = true;

    REST_JSON_MAP(
        REST_FIELD(deviceId),
        REST_FIELD(temperature),
        REST_FIELD(humidity),
        REST_FIELD(statusOk)
    )
};

// 2. Send struct directly in POST body (zero-copy serialization)
DeviceTelemetry telemetry;
client.post("/api/telemetry").body(telemetry);

// 3. Populate struct directly from response
DeviceTelemetry serverConfig;
client.get("/api/config").getBody(&serverConfig);

2. Built-in Authentication Helpers (Bearer, Basic, API Key)

Set persistent authentication headers for the lifecycle of your client:

// JWT / Bearer Token
client.bearer("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ...");

// HTTP Basic Auth (Base64 automatically computed)
client.basic("admin", "superSecretPassword");

// Custom API Key Header
client.apiKey("X-API-KEY", "your-access-key");

3. Nested Field Extraction & Array Indexing

Extract deeply nested fields or specific array elements without loading the entire JSON tree into memory:

char cityName[32];
int secondSensorVal;

// Dot notation navigation: { "company": { "address": { "city": "San Francisco" } } }
client.get("/profile").getBody("company.address.city", cityName, sizeof(cityName));

// Array indexing: [ { "val": 10 }, { "val": 25 } ]
client.get("/sensors").getBody("1.val", &secondSensorVal);

4. Network Resilience: Timeouts, Auto-Retries & Callbacks

On unreliable IoT networks, configure timeouts, automatic retry policies, and declarative callbacks:

client.get("/telemetry")
      .timeout(3000)          // 3-second timeout for this request
      .retry(2)                // Retry up to 2 times on network drops
      .onSuccess([](int code) {
          Serial.printf("Request succeeded! HTTP Code: %d\n", code);
      })
      .onError([](int code, const char* msg) {
          Serial.printf("Request failed (%d): %s\n", code, msg);
      })
      .getBody("status", &statusVar);

5. Efficient Connection & TLS Buffer Management

Keep-Alive preserves the socket and TLS buffers (~45 KB) for instant subsequent calls. When preparing for Deep Sleep or long idle intervals, release TLS buffers immediately:

// Fast burst of telemetry calls using Keep-Alive
client.get("/sync/1").getBody("val", &v1);
client.get("/sync/2").getBody("val", &v2);

// Free TLS memory before sleep or extended delay
client.end();

Why Choose ESP32-HTTP-Client?

Zero Heap Leaks: Eliminates crashes caused by String heap fragmentation and heavy JSON buffers.
Lower Energy Consumption: 12x faster network transactions mean the Wi-Fi radio is powered for less time.
Readable Codebase: Fluent API replaces repetitive boilerplate with concise, expressive statements.
Production-Ready: Includes comprehensive unit tests and full support for all HTTP methods (GET, POST, PUT, PATCH, DELETE).

Official Links & Resources

Official Documentation — Full guides, API reference, and tutorials.
GitHub Repository — Source code, issue tracker, and contributions.
Examples Directory — Ready-to-flash sketches for Arduino IDE and PlatformIO.

ESP32 HTTP Client Sem Dores de Cabeça: Consuma REST APIs com Zero Alocação de Memória

Pedro Fonseca — Thu, 06 Aug 2026 18:49:06 +0000

Consumindo REST APIs no ESP32 sem Estourar a Memória: Conheça o ESP32-HTTP-Client

Se você já desenvolveu projetos IoT no ESP32 que se comunicam com APIs REST (seja para enviar dados de sensores para a nuvem, consultar status de serviços ou integrar com Firebase e AWS), provavelmente já enfrentou um destes problemas clássicos:

Fragmentação e estouro de heap: O combo padrão HTTPClient + ArduinoJson precisa carregar todo o payload HTTP na RAM como String antes de desserializar o JSON. Em payloads médios ou grandes, isso gera Out of Memory ou travamentos intermitentes.
Lentidão em requisições consecutivas: O HTTPClient padrão refaz o handshake TLS/TCP repetidamente, adicionando centenas de milissegundos a cada chamada.
Código verboso e boilerplate excessivo: Mais de 15 a 20 linhas de código para instanciar clientes, extrair buffers, checar erros e navegar em nós JSON.

Para resolver esses gargalos de forma elegante e moderna, foi criada a biblioteca ESP32-HTTP-Client.

O que é o ESP32-HTTP-Client?

O ESP32-HTTP-Client é um cliente HTTP/REST moderno, fluente e orientado a objetos para ESP32, projetado especificamente para sistemas embarcados de alta eficiência.

Em vez de "fazer download da resposta, guardar na memória e depois processar", ele utiliza Direct Memory Binding (injeção direta) e Stream Parsing: os dados do JSON são lidos diretamente do stream da rede e injetados direto nas suas variáveis ou structs em C++, sem armazenar o payload inteiro na RAM.

// Uma linha. Zero strings intermediárias. Injeção direta em memória.
client.get("/sensor").getBody("temperature", &myFloatVariable);

Benchmark: ESP32-HTTP-Client vs Abordagem Tradicional

Em testes controlados com 100 requisições HTTP consecutivas contendo payloads JSON (usando o endpoint /users do JSONPlaceholder), os resultados comprovam a economia de recursos:

Métrica / Recurso	HTTPClient + ArduinoJson (Padrão)	ESP32-HTTP-Client	Diferencial
Heap alocado por requisição	~58.2 KB	~0.0 KB (15 bytes)	~99.9% menos RAM por request
Uso médio de RAM do sistema	~34.2%	~24.3%	~29% menos memória total
Heap livre mínimo absoluto	114.3 KB	128.6 KB	Muito mais seguro p/ apps robustas
Tempo de Execução Médio	~750 ms	~59 ms	~12x mais rápido (Keep-Alive nativo)
Linhas de Código	~15-20 linhas	1 cadeia fluente	Código limpo e sustentável
Parsing de JSON	Exige buffer `DynamicJsonDocument`	Streaming direto na variável	Zero buffer allocation

Nota sobre desempenho:

O ESP32-HTTP-Client reutiliza a mesma conexão TCP/TLS ativa (HTTP Keep-Alive) e decodifica Transfer-Encoding: chunked no fluxo de dados. Isso elimina a sobrecarga de refazer negociações criptográficas TLS a cada ciclo de leitura do seu sensor.

Quick Start: Seu primeiro request em 2 minutos

Instalação

PlatformIO (adicione ao seu platformio.ini):

  lib_deps =
      PedroFnseca/ESP32-HTTP-Client@^1.4.0

Arduino IDE: Abra Sketch → Include Library → Manage Libraries..., procure por ESP32-HTTP-Client e clique em Install.

Exemplo Básico: GET com Injeção de Dados

#include <Arduino.h>
#include <WiFi.h>
#include "ESP32HTTPClient.h"

const char* ssid     = "SEU_WIFI";
const char* password = "SUA_SENHA";

// Inicialize o client apontando para a base URL
ESP32HTTPClient client("https://jsonplaceholder.typicode.com");

void setup() {
    Serial.begin(115200);
    WiFi.begin(ssid, password);
    while (WiFi.status() != WL_CONNECTED) delay(100);

    int userId = 0;
    char title[64] = {0};
    bool completed = false;

    // Resposta esperada: { "userId": 1, "id": 1, "title": "delectus aut autem", "completed": false }
    client.get("/todos/1")
          .getBody("userId", &userId)
          .getBody("title", title, sizeof(title))
          .getBody("completed", &completed);

    Serial.printf("User ID: %d | Title: %s | Completed: %s\n", 
                  userId, title, completed ? "true" : "false");
}

void loop() {}

Recursos Avançados

O ESP32-HTTP-Client foi desenvolvido pensando em cenários reais de engenharia IoT:

1. Mapeamento Bidirecional de struct <-> JSON

Você pode mapear estruturas C++ inteiras usando a macro REST_JSON_MAP. Isso permite enviar e receber objetos completos sem tocar em bibliotecas adicionais de parsing:

// 1. Defina a struct com o mapa de campos
struct DeviceTelemetry {
    int deviceId = 101;
    float temperature = 26.4;
    float humidity = 58.0;
    bool statusOk = true;

    REST_JSON_MAP(
        REST_FIELD(deviceId),
        REST_FIELD(temperature),
        REST_FIELD(humidity),
        REST_FIELD(statusOk)
    )
};

// 2. Envie o struct diretamente no POST (serialização zero-copy)
DeviceTelemetry telemetry;
client.post("/api/telemetry").body(telemetry);

// 3. Receba dados diretamente no struct
DeviceTelemetry serverConfig;
client.get("/api/config").getBody(&serverConfig);

2. Autenticação Simplificada (Bearer, Basic, API Key)

Configurar cabeçalhos de autenticação que persistem durante o ciclo de vida do cliente:

// JWT / Bearer Token
client.bearer("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ...");

// HTTP Basic Auth (Base64 gerado automaticamente)
client.basic("admin", "senhaSuperSecreta");

// Header de API Key personalizado
client.apiKey("X-API-KEY", "minha-chave-de-acesso");

3. Extração com Dot Notation e Índices de Array

Para ler uma propriedade profundamente aninhada ou um item específico de uma lista sem carregar a árvore JSON inteira:

char cityName[32];
int secondSensorVal;

// Navegação por ponto: { "company": { "address": { "city": "São Paulo" } } }
client.get("/profile").getBody("company.address.city", cityName, sizeof(cityName));

// Acesso por índice de array: [ { "val": 10 }, { "val": 25 } ]
client.get("/sensors").getBody("1.val", &secondSensorVal);

4. Resiliência: Timeouts, Retries Automáticos e Callbacks

Em redes IoT com oscilações de sinal, o cliente oferece suporte a retries e callbacks declarativos:

client.get("/telemetry")
      .timeout(3000)          // Timeout de 3 segundos nesta requisição
      .retry(2)                // Tenta até 2 vezes caso ocorra falha de rede
      .onSuccess([](int code) {
          Serial.printf("Sucesso! HTTP Code: %d\n", code);
      })
      .onError([](int code, const char* msg) {
          Serial.printf("Falha na requisição (%d): %s\n", code, msg);
      })
      .getBody("status", &statusVar);

5. Gerenciamento de Conexão e Memória TLS

O Keep-Alive mantém o socket e o buffer TLS (~45 KB) aquecidos para máxima agilidade. Se o seu dispositivo vai entrar em modo de baixo consumo (Deep Sleep) ou passar um longo período sem comunicação, é possível liberar os buffers a qualquer momento:

// Requisições consecutivas aproveitando o Keep-Alive
client.get("/sync/1").getBody("val", &v1);
client.get("/sync/2").getBody("val", &v2);

// Libera os buffers TLS da RAM antes de um delay longo ou deep sleep
client.end();

Principais Vantagens do ESP32-HTTP-Client

Elimina vazamentos e fragmentação de heap: Reduz falhas e travamentos causados por concatenação excessiva de String e alocações dinâmicas.
Reduz o consumo energético: Requisições até 12x mais rápidas diminuem o tempo de atividade do rádio Wi-Fi.
Código limpo e conciso: A API fluente simplifica blocos complexos de código em chamadas declarativas.
Projetado para produção: Suporte completo aos métodos REST (GET, POST, PUT, PATCH, DELETE) e validação via testes unitários automatizados.

Links e Recursos Oficiais

Documentação Oficial Completa — Guias passo a passo, referência de API e exemplos.
Repositório no GitHub — Código-fonte, issues e contribuições.
Exemplos Prontos — Sketches completos para Arduino IDE e PlatformIO.