[ci skip] home assistant integration

README.md

@@ -13,6 +13,7 @@ The code has been updated to support more of the protocol published by Victron a
 This project is based on the original open source `invertergui` project by Hendrik van Wyk and contributors:
 
 - Original repository: https://github.com/diebietse/invertergui
+- Home Assistant `victron-mk3-hass` inspiration: https://github.com/j9brown/victron-mk3-hass
 
 ## Demo
 
@@ -428,6 +429,119 @@ plus remote panel controls for:
 The combined mode + current limit behavior is provided through the `panel_state` MQTT command kind,
 which mirrors `victron_mk3.set_remote_panel_state`.
 
+### Home Assistant Custom Component (MQTT)
+
+This repository also includes a custom Home Assistant integration at:
+
+- `custom_components/victron_mk2_mqtt`
+
+This component is useful if you want HA entities/services that are explicitly tied to
+`invertergui` MQTT topics, instead of relying only on MQTT auto-discovery entities.
+
+If you use this custom component, you can disable `--mqtt.ha.enabled` in `invertergui`
+to avoid duplicate entities created by MQTT discovery.
+
+Install via HACS:
+
+1. Add the integration repository in Home Assistant:
+   [![Open your Home Assistant instance and open this repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=nathan&repository=invertergui&category=integration)
+2. Install `Victron MK2 MQTT` from HACS.
+3. Restart Home Assistant.
+4. Add the YAML configuration shown below.
+
+If you are not mirroring this repo to GitHub, use the manual install method below.
+
+Manual install (alternative):
+
+```text
+<home-assistant-config>/custom_components/victron_mk2_mqtt
+```
+
+Then add YAML config:
+
+```yaml
+victron_mk2_mqtt:
+  name: Victron Inverter
+  state_topic: invertergui/updates
+  command_topic: invertergui/settings/set
+  status_topic: invertergui/settings/status
+  # topic_root is optional; defaults to state_topic root (for example "invertergui")
+  # topic_root: invertergui
+```
+
+Provided entities include:
+
+- Telemetry sensors (battery/input/output voltage/current/frequency and derived power)
+- `Remote Panel Mode` (`charger_only`, `inverter_only`, `on`, `off`)
+- `Remote Panel Current Limit` (A)
+- `Remote Panel Standby`
+- Diagnostic entities (`Data Valid`, `Last Command Error`)
+
+Service exposed by the integration:
+
+- `victron_mk2_mqtt.set_remote_panel_state`
+
+Example service call:
+
+```yaml
+service: victron_mk2_mqtt.set_remote_panel_state
+data:
+  mode: on
+  current_limit: 16.0
+```
+
+### Home Assistant MQTT-Only Dashboard (No Duplicate Entities)
+
+If you want the same control/telemetry experience but only via MQTT (without duplicate
+entities from discovery/custom integrations), use the packaged Home Assistant files:
+
+- MQTT entity + control package: `homeassistant/packages/invertergui_mqtt.yaml`
+- Lovelace dashboard: `homeassistant/dashboards/invertergui_mqtt_dashboard.yaml`
+
+The package assumes default topics (`invertergui/updates`, `invertergui/settings/set`,
+`invertergui/settings/status`). If you use custom MQTT topics, update those values in
+`homeassistant/packages/invertergui_mqtt.yaml`.
+
+Recommended for this mode:
+
+- Disable MQTT discovery output from `invertergui` (`--mqtt.ha.enabled=false`)
+- Do not enable the `victron_mk2_mqtt` custom component at the same time
+
+1. Ensure HA packages are enabled (if not already):
+
+```yaml
+homeassistant:
+  packages: !include_dir_named packages
+```
+
+2. Copy package file to your HA config:
+
+```text
+<home-assistant-config>/packages/invertergui_mqtt.yaml
+```
+
+3. Copy dashboard file to your HA config:
+
+```text
+<home-assistant-config>/dashboards/invertergui_mqtt_dashboard.yaml
+```
+
+4. Register the dashboard (YAML mode example):
+
+```yaml
+lovelace:
+  mode: storage
+  dashboards:
+    invertergui-victron:
+      mode: yaml
+      title: Victron MQTT
+      icon: mdi:flash
+      show_in_sidebar: true
+      filename: dashboards/invertergui_mqtt_dashboard.yaml
+```
+
+5. Restart Home Assistant.
+
 ## TTY Device
 
 The intertergui application makes use of a serial tty device to monitor the Multiplus.