Beginner's Guide to Adding Devices

[trip5]

Description: Guide added (with link on main page)

• Beginner’s Guide to Adding Devices

They are step-by-step guides with waaay too many pictures that should help people get their feet wet in ESPHome.

I think there are more than a few people out there who would love to get into ESPHome but the documentation is a bit dense.

Related issue (if applicable): None.

Pull request in esphome with YAML changes (if applicable): N/A

Checklist:

• [ ] I am merging into next because this is new documentation that has a matching pull-request in esphome as linked above.
  or

• [X] I am merging into current because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.

• [X] Link added in /index.rst when creating new documents for new components or cookbook. Actually, I changed the link to "Getting Started with the ESPHome Command Line" to the new "Beginner’s Guide to Adding Devices" which contains links to the various methods of getting ESPHome running (just in case).

[netlify[bot]]

✅ Deploy Preview for esphome ready!

Name	Link
🔨 Latest commit	0064d01ebb91e1d60e1a9679abe9849a59c36c44
🔍 Latest deploy log	https://app.netlify.com/projects/esphome/deploys/688ba8ca2a4a990008a076be
😎 Deploy Preview	https://deploy-preview-4411--esphome.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai[bot]]

Walkthrough

A comprehensive beginner's guide for adding devices to ESPHome was introduced. References and links to this new guide were added in the main index, the Home Assistant getting started guide, and the physical device connection guide, enhancing navigation for new users seeking step-by-step instructions.

Changes

File(s)	Change Summary
Beginner's Guide guides/beginners_guide_adding_devices.rst	Added a detailed beginner's guide for adding devices to ESPHome, covering setup, YAML configuration, secrets management, device creation, component configuration, validation, compilation, and flashing steps.
Index and Navigation Updates index.rst, guides/getting_started_hassio.rst, guides/physical_device_connection.rst	Added new references and links to the beginner's guide in the Getting Started section, "Where To Go Next" section, and "See Also" section respectively to improve discoverability for new users.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant ESPHomeDocs
    participant ESPHomeDashboard
    participant Device

    User->>ESPHomeDocs: Access beginners_guide_adding_devices
    User->>ESPHomeDashboard: Open dashboard, start device addition
    ESPHomeDashboard->>User: Guide through device creation steps
    User->>ESPHomeDashboard: Configure YAML (with secrets, substitutions, etc.)
    ESPHomeDashboard->>User: Validate YAML, compile firmware
    User->>Device: Flash firmware (via ESPHomeDashboard or other method)
    Device-->>User: Device operational, ready for integration

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Suggested reviewers

• jesserockz
• kbx81

[!NOTE]

⚡️ Unit Test Generation is now available in beta!

Learn more here, or try it out under "Finishing Touches" below.

---

📜 Recent review details

Configuration used: CodeRabbit UI Review profile: CHILL Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 04ea0e24c2c2eacd3b562d13b51cd5ba22ca0532 and 0064d01ebb91e1d60e1a9679abe9849a59c36c44.

📒 Files selected for processing (2)

