ESPHome is a system to configure ESP8266 / ESP32 devices through simple but powerful configuration files and to control the devices through Home Assistant. These include SONOFF switch devices, SONOFF smart plugs, Espurna driven ESP8266 devices, etc
Install ESPHome Add-on
- Install ESPHome
- Go to Settings -> Add-ons, click Add-on Store
- Search for ESPHome, select and click Install
- Tick Show in sidebar
- Press Start
Install ESPHome on Sonoff Basic
- Example DIY light switch Cookbook
- Initially need to connect ESP device via USB-to-TTL adapter to computer, thereafter can update OTA (over-the-air)
- Pins from top: 3V3, RX, TX, GND, GPIO14
- In ESPHome select New Device -> Continue
- Add name e.g. kitchen-leds
- Select ESP8266, press Next, then Skip
- Back at ESPHome, referring to the specific device box, edit device YAML file to get configuration required (can always update config OTA later if required). Note have used packages to split up files with device specific elements in the
device.yamlfile, and common elements in thecommon/esp_base.yamlfile, as shown here. Can add as many sensor elements as required to monitor the stats of the device
1 2 3 4 5 6 7 8 9 10 11 12 13
# # Switch on/off LED driver for Kitchen LEDs # SONOFF BASIC # # define device specifics here substitutions: devicename: kitchen-leds devicename_underscore: kitchen_leds # call-up common elements here packages: device_base: !include common/esp_base.yaml
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
# # ESP_BASE.YAML: Common device attributes defined here # SONOFF BASIC # esphome: name: ${devicename} platform: ESP8266 board: esp8285 logger: # Home Assistant API api: encryption: key: !secret api_encryption_key reboot_timeout: 1h ota: password: !secret ota_password binary_sensor: - platform: gpio name: "${devicename_underscore}_button" pin: number: GPIO0 mode: INPUT_PULLUP inverted: true on_press: - switch.toggle: fakebutton - platform: status name: "${devicename_underscore}_status" switch: - platform: template name: "${devicename_underscore}_relay" id: fakebutton optimistic: true turn_on_action: - switch.turn_on: relay turn_off_action: - switch.turn_off: relay - platform: gpio id: relay pin: GPIO12 status_led: pin: number: GPIO13 inverted: true sensor: - platform: wifi_signal name: "${devicename_underscore}_signal" update_interval: 60s - platform: uptime name: "${devicename_underscore}_uptime" text_sensor: - platform: version name: "${devicename_underscore}_version" - platform: wifi_info ip_address: name: "${devicename_underscore}_ip" wifi: ssid: !secret wifi_ssid password: !secret wifi_password # Enable fallback hotspot (captive portal) in case wifi connection fails ap: ssid: "${devicename} AP" password: !secret wifi_ap_password
- Then click 3 dots -> Install -> Manual download -> Modern format
- Compiles & downloads BIN file
- Using Google Chrome, goto WebUI: https://web.esphome.io/?dashboard_wizard
- Hold button down whilst plugging ESP into USB to put in programming mode
- Click on Connect
- Select Prepare for first use to install basic firmware as starting point
- Click Install, select BIN file in downloads folder, click Install
- Disconnect USB and reapply to boot fresh
- In Home Assistant, go to Settings -> Devices & Services. New device should be discovered so Configure it for use. Need to add API encryption key from yaml
File Structure
- Within the config folder on Home Assistant, the esphome folder is configured as follows (for this installation):
- esphome
- common
- esp_base.yaml : as above, code common to all devices
- secrets.yaml : refers to main secrets.yaml in config root
<<: !include ../../secrets.yaml
- dining-leds.yaml : device specific code, as above
- pergola-lights.yaml
- etc for other devices
- common
- esphome
- The
secrets.yamlfiles allow passwords , etc to be “centralised” and referenced within files. If upload config to GitHub say can just skip this file and all passwords are kept “secret”!