ESPHome.

ESPHome fundamentals.

ESPHome is a firmware compilation and management platform. The grower writes a YAML configuration describing what a microcontroller should do; ESPHome compiles that YAML into firmware that runs on the microcontroller; the compiled firmware integrates with Home Assistant.

The YAML describes everything.

Unlike traditional embedded development that requires C or C++ programming, ESPHome's YAML configuration is declarative. The grower says what sensors and actuators the device has, which pins they connect to, how often to report, and ESPHome figures out the implementation. For most agricultural use cases, the grower never writes a line of code. A complete node, an ESP32 reading a BME280 temperature/humidity/pressure sensor over I2C:

esphome:
  name: greenhouse-zone-1
  friendly_name: Greenhouse Zone 1

esp32:
  board: esp32dev
  framework:
    type: arduino

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

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome
    password: !secret ota_password

logger:

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: bme280_i2c
    address: 0x76
    update_interval: 60s
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    pressure:
      name: "Pressure"

Flash this once over USB and every later change goes over the air. The three named sensors appear in Home Assistant automatically through the native API, no MQTT topic to wire up. The one detail that shifts between ESPHome releases is component names: this uses the current bme280_i2c platform (renamed from bme280 in the 2024.6 release) and the list form of ota:, so check the component reference for the version you flash.

The ESP32 and ESP8266 microcontrollers.

ESPHome primarily targets two microcontroller families:

• ESP32. More capable, more memory, more I/O, has Bluetooth. Current standard for new projects. Dev boards from $5-15.
• ESP8266. Older, less capable, no Bluetooth, single-core. Still widely supported but ESP32 is usually preferable for new projects.

Various board form factors exist: bare modules, dev boards with USB, purpose-built products. Bare modules are cheaper but require more setup; dev boards are the typical starting point.

The Wi-Fi requirement (mostly).

ESPHome devices typically connect to Home Assistant over Wi-Fi. Ethernet-capable boards (some ESP32 boards, specific ESP32-S3 and ESP32-C6 models) exist for deployments where Wi-Fi is unsuitable. For most greenhouse and indoor deployments, Wi-Fi works.

The Home Assistant native API.

ESPHome devices communicate with Home Assistant through a proprietary ESPHome protocol that's faster and more efficient than MQTT. Home Assistant's ESPHome integration handles this automatically. MQTT is also supported as an alternative for deployments where MQTT is preferred.

The programming model.

ESPHome's YAML exposes components (sensors, switches, outputs, displays, etc.). Each component has its pin assignments, reporting intervals, and options. Automations within ESPHome (on-change triggers, value filters, derived sensors) handle device-level logic. Device-level automations stay on the device, reducing load on Home Assistant.

The device-building workflow.

Building an ESPHome device follows a repeatable pattern.

1. Pick the microcontroller.

For most projects: an ESP32 dev board with plenty of I/O, onboard USB, and breadboard-friendly pin headers. The common "ESP32 DevKit V1" and similar are widely available and well-documented.

2. Pick the sensors and actuators.

