Idea: Simple GUI system for configurations

[OttoWinter]

This is an idea I've had for some time, but don't have the frontend experience for to implement.

Goal

Simplify config creation for beginners by replacing raw YAML with a GUI

Observations

• Big YAML files with indentation are daunting for beginners
• Simple Key-Value YAML without indentation is easy and beginner friendly
• More complex features like automations use very complex validation schemas internally - essentially impossible to dynamically generate HTML forms for all features
• ESPHome has good modularization, for example WiFi "config fragments" are independent of GPIO Switch fragments.

Idea

Create a GUI system with draggable config fragments where you can enter the per-component YAML.

Advantages

• Lots of YAML complexity gone - most config fragments will be easy key-value
• System would still allow 100% of more complex ESPHome uses with no extra effort. Like substitutions, automations etc
• Relatively simple implementation wise, frontend just needs to show editable cards, backend stores fragments on disk and "combines" them into a normal config datastructure. Mot backend parsing/validation logic can be kept.
• Incremental improvements possible, for example at a later stage simple config schemas could be converted to HTML forms (automatically generated where possible, but also custom HTML where necessary)

Disadvantages

• Internally, the UI state will have to be stored in some JSON file (like for each card, XY coords, editor text as string to keep comments); round-trip conversion of existing YAML files while preserving things like comments is hard -> no longer able to edit YAML files in text editor, only the dashboard YAML editor (but only if you use this feature)

Alternatives

Alternative ideas considered:

• Create Forms dynamically like HA config flows:

  • would require lots of backend changes for inference of schemas
  • very hard to get 100% feature coverage (especially more complex features like automations to dynamically generate forms for), without >80% feature coverage any "power" user wouldn't be able to use this system

• NodeRED like system: works well for automation flow, but not really useful for independent things like a GPIO switch; looks very complex to implement

This issue is to get the conversation going and see if there's interest in implementing the frontend side.

In conclusion, obviously a Config GUI would be a great addition. I believe this system is the easiest starting point with significant improvements right away while keeping all power users on board. Incremental progress towards more Form-like input is also possible.

[OttoWinter]

CC @jesserockz @balloob if you find this idea interesting

[jesserockz]

I like it. It would be a great step forward.

Unfortunately I to lack the frontend skills to implement something like this.

[balloob]

The biggest problem I see is that writing to users YAML means users lose their original formatting. We can switch to ruamel.yaml to at least make comments survive, but it won't deal with secrets for example.

So then we can swap out the complete storage format and just create our own format without comments. We do this in HA, the biggest gotcha for people is that comments are lost as we store in JSON (which doens't have comments), but we have a UI in YAML.

So I like the idea, but also a hornet nest 😅

[OttoWinter]

comments are lost as we store in JSON

Yes, round-trip YAML is hard and not an option for us. But storing comments written inside the card YAML is possible. The main idea is: "store the card YAML contents as plaintext".

An example: In the GPIO switch example a user could write:

# This is my comment
name: GPIO Switch
pin: GPIO23

The backend would store this as JSON:

{
  "component": "gpio.switch",
  "content": "# This is my comment\nname:e ...",
  "x": 150.0,
  "y": 90.0
}

Notice content is plaintext; When reading the config in the backend then parses each JSON entry's content as YAML, then combines those to the full config data structure.

The editing system would write directly to the plaintext content, without ever parsing the YAML. Only when installing/validating the config do the comments get lost, but those actions don't mutate the config, so not a problem.

---

but it won't deal with secrets for example.

Example 2: secrets

WiFi Card's contents are

ssid: !secret my_ssid
password: !secret my_psk

With the system I propose, no YAML tags would be lost. The frontend+editing system don't care what you write in your card YAML and just store it as plaintext. Only the validation/install system in the backend need to parse it, but those systems never mutate the config so no problem

[EternityForest]

Honestly I'm not completely sure it wouldn't be easier to just create a proper GUI that didn't expose YAML at all.
The YAML is not at all difficult for even slightly intermediate users. Actually installing and launching the program might be just as intimidating for some beginners(Perhaps the whole thing could actually be integrated as an Arduino IDE plugin or something, so you can double click launch it?)

It's the true beginners, and people who would rather not have to Google 5 different things to find the stuff they already know but forgot the syntax for, who need the visual editor.

I could see building a simple, opinionated, and consumer-friendly config editor in just a few days with something like Vue. The whole thing could run completely in the browser for portability to different backends.

Manufacturers, or anyone else who might like to, could set up code generator sites specific to their product, entirely separate from the actual compiler. If/when there's ever a truly consumer-ready way to actually compile the project, you'd already have the frontend.

You'd have some static boxes for things like your WiFi setup, your hostname and friendly name(Although I really think those should be in flash and user-settable), API keys, etc.

You'd have a list of Apps(componenets), each of which would be a handwritten Vue component and a bit of YAML editing logic. Only a small set of these would be necessary I think to be pretty useful. They could integrate the documentation right in the UI.

I think the big use case might be user-defined timers, which you could make a nice editor for with(https://github.com/JossyDevers/cron-expression-input).

Actions would be similar, a select group of actions would be supported in the UI.

UI elements could have access to global things like lists of IDs for select-box input instead of text.

For anything not natively supported, you'd have Raw YAML components and actions(Build them first, and the editor would start life roughly equivalent to OP's proposal!).

Your "Apps" could generate multiple components each and serve as drivers, and your base configuration items could be done as an App too, so your entire "Visual source code" becomes one flat list of variations on one primitive.

At the end, all the outputs of each component editor would be merged together, and as a bonus, if you just swap out the merge function, and the of "Apps", you could reuse the framework as a config editor for anything else as well.

You avoid any issues with comments and round trip, because you simply don't support making brand new things with the visual editor. If people want comments, they can be embedded in a notes property on each individual component.

It would make the YAML file longer, but you could include the "Sources" of the file in a special property, so you could go back and edit a file that was originally made with the visual editor.

[bin-bash-mak]

The idea seems interesting. I agree that yaml can be shitty, but yaml is also very powerful. But out of curiosity, do you want to support all ESP home's features or just the basics.

As a note I really hate UI and UX development (and I am not good at it) so keep that in mind

My experience with visual programming tools mainly falls into 2 categories an I hate both because I always felt that programming is easier and they lack the flexibility that code gives:

• Blocks programming something like Scratch
• Flow or node based programming something like xod

So I don't know if it helps for blocks based programming, google has a library called blockly and there's a library for nodes in react called reactflow

So do you see you UI something like a puzzle blocks that you connect together?

Or nodes with properties that you connect together?

Or maybe a combination of the two?

[IhsenBouallegue]

I also like the idea very much. I am new to esphome but I have the skills to do it. So i threw this prototype together. If there is enough interest I might finish it. Let me know what you think!

[4b686f61-2c1b]

This is 1000% more intuitive than getting eye strain figuring out yaml formatting issues.

[archef2000]

Look great how are you pulling the options for each component? Are you reading the config validation schemas from python? Are external components supported?

[IhsenBouallegue]

For the concept I hard coded them. But I am trying to figure out how to read the schemas from esphome for example https://schema.esphome.io/2025.7.0/switch.json and convert that. I am just finding it hard to understand this schema, but I will figure it out eventually. If external components provide such a schema yes supporting them would be as easy as adding a the repo link. But that can come later.