Your First ESPHome Device: an ESP32 Visible in Home Assistant

This is genuinely the lesson this module has been building toward, your ESP32 connects by USB for the very first time, gets a minimal configuration, and finally appears in Home Assistant as a real, working device.

Checklist before you start

Confirm you genuinely have your ESP32 board, a genuine data-capable USB cable, the ESPHome add-on installed and running from Lesson 3, and your WiFi network name and password ready to type. Use Chrome or Edge for this lesson specifically, since USB flashing relies on the WebSerial standard those two browsers support well.

Step by step: tiles in ESPHome / Device Builder

Open the ESPHome dashboard from your sidebar, click New Device, and step through the wizard, name, device type, WiFi credentials, each shown as its own tile. This wizard-driven flow will feel familiar if you recall Module 9's ZHA setup wizard, a series of small, focused steps rather than one long form.

New device: esp32-office-test

Name this device "esp32-office-test", or substitute your own room, following the lowercase-hyphenated naming pattern Module 9 established for Zigbee devices. Select ESP32 as the board type when prompted, then enter your WiFi credentials, the wizard stores them securely in a shared secrets file rather than inside this device's own configuration.

Minimal YAML: six sections

The generated file contains six foundational sections, esphome (device name and platform), esp32 (chip variant), wifi (network credentials), api (Home Assistant connection), ota (over-the-air update support), and logger (diagnostic output). No sensors yet, this minimal file's entire purpose is proving the board itself connects and reports in, Lesson 5 dissects each section in far more depth.

Which installation method to choose

ESPHome offers a Plug into this computer option, USB flashing, and a Wirelessly option, OTA. Since this device has never run ESPHome firmware before, OTA isn't available yet, choose the USB option, plug your board in now if you haven't already, and select the correct serial port when your browser prompts you.

Compiling and uploading via USB

Clicking Install triggers compilation first, watch the log scroll, then a brief pause, then the actual upload over USB, shown as a progress percentage. The whole process typically takes two to four minutes on a first attempt, resist unplugging the board or closing the tab during this window, interrupting an upload partway through can leave a board in a confusing, though recoverable, state.

When to wait, and when to act

A scrolling log with occasional pauses is entirely normal, compilation genuinely takes time. A log that stops scrolling entirely for several minutes with no progress, or that shows a clear red error message, is your signal to stop and read carefully rather than waiting indefinitely, most stalls resolve with a simple retry.

Integration with Home Assistant

Once the upload finishes and your board restarts, Home Assistant should discover it automatically within about a minute, showing a new device notification you can confirm with a single click. Your ESP32 now appears in your device list, alongside your Zigbee coordinator and paired devices from Module 9, with no entities yet since this minimal configuration doesn't define any sensors.

Logs: your first diagnostic tool

Click Logs from your device's tile in the ESPHome dashboard to see a live stream of what the board is doing, connecting to WiFi, connecting to the API, and any errors along the way. This log view becomes your primary troubleshooting tool for every device this module builds, worth genuinely getting comfortable reading it today while the stakes are low.

Troubleshooting the first flash: minimum rescue steps

If the board isn't detected at all, try a different USB cable first, that's the most common cause by far. If compilation fails, read the error's first line carefully, it usually names the exact problem. If the upload starts but never finishes, unplug the board, wait ten seconds, plug it back in, and retry, a fresh connection resolves the majority of stalled uploads.

When compilation fails

A compile failure at this minimal stage is uncommon, since the wizard-generated file is already valid, but if it happens, check for an accidental edit you may have made to the YAML before clicking Install. Reverting to the wizard's original, unedited file and retrying resolves this in nearly every case.

WiFi passwords: secrets.yaml, the minimum for today

The wizard automatically created a secrets.yaml file storing your WiFi credentials, referenced by every device configuration rather than repeated in each one. Today, simply know this file exists and that it's the reason you only typed your WiFi password once, Lesson 5 explains its full role in ESPHome's security model.

First flash and Zigbee: the same discipline

Just as Module 9 asked you to pair one Zigbee device carefully before adding a second, flash exactly one ESP32 today and confirm it works fully before creating a second device. Rushing to flash several boards at once, before understanding what a successful first flash looks like, tends to multiply confusion rather than save time.

Restart test: optional, if everything works

If your device shows online in Home Assistant, unplugging it briefly and plugging it back in confirms it reconnects automatically without needing to be reflashed, a reassuring, optional check worth doing once before moving on.

IP address: write it down today

Your device's IP address, visible on its ESPHome dashboard tile, is worth noting in your smart home notebook today. You'll reference it occasionally for direct troubleshooting later in this module, and having it recorded from day one avoids a small search through your router's device list months from now.

What you record in your ESPHome notebook

Record the device's name, its IP address, today's date, and one sentence noting it flashed successfully with no sensors attached yet. This entry becomes the first row of a table you'll extend with every device this module adds.

Common questions with a first device

Readers often ask why their device shows online but has no entities, that's expected, this minimal configuration defines no sensors yet. Others ask if it's normal for the board to restart once during flashing, it is, that's the new firmware taking effect for the first time.

Exercise after this lesson

Flash your ESP32 with the minimal configuration, confirm it appears in Home Assistant, note its IP address and today's date in your notebook, and read through its live log once just to see what a healthy connection looks like.

Key takeaways

With a bare device online, Lesson 5 explains YAML's structure properly, so Lesson 6 can add a real sensor with genuine understanding rather than guesswork.

A real story: the cable that wasted an hour

A reader in this course's community spent nearly an hour convinced their brand-new ESP32 was defective, no serial port ever showed up no matter which USB port they tried. Swapping the bundled charging cable for a cable known to carry data resolved it instantly, the board had been fine the entire time, only the cable was ever at fault.

