Home Assistant - Criando seu primeiro código no ESPHome

Aprenda a criar seu primeiro código no ESPHome com facilidade - Descubra os passos essenciais para começar a programar placas ESP de forma simples e eficaz

Paloma Macetko

12 de Mar de 2024 • 10 min read

Olá meus Unicórnios! 🦄✨

O ESPHome é incrível, mas é chatinho de começar.

Neste tutorial, iremos abordar como configurar os elementos básicos necessários que para nosso script funcione.

Para o exemplo, iremos utilizar uma Placa NodeMcu ESP8266 e iremos configurar um único sensor para informar a força do sinal Wifi.

Criando um Script para nossa Placa ESP

Em seu "Home Assistant", acesse "ESPHome":

Clique em "New Device":

Clique em "Continue":

Preencha um nome para identificar a configuração, recomendo muito que este seja o nome de seu dispositivo.

Após isto, clique em "Next":

Agora precisamos selecionar a placa que iremos utilizar, neste exemplo, iremos utilizar a placa ESP8266:

💡

Aqui você pode sempre selecionar ESP8266 e depois modificar o modelo em seu código.
Isto permite definir o modelo exato.

Seu Script foi criado, clique em "Skip" para pular a instalação:

No seu Script, clique em "Edit" para que possamos editar a programação:

Será aberto a edição do código de seu dispositivo:

Entendendo o Código

Para qualquer script, precisamos configurar algumas seções importantes, vamos conversar sobre cada uma delas.

Nome do Dispositivo

A primeira coisa que iremos fazer é definir um nome para o dispositivo:

esphome:
    name: "aula1"

Aqui precisamos apenas definir o campo "name" com o nome do dispositivo que iremos utilizar.

Neste caso, defini para "aula1".

💡

Observe que deve ser um nome UNICO em sua rede

Modelo da Placa

Um ponto muito importante é configurar o modelo correto de sua placa.

Depois da primeira vez você acaba utilizando o mesmo modelo, já que normalmente você ira comprar do mesmo vendedor.

Neste exemplo, estou utilizando esta placa:

Onde o anúncio me fala:

"Módulo NodeMcu ESP-12E é uma placa de desenvolvimento que combina o chip ESP8266..."

Ou seja, precisamos configurar para utilizar a placa ESP8266 com o modelo ESP-12E.

Agora iremos verificar a lista de placas compatíveis:

PlatformIO Registry

The world’s first package and project dependency management solution for embedded development

PlatformIO Registry

Aqui localizamos o "NodeMCU 1.0 (ESP-12E Module)":

Clique em cima para abrir os detalhes desta placa:

NodeMCU 1.0 (ESP-12E Module) — PlatformIO latest documentation

Aqui precisamos localizar o ID da Placa:

Agora que temos as informações, vamos configurar:

esp8266:
  board: nodemcuv2

Aqui estamos definindo o Chip como sendo o "esp8266" o ID da placa como sendo "nodemcuv2".

Ativar Log

Recomendo sempre ativar o Log, isto nos permite ver algum problema, e identificar o IP que foi atribuído:

logger:

💡

Ao adicionar uma linha encostada da borda da esquerda, ativamos este recurso, mesmo sem preencher nenhum parâmetro

Ativando API

O Home Assistant se conecta a Placa através da API do ESPHome, então, temos de ativar o Log:

api:
  encryption:
    key: "xj+BhqlLBA98+kivomX9jHuy8zyK/gyUSsvjalib+9s="
  reboot_timeout: 0s

Aqui apenas estamos configurando o "reboot_timeout" para "0 segundos".

O campo "encryption.key" deve ser mantido conforme o ESPHome preencheu.

💡

Não altere o "encryption.key", esta é uma chave em Base64

Ativando OTA

Este é um recurso opcional, mas muito útil para permitir atualizar o Script via wifi:

ota:
  password: "523e8d5eb0ccf2bb9e5aefed3019a4f2"

💡

O ESPHome ira preencher uma senha aleatória, não é necessário alterar.

Ativando WebServer

Este recurso permite criar uma interface web, onde podemos controlar/monitorar os sensores/controles e ver os Logs.

web_server:
  port: 80
  auth:
    username: "teste1"
    password: "12345678"

Aqui precisamos apenas configurar um usuário e uma senha (Não vai deixar sem senha em!):

username: O Usuário
password: A Senha

💡

Se você deixar sem senha, qualquer pessoa dentro de sua rede terá acesso aos sensores e poderá subir um novo script!

Configurando o Wifi

Para que nossa placa se conecte a rede, precisamos configurar os dados da rede

wifi:
  ssid: "sua_rede"
  password: "senha_de_sua_rede"

Aqui precisamos apenas configurar o nome da rede e a senha da rede Wifi:

ssid: Nome da Rede Wifi
password: Senha da Rede Wifi

Criando um Sensor para identificar a potencia do Sinal Wifi

Você pode criar diversos sensores, ou qualquer coisa que seja conectada ao ESP.

Para este tutorial, iremos criar um simples sensor que indique a potencia do Sinal Wifi:

sensor:
  - platform: wifi_signal
    name: "wifi_signal_db"
    update_interval: 60s

Aqui estamos iniciando o recurso de "sensor" e definindo:

platform: De onde ira vir os dados, neste caso, do recurso nativo "wifi_signal"
name: O nome do Sensor, neste exemplo, preenchemos com "wifi_signal_db"
update_interval: O tempo de atualização do sensor, em segundos, neste exemplo, configuramos para "60s" (60 segundos)

💡

Recomendo sempre incluir este sensor, desta forma, você pode identificar se seu dispositivo não esta demasiadamente longe

Script Completo

Depois de preenchermos todos os dados, iremos ter as configurações básicas, devendo ficar similar ao script abaixo:

esphome:
    name: "aula1"
    
esp8266:
  board: nodemcuv2

logger:

api:
  encryption:
    key: "xj+BhqlLBA98+kivomX9jHuy8zyK/gyUSsvjalib+9s="
  reboot_timeout: 0s

ota:
  password: "523e8d5eb0ccf2bb9e5aefed3019a4f2"

web_server:
  port: 80
  auth:
    username: "teste1"
    password: "12345678"

wifi:
  ssid: "sua_rede"
  password: "senha_de_sua_rede"

sensor:
  - platform: wifi_signal
    name: "wifi_signal_db"
    update_interval: 60s

Compilando Script

Após configurarmos todo o Script, clique em "Save":

Após o Script ser salvo, será exibido uma mensagem:

Agora clique em "Install":

Selecione "Manual Download":

Aguarde o Script ser Compilado, isto pode demorar um pouco:

Após a Compilação ser finalizada, será exibido "SUCCESS":

A compilação gera um arquivo "BIN" para que importemos para nosso ESP:

O Download será iniciado automaticamente, porem, seu navegador pode bloquear por segurança, neste caso, clique em "Manter" para fazer o Download do Arquivo BIN:

Enviando arquivo Compilado para o ESP

Conecte seu ESP ao computador, utilizando um Cabo USB de ótima qualidade.

Não utilize cabos ruins, pode não funcionar, corromper o Upload ou ainda destruir seu ESP.

💡

Já ocorreu comigo estes três casos, ao utilizar os cabos falsificados

Após isto, acesse o Link abaixo:

Web - ESPHome

ESPHome

Clique em "Connect":

Na janela aberta, selecione a Porta COM de seu ESP e clique em "Conectar"

💡

Normalmente o ESP aparece com o sufixo "Pareado"

Após isto, será exibido "Connected" indicando que o ESP esta conectado corretamente:

Clique em "Install":

Selecione o Arquivo BIN e clique em "Install":

Aguarde seu Script ser enviado para seu ESP:

Após Concluir, será exibido "Configuration installed!":

Testando seu Dispositivo

Clique em "Logs":

Procure por "IP Address" para identificar o IP que foi atribuído a seu dispositivo:

Neste caso, foi atribuído o IP:

192.168.20.43

Acesse este IP em seu navegador e entre com o usuário e senha que criamos na criação do Script:

Se tudo der certo, deve abrir uma interface mostrando nosso sensor de potencia do Wifi:

Integrando Dispositivo ao Home Assistant

Em seu Home Assistant, clique em "Configurações -> Dispositivos & Serviços":

O seu dispositivo será exibido em "Descoberto":

Clique em "Configurar":

Na janela aberta, clique em "Enviar":

Será exibido uma janela para preencher "Chave de Encriptação", preencha a mesma chave que criamos quando criamos o Script e clique em "Enviar":