Repository navigation
Conversation
…ected After the api_stale_grace_period substitution (default 30s) without Home Assistant, chips, home custom buttons and the weather picture are hidden, the indoor temperature falls back to the embedded sensor, and the outdoor temperature and the home values are greyed out. Everything recovers on reconnection without waiting for a state change. Closes #519 Related to #514
docs: Add a reference of the ESPHome substitutions available to users
ci: Skip link checks for the Home Assistant community forum
feat: Indicate stale home page values while Home Assistant is disconnected
docs: Add section on how AI is used in this project
docs: Add security policy and code of conduct
…stence docs: Remove outdated guidance to disable Bluetooth for TFT uploads
|
No actionable comments were generated in the recent review.
 |
| Layer / File(s) | Summary |
|---|---|
Graph data model and history calculations components/nspanel_easy/page_graph.h, components/nspanel_easy/page_graph.cpp, components/nspanel_easy/pages.h |
Adds graph configuration and history APIs, graph calculations, HMI component identifiers, and graph page registration. |
Blueprint history flow and panel drawing nspanel_easy_blueprint.yaml, esphome/nspanel_esphome_page_graph.yaml, esphome/nspanel_esphome_standard.yaml, hmi/dev/nextion2text/nspanel_*/graph.txt, docs/blueprint.md |
Adds optional graph settings for four Home values. The Blueprint retrieves five-minute recorder statistics and sends history and updates to ESPHome. ESPHome draws and refreshes the page; both HMI layouts define graph components. |
Stale API display handling
| Layer / File(s) | Summary |
|---|---|
API stale-state lifecycle components/nspanel_easy/base.cpp, components/nspanel_easy/base.h, esphome/nspanel_esphome_api.yaml, esphome/nspanel_esphome_api_subscribe.yaml |
Adds a configurable grace period, stale-state updates on disconnection and reconnection, and subscription rerendering when stale state changes. |
Subscription and home-page rendering components/nspanel_easy/chips.cpp, components/nspanel_easy/chips.h, components/nspanel_easy/page_home.cpp, components/nspanel_easy/page_home.h, esphome/nspanel_esphome_page_home.yaml |
Hides chips and selected home-page content while stale. Indoor temperature uses the panel sensor. Outdoor temperature and Blueprint-pushed values and icons are greyed out. |
Blueprint and firmware behavior
| Layer / File(s) | Summary |
|---|---|
Subscription bindings and text sizing components/nspanel_easy/api_subscriptions.cpp, components/nspanel_easy/api_subscriptions.h, components/nspanel_easy/text.cpp, components/nspanel_easy/text.h, esphome/nspanel_esphome_page_entities.yaml |
Binding comparisons now match targets instead of positions. Text length uses UTF-8 width weighting, with configurable entity-page font thresholds. |
Buttons and climate presets nspanel_easy_blueprint.yaml, components/nspanel_easy/addon_climate.h, esphome/nspanel_esphome_addon_climate_base.yaml, docs/blueprint.md, docs/addon_climate.md |
Adds group button actions and changes momentary-indicator handling. Climate presets display preset icons and active-state colors. |
Weather, QR codes, and display compatibility nspanel_easy_blueprint.yaml, esphome/nspanel_esphome_page_qrcode.yaml, esphome/nspanel_esphome_version.yaml, hmi/dev/nextion2text/nspanel_*/boot.txt |
Adds forecast day/night icon selection, bounds QR title length at a UTF-8 boundary, sets restore-data limits, and raises the minimum TFT version to 22.3. |
Home-value and utility refresh behavior nspanel_easy_blueprint.yaml, esphome/nspanel_esphome_page_utilities.yaml |
Moves clearing of unconfigured home slots to startup or automation reload. Home-value updates also run while the graph page is open. |
Policies and user documentation
| Layer / File(s) | Summary |
|---|---|
Conduct, security, and AI contribution guidance CODE_OF_CONDUCT.md, SECURITY.md, CONTRIBUTING.md, docs/ai_usage.md, README.md, docs/README.md |
Adds conduct and security policies and documents AI use and contribution expectations. Project pages link to these resources. |
Setup and reference guidance docs/network.md, docs/substitutions.md, docs/backup_stock_firmware.md, docs/install.md, docs/customization.md, docs/README.md |
Adds network, substitution, and stock-firmware backup guides. Installation and customization guidance changes the Bluetooth Proxy and network examples. |
Update and feature documentation docs/howto.md, docs/addon_upload_tft.md, docs/tft_upload.md, docs/different_version.md, docs/blueprint.md, docs/addon_climate.md, docs/addon_espectre.md, README.md, .rules/mlc_config.json |
Revises update and TFT-upload instructions and documents graph, climate preset, and customization behavior. The link checker ignores Home Assistant community URLs. |
CI maintenance
| Layer / File(s) | Summary |
|---|---|
Validation tool versions .github/requirements.txt, .github/workflows/* |
Updates the pinned flake8 version and Python and Markdown validation action versions. |
Estimated code review effort: 5 (Critical) | ~90 minutes
Change: Feature · Severity of issue fixed: Medium
Sequence Diagram(s)
sequenceDiagram
participant HomeValue
participant Blueprint
participant Recorder
participant ESPHomeGraph
participant NextionGraph
HomeValue->>Blueprint: Open graph for configured entity
Blueprint->>Recorder: Request five-minute mean statistics
Recorder->>Blueprint: Return history
Blueprint->>ESPHomeGraph: Send graph configuration and history
ESPHomeGraph->>NextionGraph: Draw graph
ESPHomeGraph->>Blueprint: Request newer samples while graph is open
Suggested reviewers: actions-user
Merge Risk: 
2b057
-
Concurrent Blueprint updates can leave the panel with incorrect entity bindings and cause unnecessary restarts.
Pre-merge checks: 
-
Check name Status Explanation Resolution Linked Issues check [ #519] The stale-state flag, grace timer, reconnect refresh, and stale rendering behavior are implemented. [#588] The combined update guide documents the firmware, TFT, and Blueprint order. [#591] Unc…For [ #579], either implement the issue's specified sampled-value and firmware ring-buffer design, or update the active requirement to explicitly accept recorder-statistics history. For [#593], add an explicit text-scaling enable/disable set…Out of Scope Changes check The direct linked targets cover stale home values, graphs, update instructions, API-set home values, entity-page scaling, climate refresh errors, hardware-button groups, QR restoration, and binding-pu… Move unrelated features and documentation to pull requests with matching active direct issues, or add active direct issue targets that define their coding scope. Keep changes that support [ #519], [#579], [#588], [#591], [#593], [#598], [#60…-
Check name Status Explanation Description Check Check skipped - CodeRabbit’s high-level summary is enabled. Title check The title clearly identifies the primary changes: the graph page, stale home values indicator, and active climate preset behavior. It is concise and directly related to the changeset. Docstring Coverage Docstring coverage is inconclusive: files from earlier reviews still need to be rechecked within the check's analysis limits. Not blocking.
Full details: Linked Issues check
-
Explanation
[
#519] The stale-state flag, grace timer, reconnect refresh, and stale rendering behavior are implemented. [#588] The combined update guide documents the firmware, TFT, and Blueprint order. [#591] Unconfigured home slots and API-set colors are preserved. [#598] Climate refresh tolerates missingold_state. [#601] Hardware-button entity and state-indicator selectors accept old-style groups. [#619] QR globals define restore lengths for the supported QR and title limits. [#625] Repeated staged targets restart the staging push. [#579] The implementation uses Home Assistant recorder statistics and transfers history, which does not meet the issue's specified Blueprint sampling and firmware ring-buffer design. [#593] The implementation adds font-length thresholds, but it does not provide an on/off control for text scaling. The change inventory identifies no new automated tests for the graph or scaling behavior.Resolution
For [
#579], either implement the issue's specified sampled-value and firmware ring-buffer design, or update the active requirement to explicitly accept recorder-statistics history. For [#593], add an explicit text-scaling enable/disable setting while preserving the documented default behavior. Add automated coverage for the new graph and scaling behavior where the repository test framework supports it.
Full details: Out of Scope Changes check
-
Explanation
The direct linked targets cover stale home values, graphs, update instructions, API-set home values, entity-page scaling, climate refresh errors, hardware-button groups, QR restoration, and binding-push concurrency. The reviewed changes also add active climate-preset display behavior, weather day/night handling, button-page behavior, screensaver brightness changes, Bluetooth Proxy and TFT workflow changes, network and firmware-backup guides, security, conduct and AI documents, API entity-length handling, utility-button changes, and CI tool updates. The supplied direct linked issues do not define these objectives. The changes are therefore not limited to the linked issue scope.
Resolution
Move unrelated features and documentation to pull requests with matching active direct issues, or add active direct issue targets that define their coding scope. Keep changes that support [
#519], [#579], [#588], [#591], [#593], [#598], [#601], [#619], and [#625].
-
Finishing Touches
-
Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
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.
Reviewer's GuideThis release PR combines repository governance and security/AI transparency documentation with a firmware behavior change that detects prolonged Home Assistant disconnection, marks subscribed values stale after a configurable grace period, applies component-specific fallbacks or visual suppression, and re-renders cached state on reconnection; it also consolidates ESPHome substitution and Bluetooth/TFT configuration guidance. Sequence diagram for stale Home Assistant value handlingsequenceDiagram
participant HA as HomeAssistant
participant API as api_server
participant Timer as api_stale_timer
participant Panel as NSPanel
participant Render as api_stale_changed
HA--xAPI: Disconnect state subscription
API->>Timer: execute()
Timer->>Timer: delay(api_stale_grace_period)
Timer->>API: is_connected_with_state_subscription()
API-->>Timer: false
Timer->>Panel: api_stale = true
Timer->>Render: execute()
Render->>Panel: sub_render_all()
Panel-->>Panel: Hide stale controls, grey values, or use local fallback
HA->>API: Reconnect state subscription
API->>Timer: stop()
API->>Panel: api_stale = false
API->>Render: execute()
Render->>Panel: sub_render_all()
Panel-->>Panel: Restore cached Home Assistant values
Flow diagram for stale home display renderingflowchart TD
A[Home Assistant state subscription disconnected] --> B{Grace period elapsed}
B -- No --> C[Keep last display values]
B -- Yes --> D[Set api_stale]
D --> E[Hide chips, custom buttons, and weather]
D --> F[Grey home values and outdoor temperature]
D --> G[Use panel sensor for indoor temperature]
E --> H{Home Assistant reconnects}
F --> H
G --> H
H --> I[Clear api_stale]
I --> J[Re-render cached bindings and restore colors]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
panel-easy-assistant
Bot
changed the title
fix: Prevent concurrent binding pushes from mixing and restarting the panel
Bumps [flake8](https://github.com/pycqa/flake8) from 7.4.1 to 7.5.0. - [Commits](PyCQA/flake8@7.4.1...7.5.0) --- updated-dependencies: - dependency-name: flake8 dependency-version: 7.5.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com>
Bumps the actions-official group with 1 update: [actions/setup-python](https://github.com/actions/setup-python). Updates `actions/setup-python` from 7.0.0 to 7.1.0 - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](actions/setup-python@v7.0.0...v7.1.0) --- updated-dependencies: - dependency-name: actions/setup-python dependency-version: 7.1.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: actions-official ... Signed-off-by: dependabot[bot] <support@github.com>
Bumps the actions-markdown group with 1 update: [DavidAnson/markdownlint-cli2-action](https://github.com/davidanson/markdownlint-cli2-action). Updates `DavidAnson/markdownlint-cli2-action` from 24.2.0 to 25.0.0 - [Release notes](https://github.com/davidanson/markdownlint-cli2-action/releases) - [Commits](DavidAnson/markdownlint-cli2-action@v24.2.0...v25.0.0) --- updated-dependencies: - dependency-name: DavidAnson/markdownlint-cli2-action dependency-version: 25.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: actions-markdown ... Signed-off-by: dependabot[bot] <support@github.com>
…e8-7.5.0 build: bump flake8 from 7.4.1 to 7.5.0 in /.github
…ons-official-d87422eef0 ci: bump actions/setup-python from 7.0.0 to 7.1.0 in the actions-official group
…ons-markdown-7be0ce6664 ci: bump DavidAnson/markdownlint-cli2-action from 24.2.0 to 25.0.0 in the actions-markdown group
|
Sorry @panel-easy-assistant[bot], your pull request is larger than the review limit of 150,000 diff characters |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Linked issues
#519 Indicate stale home page values while Home Assistant is disconnected · 1 of 2 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Indicate stale home-page values using UnavailableBehavior | 🟡 Partly met | Stale values are indicated, but stale chips and custom buttons are hidden unconditionally instead of following the configured unavailable-entity behavior. |
| 2 | Recover on reconnect without waiting for a state change | ✅ Met | The reconnect path clears api_stale and re-renders cached subscription states. |
#579 `Enhancement` Graph page for the history of a numeric sensor · 2 of 2 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Add an optional graph page for Home page sensor history | ✅ Met | The Blueprint adds per-value graph options and supplies recorder statistics for the graph page. |
| 2 | Show the current value, scale bounds and time axis | ✅ Met | The page draws the current value, min/max labels, bound lines and local-time ticks. |
#588 `Enhancement` Clearer update instructions · 1 of 1 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Give clear instructions for updating a running panel | ✅ Met | The guide now presents firmware, TFT and Blueprint updates in one sequence and explains that the TFT normally updates automatically. |
#591 `Bug` texts and icon set through API are now more visible if not configured in blueprint · 1 of 2 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Keep API-set values and icons on unconfigured Home page slots | ✅ Met | Unconfigured slots are cleared only when the Blueprint settings are refreshed, rather than whenever Home page values are updated. |
| 2 | Provide a setting to enable or disable clearing unconfigured slots | 🟡 Partly met | The change preserves API-set values during normal page updates, but does not add a setting; slots are still cleared on Blueprint reload or Home Assistant start. |
#593 `Enhancement` entity pages text scaling switch · 1 of 1 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Allow users to turn entity-page value scaling on or off | ✅ Met | The configurable font thresholds let users keep the default font by setting both limits to 255, and the documented defaults preserve the existing scaling behavior. |
#598 `Bug` NSPanel Easy Blueprint v2026.10.7 intermittently fails while refreshing the climate details page · 1 of 1 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Handle climate refreshes when old_state is absent | ✅ Met | The refresh template checks whether old_state exists before reading it and treats a missing prior state as a reason to push the options again. |
#601 `Enhancement` Allow group entities for hardware buttons · 2 of 2 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Allow group entities as hardware-button entities and state indicators | ✅ Met | The group domain is added to both hardware-button selectors. |
| 2 | Toggle group members together according to the group state | ✅ Met | A press turns all members off when the group is on and on when it is off. |
#619 QR code longer than 63 characters is not restored after reboot · 1 of 1 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Persist QR codes up to the Nextion component's supported length | ✅ Met | The QR string restore limit is set to 105 characters, and the title also receives an explicit restore limit. |
#625 `Bug` Concurrent binding pushes interleave on automation reload; panels reboot twice · 1 of 1 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Prevent concurrent binding pushes from mixing | ✅ Met | A repeated target restarts staging, and staged bindings are compared with the live set by target rather than position. |
|
@coderabbitai resume |
Action performed
|
|
@coderabbitai review |
Sourcery withdrew this approval because it has stopped reviewing this pull request.
|
Sourcery has withdrawn its approval of this pull request. It auto-reviews a pull request 5 times, and this push is past that limit, so the approval no longer reflects code Sourcery has read. Comment |
|
@sourcery-ai review |
|
Sorry @edwardtfn, your pull request is larger than the review limit of 150,000 diff characters |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Action not completed
|
…nt the upload_tft prerequisite
Highlights
A release shaped by the community
Most of the changes in this release come from contributors, which is what keeps this project moving. Thank you!
EnhancementGraph page for the history of a numeric sensor #579, feat: Add a graph page for the Home page values #590)Graph page for the Home page values
Each of the four Home page values has a new Graph option. When it is enabled, tapping the value (or its icon) opens a page with a graph of the entity over the last 24 hours, one point per 5 minutes, together with the current value, the lower and upper bounds of the scale and the local time every 6 hours. The scale is automatic by default, and either bound can be fixed with the new Graph minimum and Graph maximum inputs. The graph is drawn from the recorder statistics of Home Assistant, so only sensors with a
state_classofmeasurementormeasurement_anglecan be graphed. Seedocs/blueprint.md. Contributed by @JPicard90. (#579, #590)Stale values indicated while Home Assistant is disconnected
When Home Assistant is unreachable for longer than a grace period (30 seconds by default), the home page no longer shows its last received values as if they were current. Chips from Home Assistant entities, the home custom buttons and the weather picture are hidden, the outdoor temperature and the home values are grayed out, and the indoor temperature falls back to the panel's own sensor. Short drops, like a Home Assistant restart, leave the display untouched, and the relay and embedded thermostat chips are not affected, as they are controlled locally. Everything is restored as soon as the connection is back, without waiting for a state change in Home Assistant. The grace period can be changed with the new
api_stale_grace_periodsubstitution, documented indocs/substitutions.md. (#519, #580)Active climate preset on the climate page
The preset button on the climate page now shows which preset is active. For the standard presets (home, away, boost, comfort, eco, sleep and activity), the button shows the same icon Home Assistant uses for that preset, and it is highlighted while a preset is active. When no preset is active, or for custom presets, the button keeps the generic preset icon. This works for Home Assistant climate entities and for the embedded thermostat, where the panel updates the button itself, so it keeps working while Home Assistant is unavailable. (#613)
Bluetooth Proxy and TFT updates together
The documentation no longer recommends disabling Bluetooth Proxy for TFT updates. The TFT upload add-on releases the Bluetooth memory before the upload starts, so both add-ons can be enabled at the same time, including for automatic TFT updates. See
docs/install.mdanddocs/addon_upload_tft.md. (#578, #584)Improvements
group.*) can now be selected as the entity and as the State Indicator Entity of the left and right hardware buttons. A press turns all members off when the group is on, and all on when it is off, so a group with mixed states ends up in one state. The members must supportturn_onandturn_off(e.g. lights, switches, fans or covers). (EnhancementAllow group entities for hardware buttons #601, feat: Allow group entities for hardware buttons #602)page_entities_value_font_large_max_len(default8) andpage_entities_value_font_medium_max_len(default12) substitutions, documented indocs/substitutions.md. The defaults are unchanged. (Enhancemententity pages text scaling switch #593, improve: Make entities page value font thresholds configurable #596)Bug fixes
sundomain show a night icon. Before, the day pictures were always shown. The forecast pages show the night pictures only for a forecast that covers only the night, and keep the day pictures otherwise. Theexceptionalcondition also shows its picture again, instead of failing with an error in Home Assistant. Contributed by @Bascht74. (fix: Show the night picture on today's weather page after sunset #600, fix: Show night pictures on forecast pages only for night-only forecasts #614)Enhancemententity pages text scaling switch #593, fix: Size entities page values correctly for non-Latin text #599)Invalid variable namewarning. The log no longer shows this warning each time the Blueprint sets up the panel with the utilities button on the home page. Contributed by @Bascht74. (fix: Stop the Invalid variable name warning when the Blueprint sets up the panel #604)iconaction are also kept, instead of being replaced by the Blueprint color after Home Assistant reconnects or the display restarts. (Bugtexts and icon set through API are now more visible if not configured in blueprint #591, fix: Keep values and icon colors set through the API on unconfigured home page slots #597)qrcode_restore_value: true, QR codes longer than 63 characters, like most Wi-Fi codes, are now restored after a reboot, instead of the panel showing an older code or the initial value until Home Assistant sends the code again. (QR code longer than 63 characters is not restored after reboot #619, fix: Restore QR codes longer than 63 characters after reboot #622)UndefinedErroraboutold_statewhile refreshing an open climate page. (BugNSPanel Easy Blueprint v2026.10.7 intermittently fails while refreshing the climate details page #598)BugConcurrent binding pushes interleave on automation reload; panels reboot twice #625, fix: Prevent concurrent binding pushes from mixing and restarting the panel #626)Documentation
docs/backup_stock_firmware.mdexplains how to back up the original firmware before the first flash, and how to restore it later. Each panel's original firmware holds unique device credentials that the first flash erases, so this backup is the only way to fully return a panel to its original state, for example to claim the warranty. (docs: Add guide to back up the original Sonoff firmware #618)docs/network.mdcovers the panel network settings: Wi-Fi, DHCP or a manual IP address, gateway and DNS, different subnets and VLANs, and the connection to Home Assistant. It also explains why the panel needs internet access (only to download the TFT from GitHub), what happens when it is blocked, and which firewall rules to use. The network examples moved there fromdocs/customization.md. (docs: Add network guide #623)docs/customization.mdanddocs/addon_espectre.md, as neither is part of the standard configuration anymore. (docs: Remove outdated web server and captive portal references #624)docs/substitutions.mdlists the substitutions you can set in your panel's YAML, with the default and the effect of each one. (docs: Add a reference of the ESPHome substitutions available to users #582)SECURITY.mdexplains how to report vulnerabilities privately, andCODE_OF_CONDUCT.mdadopts the Contributor Covenant 3.0 for the repository, the Discord server and the Home Assistant Community forum thread. (docs: Add security policy and code of conduct #586)docs/ai_usage.mddescribes how AI is used in this project, how to identify posts from thepanel-easy-assistant[bot]account, and the expectations for AI-assisted contributions. (docs: Add section on how AI is used in this project #585)docs/howto.mdgives one path for the default configuration: update the firmware, let the TFT update automatically, then re-import the Blueprint. The README, the installation guide and the firmware version notification now point to it, and no longer ask to editref:or to follow a component update order. (EnhancementClearer update instructions #588, docs: Simplify update instructions #589)Other changes
actions/setup-python7.1.0,DavidAnson/markdownlint-cli2-action25.0.0 andflake87.5.0. (ci: bump actions/setup-python from 7.0.0 to 7.1.0 in the actions-official group #608, build: bump flake8 from 7.4.1 to 7.5.0 in /.github #627, ci: bump actions/setup-python from 7.0.0 to 7.1.0 in the actions-official group #628, ci: bump DavidAnson/markdownlint-cli2-action from 24.2.0 to 25.0.0 in the actions-markdown group #629)Update notes
docs/howto.md: update the firmware, let the TFT update automatically, then re-import the Blueprint.qrcode_restore_valueis enabled, the QR code and its title are not restored on the first boot after the update. They are shown again once Home Assistant sends the code, and restored normally from then on.Closes #519
Closes #579
Closes #588
Closes #591
Closes #593
Closes #598
Closes #601
Closes #619
Closes #625
Related to #478, #514, #548, #578 and #609
Summary by Sourcery
Improve resilience and transparency when Home Assistant is unavailable, expand ESPHome configuration documentation, and simplify panel maintenance guidance.
New Features:
Bug Fixes:
Enhancements:
CI:
Documentation:
Chores:
Summary by CodeRabbit
New Features
Bug Fixes
Documentation