Este projeto demonstra como integrar o ESP32 a um sistema moderno de notificações push utilizando o serviço ntfy.sh. A proposta é oferecer uma forma simples e flexível de enviar alertas diretamente para o celular, navegador (via Web Push) ou aplicativo de desktop multiplataforma, utilizando o serviço ntfy.sh., sem depender de servidores intermediários complexos ou chaves de API.
A aplicação desenvolvida usa a biblioteca AsyncWebServer para criar uma interface web embarcada que permite ao usuário testar e experimentar os parâmetros das mensagens de forma interativa — escolhendo o tópico, título, mensagem, tags, prioridade e até ações clicáveis.
Em projetos de automação residencial, monitoramento ambiental ou sistemas IoT é fundamental enviar/receber notificações quando um evento importante ocorre — por exemplo, uma variação de tensão, temperatura fora do limite, detecção de presença ou falha em um dispositivo remoto.
O serviço ntfy.sh simplifica esse processo: ele recebe mensagens via HTTP POST e as distribui automaticamente a todos os dispositivos inscritos no mesmo tópico. Entre as vantagens que motivaram o uso desse serviço estão:
Assim, o projeto serve como base para aplicações que precisem gerar alertas inteligentes diretamente a partir do ESP32 — sem depender de serviços externos proprietários.
Para tornar o acesso ao aplicativo mais fácil, as seguintes funcionalidades foram adicionadas:
1. Alias DNS local (mDNS)
Permite o acesso rápido ao servidor web através da URL amigável http://ntfy_sh.local em vez do endereço IP numérico.
2. Sincronização de tempo (NTP ou navegador)
O relógio interno do ESP32 é sincronizado automaticamente com um servidor NTP quando conectado ao Wi-Fi.
O ntfy.sh é um serviço de mensagens e notificações em tempo real baseado em protocolo HTTP e WebSocket. Com ele, é possível enviar mensagens de qualquer dispositivo — inclusive um microcontrolador como o ESP32 — e recebê-las instantaneamente em outros dispositivos, sejam celulares, navegadores ou aplicativos de desktop.
A ideia central é simples: cada mensagem é enviada para um tópico, e qualquer cliente inscrito nesse mesmo tópico recebe a notificação. O sistema não exige autenticação nem configuração prévia, ou seja, não é burocrático, sendo ideal para projetos de automação, alertas e testes rápidos.
Formas de acesso e uso
O ntfy.sh pode ser utilizado de diferentes maneiras, dependendo do dispositivo:
ntfy subscribe meu_teste_esp32
Esse modo é útil em servidores Linux, scripts e integrações com automação.
O conceito de tópico
O tópico é o nome do canal de comunicação entre quem envia e quem recebe as notificações. Todos os dispositivos que publicarem ou assinarem o mesmo tópico compartilham as mesmas mensagens. Por exemplo, enviar uma mensagem para https://ntfy.sh/alerta_temperatura fará com que todos os assinantes desse tópico recebam a notificação.
Não há necessidade de cadastro ou chave de autenticação no servidor público ntfy.sh, por isso o acesso é aberto — o que traz praticidade, mas também exige atenção com a privacidade.
Boas práticas e privacidade
Como os tópicos públicos podem ser acessados por qualquer pessoa que conheça o nome, é importante criar tópicos com nomes complexos e difíceis de adivinhar, evitando nomes genéricos como teste ou alerta.
Uma boa prática é gerar tópicos com combinações aleatórias, por exemplo: projeto_07c2_07e9_alerts ou esp32_12fa_89db_temp. Esses identificadores tornam muito improvável que outra pessoa acesse seu canal.
Se desejar ainda mais segurança, o ntfy permite usar tokens de autenticação ou até mesmo hospedar uma instância própria do servidor. Dessa forma, as notificações ficam restritas à sua rede ou organização. Tais recursos mais avançados (Autenticação, Servidor Interno e Cliente Desktop) não serão abordados neste post.
Para este post adotaremos o tópico definido como a seguir:
#define TOPIC "post_eletrogate_esp32_ntfy_sh_out_2025" // Tópico para o envio
Geradores automáticos de nomes de tópicos
Não há, até o momento, uma ferramenta oficial para gerar nomes de tópicos no próprio ntfy.sh. Entretanto, é possível usar qualquer gerador de strings aleatórias, como:
Essa prática garante mais privacidade e ajuda a evitar colisões de tópicos com outros usuários do serviço público.
Como alternativa à geração de nomes aleatórios por sites externos, é possível criar o nome do tópico diretamente no código do ESP32. A função a seguir combina um prefixo com parte do endereço MAC do dispositivo e com alguns caracteres aleatórios, criando um identificador praticamente único e difícil de adivinhar.
//------------------------------------------------------------------------------
// Gera um nome de tópico único combinando um prefixo com o MAC do WiFi com
// sufixos aleatórios: <prefixo>_<mac-parcial>_<hex-aleatorio>
// Exemplo de saída: "esp32_c3_1f9a60_a3f1b2"
//------------------------------------------------------------------------------
String gerarTopicoAleatorio(String prefixo)
{
String mac = WiFi.macAddress(); // EX: "24:0A:C4:1F:9A:60"
mac.replace(":", "");
mac.toLowerCase();
String macTail = mac.substring(6); // pega metade final para compactar (ex.: "1f9a60")
// sufixo aleatório com 6 hex (24 bits)
String sufixo;
sufixo.reserve(6);
for (int i = 0; i < 6; i++) {
sufixo += String(random(16), HEX); // 0..f
}
String p = sanitizeTopicToken(prefixo);
if (p.length() == 0) p = "esp32"; // fallback
return p + "_" + macTail + "_" + sufixo;
}
O prefixo ajuda a organizar projetos (ex.: esp32_c3, coletora, receptora), e que o restante do nome vem do MAC parcial + sufixo aleatório para evitar colisões/adivinhação.
O botão “Sugerir tópico” consulta o próprio ESP32 em /gen-topic — ou seja, o usuário não precisa abrir sites externos.
Lembre que o ntfy aceita letras, números, hífen, sublinhado e ponto (a função já sanitiza o prefixo para isso).
Essa estratégia é especialmente útil em projetos com múltiplos módulos ESP32, evitando colisões e garantindo um bom nível de privacidade mesmo no servidor público ntfy.sh.
Exemplo rápido
Com esses passos, você compreende de forma prática como o ntfy.sh funciona e como o ESP32 pode interagir com ele para criar notificações de automação.
Planos e Limites de Uso do Serviço ntfy.sh
O servidor público ntfy.sh é oferecido gratuitamente e é ideal para testes, protótipos e aplicações pessoais de automação. Não há necessidade de criar conta ou realizar autenticação para o envio de mensagens em tópicos públicos.
Entretanto, por ser um serviço compartilhado, o ntfy.sh impõe limites automáticos de uso para garantir estabilidade e evitar abusos. Esses limites são suficientes para a maioria dos projetos baseados em microcontroladores, incluindo o uso com o ESP32-C3 Mini.
Uso gratuito (servidor público)
| Recurso | Limite aproximado | Observações |
| Mensagens enviadas | até 100 por hora por IP | O servidor pode aplicar limitação temporária se o volume for muito alto. |
| Tamanho da mensagem | 4 KB (texto) | Mensagens maiores são truncadas automaticamente. |
| Anexos (attach) | até 15 MB | Arquivos hospedados temporariamente. |
| Retenção das mensagens | 12 horas | As mensagens antigas são automaticamente removidas após esse período. |
| Privacidade | Aberta | Tópicos são públicos; use nomes aleatórios para evitar acessos indevidos. |
Essas restrições são mais do que suficientes para fins educacionais e experimentais, sendo perfeitamente adequadas ao projeto de notificações com ESP32.
ntfy Pro – versão paga
Para aplicações profissionais, corporativas ou com grande volume de notificações, existe a versão ntfy Pro, que oferece maior capacidade, autenticação e histórico expandido.
Os planos pagos são bastante acessíveis (a partir de aproximadamente US$ 1 a 3 por mês) e podem ser consultados em: https://ntfy.sh/pro.
Hospedagem própria (self-hosted)
Outra alternativa é instalar uma instância própria do servidor ntfy. Por ser um software open-source (licença Apache 2.0), qualquer pessoa pode executar o serviço localmente, garantindo privacidade total e eliminando limites de uso.
docker run -d --name ntfy \ -p 80:80 \ -v /var/cache/ntfy:/var/cache/ntfy \ binwiederhier/ntfy serve
Essa abordagem é ideal para redes locais, ambientes industriais ou projetos que demandem controle total sobre as notificações.
Em resumo, o servidor público gratuito do ntfy.sh é suficiente para a maioria das aplicações educacionais e de automação doméstica, mas a versão Pro e a opção self-hosted ampliam significativamente as possibilidades de uso em contextos profissionais.
Figura 1 – Resumo da Arquitetura do Serviço Ntfy.sh
O ESP32-C3 Mini é uma das versões mais compactas e eficientes da família ESP32, baseada no microcontrolador ESP32-C3 fabricado pela Espressif Systems. Ele utiliza um núcleo RISC-V de 32 bits, combinando baixo consumo de energia, excelente conectividade Wi-Fi (2.4 GHz) + Bluetooth Low Energy (BLE 5.0) e compatibilidade total com o ecossistema do Arduino IDE.
Apesar do tamanho reduzido, o módulo oferece recursos suficientes para aplicações de IoT, automação e monitoramento remoto, como GPIOs digitais, ADCs, comunicação UART/I²C/SPI e suporte nativo a USB. No projeto atual, ele é responsável por conectar-se à rede Wi-Fi e enviar notificações ao serviço ntfy.sh sempre que um evento for detectado — por exemplo, o acionamento de um botão físico.
Figura 2 – Pinout do ESP32C3 Mini
Configuração da Placa no Arduino IDE
Para programar o módulo, selecione a placa ESP32C3 Dev Module no menu Ferramentas → Placa do Arduino IDE. Essa opção garante que o compilador utilize os parâmetros corretos de pinagem e inicialização USB.
Figura 3 – Definição da Placa ESP32C3 Mini
Uma configuração importante que merece destaque é o parâmetro USB CDC on Boot, localizado também em Ferramentas → USB CDC on Boot. Esse parâmetro define se a interface USB do chip atuará como porta serial logo após o reset.
Portanto, para que as mensagens de log e depuração do projeto sejam exibidas corretamente, o parâmetro USB CDC on Boot deve estar ajustado para Enabled. Essa configuração é especialmente útil no ESP32-C3 Mini, que utiliza a própria porta USB-C tanto para alimentação quanto para comunicação serial, dispensando conversores externos como o CH340 ou CP2102.
Figura 4 – Configuração de Parâmetros de Compilação
Upload automático de código
Um ponto prático do ESP32-C3 Mini é que o processo de gravação do firmware (Upload) ocorre de forma automática, sem necessidade de manter o botão BOOT pressionado durante o reset da placa. Essa facilidade é garantida pelo bootloader USB nativo do chip, que coloca o dispositivo em modo de gravação assim que o Arduino IDE inicia o upload.
Portanto, mesmo que o parâmetro USB CDC on Boot esteja desativado, a gravação do código continua funcionando normalmente. O que esse parâmetro realmente controla é apenas a porta serial do firmware, ou seja, se as mensagens do comando Serial.println() serão exibidas automaticamente no Monitor Serial após a reinicialização.
Em resumo:
Em situações raras (por exemplo, se o upload for interrompido ou o driver USB falhar), pode ser necessário manter o botão BOOT pressionado por alguns segundos para forçar o modo de gravação manualmente.
Para fins didáticos, serão utilizados um push button (chave tátil) e um LED vermelho de 5 mm, montados em uma mini protoboard. O botão servirá como gerador de eventos e o LED indicará visualmente o estado atual. Quando o botão for pressionado, o ESP32-C3 enviará uma notificação para o serviço ntfy.sh utilizando o modo de cabeçalhos HTTP, em vez de JSON — uma alternativa simples e útil para desenvolvedores que desejam enviar mensagens rápidas sem montar objetos complexos.
Esse exemplo mostrará que é possível acionar notificações com pouquíssimas linhas de código, explorando a agilidade do protocolo HTTP e a praticidade do ntfy.sh em aplicações de automação e monitoramento remoto.
Figura 5 – Diagrama do Circuito
Nesta seção é apresentada a integração completa entre o ESP32-C3 Mini, a interface web embarcada e o serviço ntfy.sh. O objetivo é demonstrar, de forma prática, como as notificações são geradas, tanto por meio da interface web quanto pelo acionamento físico do botão no protótipo.
Interface Web embarcada
O projeto utiliza a biblioteca AsyncWebServer para hospedar uma página HTML diretamente na memória do ESP32. Essa interface permite preencher os parâmetros da mensagem (tópico, título, tags, prioridade, etc.) e enviá-los ao serviço ntfy.sh no formato JSON.
Na figura a seguir observa-se a tela da interface, onde é possível configurar todos os campos da notificação e testar diferentes combinações:
Figura 6 – Tela do Aplicativo no Desktop
Figura 7 – Tela do Aplicativo no Celular
A interface também permite que o usuário adicione tags visuais (como warning, fire, bulb, bell, etc.) de duas formas distintas: fornecendo o nome da tag e pressionando o botão “Adicionar Tag” ou selecionando o emojis no combobox e pressionando o botão “Adicionar Sugestão”. Na Referência 2 existe o link para a lista de tags/emojis que podem ser utilizadas. Há também a possibilidade de definir ações personalizadas com links externos. Esses recursos enriquecem a mensagem recebida no aplicativo, facilitando a interpretação dos alertas. Opcionalmente, o usuário pode gerar nomes mais complexos para tópicos.
Envio de alertas via cabeçalho HTTP
Além do envio em formato JSON, o serviço ntfy.sh permite enviar notificações de forma mais simples, utilizando apenas cabeçalhos HTTP. Essa alternativa é especialmente útil para microcontroladores, pois elimina a necessidade de montar objetos JSON e reduz o uso de memória.
No exemplo do projeto, o botão tátil é usado para alternar o estado do LED e enviar uma notificação imediata. Cada vez que o botão é pressionado, o ESP32 envia um POST com os cabeçalhos apropriados:
//--------------------------------------------
// Verifica se o botão do LED foi pressionado
//--------------------------------------------
if (buttonState)
{
// Inverte o estado do LED
estadoLED = !estadoLED;
digitalWrite(pinLED,estadoLED);
char msg[64];
sprintf(msg, "Botão pressionado mudou o estado do LED para %s",ledONOFF[estadoLED].c_str());
Serial.println(msg);
// Enviar a Notificação
Serial.printf("Resultado do Envio: %s\n",sendAlertLed(TOPIC,TITLE,String(msg),PRIORITY).c_str());
// Reseta o estado do botão
buttonState = false;
}//-------------------------------------------
// Envia a Notificação via cabeçalho do http
//-------------------------------------------
String sendAlertLed(String topic, String title, String message, int priority)
{
// Enviando a notificação de forma simples
HTTPClient http;
// URL completa do tópico
String url = String(NTFY_URL) + topic;
http.begin(url);
http.addHeader("Content-Type", "text/plain");
// Atributos extras
http.addHeader("Title", title);
http.addHeader("Priority", String(priority)); // 1=min, 3=default, 5=max
http.addHeader("Tags", ledTAGS[estadoLED]);
int httpResponseCode = http.POST(message);
String rc;
if (httpResponseCode > 0)
{
rc = "Notificação enviada! Código: " + String(httpResponseCode);
}
else
{
rc = "Erro ao enviar: " + http.errorToString(httpResponseCode);
}
http.end();
return rc;
}O servidor ntfy.sh interpreta automaticamente os cabeçalhos: Title define o título da notificação, Priority ajusta o nível de alerta, e Tags insere os ícones correspondentes no aplicativo. O corpo do POST contém a mensagem principal (neste caso, o estado do LED).
Na prática, isso significa que o ESP32 pode gerar notificações ricas com pouquíssimas linhas de código, sem depender de bibliotecas externas de formatação JSON.
Notificações recebidas
As figuras a seguir mostram exemplos de notificações recebidas no aplicativo ntfy em um smartphone e também no navegador, quando o mesmo tópico está aberto em https://ntfy.sh/app.
Figura 8 – Tela do App com as Notificações (Alertas)
Figura 9 – Tela do App Web com as Notificações (Alertas)
É possível observar que cada notificação inclui o título, a mensagem, as tags visuais e o carimbo de tempo gerado automaticamente pelo servidor ntfy.sh.
Verificação pelo monitor serial
Durante os testes, o Monitor Serial do Arduino IDE exibe mensagens de depuração confirmando o envio das requisições HTTP e o código de retorno do servidor (geralmente HTTP 200 OK). Esses logs ajudam a validar o funcionamento e são especialmente úteis para verificar a conectividade Wi-Fi e o status das respostas do servidor.
Figura 10 – Mensagens na Console do IDE
Com esta base, o projeto demonstra como o ESP32 pode emitir notificações instantâneas para qualquer dispositivo, usando um serviço gratuito, seguro e compatível com JSON. Além de ser uma excelente ferramenta didática, a integração com ntfy.sh abre caminho para diversas aplicações reais em automação residencial, monitoramento remoto, sistemas de alerta e IoT distribuído.
|
|
A Eletrogate é uma loja virtual de componentes eletrônicos do Brasil e possui diversos produtos relacionados à Arduino, Automação, Robótica e Eletrônica em geral.
Conheça a Metodologia Eletrogate e Lecione um Curso de Robótica nas Escolas da sua Região!
Rua Rio de Janeiro, 441
Centro - Belo Horizonte/MG
CEP 30160-041
*Não temos atendimento físico
Eletrogate Componentes Eletrônicos
CNPJ: 18.917.521/0001-73