• guides/getting_started_hassio.rst (1 hunks)
• index.rst (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• guides/getting_started_hassio.rst
• index.rst

✨ Finishing Touches

🧪 Generate unit tests

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai generate unit tests to generate unit tests for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[trip5]

The nitpick suggestions were pretty good. I'll put them in.

[trip5]

I think I have to tag someone. @jesserockz I know it's not your usual - but I think these guides would be very helpful for noobs.

[jekader]

Thank you @trip5 for this contribution, indeed it's a bit hard for beginners to grasp what steps are needed to set up esphome for the first time.

[DjordjeMandic]

Thanks 👍! I will try following this guide to make sure nothing has changed. Gotta test it if it's really noob-proof 😁

[trip5]

I started looking through this but am far from done -- so this review is nowhere near complete. I figured we should talk about it more (on Discord) before I spend too much time. 😇

Sure. Sorry, I don't know Discord too well but I'm often online anyways these days. In the ESPHome Discord as Trip5 but my ID is _trip5_.

[trip5]

A lot of minor edits, too. I think I had stuck to 140-150 character lines so I went through it and restructured so all but .. figure:: :alt:s stop before the 120th column.

[trip5]

@kbx81 Thanks a lot for helping out with this. Actually, I had a few users of my Clock firmware (which can use but doesn't require Home Assistant) ask numerous questions how to install, and I wanted to help ease the journey a bit.

Do you actually have the ability to put this in ESPHome Docs? Is it alright that the main page will link to the "Beginner’s Guide to Adding Devices"?

[kbx81]

@kbx81 Thanks a lot for helping out with this. Actually, I had a few users of my Clock firmware (which can use but doesn't require Home Assistant) ask numerous questions how to install, and I wanted to help ease the journey a bit.

Happy to help -- thanks for putting in the effort! 🍻

Do you actually have the ability to put this in ESPHome Docs? Is it alright that the main page will link to the "Beginner’s Guide to Adding Devices"?

We do need a friendly, detailed "beginner's guide" -- I think we have a bit of a gap there. Would we link to it from the main page? ...probably? We've been discussing various changes to our documentation, but nothing specific has come to mind yet and it's mostly just been kicking around ideas.

[trip5]

Well, lol, I mean I already edited the main page as so: (screenshot from the deploy preview here: https://deploy-preview-4411--esphome.netlify.app/ )

I'm no dummy at command line but putting "command line" on the front page as a "getting started" guide can be off-putting for new users... I tried (and failed) and I think only ESPHome OGs and hardcore users will go for it. But it might be useful (for everyone) to have both linked on the front?

I just rechecked https://esphome.io/guides/getting_started_command_line and it's a little better than it was when I started this doc but... I think I glazed over when I saw "Go open that file in an editor of your choice." Maybe this one should be renamed to something to indicate it's for advanced users?

[kbx81]

I'm no dummy at command line but putting "command line" on the front page as a "getting started" guide can be off-putting for new users... I tried (and failed) and I think only ESPHome OGs and hardcore users will go for it. But it might be useful (for everyone) to have both linked on the front?

All of the tooling is command-line based so it's pretty unavoidable once you get a bit deeper into ESPHome (beyond the EDB alone, that is)...and that's not to mention that the EDB is largely just showing you stuff you'd see if you were using the command line, anyway.

EDIT: Sorry, didn't mean to express that we shouldn't move the command-line document elsewhere -- I agree, most new users tend to want an easier way to get started. 😅 We are working on bringing up some developer docs so maybe the CLI documentation can move there once that's a bit further along.

I just rechecked esphome.io/guides/getting_started_command_line and it's a little better than it was when I started this doc but... I think I glazed over when I saw "Go open that file in an editor of your choice." Maybe this one should be renamed to something to indicate it's for advanced users?

I recently re-worked the "from HA" guide and it's on my list to re-work the CLI guide, as well -- as I think you're suggesting, it could also use some work. haha

[trip5]

EDB? Is that the WebUI for ESPHome? To be fair, I've managed quite well without resorting to command line (and from what I read, the Docker install doesn't even have it). Also, to be fair, Windows is "good enough" for most people and they think cmd is some sort of super-hacker trickery. Using a GUI like ESPHome is actually enjoyable (unlike ArduinoUI).

What reasons would there be to use the command line in ESPHome? -- I mean except esptool.

BTW, I'm very willing to help out on the CLI guide if you'd like. I don't mind experimenting with it again!

[kbx81]

EDB?

"ESPHome Device Builder" -- my informal name for the tool & saves a lot of typing. haha

I've managed quite well without resorting to command line (and from what I read, the Docker install doesn't even have it). Also, to be fair, Windows is "good enough" for most people and they think cmd is some sort of super-hacker trickery. Using a GUI like ESPHome is actually enjoyable (unlike ArduinoUI).

Admittedly I'm sort of looking at this through the lens of a developer, so the EDB isn't really useful for me; I think if you have any desire at all to do development/poking around under the hood, the EDB starts to break down as it isn't particularly accommodating for that. It's a friendly front-end for editing YAML and getting it installed onto a device, but not so much a "real" development tool.

What reasons would there be to use the command line in ESPHome? -- I mean except esptool.

Literally all of the build tooling runs in a terminal. If you're doing anything more "advanced" than just editing YAML, compiling it and installing it onto a device, you end up in a terminal. haha

A situation we see a lot of is people running the EDB as an add-on to an HA instance they've already set up on some SBC (Raspberry Pi, O-Droid or now even HA Yellow/Green). Compiling takes an eternity on most SBCs but we find a lot of people don't realize that there is "another way" and that you can run the ESPHome tooling locally and then compiling a config takes well under a minute as opposed to over an hour.

Personal preference comes into the picture, too. I by far prefer to use VSCode as opposed to some other text editor running in my web browser -- it's not uncommon that I have many device configurations open simultaneously (in tabs) and am copy/pasting stuff between them. Doing that in the EDB is cumbersome at best. Keep in mind that I have nearly 60 ESPHome devices running here so I have a lot of configs...and that's not to mention all of the development work I do on a day-to-day basis.

[trip5]

Literally all of the build tooling runs in a terminal. If you're doing anything more "advanced" than just editing YAML, compiling it and installing it onto a device, you end up in a terminal. haha

OK. This is true. Even compiling is a terminal. Usually non-interactive but terminal still.

on most SBCs but we find a lot of people don't realize that there is "another way" and that you can run the ESPHome tooling locally and then compiling a config takes well under a minute as opposed to over an hour.

Can confirm. Moved from a Pi 4 to an ODroid x86 for this exact reason. Never considered the compiler could be run locally.

many device configurations open simultaneously (in tabs) and am copy/pasting stuff between them. Doing that in the EDB is cumbersome at best.

Also true. I usually end up resorting to Notepad++ and VSStudio as well... and several tabs open as well. But for new users... they should figure out their own personal preference. And I think new users will (like me) start with 2 or 3 ESPHome devices. Some may never move past that. I myself still prefer Tasmota for switches and lights. The thought of having 20 more YAMLs - all of them almost the same - annoys me. But there's a tool in development esphome-editor that is geared towards multiple devices with similar configurations. I'll get around to it eventually. Right now in a temporary living situation so most of my smart devices are just gathering dust until the move is complete and I can get back to "living ten minutes in the future" (as I tell my wife).

[github-actions[bot]]

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days. Thank you for your contributions.

[trip5]

Not stale.

[trip5]

Making another effort to get this some proper attention. I've resolved the conflict with index.rst and re-added a link to my Beginner's Guide to the main page. I really do think it would be helpful to give new users a step-by-step walk-through but with a bit more detail than what is in the hassio guide... and certainly a bit easier to step up to the WebUI than the command line or wading through guides.

[esphome[bot]]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks :+1:

Learn more about our pull request process.

[trip5]

It will be something that goes out of date if Docker Desktop decides to change something.

You're not wrong. Removed those files and the link to it completely.

[trip5]

Sorry that took so long. Slipped my mind to make more changes.... A lot of little changes made on the suggestion of the AI. Many were important.