New integration: Victron VRM Forecasts #38749
Conversation
|
It seems that this PR is targeted against an incorrect branch. Documentation updates which apply to our current stable release should target the |
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughA new documentation file has been introduced for the Victron VRM Forecasts integration in Home Assistant. This documentation outlines the integration's capabilities to import solar production and consumption forecasts from the Victron VRM portal using the VRM REST API v2. It details prerequisites, setup instructions, sensor entities provided, integration with the Energy dashboard, troubleshooting guidance, and relevant external resources. The integration supports configuration via Home Assistant's config flow and is categorized under Energy with cloud polling as the IoT class. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant HomeAssistant
participant VRM_API
User->>HomeAssistant: Configure VRM Forecasts Integration (provide token, site ID)
HomeAssistant->>VRM_API: Request forecast data (production & consumption)
VRM_API-->>HomeAssistant: Return forecast data
HomeAssistant->>HomeAssistant: Create/update forecast sensor entities
User->>HomeAssistant: Add sensors to Energy dashboard
HomeAssistant-->>User: Display forecast data and peak times
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
source/_integrations/vrm_forecasts.markdown (2)
17-18: Enhance introduction clarity
Consider rephrasing the opening sentence for conciseness and readability. For example:
“Pulls day-ahead and next-hour solar production and consumption forecasts from the Victron VRM portal (via REST API v2) into Home Assistant’s Energy dashboard and as individual sensors.”
77-83: Expand troubleshooting tips
Consider adding checks for token expiration/permissions (e.g., “Verify the access token is valid and has necessary scopes”) and inspecting Home Assistant logs for API fetch errors to help users diagnose common connectivity issues.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/vrm_forecasts.markdown(1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/vrm_forecasts.markdown
[uncategorized] ~43-~43: Loose punctuation mark.
Context: ...or.energy_production_estimate_yesterday`: Estimated energy production — Yesterday...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~55-~55: Loose punctuation mark.
Context: ...r.energy_consumption_estimate_yesterday`: Estimated energy consumption — Yesterda...
(UNLIKELY_OPENING_PUNCTUATION)
🔇 Additional comments (5)
source/_integrations/vrm_forecasts.markdown (5)
1-15: Front matter validation
All metadata fields (title, description, ha_category, ha_release, ha_iot_class, ha_config_flow, ha_codeowners, ha_domain, ha_platforms, ha_integration_type) are correctly specified and adhere to Home Assistant documentation standards.
33-37: Config flow inclusion
Theintegrations/config_flow.mdsnippet is correctly included and wrapped between horizontal rules, providing standard UI configuration instructions.
39-52: Solar sensor entities approved
The definitions and descriptions for the solar production forecast sensors are clear, consistent, and follow naming conventions used elsewhere in the platform.🧰 Tools
🪛 LanguageTool
[uncategorized] ~43-~43: Loose punctuation mark.
Context: ...or.energy_production_estimate_yesterday`: Estimated energy production — Yesterday...(UNLIKELY_OPENING_PUNCTUATION)
53-63: Consumption sensor entities approved
The definitions and descriptions for the consumption forecast sensors are clear, consistent, and correctly mirror the structure of the production sensors.🧰 Tools
🪛 LanguageTool
[uncategorized] ~55-~55: Loose punctuation mark.
Context: ...r.energy_consumption_estimate_yesterday`: Estimated energy consumption — Yesterda...(UNLIKELY_OPENING_PUNCTUATION)
86-91: Useful links validated
External references to the VRM API docs, VRM Portal manual, and VRM portal are accurate and relevant.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
source/_integrations/vrm_forecasts.markdown (3)
21-26: Consider adding API scopes to prerequisites
To help users provision their access token correctly, you could explicitly document the required VRM API scopes in the prerequisites section.- **VRM access token** (keep this secret!). Create one in the VRM Portal at **Preferences → Integrations → Access tokens** or use [this link](https://vrm.victronenergy.com/access-tokens). + - **Required API scopes**: `read:forecast`, `read:site` - **VRM Site ID**: found under **Settings → General** in your site’s VRM Portal page.
40-43: Grammar in Data Updates
Minor nitpick: the sentence could read more smoothly by explicitly referring to “integration” or using a neutral subject.- The Victron VRM Forecasts fetches fresh data from the VRM API every 60 minutes. + The Victron VRM Forecasts integration fetches fresh data from the VRM API every 60 minutes.
44-69: Sensor Entities: Consider tables for clarity
While bullet lists work, presenting entities in a table (with columns for Entity ID, Friendly Name, Unit, etc.) can improve readability and ensure consistency with other integration docs.Example structure:
| Entity ID | Description | Unit | |---------------------------------------------|------------------------------------------|------| | `sensor.energy_production_estimate_yesterday` | Estimated energy production — Yesterday | kWh | ...🧰 Tools
🪛 LanguageTool
[uncategorized] ~48-~48: Loose punctuation mark.
Context: ...or.energy_production_estimate_yesterday`: Estimated energy production — Yesterday...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~60-~60: Loose punctuation mark.
Context: ...r.energy_consumption_estimate_yesterday`: Estimated energy consumption — Yesterda...(UNLIKELY_OPENING_PUNCTUATION)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/vrm_forecasts.markdown(1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/vrm_forecasts.markdown
[uncategorized] ~48-~48: Loose punctuation mark.
Context: ...or.energy_production_estimate_yesterday`: Estimated energy production — Yesterday...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~60-~60: Loose punctuation mark.
Context: ...r.energy_consumption_estimate_yesterday`: Estimated energy consumption — Yesterda...
(UNLIKELY_OPENING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (7)
source/_integrations/vrm_forecasts.markdown (7)
1-15: Front Matter Metadata
The YAML front matter is correctly populated with the expected keys (title,description,ha_category, etc.) and matches the upcoming 2025.5 release. All required metadata appears in place.
17-18: Introduction Clarity
The overview succinctly describes the integration’s purpose and capabilities. It’s clear and follows Home Assistant documentation conventions.
27-32: Admonition Usage
The{% hint style="important" %}block is used correctly and follows the recommended macro syntax for security notices.
36-36: Config Flow Include
Including theintegrations/config_flow.mdsnippet ensures users see the standard configuration UI flow without duplication—good reuse of shared docs.
72-79: Adding to the Energy Dashboard
The step-by-step instructions are clear and accurate. They correctly guide users through adding forecast production to the Energy dashboard.
82-90: Troubleshooting Guidance
The troubleshooting section covers the common failure modes (missing sensors, auth issues, API errors) thoroughly.
93-98: Useful Links
The curated list of external resources is appropriate and correctly formatted.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
source/_integrations/vrm_forecasts.markdown (6)
3-3: Refine the description field.
Current:description: Instructions for implementation of Victron VRM Forecasts into Home Assistant.Consider making it more concise and action-oriented, for example:
description: Pull solar production and consumption forecasts from Victron VRM into Home Assistant.This helps users immediately grasp the integration’s purpose.
17-19: Replace horizontal rules with headings.
The repeated---lines render as<hr>but may not match the style of other docs. Consider removing them and relying solely on##-style headings for section separation to maintain consistency.
27-32: Standardize admonition syntax.
Home Assistant docs often favor the hint macro for consistency. Instead of:{% important %} Your VRM access token… {% endimportant %}use:
{% hint style="important" %} Your VRM access token… {% endhint %}This aligns with other
hint-based blocks and ensures uniform styling.
40-43: Clarify data update interval.
You note “fetches fresh data… every 60 minutes.” If this interval is fixed, mention that it cannot be altered. If it’s user-configurable, indicate where or how to adjust it.
72-79: Clarify Energy Dashboard instructions.
Since only production forecasts can be added under Solar panels, consider adding a note like:Consumption forecast sensors are not yet supported in the Energy dashboard UI.
This will help users understand why they don’t see consumption options.
82-90: Enhance troubleshooting guidance.
To further assist users:
- Include example log excerpts for common errors (e.g., 401/403 API errors).
- Link to the UI path where one updates the access token and site ID.
These additions can reduce back-and-forth on the forums.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/vrm_forecasts.markdown(1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/vrm_forecasts.markdown
[uncategorized] ~48-~48: Loose punctuation mark.
Context: ...or.energy_production_estimate_yesterday`: Estimated energy production — Yesterday...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~60-~60: Loose punctuation mark.
Context: ...r.energy_consumption_estimate_yesterday`: Estimated energy consumption — Yesterda...
(UNLIKELY_OPENING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (5)
source/_integrations/vrm_forecasts.markdown (5)
1-15: Verify front matter keys and formatting.
The YAML front matter should align with the standard integration template. In particular:
- Confirm that
ha_iot_classuses the correct canonical value (cloud_pollingvs.Cloud Polling) as seen in other docs.- Ensure required keys such as
sidebar_titleandlayoutare present if your project’s template mandates them.
Please cross-check this file against an official integration reference to avoid rendering issues.
36-36: Confirm the config flow include.
Good use of{% include integrations/config_flow.md %}. Please verify thatconfig_flow.mdexists insource/_includes/integrations/and renders correctly in context.
44-69: Verify sensor entity IDs.
The list of entities under Solar Production Forecast and Consumption Forecast must exactly match the code-generatedentity_ids. Even small typos (e.g., missing underscores) will prevent sensors from appearing. Please cross-check these against the integration’sconst.pyor the sensor registration logic.🧰 Tools
🪛 LanguageTool
[uncategorized] ~48-~48: Loose punctuation mark.
Context: ...or.energy_production_estimate_yesterday`: Estimated energy production — Yesterday...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~60-~60: Loose punctuation mark.
Context: ...r.energy_consumption_estimate_yesterday`: Estimated energy consumption — Yesterda...(UNLIKELY_OPENING_PUNCTUATION)
95-98: Validate external links.
Please click through and confirm that:
- The VRM JSON API v2 docs URL is correct and up to date.
- The VRM Portal manual link still resolves.
- The base VRM Portal URL hasn’t changed.
Broken links here will lead to support tickets.
48-48: The LanguageTool warnings about loose punctuation at the sensor list lines are false positives—those colons are required for proper Markdown formatting.Also applies to: 60-60
🧰 Tools
🪛 LanguageTool
[uncategorized] ~48-~48: Loose punctuation mark.
Context: ...or.energy_production_estimate_yesterday`: Estimated energy production — Yesterday...(UNLIKELY_OPENING_PUNCTUATION)
Proposed change
Added documentation for the new Victron VRM Forecasts integration.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit