Fri3d Camp

Aan de slag met ESPHome en HomeAssistant

Practical information for my Aan de slag met ESPHome en HomeAssistant workshop at Fri3d Camp 2022. Still a work in progress…

Hardware list

  • half bread board
  • ESP32 board, for example the LOLIN32 lite
  • USB A to micro cable
  • Breadboard with 400 holes
  • male/male jumper wires
  • a reed switch

Hookup

Position the LOLIN32 LITE board on the breadboard and connect the reed switch between GPIO 32 and GND

Software setup

Browser

Open Chromium, Google Chrome of Microsoft Ege.

Ga naar web.esphome.io en volg de instructies op de pagina:

  1. Steek de USB kabel in jouw PC en het ESP32 bordje
  2. Klik op CONNECT
  3. Selecteer de juiste seriële poort. Op Linux is dat meestal USB Serial (ttyUSB0)
  4. Je zou ESP Device moeten zien met status CONNECTED
  5. Klik op PREPARE FOR INSTALLATION
  6. Klik op MAKE ADOPTABLE
  7. Het installeren duurt ongeveer 2 minuten. Als het niet lukt kan het helpen om op het ESP bordje eens op het RST (reset) knopje te drukken

Woohoo, het ESP bordje heeft nu een basisversie van ESPHome. Om de configuratie verder te zetten kunnen we dat via WiFi doen.

Voor je de kabel uittrekt kan je eens de logs checken. Klik op LOGS en dan op het RESET DEVICE. Voorbeeld van logs:

[I][logger:214]: Log initialized
[C][ota:461]: There have been 2 suspected unsuccessful boot attempts.
[D][esp32.preferences:114]: Saving preferences to flash...
[I][app:029]: Running through setup()...
[C][esp32_ble:026]: Setting up BLE...
[D][esp32_ble:040]: BLE setup complete
[D][esp32_ble_server:033]: Setting up BLE Server...
[D][esp32_ble_server:070]: BLE server setup successfully
[C][wifi:037]: Setting up WiFi...
[C][wifi:201]: Setting up AP...
[C][wifi:203]:   AP SSID: 'esphome-web-19448c'
[C][wifi:204]:   AP Password: ''
[C][wifi:213]:   IP Address: 192.168.4.1
[D][esp32_improv.component:200]: Setting Improv to start
[C][web_server:095]: Setting up web server...
[C][ota:085]: Over-The-Air Updates:
[C][ota:086]:   Address: esphome-web.local:3232
[W][ota:095]: Last Boot was an unhandled reset, will proceed to safe mode in 8 restarts
[C][api:025]: Setting up Home Assistant API server...
[D][wifi:373]: Starting scan...
[I][app:062]: setup() finished successfully!
[I][app:102]: ESPHome version 2022.3.0 compiled on Mar 24 2022, 01:01:34
[I][app:104]: Project esphome.web version 1.0
[C][logger:233]: Logger:
[C][logger:234]:   Level: DEBUG
[C][logger:235]:   Log Baud Rate: 115200
[C][logger:236]:   Hardware UART: UART0
[C][esp32_ble:206]: ESP32 BLE:
[C][esp32_ble_server:160]: ESP32 BLE Server:
[C][esp32_improv.component:214]: ESP32 Improv:
[C][esp32_improv.component:216]:   Status Indicator: 'NO'
[C][captive_portal:088]: Captive Portal:
[C][wifi:491]: WiFi:
[C][wifi:353]:   Local MAC: 78:E3:6D:19:44:8C
[C][wifi:354]:   SSID: [redacted]
[C][wifi:355]:   IP Address: 0.0.0.0
[C][wifi:357]:   BSSID: [redacted]
[C][wifi:358]:   Hostname: 'esphome-web-19448c'
[C][wifi:360]:   Signal strength: 0 dB ▂▄▆█
[C][wifi:364]:   Channel: 1
[C][wifi:365]:   Subnet: 0.0.0.0
[C][wifi:366]:   Gateway: 0.0.0.0
[C][wifi:367]:   DNS1: 0.0.0.0
[C][wifi:368]:   DNS2: 0.0.0.0
[C][web_server:207]: Web Server:
[C][web_server:208]:   Address: esphome-web.local:80
[C][mdns:084]: mDNS:
[C][mdns:085]:   Hostname: esphome-web-19448c
[C][ota:085]: Over-The-Air Updates:
[C][ota:086]:   Address: esphome-web.local:3232
[W][ota:095]: Last Boot was an unhandled reset, will proceed to safe mode in 8 restarts
[D][esp32_improv.component:076]: Service started!
[C][api:138]: API Server:
[C][api:139]:   Address: esphome-web.local:6053
[C][api:143]:   Using noise encryption: NO
[C][improv_serial:032]: Improv Serial:

Het bordje zendt een uniek WiFi netwerk uit esphome-web-xxxxxx.

Prepare your device for adoption
This will install a basic version of ESPHome to your device and help you connect it to your network.

Command line

