Add HomeWizard P1 usermod: live grid power visualization ("Grid Flow" effect)

[stephancar]

What it does

New usermod homewizard_p1 (ESP32 only) that polls a HomeWizard P1 meter (a popular WiFi P1 dongle for European smart meters) on the local network and visualizes the home's live grid power through a new "Grid Flow" effect:

• Import/offtake (consuming from grid): purple pulses flowing toward the segment start, speed and brightness scale with wattage
• Export/injection (e.g. solar): green pulses flowing toward the segment end
• Near zero: calm white breathing (configurable deadband)

The meter is discovered automatically via mDNS (_hwenergy._tcp), or a fixed host can be configured. Deadband, full-scale wattage, and poll interval are configurable in Usermod Settings; the effect has Speed / Pulses / Trail / Blur sliders.

How it works

• All networking (mDNS discovery + HTTP polling of the local API v1 /api/v1/data) runs on a dedicated low-priority FreeRTOS task pinned to core 0 (same pattern as the audioreactive usermod's processing task), so blocking calls can never stall the LED pipeline. The task publishes 32-bit values (atomic on ESP32); host strings are exchanged under a mutex.
• The effect renders from a low-pass filtered power value (~1.2 s time constant), and the pulse position is integrated over time, so poll steps, deadband crossings and import/export flips all animate smoothly with no jumps.
• Data-loss handling: the effect falls back to a clearly visible dim breathing; the last discovered meter IP is never discarded (background re-discovery only replaces it on success), so the usermod self-heals after WiFi/mDNS hiccups or meter IP changes.

Testing

• Tested on real hardware: ESP32 (esp32dev) + WS2812B (120 LEDs) + HomeWizard HWE-P1 (local API v1).
• Long-run stability: 12 minutes of continuous injection/neutral/offtake state cycling with stable heap and no resets; separate stress tests for data-loss recovery (meter unreachable → dim breathing → automatic recovery) and mDNS rediscovery.
• The folder includes p1_simulator.py, a small fake local-API server that cycles injection/neutral/offtake every 10 s, so the usermod can be developed and tested without a real meter. Rendered output was verified against it via /json/live.
• Compiles clean for esp32dev; library.json restricts the usermod to espressif32 (it needs a FreeRTOS task).

Notes

• No changes outside usermods/homewizard_p1/; no platformio.ini changes.
• Larger AI-generated sections are marked with // AI: comments per AGENTS.md; the code was written with AI assistance, reviewed and hardware-tested by the contributor.
• Happy to receive maintainer guidance on anything (naming, effect metadata, etc.).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added an ESP32-only “HomeWizard P1” WLED usermod that fetches meter power via the local API, using mDNS auto-discovery or a manual host:port override.
  • Added a “Grid Flow” visualization that smoothly responds to active_power_w, including import/export direction, neutral deadband breathing, and a graceful neutral “no data” state when updates stop.
  • Added visual tuning (Speed, Pulses, Trail, Blur) and behavior controls (update interval, deadband, full-scale).

• Documentation

  • Added full README setup instructions, configuration details, effect guidance, troubleshooting, and a P1 simulator for testing.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• ✅ Review completed - (🔄 Check again to review again)

Walkthrough

Adds an ESP32-only HomeWizard P1 usermod that discovers or uses a configured host, polls the local API on a dedicated task, smooths power readings, and renders a “Grid Flow” effect. It also adds build metadata, a simulator, and user-facing documentation.

Changes

HomeWizard P1 Usermod

Layer / File(s)	Summary
Shared state and effect definitions usermods/homewizard_p1/homewizard_p1.cpp	Defines shared state and constants, and the Grid Flow rendering mode that maps smoothed power to directional pulses with trail, blur, and presence-based breathing.
Discovery and fetch task implementation usermods/homewizard_p1/homewizard_p1.cpp	Adds HomeWizardP1Usermod task state, mutex-protected host handling, mDNS discovery, HTTP fetch and streamed JSON parsing of active_power_w, and the background polling loop with retry and rediscovery behavior.
Loop smoothing and status reporting usermods/homewizard_p1/homewizard_p1.cpp	loop() filters power and presence over time, and addToJsonInfo() reports live readings or task-derived status/error strings.
Configuration and registration usermods/homewizard_p1/homewizard_p1.cpp, usermods/homewizard_p1/library.json	addToConfig/readFromConfig serialize and clamp settings, update task-visible host state, define the module build metadata, and register the usermod instance.
Simulator and documentation usermods/homewizard_p1/p1_simulator.py, usermods/homewizard_p1/readme.md	Adds the Python HomeWizard API simulator and README coverage for setup, configuration, troubleshooting, simulator usage, and technical notes.

Estimated code review effort: 4 (Complex) | ~60 minutes

Suggested reviewers: blazoncek

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the new HomeWizard P1 usermod and its live Grid Flow visualization feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@usermods/homewizard_p1/homewizard_p1.cpp`:
- Line 322: The early return in the HomeWizard usermod update flow leaves the
Grid Flow effect state active when the usermod is disabled. Update the logic
around the enabled check in homewizard_p1.cpp (the update/smoothing path in the
HomeWizard usermod class) so disabling the usermod also clears or resets the
registered Grid Flow state before returning, preventing stale import/export
visuals from persisting.
- Line 224: The host/port parsing in homewizard_p1.cpp currently uses atoi() and
assigns directly to a uint16_t, which lets malformed, negative, or oversized
ports wrap to unintended values. Update the host:port parsing logic around the
colon handling to validate the port string explicitly in the same parsing flow,
reject non-numeric or out-of-range values, and only accept ports within the
valid 1–65535 range before storing them in port. Use the existing parsing block
near the colon check to enforce this validation and fail the config instead of
silently normalizing bad input.
- Around line 176-188: The mutex/task creation paths in homewizard_p1 need
failure handling: `ensureMutex()` currently assumes `xSemaphoreCreateMutex()`
succeeds, and `setup()` appears to ignore a failed `xTaskCreatePinnedToCore()`
result. Update `ensureMutex()` and `getEffectiveHost()` so they detect a null
`p1Mutex` and skip any `xSemaphoreTake()`/`xSemaphoreGive()` usage when creation
fails, and add a check around the `xTaskCreatePinnedToCore()` call in `setup()`
to surface the error instead of leaving the usermod idle. Use the existing
`ensureMutex`, `getEffectiveHost`, and `setup` symbols to locate the affected
code.
- Around line 29-30: The shared P1 scalar fields are crossing the
fetch-task/main-thread boundary without a real synchronization mechanism, so
protect `p1PowerW`, `p1LastGoodMs`, `taskStatus`, `taskHttpCode`,
`updateIntervalMs`, `autoDiscover`, and `cfgEnabled` using the existing
`p1Mutex` or convert them to `std::atomic` and read/write them consistently.
Update the relevant access points in the HomeWizard P1 task and its readers so
these values are accessed under the same synchronization scheme as the host
strings, rather than relying on `volatile`.
- Around line 242-255: Parse the HomeWizard response as a stream in the logic
around http.getString(), deserializeJson, and p1PowerW so the filter works
without buffering the whole body, and replace the containsKey check with a
numeric type check on active_power_w. Update the flow in the same block to
deserialize directly from http.getStream() and only assign p1PowerW when
doc["active_power_w"].is<float>() is true; otherwise set ST_JSON_ERR and return.
- Around line 419-420: The wattage normalization in the configuration path can
overflow when `p1DeadbandW` is at `INT_MAX`, so update the logic around
`p1DeadbandW` and `p1FullScaleW` to avoid evaluating `p1DeadbandW + 1` in the
same integer type. Use a wider intermediate or clamp the upper bound first, then
enforce that `p1FullScaleW` remains strictly greater than `p1DeadbandW` inside
the `homewizard_p1` normalization code.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7f1ca196-802d-4942-a4d2-62dfaae98475

📥 Commits

Reviewing files that changed from the base of the PR and between 8a67495 and 0d6a248.

📒 Files selected for processing (4)

• usermods/homewizard_p1/homewizard_p1.cpp
• usermods/homewizard_p1/library.json
• usermods/homewizard_p1/p1_simulator.py
• usermods/homewizard_p1/readme.md

[stephancar]

All coderabbit findings addressed in 2c6efd0:

• Cross-task scalars: switched from volatile to std::atomic for everything crossing the fetch-task boundary (p1PowerW, p1LastGoodMs, taskStatus, taskHttpCode, updateIntervalMs, autoDiscover, cfgEnabled).
• Mutex/task creation failures: ensureMutex() now reports failure, every xSemaphoreTake() path is guarded against a null mutex, and a failed xTaskCreatePinnedToCore() is surfaced on the info page (ST_TASK_FAIL) instead of leaving the usermod silently idle.
• host:port validation: strtol with full range/format checking; malformed or out-of-range ports are rejected (connection-error status) instead of wrapping.
• Stream parsing + numeric check: response is parsed via http.getStream() (no full-body buffering) and the assignment is gated on doc["active_power_w"].is<float>(), which also rejects a present-but-null field.
• Disabled-state reset: disabling the usermod clears the smoothed power/presence state so the still-registered effect falls back to its idle rendering instead of showing stale import/export visuals.
• Overflow guard: deadbandW is clamped before deriving the full-scale floor, so deadbandW + 1 can no longer overflow at extreme config values.

Compiled for esp32dev and re-tested on the real hardware setup (ESP32 + WS2812B + HWE-P1): meter auto-discovery, polling, and the Grid Flow effect all verified working on the updated build.

🤖 Generated with Claude Code

[softhack007]

portMAX_DELAY can hang forever. Better to use a realistic shorter dalay, and some code to handle mutex aquisition failure.

[softhack007]

portMAX_DELAY => see my previous comments

[softhack007]

if this is not timing-critical (=needs to respond to an event within 1-2milliseconds), you can better use xTaskCreate (without pin to core).

Also check if 10240 words of stack are really needed, it seems excessive.

[softhack007]

Compiled for esp32dev and re-tested on the real hardware setup (ESP32 + WS2812B + HWE-P1): meter auto-discovery, polling, and the Grid Flow effect all verified working on the updated build.

🤖 Generated with Claude Code

@stephancar I would prefer if you take the time to respond in person, instead of letting your AI talk for you.
After all, I'm also taking the time to review your work in person.

[softhack007]

No need to pin this task to core #0. Simply use xTaskCreate() instead.

[softhack007]

Don't use portMAX_DELAY. Better to find a reasonable max delay, and handle mutex acquisition failure gracefully.

[softhack007]

portMAX_DELAY is dangerous - see my previous comment.

[softhack007]

Same.

[softhack007]

@stephancar why did you add this to the readme?

[stephancar]

I've lost days to problems that turned out to be other things (a leftover home assistant automation that controlled the wled controller as well as an undersized power supply)

[softhack007]

@stephancar is brownout directly caused by your usermod?

[stephancar]

no this turned out to be the undersized PSU and/or the home assistant automation that I forgot about (it turned wled on or of based on whether I had injection or not)

[softhack007]

This ifdef can be omitted - the complete usermod will not compile on 8266 any way.

[softhack007]

same

[softhack007]

Suggestion: add a compile-time blocker for 8266 here. Then you can remove all remaining #ifdef ARDUINO_ARCH_ESP32 checks.

#ifndef ARDUINO_ARCH_ESP32
  #error "this usermod only supports esp32 boards"
#endif

[willmmiles]

None of them should be necessary at all. The supported platform list is already set in library.json.

[softhack007]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@usermods/homewizard_p1/homewizard_p1.cpp`:
- Around line 456-457: Guard the mutex acquisition in readFromConfig() because
ensureMutex() may fail and leave p1Mutex null before xSemaphoreTake() is called.
Update the readFromConfig() path to check the result of ensureMutex() (or
combine it with the mutex take like the other call sites) and return early if
the mutex could not be created, so xSemaphoreTake(p1Mutex, ...) is never reached
with a null handle.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ab7709e6-53af-4439-bf3b-2dae27abb9d9

📥 Commits

Reviewing files that changed from the base of the PR and between bc2c80d and 0f9ec56.

📒 Files selected for processing (4)

• usermods/homewizard_p1/homewizard_p1.cpp
• usermods/homewizard_p1/library.json
• usermods/homewizard_p1/p1_simulator.py
• usermods/homewizard_p1/readme.md

[stephancar]

Compiled for esp32dev and re-tested on the real hardware setup (ESP32 + WS2812B + HWE-P1): meter auto-discovery, polling, and the Grid Flow effect all verified working on the updated build.
🤖 Generated with Claude Code

@stephancar I would prefer if you take the time to respond in person, instead of letting your AI talk for you. After all, I'm also taking the time to review your work in person.

Fair point, sorry! This is my first PR and Im learning about AI tooling for the code (as marked in the sources). From here on the replies are my own. Thanks for taking the time to review my code, the suggestions are very helpfull!