Andreas Spiess had released a decent “getting started in ESPHome for Arduino/cpp users”.
I think it does a decent job of outlining some common stumbling blocks and questions.
Here it is.
Beware seasoned ESPHome users there’s a couple of things in there that might make your eye twitch.
@ImaginaryTango I’m curious how much you think it may have helped with your recent onboarding/learning?
Apologies. I saw this post and I’m keeping it open in a tab, but haven’t had time to watch the video when I can give it full attention.
I have thought about the issues I had. Much of it is how to reference variable values, since you can’t just name the variable. I’ve been thinking it might be worth it to add a page to the documentation about how to do that. I could write a rough draft of it, but I’d need someone (or more than one person) to make sure what I write is accurate.
Had time to watch it earlier than I expected.
He makes some interesting points that I remember were issues for me when I first learned how to write a GUI. I had been programming, at one level or another, since the 70s, but it was all just sequential programs that would run from the command line. Nothing was running in parallel. I remember dealing with issues similar to what he talks about when I switched from that to a GUI. Writing the setup was easy - just start the program at line 1 and write things in sequence. But once you get to a GUI loop starting, and then you’re writing all the functions for each button or other widget in the GUI, it takes practice to accept that those functions might run in parallel or will run only if the user activates a widget. It’s also a similar learning curve when moving from just writing sequential programs with subroutines to writing OOP. (At least it was for me.)
Much of what he talks about here is a similar issue and it drives home, to me, how we all come into something like ESPHome from different backgrounds. If you’re used to writing GUIs, than I don’t think anything he discusses in this is an issue.
For me, the issues were, I think, C++ and protocol/format related. First, from what I had seen before in HA and YAML for one or two other things, I thought it was a configuration file and had trouble making sense of much of what ESPHome does. Then it hit me that the ESPHome YAML file was essentially an OOP program and almost like writing for a GUI. My other issue is that I haven’t used C++ in 15 years or more. When I was using it, I loved it and wish I had reason to write in it now. But it’s been so long I don’t remember the syntax of using pointers. (No issue with the concept of pointers and how they work - it’s syntax.)
So, from my personal experience, if you come into ESPHome as a non-C++ programmer, it can be confusing as heck. I’ve been thinking about this while I’ve been working on the hardware side of things in KiCad. I’m trying to organize my thoughts so I could write at least an outline for a “New to ESPHome” page for the docs. I think one of the first things I’d point out is that the YAML file is basically OOP and that all the sections are objects and will be running concurrently. Next I’d cover formatting - like the issue that I spent, literally, days, trying to understand: How to access variables. (Like if you want to print a variable value in the log, you do one thing, if you want to use the value for a formula or delay statement or something like that, you use another format. Strings need c_str() to get the value, numbers don’t and booleans act more like numbers (if I’m remembering correctly).)
I have been trying to think of other issues I ran into or that I think people would have trouble with, but maybe it’s a good idea to just get started with the points I’ve mentioned and get feedback from other people as they come in and try to figure out ESPHome.