Ik kreeg de CLI installatie van esphome niet werkend met pip3/python op Debian 11.

Follow Installing ESPHome Manually for installing the ESPHome software using the pip3 command of python. The instructions are almost identical on Linux, Mac or Windows.

  1. Open a command window or terminal.
  2. Make sure you are running a recent version of Python 3:

    $ python3 --version
    Python 3.7.1
  3. Install ESPHome:

    $ sudo apt install rustc
    $ python3 -m venv esphome
    source esphome/bin/activate
    pip3 install setuptools_rust # was nodig op Debian 11
    pip3 install --user esphome
  4. confirm that ESPHome has been successfully installed:

    $ esphome version
    Version: 2021.12.3

Getting Started

see Getting Started with the ESPHome Command Line

Home Assistant

We will continue configuring the ESPHome device from within Home Assistant. Home Assistant is not a requirement as you can run ESPHome as a stand alone device, but then you will need to instal the ESPHome software on your PC.

The workshop is running Home Asisstant on a Raspberry Pi 3B+.

Things after basic setup of Home Assistant:

  1. Change hostname for this workshop: Settings> Systeem > Network > Hostname: ha-esp-fri3d
  2. Enable SSH: Settings > Add-ons > ADD-ON STORE> Terminal & SSH > INSTALL

Install the ESPHome Dashboard for Home Assistant:

  1. Settings > Add-ons > ADD-ON STORE
  2. Search for esp and Click on ESPHome > INSTALL
  3. This could take some time. Check the Log tab:

    [services.d] starting services 
    [services.d] done.
    [17:03:17] INFO: Waiting for dashboard to come up...
    [17:03:19] INFO: Starting ESPHome dashboard...
    2022-08-06 17:03:23,694 INFO Starting dashboard web server on unix socket /var/run/esphome.sock and configuration dir /config/esphome...
    [17:03:23] INFO: Starting NGINX...
  4. For Easy access to the ESPHome Web UI, check Show in sidebar
  5. When you click ESPHome in the sidebar you should see “Welcome to ESPHome. It looks like you don’t yet have any devices”.

We will do the first connection and initialization of the ESP board:

  1. On the ESPHome Dashboard, click NEW DEVICE and OPEN ESPHOME WEB
  2. Click CONNECT
  3. Select the serial port. On Linux this could be USB Serial (ttyUSB0) and click Connect
  4. You should see ESP Device with status CONNECTED
  5. Click PREPARE FOR ADOPTION
  6. Click MAKE ADOPTABLE
  7. If the connection does not work, try pressing the RST button on the ESP board shortly after clicking Retry
  8. When you get Confituration installed, click Close
  9. You will see a device ID like esphome-web-5df3c4, this is the WiFi network the ESP device is now transmitting.
  10. Click CONNECT TO WI-FI to configure the ESP device to connect to the Fri3d Camp WiFi network
  11. Select the Network, enter the password and CONNECT
  12. When you get Provisioned, You can click CLOSE.

An alternative way to configure the WiFi settings of the ESP device:

(instructions go here)

Your newly configured ESP board shoud be visible in the ESPHome dashboard of Home Assistant with status DISCOVERED.

  1. Click ADOPT to add the device.
  2. Again, you will need to enter the WiFi network and Password and click ADOPT
  3. You could give the device a new name then click INSTALL.
  4. We get a terminal like window that shows esphome installing on the ESP device. The first time ESPHome will download the necessary toolchain. This will also happen when there are new versions.
  5. You can click STOP when the installation has completed

Example of a succesfull upload:

INFO Successfully compiled program.
INFO Resolving IP address of esphome-web-5df3c4.local
INFO  -> 192.168.1.5
INFO Uploading /data/esphome-web-5df3c4/.pioenvs/esphome-web-5df3c4/firmware.bin (889088 bytes)
Uploading: [============================================================] 100% Done...

INFO Waiting for result...
INFO OTA successful
INFO Successfully uploaded program.
INFO Starting log output from esphome-web-5df3c4.local using esphome API
INFO Successfully connected to esphome-web-5df3c4.local
[15:01:30][I][app:102]: ESPHome version 2022.6.2 compiled on Aug  7 2022, 14:58:08
[15:01:30][C][wifi:491]: WiFi:
[15:01:30][C][wifi:353]:   Local MAC: 10:52:1C:5D:F3:C4
[15:01:30][C][wifi:354]:   SSID: [redacted]
[15:01:30][C][wifi:355]:   IP Address: 192.168.1.5
[15:01:30][C][wifi:357]:   BSSID: [redacted]
[15:01:30][C][wifi:358]:   Hostname: 'esphome-web-5df3c4'
[15:01:30][C][wifi:360]:   Signal strength: -85 dB ▂▄▆█
[15:01:30][C][wifi:364]:   Channel: 11
[15:01:30][C][wifi:365]:   Subnet: 255.255.255.0
[15:01:30][C][wifi:366]:   Gateway: 192.168.1.254
[15:01:30][C][wifi:367]:   DNS1: 192.168.1.254
[15:01:30][C][wifi:368]:   DNS2: 0.0.0.0
[15:01:30][C][logger:275]: Logger:
[15:01:30][C][logger:276]:   Level: DEBUG
[15:01:30][C][logger:277]:   Log Baud Rate: 115200
[15:01:30][C][logger:278]:   Hardware UART: UART0
[15:01:30][C][captive_portal:088]: Captive Portal:
[15:01:30][C][mdns:084]: mDNS:
[15:01:30][C][mdns:085]:   Hostname: esphome-web-5df3c4
[15:01:30][C][ota:085]: Over-The-Air Updates:
[15:01:30][C][ota:086]:   Address: esphome-web-5df3c4.local:3232
[15:01:30][C][api:138]: API Server:
[15:01:30][C][api:139]:   Address: esphome-web-5df3c4.local:6053
[15:01:30][C][api:143]:   Using noise encryption: NO

When the initial installation is complete you should see your ESP board with status ONLINE in the ESPHome dashboard.

Hello World!

To change the configuration just click EDIT on the appropriate device in the ESPHome dashboard.

After the initial installation of our ESP board, ESPHome has already provided a basic configuration:

esphome:
  name: esphome-web-5df3c4

esp32:
  board: esp32dev
  framework:
    type: arduino

# Enable logging
logger:

# Enable Home Assistant API
api:

ota:


wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Esphome-Web-5Df3C4"
    password: "NOwVoHqNA8CI"

captive_portal:
    

The ap and captive_portal option make sure the ESP board wil act as a WiFi access point if it can not connect to the configured WiFi (e.g. because a bad password). This is a log of this situation:

[W][wifi:442]: No matching network found!
[W][wifi:572]: Restarting WiFi adapter...
[I][wifi:136]: Starting fallback AP!
[C][wifi:201]: Setting up AP...
[C][wifi:203]:   AP SSID: 'Esphome-Web-5Df3C4'
[C][wifi:204]:   AP Password: 'NOwVoHqNA8CI'
[C][wifi:213]:   IP Address: 192.168.4.1

We will add the configuration for a magnetic reed switch by adding this “code” to the bottom of the file:

light:
  - platform: binary
    name: "LED-5df3c4"
    output: light_22
    id: LED

output:
  - id: light_22
    platform: gpio
    pin: GPIO22 # this is the built in LED next to 22 on the LOLIN32 lite board
    inverted: true # the LED turns on when the output goes LOW

binary_sensor:
  - platform: gpio
    pin:
      number: 32
      mode:
        input: true
        pullup: true
    filters:
      - invert:
    name: "magnet-5df3c4"
    on_press:
      then:
        - light.turn_on: LED
    on_release:
      then:
        - light.turn_off: LED

While we are busy, we can also change the basic configuration by specifying the board model we are using:

esp32:
  board: lolin32_lite

Some YAML explanation? Not a programming language but a data/markup language. Indentation is important!

Click INSTALL and Wirelessly to update your board. Updating wirelessly means that the device no longer needs to be tethered to the computer, you can power it with a USB power brick/charger, power bank or solar panel.

Note that building the code and uploading takes about 5 minutes, that is a bit slow. This is partially because we are using a Raspberry Pi 3. On a Pi 4 this should run faster. Another alternative is running Home Assistant on a virtual server.

Note that the editor is “smart”, when we try to configure pin 35 it complains by marking the line with a red cross. When you hover over it, we get the explanation: GPIO35 (34-39) does not support pullups.

After uploading the code we can see the state of the inputs change when we move a magnet close to the reed switch.

An Example of measuring Gas and Water usage by sensing the magnetic pulses generated by the counter in the utility meter:

  - platform: pulse_counter
    pin: 26
    name: "Gas"
    id: gas_l
    unit_of_measurement: 'L/min'
    filters:
      - multiply: 10 #1 pulse per 0,01m³
    update_interval: 1200s
    accuracy_decimals: 1
    icon: mdi:counter
    device
  - platform: pulse_counter
    pin: 25
    name: "Water"
    unit_of_measurement: 'L/min'
    filters:
      - multiply: 0.5 #2 pulses per litre = 2000 pulses per m³
    update_interval: 300s
    accuracy_decimals: 1
    icon: mdi:water

Configuring the ESP is all good, but how do we get sensors and stuff into Home Assistant. For this we need the ESPHome Integration.

So think of the ESPHome Dashboard as the “configuration manager” for your ESPHome boards and the ESPHome Integration as the “link” for the ESPHome boards to Home Assistant.

To install the integration:

  1. You should see a new notification in Home Assistant: “We have discovered new devices on your network.”
  2. Click on Check it out
  3. This should take you to the Integrations page and should show an “discovered” device.
  4. Click on CONFIGURE and SUBMIT
  5. You can optionally assign the device to an area. This can be useful.

Checking the device you should see 2 entities: LED and Magnetic reed switch. These entities are also automatically added to the “Overview” in Home Assistant.

Leave a Reply

Your email address will not be published. Required fields are marked *