Based on what the device needs to do. For a multi-sensor node: temperature/humidity chip (DHT22, SHT31, AHT20, or similar), possibly a light sensor (BH1750), possibly CO2 sensor (SCD40 or SCD41), maybe a PAR sensor through appropriate signal conditioning. For a relay controller: relay module with appropriate voltage and current ratings. For a BLE proxy: just the ESP32 (its BLE radio is all that's needed).

3. Wire it.

Most sensor chips connect via I2C (two-wire) or SPI (four-wire) buses. Multiple sensors can share an I2C bus. Relay modules connect to GPIO pins with appropriate drive capability. ESP32 boards have plenty of usable GPIO.

4. Write the YAML.

The ESPHome configuration describes what's connected. A simple example:

5. Compile and flash.

ESPHome compiles the YAML into firmware. The first flash requires a USB cable connection. The device receives the firmware over serial. After the first flash, subsequent updates happen over Wi-Fi (OTA, over-the-air).

6. Deploy.

Power the device from a USB wall adapter (for sensors and light loads) or appropriate mains-connected power supply (for relays controlling mains-powered loads). Place the device in its operational location.

7. Home Assistant integration.

Home Assistant auto-discovers ESPHome devices on the local network. Add the integration through Settings → Devices & Services. Enter the device's encryption key (ESPHome creates one during compilation). Device appears with its entities.

8. Name, area-assign, and verify.

Per the organization conventions. Make the device's entities match the established naming pattern.

Common agricultural ESPHome patterns.

Patterns that come up repeatedly in agricultural deployments.

The multi-sensor node.

One ESP32 with temperature/humidity, light, and CO2 sensors in a small enclosure. Placed in a greenhouse zone. Reports all values over Wi-Fi to Home Assistant. The whole node runs a modest amount in parts, enclosure included, and replaces three or four separate commercial sensors at lower cost and with better data consistency.

The specific sensor choice matters:

• Temperature and humidity. SHT31 is accurate; SHT4x newer with comparable accuracy; AHT20 cheaper but less accurate; DHT22 older and less reliable. SHT31 is the typical recommendation.
• Light. BH1750 for simple lux-equivalent readings; specific PAR sensors for agricultural-grade light measurement (more expensive and more complex).
• CO2. SCD40 or SCD41 are photoacoustic and accurate. Cheaper options exist but produce less reliable readings.

The relay controller.

ESP32 with 2-8 relays in an enclosure. Controls pumps, valves, fans, heaters. Subscribes to commands from Home Assistant; reports current state back. Provides Home Assistant with remote control over mains-powered equipment.

Relay sizing: match relay current rating to the load. For most sensor-scale loads (small fans, small pumps), 10A relays are adequate. For larger loads (larger pumps, heaters), 30A relays or contactors are appropriate. Never use a relay rated at the exact load current. Margin matters.

Safety considerations: mains-connected ESP32 devices need proper enclosures (electrical code compliance, appropriate fuses, grounding). ESPHome devices are low-voltage microcontrollers; when they control mains equipment, the control side and mains side need proper isolation.

The BLE proxy.

ESP32 with ESPHome's Bluetooth proxy component. No external sensors; just the ESP32 itself. Extends BLE coverage to whatever location the proxy is placed. Mentioned in Bluetooth Low Energy; the ESPHome configuration is a few lines.

The soil moisture monitor.

ESP32 with capacitive or resistive soil moisture sensors. Low-power variant (deep-sleep most of the time, wake briefly to report) for battery-powered operation. More accurate and reliable than the very cheap consumer soil moisture devices.

The flow meter integration.

ESP32 connected to a water flow meter (hall-effect pulse output). Counts pulses, converts to flow rate, reports to Home Assistant. Useful for irrigation flow monitoring, fertigation flow verification, leak detection through flow anomalies.

The display panel.

ESP32 with a small LCD or e-ink display. Shows current zone conditions at a glance, mounted near the zone for walk-up status checks. Receives data from Home Assistant; displays summary status. Useful in operations where workers should see current status without checking phones.

The custom sensor adapter.

Commercial sensors that don't have Home Assistant integration but do expose their data over serial, I2C, SPI, or analog can be adapted through ESPHome. The ESP32 reads the commercial sensor's data; ESPHome exposes it as Home Assistant entities.

The irrigation controller.

ESP32 with multiple relays for irrigation valves, possibly with flow meters and pressure sensors. Becomes the operation's irrigation controller: receives schedule and commands from Home Assistant, controls valves, reports back. More flexible than commercial irrigation controllers for operations with custom needs.

OTA updates.

Once deployed, ESPHome devices update over Wi-Fi. The grower edits the YAML configuration on the Home Assistant host (or wherever ESPHome is hosted), clicks compile and upload, and the device updates without physical access.

Update safety.

ESPHome has some built-in update safety:

• The device boots new firmware; if it fails (can't connect to Wi-Fi, crashes repeatedly), it falls back to the previous firmware.
• The OTA transfer is atomic: either the new firmware is complete and takes over, or the old firmware remains active.

Update failure modes.

Updates can still go wrong:

• A YAML configuration bug that causes repeated reboots.
• A Wi-Fi configuration change that works at the ESPHome host but fails at the device's physical location.
• A hardware-specific issue where new firmware triggers something the old firmware didn't.

For critical devices, testing updates on a non-production copy first reduces risk. For all devices, physical access for serial-cable recovery remains the fallback when OTA fails.

Update discipline.

A fleet of ESPHome devices needs update management. Updating all devices simultaneously is risky; updating one at a time allows monitoring for issues. ESPHome's interface shows which devices have pending updates; a grower can apply them deliberately rather than all at once.

ESPHome failure modes.

Specific problems that affect ESPHome deployments.

The Wi-Fi that dropped. ESPHome device lost Wi-Fi connection and didn't reconnect cleanly. Reports stopped arriving at Home Assistant. Fix: ESPHome has reconnection logic; check Wi-Fi coverage at the device location; consider wired Ethernet on boards that support it.

The sensor that read wrong through an I2C wiring error. Sensor was wired with SDA/SCL swapped, or without pull-up resistors. Readings were nonsense or the sensor didn't respond. Fix: verify wiring against documentation, include I2C pull-ups when needed (many ESP32 dev boards have them built in; bare modules may not).

The enclosure that overheated. ESP32 in a small plastic enclosure in a warm greenhouse ran hotter than its spec. Eventually failed intermittently. Fix: ventilation in enclosure, avoid direct sun on enclosure, consider active cooling for very warm environments.

The power supply that wasn't stable. Cheap USB wall adapters can provide marginal or noisy power. ESP32 reboots or misbehaves. Fix: quality USB power supplies, or mains-to-5V power supplies with clean output.

The YAML update that broke everything. A YAML change compiled successfully but the new firmware had a runtime issue. Device rebooted repeatedly. Fix: test configuration changes on a non-production device before applying to the fleet; keep working YAML as a rollback point.

The OTA that didn't complete. Update started but failed before finishing. Device rebooted into the old firmware (the OTA safety caught it). Fix: retry OTA; investigate if specific devices fail consistently (Wi-Fi issues, hardware problems).

The device that stopped reporting without disconnecting. Device showed as online but sensor values hadn't updated in hours. Investigation: sensor chip failure, not the ESP32 itself. Fix: ESPHome-level availability based on recent updates rather than just connection status; hardware diagnostics.

The relay that welded closed. A relay's contacts welded under an overload event. ESPHome commanded it off; the physical contacts stayed closed. Load continued running. Fix: appropriate relay sizing with margin, fuses in the mains-side circuit, power monitoring to verify commanded state.

The fleet-wide update that broke many devices. A shared configuration change affected all similar devices; the change had a bug. All devices in the group became unreliable at once. Fix: stage updates. Apply to one device, verify, then expand to the fleet.

The Wi-Fi bandwidth that got consumed. A large fleet of ESPHome devices reporting frequently saturated the Wi-Fi access point's capacity. Symptom: intermittent device drops, especially during high-traffic periods. Fix: reporting interval tuning, Wi-Fi capacity planning (enterprise AP, multiple APs for coverage and load distribution).

What not to do.

Don't use marginal Wi-Fi coverage. ESPHome depends on Wi-Fi. Weak signal produces intermittent devices. Strong signal or Ethernet is worth the effort.

Don't skimp on power supplies. Cheap USB adapters cause hard-to-diagnose intermittent problems. A good quality 5V/2A or 5V/3A supply per device is worth the small extra cost.

Don't deploy without proper enclosures for mains applications. Electrical safety matters. An ESP32 controlling mains equipment needs a proper enclosure with appropriate compliance.

Don't update the whole fleet simultaneously. Stage updates. A bad configuration affecting many devices at once is a bigger problem than affecting one.

Don't skip version control on ESPHome configurations. Git or similar saves the working state. When an update breaks things, reverting to the previous working configuration is much easier with version history.

Don't forget physical device access. When OTA fails, physical access (USB cable to computer) is the recovery path. Devices in sealed enclosures in hard-to-reach locations become painful if they fail.

Don't ignore the hardware safety layer. An ESPHome relay controlling a heater doesn't replace the heater's thermal cutoff. ESPHome improves operation; hardware safety handles catastrophic cases.

Don't over-engineer devices that don't need it. A single-sensor temperature node doesn't need six features and four communications paths. Simple devices that do one thing reliably beat complex devices that do many things with multiple failure modes.