goodwe-addon/goodwe_controller/DECISIONS/UX-15-setup-only-mode.md

UX-15 — setup-only mode: a new install serves the wizard

Status: DECIDED 2026-09-28 (owner decision; UX-15 dev). Card 6aba0053d27a32cb3f210dcc. Changes the CFG-01 startup gate and closes the open question in UX-13-setup-wizard §2. Amends UX-02-two-config-surfaces §4.

1. The rule

config.yaml ships setpoint_entity: "", so a new install's options are refused by rule 1 of validate_startup_config(): no inverter to control. Until now that was exit 78 before any page was served, and the installer had to fill in the entity on the Configuration tab before the wizard could open.

The add-on now starts in setup-only mode when, and only when (setuponly.applies()):

• the options name no inverter at all: no flat setpoint_entity and no inverters entry, and
• rule 1's refusal (no_power_request_problem()) is the gate's only refusal.

In setup-only mode it serves the page, says it is in setup (banner, /status setup_only: true, a WARNING log line) and opens the wizard when the page is opened with no route (setup_needed is no_power_request). After the wizard's save and restart the normal gate applies to the saved options.

2. What still exits 78, and why

Everything else the gate refuses, including:

• a complete configuration that is refused, e.g. maintenance_charge_w above max_w;
• no power request entity and any other refusal;
• an inverters list whose entry has a blank power request entity.

These are configurations somebody edited. The Configuration tab stored them, the log's refusal banner names each problem, and the tab is where they are fixed (UX-02 §4). Serving the wizard there would put a six-step setup in front of someone who needs to change one field. A narrow rule also keeps the setup-only decision to one comparison against one known sentence, so a new validator rule cannot widen it by accident: any other refusal fails the equality and exits 78.

The cost: an installer who first sets, say, a DSMR meter with no entities on the Configuration tab and leaves the power request entity empty gets exit 78, not the wizard. The log then names both fields.

3. Why it cannot command

Setup-only mode builds nothing that commands. amain() branches to setuponly.serve() before the MQTT broker, the controller, the meter task and the tariff task are built, and it returns from there when the Supervisor stops it. What serves the page is SetupOnly, which holds no inverter.

Three checks make it structural rather than a convention:

1. The HomeAssistant is read-only (HomeAssistant(read_only=True)). call() refuses before it sends anything, and every service call goes through it: number.set_value (set_number()), notifications, all of them. The flag is fixed at construction, and there is no setter.
2. SetupOnly refuses a HomeAssistant that can write, and Controller refuses one that cannot. So neither can be built on the wrong one.
3. /action answers 409 in setup-only mode, before handle_action(). Start, Stop and the battery cycle do nothing.

No MQTT client is created, so nothing is published. The page's other routes already read only, or write the add-on's own options (UX-02 §6).

Setup-only mode writes no Store file. The wizard's save writes setup_done, as in any mode. So a new install that is set up on the Configuration tab instead still has a fresh Store on its first normal boot, and the first-run rule (UX-13 §2) sends it to the wizard as before.

4. How it is held

• test_setup_only.py part 1: when it applies, including the three exit-78 cases above. Part 2: the read-only write path refuses with nothing sent, and the two constructors refuse. Part 3 boots the real main() on the shipped defaults against a fake Supervisor and Home Assistant over HTTP and logs every request: the page is served, /status says setup-only, Start and the cycle get 409, and there are 0 service calls and no MQTT request, also with auto_start on and a Store that says control was started. The wizard's save is then booted: it passes the normal gate, does not open the wizard again, and every write is 0 W (shadow). Part 4: the refused configurations exit 78 and serve nothing.
• Mutations, each red: applies() always false or always true, the read-only refusal removed, the Controller's check removed, amain() giving setup-only mode a writable HomeAssistant, /action's 409 removed, and the return after serve() removed.
• TEST-23 (PR #147 review, 2026-09-28): the add-on image on the shipped defaults and an empty /data made 0 service calls and no MQTT request in 3.5 minutes of setup-only mode, counted in both the stand-in and the rig shim logs. The wizard save then passed Supervisor 2026.08.0's AppOptions, and after the restart it ran in shadow: 11 of 11 writes were set_value 0.0.

5. The wizard fixes in the same card

• F1. /config/validate converts what it can of a page model (uimodel.ui_to_options_partial()), so a conversion error blocks its own step beside its field and the live checks still run on the rest. A refusal about a key the failed conversion writes is left out, because it would judge the stored value. The save still refuses such a model (422, with steps).
• F2. A save from the page model sends base, the model it opened. The add-on writes only the keys whose value differs from base, onto the blob stored now (uipage.only_edits()). So "save again to keep yours" after a 409 keeps the other surface's changes. A key both surfaces changed takes this page's value, which is what the second press after the banner means.
• Meter entity. On the last step a meter entity Home Assistant does not have is red, like a missing power request entity, so a skipped kettle test cannot let it through. In the Installer view it stays a warning.
• Step 1 after a skip. When the kettle test saw the reading fall and was then skipped, step 1 says the reading went down. The skip stays (UX-13 §3).