Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Initial Victron Venus documentation. #35739

Open
wants to merge 2 commits into
base: next
Choose a base branch
from
Open

Initial Victron Venus documentation. #35739

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2748278
Documentation for Victron Venus based integration. Ref Pull Request #…
JohansLab Nov 14, 2024
0349389
Fix ha_release.
JohansLab Nov 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions source/_integrations/victronvenus.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
title: "Victron Venus OS Integration"
description: "Documentation for the Victron Venus integration"
ha_release: "2024.12"
ha_category: Sensor
ha_iot_class: "Local Push"
ha_config_flow: true
ha_codeowners:
- '@JohansLab'
ha_domain: victronvenus

Comment on lines +1 to +11
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codebase verification

Release version "2024.12" seems far in the future

  • Please confirm if this version is intentional.
  • The "Energy" category is not recognized in the current integrations. Consider using existing categories or defining "Energy" appropriately.
🔗 Analysis chain

Verify the release version and integration categories

A few suggestions for the metadata:

  1. The release version "2024.12" seems quite far in the future. Please verify if this is the intended version.
  2. Consider adding more categories based on the integration's capabilities:
    • "Energy" - since it provides energy-related sensors
    • "Battery" - for battery monitoring features
    • "Solar" - for solar panel monitoring
🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Check other energy-related integrations for consistent categorization
rg -l "ha_category:.*Energy" source/_integrations/

Length of output: 52

Script:

#!/bin/bash
# Search for category definitions in documentation
rg "ha_category:" docs/

Length of output: 69

Script:

#!/bin/bash
# List all category definitions in integrations
rg "ha_category:" source/_integrations/

Length of output: 71645

---

The Victron Venus OS integration allows connection to a Venus Victron OS device
that has local MQTT enabled. This add-on will automatically configure the
integration through UPnP/Simple Service Discovery Protocol if possible.

### List of exposes sensors

#### Grid Sensors

- The number of grid phases e.g. 1 for single-phase, or 3 for three-phase.
If there is a grid failure then the number of phases will be 0. This can be used
detect grid failure.
- The AC voltage, current and power for each of the available grid phases.
- The combined voltage, current and power for the combined grid input.
- The lifetime running total of all energy consumed from the grid, or fed back
to the grid. These figures generally only makes sense as delta values.

#### Solar Panels

- The DC voltage, current and power of the solar panels.
- The lifetime running total yield of the solar panels. These figures generally
only makes sense as delta values.
- The maximum power produced by the solar panels for the current day.

#### Batteries

- The DC voltage, current and power of the batteries.
- The temperature of the battery.
- The lifetime running total of energy charged and discharged from the battery.
These figures generally only makes sense as delta values.
- The current capacity and installed capacity of the batteries in Ampere-Hours (Ah).
- The state of charge of the batteries.

#### Consumption

- The AC Load in watts on the inverter input.
- The Critical Loads in watts on the inverter output.

### Enabling local MQTT on a Victron Venus device

If your Victron Venus device is not automatically detected ensure that MQTT on
LAN is enabled. To enable MQTT on your device the following instructions can be
followed (as tested on a Cerbo GX):

- Connect to your device using a browser. By default the device should be
available at [http://venus.local.](http://venus.local./).
- In the menu navigate to Settings > Services and ensure MQTT on LAN is switched
on.
Comment on lines +53 to +60
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix grammar and URL formatting issues

  1. Add missing commas:
-If your Victron Venus device is not automatically detected ensure that MQTT on
+If your Victron Venus device is not automatically detected, ensure that MQTT on
-By default the device should be
+By default, the device should be
  1. Fix malformed URL:
-[http://venus.local.](http://venus.local./).
+[http://venus.local](http://venus.local)
  1. Consider adding troubleshooting steps for common issues:
    • What to do if the device is not available at the default URL
    • How to verify MQTT is working correctly
    • Common error messages and their solutions

Committable suggestion skipped: line range outside the PR's diff.

🧰 Tools
🪛 LanguageTool

[uncategorized] ~53-~53: Possible missing comma found.
Context: ...ctron Venus device is not automatically detected ensure that MQTT on LAN is enabled. To ...

(AI_HYDRA_LEO_MISSING_COMMA)

[uncategorized] ~57-~57: Did you mean: “By default,”?
Context: ...Connect to your device using a browser. By default the device should be available at [htt...

(BY_DEFAULT_COMMA)

[uncategorized] ~59-~59: Possible missing comma found.
Context: ...local.](http://venus.local./). - In the menu navigate to Settings > Services and ens...

(AI_HYDRA_LEO_MISSING_COMMA)

Comment on lines +51 to +60
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Enhance setup instructions with troubleshooting steps

Consider adding:

  1. Network requirements and firewall settings
  2. MQTT broker configuration details (port, authentication if needed)
  3. Steps to verify successful connection
  4. Common error messages and their solutions
🧰 Tools
🪛 LanguageTool

[uncategorized] ~53-~53: Possible missing comma found.
Context: ...ctron Venus device is not automatically detected ensure that MQTT on LAN is enabled. To ...

(AI_HYDRA_LEO_MISSING_COMMA)

[uncategorized] ~57-~57: Did you mean: “By default,”?
Context: ...Connect to your device using a browser. By default the device should be available at [htt...

(BY_DEFAULT_COMMA)


### Limitations

The integration currently has the following limitations:

- The integration was built and tested against an installation consisting of a
single-phase grid-tied Multiplus Inverter, with a single MPPT Solar Charger and
a battery that contains its own BMS. Your installation might have a different
configuration.
- The integration does not currently support generators and other configuration
options.
- The integration currently only exposes sensors, it does not yet allow changing
settings from Home Assistant.
- This integration was not tested with MQTT with SSL.