Um HTTP GET de um ESP32: buscar o clima
- 526componentes na bancada
- 46placas rodando agora
- 1.00xtempo real, em todas as placas
A maioria dos projetos conectados é uma placa pedindo um pedacinho de dados a um servidor e fazendo algo com eles: o clima, a hora, uma configuração. Em um ESP32 no mundo Arduino isso é a biblioteca HTTPClient, e o padrão é sempre os mesmos cinco passos: entrar na rede, iniciar uma requisição, fazer o GET, ler o corpo e encerrar a requisição.
O circuito acima é um ESP32-C3 rodando o exemplo pronto de WiFi: buscar o clima. Antes de tudo, a parte honesta: a rede no Mokxi é simulada. Não há rádio, e nada sai da sua aba do navegador a menos que você entre e ative a internet real. Quatro nomes inventados respondem (time.mokxi, weather.mokxi, echo.mokxi e api.mokxi) e o código da placa é o código que você enviaria para um ESP32 de verdade. Aperte Rodar e o monitor serial mostra os pontinhos do loop de conexão, depois "IP address: 192.168.4.2", e depois a cada cinco segundos:
Cada busca mostra "HTTP 200", depois o corpo, {"location":"Mokxi","temperatureC":21.5,"humidity":48,"simulated":true}, e depois os dois números que o sketch extraiu dele: "temperature: 21.5 C" e "humidity: 48 %".
Os cinco passos
WiFi.begin(ssid, password) starts joining, and the sketch waits in a loop until WiFi.status() returns WL_CONNECTED. Then, for each request, it makes a WiFiClient and an HTTPClient, calls http.begin(client, url), and http.GET() sends the request and waits for the reply. GET returns the HTTP status code, 200 for success, and http.getString() returns the body. http.end() frees the connection.
Dois detalhes importam em hardware real. Verifique o código antes de usar o corpo: um número negativo significa que a requisição nunca terminou (sem rede, um nome que não resolve, um timeout) e um 404 ou 500 significa que o servidor respondeu com um erro. E sempre chame end(), mesmo depois de uma falha, para que a conexão e seus buffers sejam liberados antes da próxima requisição; uma placa que pula isso pode vazar um pouquinho de memória a cada requisição até parar de funcionar.
WiFiClient client;
HTTPClient http;
http.begin(client, "http://weather.mokxi/");
int code = http.GET();
if (code <= 0) {
Serial.print("request failed: ");
Serial.println(HTTPClient::errorToString(code));
http.end();
return;
}
Serial.print("HTTP ");
Serial.println(code);
String body = http.getString();
http.end();Extraindo números do JSON
A resposta é JSON, um formato de texto simples com nomes e valores. Este sketch procura o texto "temperatureC", pula a aspa, os dois pontos e quaisquer espaços, e copia caracteres até a próxima vírgula ou chave de fechamento. Isso basta para uma resposta plana que você controla, e mantém o sketch legível. Para algo aninhado ou vindo de um serviço de terceiros, use um parser de verdade; em uma placa física a maioria das pessoas instala a biblioteca ArduinoJson.
Abra a aba Nuvem ao lado de Serial enquanto ele roda. Ela lista cada requisição que a placa fez, com seu status e corpo, e tem dois campos para os números com que weather.mokxi responde. Mude a temperatura para 30 e a próxima busca, em no máximo cinco segundos, mostra "temperature: 30 C". Esse é o mesmo vai e vem que uma placa real faz com um serviço de clima real, com o servidor sob o seu controle.
Quando a requisição falha
O sketch pede de propósito http://example.com/ uma vez em setup(), e com a internet real desligada o monitor serial mostra o motivo da falha: sem internet real, apenas nomes sob .mokxi. Uma placa real sem rota até um servidor falha no mesmo lugar, no GET, com um código negativo, e imprimir HTTPClient::errorToString(code) é o jeito mais rápido de saber o porquê.
Para praticar o tratamento de erros do servidor, abra o exemplo do laboratório de API com o botão abaixo. Ele busca http://api.mokxi/data, e a aba Nuvem deixa você escolher o código de status e o JSON que volta. Configure 404 ou 500 e veja o que seu código faz com uma resposta inesperada. Endereços https:// falham aqui de propósito, com uma mensagem dizendo que TLS não é simulado; em um ESP32 real uma requisição https precisa de WiFiClientSecure e do certificado do servidor.
Hábitos que valem a pena
Não pergunte com muita frequência. Um serviço de clima real atualiza a cada poucos minutos e muitos limitam quantas vezes uma chave pode chamá-los; a cada cinco segundos está ótimo para weather.mokxi e é demais para a maioria dos serviços reais. Uma vez por minuto ou menos é um padrão educado.
Mantenha segredos fora do código compartilhado. Um sketch com uma senha de WiFi ou uma chave de API vai para onde quer que você o cole. Coloque-os em um header separado que você não compartilha, e troque a senha de qualquer rede cujos dados acabaram em um post público.
Um GET bloqueado bloqueia tudo. http.GET() espera a resposta, então enquanto espera o sketch não lê botões nem atualiza um display. No Mokxi uma requisição custa ao sketch seu vai e vem simulado, como custaria no hardware, e é por isso que um projeto que precisa continuar responsivo busca raramente e faz o outro trabalho com millis() em vez de delay().
Abra este circuito no editor. ESP32-C3: buscar o clima, ligado como roda no topo desta página. Mude um componente ou um valor e rode de novo.
Perguntas
Quais placas podem rodar isto?
No Mokxi, as placas com rádio no hardware real: o ESP32-C3, o ESP32-C6, o ESP32 DevKit clássico, o ESP8266 NodeMCU e o Raspberry Pi Pico W. O mesmo exemplo existe para cada um deles.
Meu sketch pode acessar um site real a partir do simulador?
Sim, depois que você entra. Ative Internet real no painel Nuvem, e requisições HTTP e HTTPS para hosts reais saem pelo gateway do Mokxi. Com ela desligada, só nomes sob .mokxi resolvem, nada sai da aba do navegador, e qualquer outra coisa retorna um erro com uma frase explicando o porquê.
O que significa o código HTTP -1 em um ESP32?
A conexão foi recusada ou não pôde ser feita: geralmente sem WiFi, endereço errado ou um servidor que não existe. HTTPClient::errorToString(code) imprime o motivo em palavras.
Devo usar GET ou POST?
GET para ler dados, POST para enviá-los, por exemplo uma leitura de sensor para um serviço de registro. O HTTPClient tem http.POST(body), e echo.mokxi responde a um POST com o corpo que você enviou, então dá para testar aqui.
Por que http.getString() volta vazio?
Geralmente porque a requisição falhou e o código foi negativo, ou o servidor respondeu sem corpo, como um 204 faz. Imprima primeiro o código de status; se for 200 e o corpo continuar vazio, imprima http.getSize() para ver quantos bytes o servidor disse que estava enviando.
Monte isto de verdade
Abra o editor, mude um valor e veja o número mudar junto. Nada para instalar, e não precisa de conta.