Why a minimal first device is deliberate

It would be entirely possible to add a sensor to today's configuration and flash both at once, but this course separates the two deliberately, proving the board itself connects reliably before adding a sensor's own variables, wiring, calibration, YAML syntax, into the mix. If something goes wrong later with a sensor attached, you'll already know the board and network connection are solid.

Comparing this device to your Zigbee smart plug

Your Zigbee smart plug from Module 9 paired in seconds with no configuration file at all. This ESP32 took several minutes and a written YAML file to reach the same basic milestone, appearing in Home Assistant, a genuine illustration of the tradeoff Lesson 1 described between convenience and flexibility.

What "done" looks like for this lesson

You're done with this lesson once your ESP32 shows as online in Home Assistant, its log shows a clean, repeating connection cycle, and its details are written in your notebook. Nothing more is required today, resist the temptation to start adding sensors before Lesson 5 explains how.

Co dalej: what's next

Lesson 5 opens up YAML's structure properly, section by section, so that Lesson 6's first real sensor makes complete sense rather than feeling like magic.

Understanding the serial port prompt

When your browser asks you to choose a serial port, it's listing every connected USB device your computer currently recognizes, not just your ESP32. If more than one option appears, unplug the board, note which options remain, plug it back in, and pick the option that newly appeared, a reliable way to identify the right port even on a computer with several other USB devices connected.

What a healthy log actually looks like

A healthy log shows the board booting, connecting to your WiFi network by name, receiving an IP address, and then connecting to Home Assistant's API, each step logged as a short, clear line. Once connected, the log settles into a quiet rhythm, occasional heartbeat messages rather than a constant stream, that quiet steadiness is exactly what you want to see.

If your board connects to WiFi but not to Home Assistant

Occasionally a board joins your WiFi network successfully but Home Assistant never shows the discovery notification, usually because the two are on genuinely different networks, a guest WiFi network versus your main one, for instance. Confirm your ESP32 and your Home Assistant server share the same network, this single detail resolves the vast majority of these cases.

Naming the entity that eventually appears

Today's minimal device creates no sensor entities, but it does register itself as a device in Home Assistant's device list, visible under Settings, then Devices and Services, then ESPHome. Confirm it appears there with the exact name you gave it during setup, a small verification step worth doing before moving to Lesson 5.

What "esp32-office-test" as a name actually buys you

A specific, descriptive device name pays off the moment you have two or three ESP32 devices running at once, distinguishing "esp32-office-test" from a future "esp32-greenhouse" or "esp32-garage" at a glance, rather than a string of generic default names that all look identical in a crowded dashboard.

Renaming a device after the fact

If you'd like to rename this test device once you understand the pattern better, ESPHome supports renaming, though it requires reflashing since the device's name is baked into its firmware, not just a label. For this reason, choosing a name you're reasonably happy with today, even for a "test" device, saves a small amount of rework later.

Comparing today's process to the PL module's own pacing

This lesson deliberately covers only a bare device, no sensors, mirroring the same incremental pacing every earlier module in this course has followed, one genuinely new concept at a time rather than several at once. Readers who've followed this course from Module 1 will recognize the pattern immediately.

What happens if you unplug the board mid-flash

Interrupting a flash partway through occasionally leaves a board unresponsive to further flashing attempts over USB in its current state. This is almost always recoverable, holding the board's Boot button while reconnecting it, a step covered in ESPHome's own troubleshooting documentation, forces it back into a flashable state, worth knowing exists even if you never need it today.

A second look at your device list

Take a moment to genuinely look at your full device list now, your Zigbee coordinator, your paired Zigbee devices from Module 9, and this brand-new ESP32, all peacefully coexisting in the same Home Assistant instance without any conflict whatsoever. This is a genuinely satisfying milestone to reach, two entirely different smart home technologies working smoothly together under one single roof.

A real story: the "New Device" that appeared twice

A reader in this course's community flashed their board once, then, seeing no immediate discovery notification appear, assumed it had genuinely failed and flashed it a second time from a completely fresh device entry. Home Assistant briefly showed two device entries for what was physically one board, resolved simply by deleting the duplicate and keeping the entry that matched the board's actual, final name. The lesson was patience, discovery can take a minute or two, worth waiting for before assuming something failed.

Why patience matters more here than with Zigbee

Zigbee pairing in Module 9 gave near-instant feedback, a device either paired successfully within seconds or clearly and obviously failed. ESPHome's process has more steps, compile, upload, restart, connect, discover, each taking its own small amount of time, and the cumulative wait can feel longer even though nothing is actually wrong. Recognizing this difference in advance helps you stay calm through what is, in practice, a routine several-minute process.

Confirming the board didn't overheat during flashing

An ESP32 may feel slightly warm to the touch after several minutes of compilation and flashing, this is entirely normal and not a cause for concern. Genuinely hot, uncomfortable-to-touch, or accompanied by a burning smell would be cause to stop immediately and disconnect, but ordinary mild warmth from active use is expected behavior for this class of board.

Keeping a second browser tab open for logs

A useful habit going forward, keep the ESPHome dashboard's Logs view open in a second browser tab while you work in Home Assistant's main interface in the first, letting you watch a device's live behavior while checking its entities appear correctly, without constantly switching between two entirely separate pages.

What a stable connection means for battery life, or the lack of it

Unlike Module 9's battery-powered Zigbee sensors, this ESP32 stays permanently connected to WiFi and permanently powered over USB, it doesn't sleep or conserve power the way a battery device does. That constant connection is part of why ESPHome devices report continuously and respond quickly, a genuine tradeoff against needing a permanent power source rather than running quietly on a coin cell battery for a year or more.