ESPHome Device Setup

ESPHome devices run open firmware that talks to Home Assistant directly over the local network, with no cloud account. Once a device is on Wi-Fi, Home Assistant discovers it through the ESPHome integration. What differs between products is how they get their firmware and Wi-Fi credentials.

How ESPHome Devices Join Home Assistant

Step 1: Connect the Device to Wi-Fi

Ready-made ESPHome devices ship without Wi-Fi credentials. Give them yours in one of two ways:

• Bluetooth from Home Assistant (Improv): power the device near a Home Assistant Bluetooth adapter or Bluetooth proxy. It appears under Settings > Devices & Services as Discovered with (Improv via BLE) after its name. Select Add, enter the Wi-Fi network and password, and wait for the confirmation.
• The device’s hotspot: if the device cannot join Wi-Fi within about a minute, it opens its own hotspot. Join it from a phone and open http://192.168.4.1 if the setup page does not appear, then choose the network.

ESPHome devices use 2.4 GHz Wi-Fi. On a mesh network that hides the 2.4 GHz band, type the network name by hand.

Step 2: Add the Device to Home Assistant

1. Go to Settings > Devices & Services.
2. The device appears under Discovered as ESPHome. Select Add, then Submit, and choose an area.
3. If the firmware uses an encryption key, Home Assistant asks for it. Ready-made devices usually do not; a device you flashed with your own configuration does, and the key is in that configuration.

If the device is not discovered, select Add Integration, search for ESPHome, and enter its IP address or <device-name>.local.

Optional: Take Control in the ESPHome Device Builder

The ESPHome Device Builder app can adopt a ready-made device (“Take control”) so you can edit its configuration. You do not need it to use the device in Home Assistant. Once adopted, the device’s firmware updates come from the Device Builder instead of the manufacturer’s update entity, so only adopt a device you intend to maintain yourself.

Firmware Updates

Most ready-made devices show a Firmware update entity in Home Assistant and update over the air from the manufacturer’s server. The device needs outbound HTTPS (port 443) to reach that server. On an IoT network that blocks it, updates never appear.

Allowing Home Assistant Actions

A device can only call Home Assistant actions, such as creating a notification, if you allow it. Open the device in the ESPHome integration, select Configure, and check Allow the device to perform Home Assistant actions. It is off by default, and only the ratgdo below uses it.

Apollo MSR-2 and MTR-1

Both presence sensors ship with ESPHome.

• Wi-Fi: use Improv over Bluetooth, or join the sensor’s hotspot (Apollo MSR2 Hotspot or Apollo MTR1 Hotspot). Power the sensor from a 5 V USB adapter.
• Updates: both sensors update from their Firmware entity in Home Assistant.
• Recovery: Apollo provides a browser installer for reflashing the factory firmware over USB-C.

Everything Presence One, Lite, and Pro

All three ship with ESPHome and set up through Improv over Bluetooth. The sensor appears in Home Assistant as everything-pr-xxxxxx (Improv via BLE) (or everything-presence-pro-xxxxxx for the Pro).

• Keep the default device name: the Everything Presence Zone Configurator relies on it.
• Updates: on the One and the Lite, the firmware update entity is disabled by default. Enable it in the device’s entity list to update from Home Assistant.
• Pro on Ethernet: the Pro ships on Wi-Fi. To switch it to PoE, connect the Ethernet cable first, set the Network Type configuration entity to Ethernet, select Apply Update, wait one to two minutes, then unplug the USB-C cable. Switching without a cable connected leaves the sensor unreachable until you reflash it over USB.

ratgdo32 and ratgdo32 disco

The ratgdo garage door controller needs its ESPHome firmware installed for the opener it is wired to.

1. Open the ratgdo ESPHome installer in Chrome or Edge.
2. Choose the opener’s protocol. Check the exact opener model against ratgdo’s compatibility list ; the learn button color is a first hint:
   • Security+ 2.0: round yellow learn button. The 8500W and RJ070 wall-mount openers are Security+ 2.0 too.
   • Security+ 1.0: purple, brown, orange, or red learn button, and the 8500, 8500C, RJ020, and RJO20C wall-mount openers.
   • Dry contact: openers without a supported protocol. Home Assistant can only tell open from closed with the opener’s limit switches wired in, or with the optional ratgdo encoder.
3. Choose the board (ratgdo32 or ratgdo32 disco), connect it with a USB-C data cable, not through a hub or monitor, and select Install.
4. Power the board. When its blue light flashes, give it Wi-Fi through Improv in Home Assistant, or join the ratgdo hotspot and open http://ratgdo.local.
5. Add it in Home Assistant as described above, then open and close the door once without stopping so the ratgdo learns its travel.

Allow the ratgdo to perform Home Assistant actions (see above) so it can raise a notification when it loses sync with the opener. The ratgdo firmware has no update entity: update it from the ESPHome Device Builder after adopting it, or from its web page.

Emporia Vue 3 (ESPHome Conversion)

The Vue 3 ships with Emporia’s cloud-only firmware. To run it locally, it is converted to ESPHome with the community emporia-vue-local project. This is a bench job, done before the monitor goes into the panel:

• Emporia does not support flashed units. Restoring the factory firmware is only possible from the backup described below.
• Never flash the board while it is connected to mains power. Flash it on the bench with the case open and the board powered from a 3.3 V USB-to-serial adapter, following the project’s pinout. Feeding the board 5 V destroys it.
• Back up the factory firmware first with esptool, as the project describes, so the unit can be restored.
• Panel installation is for a qualified electrician. The service conductors feeding the panel stay live even with the main breaker off. Install the current clamps following Emporia’s manual, with each arrow pointing toward the breaker, and record which circuit each clamp measures. Solar and other two-way circuits are handled in the configuration, not by turning the clamp around.

The project’s configuration enables an encryption key, so Home Assistant asks for it when you add the monitor. Its daily energy sensors feed the Home Assistant Energy dashboard.

Troubleshooting

1. The device is not discovered. Discovery relies on mDNS, which does not cross VLANs on its own. Add the device by IP address, or relay mDNS between the networks.
2. The device does not join Wi-Fi. Check that it is offered a 2.4 GHz network, and type the network name by hand on a mesh network.
3. Home Assistant asks for an encryption key you do not have. The device runs a configuration with encryption enabled: find the key in that configuration, or reflash the manufacturer’s firmware.
4. Firmware updates never appear. Allow outbound HTTPS from the device, and check that the update entity is enabled.