# Inverter GUI [Repository](https://git.coadcorp.com/nathan/invertergui) | [Container Image](https://registry.coadcorp.com/nathan/invertergui) The invertergui allows the monitoring of a [Victron Multiplus](https://www.victronenergy.com/inverters-chargers/multiplus-12v-24v-48v-800va-3kva) via the [MK3/MK2 USB](https://www.victronenergy.com/accessories/interface-mk3-usb) or the MK2 RS232. The [`registry.coadcorp.com/nathan/invertergui`](https://registry.coadcorp.com/nathan/invertergui) container image is a build of this repository. The code has been updated to support more of the protocol published by Victron at https://www.victronenergy.com/upload/documents/Technical-Information-Interfacing-with-VE-Bus-products-MK2-Protocol-3-14.pdf ## Acknowledgements 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 ![demo](./invertergui_demo.gif "Invertergui Demo") ## Quick Start ```console docker run --name invertergui --device /dev/ttyUSB0:/dev/ttyUSB0 -p 8080:8080 registry.coadcorp.com/nathan/invertergui:latest ``` ## Requirements This project makes use of [Go Modules](https://github.com/golang/go/wiki/Modules). The minimum supported version for Go is 1.22 ## Driver API: Metadata + Safe Transactions The MK2 driver now includes a metadata and transaction safety layer via the `mk2driver.MetadataControl` interface: - Register metadata lookup (`RegisterMetadata`, `ListRegisterMetadata`) - Generic register reads by kind/id (`ReadRegister`) - Transactional writes with retry and verify (`WriteRegister`) `WriteRegister` supports: - `ReadBeforeWrite` - `VerifyAfterWrite` - configurable retry count and delay This layer is additive and does not replace existing `WriteSetting`, `WriteRAMVar`, or panel control APIs. ## Advanced Control + Orchestration Features The codebase now includes: - Full MK2 command-path coverage in driver APIs for: - `0x0E` device state read/write - register read by id (`0x30`, `0x31`) - selected read/write flows (`0x32`, `0x33`, `0x34`, `0x35`) - RAM var metadata/info (`0x36`) - write-by-id flows (`0x37`, `0x38`) - Register metadata with `unit`, `min/max`, `scale`, `writable`, and `safety_class`. - Transaction-safe writes with read-before-write, verify-after-write, retry/backoff, and timeout classes. - Snapshot/diff/restore register workflows with rollback on partial restore failure. - Alarm engine with LED/state alarms + command-failure alarms, including debounce and clear behavior. - Venus-like derived operating state model: `Off`, `Inverter`, `Charger`, `Passthru`, `Fault`. - Historical counters for energy and availability: - `energy_in_wh`, `energy_out_wh` - battery charge/discharge Wh - uptime seconds - fault count + last fault timestamp - Multi-device orchestration fields and topics: - `device_id`, `instance_id`, `phase`, `phase_group` - per-device topics and phase-group fanout topics - Command arbitration/policy layer: - single serialized write path - lockout windows - source tagging (`ui`, `mqtt`, `automation`) - max current guardrail + mode rate limit + maintenance/read-only profiles - Venus-compatible MQTT mode (`N/...` + optional `W/...`) for HA/Node-RED/VRM-style workflows. - Guide-style Victron ESS MQTT paths (`settings/0/Settings/CGwacs/*`) with `victron/N/...` and `victron/W/...` prefix compatibility. - Structured diagnostics bundle topics with protocol traces, recent command history, and health score. ## Getting started ```bash Usage: invertergui [OPTIONS] Application Options: --address= The IP/DNS and port of the machine that the application is running on. (default: :8080) [$ADDRESS] --read_only Disable all write operations and run in monitoring-only mode. [$READ_ONLY] --data.source= Set the source of data for the inverter gui. "serial", "tcp" or "mock" (default: serial) [$DATA_SOURCE] --data.host= Host to connect when source is set to tcp. (default: localhost:8139) [$DATA_HOST] --data.device= TTY device to use when source is set to serial. (default: /dev/ttyUSB0) [$DATA_DEVICE] --cli.enabled Enable CLI output. [$CLI_ENABLED] --mqtt.enabled Enable MQTT publishing. [$MQTT_ENABLED] --mqtt.broker= Set the host port and scheme of the MQTT broker. (default: tcp://localhost:1883) [$MQTT_BROKER] --mqtt.client_id= Set the client ID for the MQTT connection. (default: inverter-gui) [$MQTT_CLIENT_ID] --mqtt.topic= Set the MQTT topic updates published to. (default: invertergui/updates) [$MQTT_TOPIC] --mqtt.command_topic= Set the MQTT topic that receives write commands for Victron settings/RAM variables. (default: invertergui/settings/set) [$MQTT_COMMAND_TOPIC] --mqtt.status_topic= Set the MQTT topic where write command status updates are published. (default: invertergui/settings/status) [$MQTT_STATUS_TOPIC] --mqtt.device_id= Set logical device ID used for per-device orchestration topics. (default: invertergui) [$MQTT_DEVICE_ID] --mqtt.history_size= Number of samples retained for rolling history summaries. (default: 120) [$MQTT_HISTORY_SIZE] --mqtt.instance_id= Device instance ID for multi-device orchestration and Venus compatibility. (default: 0) [$MQTT_INSTANCE_ID] --mqtt.phase= Electrical phase label for this instance (L1/L2/L3). (default: L1) [$MQTT_PHASE] --mqtt.phase_group= Grouping key for parallel/3-phase system aggregation topics. (default: default) [$MQTT_PHASE_GROUP] --mqtt.ha.enabled Enable Home Assistant MQTT discovery integration. [$MQTT_HA_ENABLED] --mqtt.ha.discovery_prefix= Set Home Assistant MQTT discovery prefix. (default: homeassistant) [$MQTT_HA_DISCOVERY_PREFIX] --mqtt.ha.node_id= Set Home Assistant node ID used for discovery topics and unique IDs. (default: invertergui) [$MQTT_HA_NODE_ID] --mqtt.ha.device_name= Set Home Assistant device display name. (default: Victron Inverter) [$MQTT_HA_DEVICE_NAME] --mqtt.venus.enabled Enable Venus-style MQTT compatibility topics (N/W model). [$MQTT_VENUS_ENABLED] --mqtt.venus.portal_id= Set Venus portal ID segment used in N/W topics. (default: invertergui) [$MQTT_VENUS_PORTAL_ID] --mqtt.venus.service= Set Venus service segment used in N/W topics. (default: vebus/257) [$MQTT_VENUS_SERVICE] --mqtt.venus.subscribe_writes Subscribe to Venus W/... topics and map to MK2 commands. [$MQTT_VENUS_SUBSCRIBE_WRITES] --mqtt.venus.topic_prefix= Optional topic prefix before Venus N/W topics, e.g. victron. [$MQTT_VENUS_TOPIC_PREFIX] --mqtt.venus.guide_compat Enable guide-style settings/0/Settings/CGwacs compatibility paths. [$MQTT_VENUS_GUIDE_COMPAT] --mqtt.username= Set the MQTT username [$MQTT_USERNAME] --mqtt.password= Set the MQTT password [$MQTT_PASSWORD] --mqtt.password-file= Path to a file containing the MQTT password [$MQTT_PASSWORD_FILE] --control.profile= Write policy profile: normal, maintenance, or read_only. (default: normal) [$CONTROL_PROFILE] --control.max_current_limit= Optional max AC current limit guardrail in amps (0 disables). (default: 0) [$CONTROL_MAX_CURRENT_LIMIT] --control.mode_change_min_interval= Minimum time between mode changes. (default: 3s) [$CONTROL_MODE_CHANGE_MIN_INTERVAL] --control.lockout_window= Post-command lockout window for command arbitration. (default: 0s) [$CONTROL_LOCKOUT_WINDOW] --control.allowed_panel_modes= Comma-separated allowlist of remote panel modes. Supported values: on, off, charger_only, inverter_only. Empty allows all modes. [$CONTROL_ALLOWED_PANEL_MODES] --loglevel= The log level to generate logs at. ("panic", "fatal", "error", "warn", "info", "debug", "trace") (default: info) [$LOGLEVEL] Help Options: -h, --help Show this help message ``` ### Read-Only Mode Set `READ_ONLY=true` (or `--read_only`) to disable all write operations. When read-only mode is enabled, the app still monitors and publishes telemetry, but it will not send commands to the Victron device. This affects: - MQTT command handling (`--mqtt.command_topic` commands are ignored) - Web UI control actions (`POST /api/remote-panel/state` and `POST /api/remote-panel/standby`) ### Remote Panel Mode Allowlist Set `CONTROL_ALLOWED_PANEL_MODES` (or `--control.allowed_panel_modes`) to restrict which remote panel modes can be selected from Web UI, MQTT, Home Assistant, and Venus-compatible write paths. Supported values: - `on` - `off` - `charger_only` - `inverter_only` Use a comma-separated list. Empty means all modes are allowed. Example: - `CONTROL_ALLOWED_PANEL_MODES=off,charger_only` Example `docker-compose.yml` snippet: ```yaml services: invertergui: image: registry.coadcorp.com/nathan/invertergui:latest environment: READ_ONLY: "true" CONTROL_ALLOWED_PANEL_MODES: "off,charger_only" devices: - "/dev/ttyUSB0:/dev/ttyUSB0" command: ["--mqtt.enabled", "--mqtt.broker=tcp://192.168.1.1:1883", "--loglevel=info"] ``` ### Home Assistant Guide-Style ESS Control To mimic the Victron community ESS control approach (MQTT `N/...` state + `W/...` writes under `settings/0/Settings/CGwacs/...`): 1. Start invertergui with: - `MQTT_VENUS_ENABLED=true` - `MQTT_VENUS_GUIDE_COMPAT=true` - `MQTT_VENUS_TOPIC_PREFIX=victron` - `MQTT_VENUS_PORTAL_ID=invertergui` (or your chosen portal id) 2. In Home Assistant: - Use the included custom integration (`custom_components/victron_mk2_mqtt`) which now exposes ESS-style entities and service calls. - Or use `homeassistant/packages/invertergui_mqtt.yaml`, which includes guide-style MQTT entities: - `number.victron_ess_grid_setpoint` - `number.victron_ess_max_charge_power` - `number.victron_ess_max_discharge_power` - `switch.victron_ess_optimized_mode` Compatibility note: - MK2/VE.Bus does not expose every Venus ESS feature one-to-one. This project maps ESS-style commands onto available MK2 controls (mode/current-limit/policy-safe behavior) to provide similar Home Assistant control flow. ## Port 8080 The default HTTP server port is hosted on port 8080. This exposes the HTTP server that hosts the: - Web GUI - Munin Plugin - Prometheus Monitor ### Web GUI The GUI location is at the root (http://localhost:8080/) of the HTTP server. Example output: ``` Date: Mon, 17 Dec 2018 18:14:51 +0000 LEDs: Mains Float Output Current: 1.580 A Output Voltage: 227.830 V Output Frequency: 50.026 Hz Output Power: 359.971 VA Input Current: 1.750 A Input Voltage: 227.830 V Input Frequency: 50.103 Hz Input Power: 398.703 VA Input - Output Power: 38.731 VA Battery Current: -0.050 A Battery Voltage: 13.170 V Battery Power: -0.659 W Battery Charge: 100.000 % ``` The web UI also includes a **Remote Panel Control** section for: - Remote Panel Mode (`on`, `off`, `charger_only`, `inverter_only`) - Remote Panel Current Limit (AC input current limit in amps) - Remote Panel Standby (prevent sleep while turned off) The combined mode + current limit action maps to the same behavior as `set_remote_panel_state` in `victron-mk3`. The backing HTTP API endpoints are: - `GET/POST /api/remote-panel/state` - `GET/POST /api/remote-panel/standby` ### Munin The Munin plugin location is at /munin (http://localhost:8080/munin). Example output: ``` multigraph in_batvolt volt.value 13.154 multigraph in_batcharge charge.value 100.000 multigraph in_batcurrent current.value -0.092 multigraph in_batpower power.value -1.209 multigraph in_mainscurrent currentin.value 1.860 currentout.value 1.676 multigraph in_mainsvoltage voltagein.value 225.786 voltageout.value 225.786 multigraph in_mainspower powerin.value 419.945 powerout.value 378.372 multigraph in_mainsfreq freqin.value 50.361 freqout.value 50.026 ``` ### Prometheus The Prometheus endpoint is at the default /metrics path (http://localhost:8080/metrics). Sample Prometheus yaml entry: ```yml - job_name: "victron" static_configs: - targets: ["localhost:8080"] ``` The metrics that are tracked: ``` # HELP battery_charge_percentage Remaining battery charge. # TYPE battery_charge_percentage gauge battery_charge_percentage 100 # HELP battery_current_a Battery current. # TYPE battery_current_a gauge battery_current_a -0.06 # HELP battery_power_w Battery power. # TYPE battery_power_w gauge battery_power_w -0.7896 # HELP battery_voltage_v Voltage of the battery. # TYPE battery_voltage_v gauge battery_voltage_v 13.16 # HELP go_gc_duration_seconds A summary of the GC invocation durations. # TYPE go_gc_duration_seconds summary go_gc_duration_seconds{quantile="0"} 5.3183e-05 go_gc_duration_seconds{quantile="0.25"} 0.000116 go_gc_duration_seconds{quantile="0.5"} 0.000156305 go_gc_duration_seconds{quantile="0.75"} 0.000313721 go_gc_duration_seconds{quantile="1"} 0.044886879 go_gc_duration_seconds_sum 0.394171418 go_gc_duration_seconds_count 58 # HELP go_goroutines Number of goroutines that currently exist. # TYPE go_goroutines gauge go_goroutines 8 # HELP go_info Information about the Go environment. # TYPE go_info gauge go_info{version="go1.11.3"} 1 # HELP go_memstats_alloc_bytes Number of bytes allocated and still in use. # TYPE go_memstats_alloc_bytes gauge go_memstats_alloc_bytes 3.21496e+06 # HELP go_memstats_alloc_bytes_total Total number of bytes allocated, even if freed. # TYPE go_memstats_alloc_bytes_total counter go_memstats_alloc_bytes_total 1.7361072e+08 # HELP go_memstats_buck_hash_sys_bytes Number of bytes used by the profiling bucket hash table. # TYPE go_memstats_buck_hash_sys_bytes gauge go_memstats_buck_hash_sys_bytes 1.451092e+06 # HELP go_memstats_frees_total Total number of frees. # TYPE go_memstats_frees_total counter go_memstats_frees_total 263807 # HELP go_memstats_gc_cpu_fraction The fraction of this program's available CPU time used by the GC since the program started. # TYPE go_memstats_gc_cpu_fraction gauge go_memstats_gc_cpu_fraction 0.00018297252897512647 # HELP go_memstats_gc_sys_bytes Number of bytes used for garbage collection system metadata. # TYPE go_memstats_gc_sys_bytes gauge go_memstats_gc_sys_bytes 2.37568e+06 # HELP go_memstats_heap_alloc_bytes Number of heap bytes allocated and still in use. # TYPE go_memstats_heap_alloc_bytes gauge go_memstats_heap_alloc_bytes 3.21496e+06 # HELP go_memstats_heap_idle_bytes Number of heap bytes waiting to be used. # TYPE go_memstats_heap_idle_bytes gauge go_memstats_heap_idle_bytes 6.2537728e+07 # HELP go_memstats_heap_inuse_bytes Number of heap bytes that are in use. # TYPE go_memstats_heap_inuse_bytes gauge go_memstats_heap_inuse_bytes 3.981312e+06 # HELP go_memstats_heap_objects Number of allocated objects. # TYPE go_memstats_heap_objects gauge go_memstats_heap_objects 5588 # HELP go_memstats_heap_released_bytes Number of heap bytes released to OS. # TYPE go_memstats_heap_released_bytes gauge go_memstats_heap_released_bytes 0 # HELP go_memstats_heap_sys_bytes Number of heap bytes obtained from system. # TYPE go_memstats_heap_sys_bytes gauge go_memstats_heap_sys_bytes 6.651904e+07 # HELP go_memstats_last_gc_time_seconds Number of seconds since 1970 of last garbage collection. # TYPE go_memstats_last_gc_time_seconds gauge go_memstats_last_gc_time_seconds 1.5450709952576678e+09 # HELP go_memstats_lookups_total Total number of pointer lookups. # TYPE go_memstats_lookups_total counter go_memstats_lookups_total 0 # HELP go_memstats_mallocs_total Total number of mallocs. # TYPE go_memstats_mallocs_total counter go_memstats_mallocs_total 269395 # HELP go_memstats_mcache_inuse_bytes Number of bytes in use by mcache structures. # TYPE go_memstats_mcache_inuse_bytes gauge go_memstats_mcache_inuse_bytes 3456 # HELP go_memstats_mcache_sys_bytes Number of bytes used for mcache structures obtained from system. # TYPE go_memstats_mcache_sys_bytes gauge go_memstats_mcache_sys_bytes 16384 # HELP go_memstats_mspan_inuse_bytes Number of bytes in use by mspan structures. # TYPE go_memstats_mspan_inuse_bytes gauge go_memstats_mspan_inuse_bytes 27208 # HELP go_memstats_mspan_sys_bytes Number of bytes used for mspan structures obtained from system. # TYPE go_memstats_mspan_sys_bytes gauge go_memstats_mspan_sys_bytes 32768 # HELP go_memstats_next_gc_bytes Number of heap bytes when next garbage collection will take place. # TYPE go_memstats_next_gc_bytes gauge go_memstats_next_gc_bytes 4.194304e+06 # HELP go_memstats_other_sys_bytes Number of bytes used for other system allocations. # TYPE go_memstats_other_sys_bytes gauge go_memstats_other_sys_bytes 775332 # HELP go_memstats_stack_inuse_bytes Number of bytes in use by the stack allocator. # TYPE go_memstats_stack_inuse_bytes gauge go_memstats_stack_inuse_bytes 589824 # HELP go_memstats_stack_sys_bytes Number of bytes obtained from system for stack allocator. # TYPE go_memstats_stack_sys_bytes gauge go_memstats_stack_sys_bytes 589824 # HELP go_memstats_sys_bytes Number of bytes obtained from system. # TYPE go_memstats_sys_bytes gauge go_memstats_sys_bytes 7.176012e+07 # HELP go_threads Number of OS threads created. # TYPE go_threads gauge go_threads 10 # HELP mains_current_in_a Mains current flowing into inverter # TYPE mains_current_in_a gauge mains_current_in_a 2.17 # HELP mains_current_out_a Mains current flowing out of inverter # TYPE mains_current_out_a gauge mains_current_out_a 2 # HELP mains_freq_in_hz Mains frequency at inverter input # TYPE mains_freq_in_hz gauge mains_freq_in_hz 50.36082474226804 # HELP mains_freq_out_hz Mains frequency at inverter output # TYPE mains_freq_out_hz gauge mains_freq_out_hz 50.153452685421996 # HELP mains_power_in_va Mains power in # TYPE mains_power_in_va gauge mains_power_in_va 491.6352 # HELP mains_power_out_va Mains power out # TYPE mains_power_out_va gauge mains_power_out_va 453.12 # HELP mains_voltage_in_v Mains voltage at input of inverter # TYPE mains_voltage_in_v gauge mains_voltage_in_v 226.56 # HELP mains_voltage_out_v Mains voltage at output of inverter # TYPE mains_voltage_out_v gauge mains_voltage_out_v 226.56 # HELP process_cpu_seconds_total Total user and system CPU time spent in seconds. # TYPE process_cpu_seconds_total counter process_cpu_seconds_total 39.73 # HELP process_max_fds Maximum number of open file descriptors. # TYPE process_max_fds gauge process_max_fds 1.048576e+06 # HELP process_open_fds Number of open file descriptors. # TYPE process_open_fds gauge process_open_fds 8 # HELP process_resident_memory_bytes Resident memory size in bytes. # TYPE process_resident_memory_bytes gauge process_resident_memory_bytes 1.2742656e+07 # HELP process_start_time_seconds Start time of the process since unix epoch in seconds. # TYPE process_start_time_seconds gauge process_start_time_seconds 1.54506833485e+09 # HELP process_virtual_memory_bytes Virtual memory size in bytes. # TYPE process_virtual_memory_bytes gauge process_virtual_memory_bytes 1.15101696e+08 ``` ### MQTT The MQTT client will publish updates to the given broker at the set topic. #### MQTT Configuration Options ```bash --mqtt.enabled Enable MQTT publishing. [$MQTT_ENABLED] --mqtt.broker= Set the host port and scheme of the MQTT broker. (default: tcp://localhost:1883) [$MQTT_BROKER] --mqtt.client_id= Set the client ID for the MQTT connection. (default: inverter-gui) [$MQTT_CLIENT_ID] --mqtt.topic= Set the MQTT topic updates published to. (default: invertergui/updates) [$MQTT_TOPIC] --mqtt.command_topic= Set the MQTT topic that receives write commands for Victron settings/RAM variables. (default: invertergui/settings/set) [$MQTT_COMMAND_TOPIC] --mqtt.status_topic= Set the MQTT topic where write command status updates are published. (default: invertergui/settings/status) [$MQTT_STATUS_TOPIC] --mqtt.device_id= Set logical device ID used for per-device orchestration topics. (default: invertergui) [$MQTT_DEVICE_ID] --mqtt.history_size= Number of samples retained for rolling history summaries. (default: 120) [$MQTT_HISTORY_SIZE] --mqtt.ha.enabled Enable Home Assistant MQTT discovery integration. [$MQTT_HA_ENABLED] --mqtt.ha.discovery_prefix= Set Home Assistant MQTT discovery prefix. (default: homeassistant) [$MQTT_HA_DISCOVERY_PREFIX] --mqtt.ha.node_id= Set Home Assistant node ID used for discovery topics and unique IDs. (default: invertergui) [$MQTT_HA_NODE_ID] --mqtt.ha.device_name= Set Home Assistant device display name. (default: Victron Inverter) [$MQTT_HA_DEVICE_NAME] --mqtt.venus.enabled Enable Venus-style MQTT compatibility topics (N/W model). [$MQTT_VENUS_ENABLED] --mqtt.venus.portal_id= Set Venus portal ID segment used in N/W topics. (default: invertergui) [$MQTT_VENUS_PORTAL_ID] --mqtt.venus.service= Set Venus service segment used in N/W topics. (default: vebus/257) [$MQTT_VENUS_SERVICE] --mqtt.venus.subscribe_writes Subscribe to Venus W/... topics and map to MK2 commands. [$MQTT_VENUS_SUBSCRIBE_WRITES] --mqtt.username= Set the MQTT username [$MQTT_USERNAME] --mqtt.password= Set the MQTT password [$MQTT_PASSWORD] --mqtt.password-file= Path to a file containing the MQTT password [$MQTT_PASSWORD_FILE] ``` Related global option: ```bash --read_only Disable all write operations and run in monitoring-only mode. [$READ_ONLY] ``` The MQTT client can be enabled by setting the environment variable `MQTT_ENABLED=true` or flag `--mqtt.enabled`. All MQTT configuration can be done via flags or as environment variables. The URI for the broker can be configured format should be `scheme://host:port`, where "scheme" is one of "tcp", "ssl", or "ws". When `--mqtt.command_topic` is configured, the application subscribes to that topic and accepts JSON write commands. The recommended command for inverter control follows the same model used by `victron-mk3`: ```json { "request_id": "optional-correlation-id", "kind": "panel_state", "switch": "on", "current_limit": 16.5 } ``` `switch` supports `charger_only`, `inverter_only`, `on`, and `off` (or numeric values `1..4`). `current_limit` is in amps and optional. If omitted, only the switch state is changed. To update only the current limit (while preserving the last known mode), send: ```json { "kind": "panel_state", "current_limit": 12.0 } ``` If no prior mode is known (for example on a fresh broker state), this command is rejected until a mode command is sent once. Standby can be controlled with: ```json { "kind": "standby", "standby": true } ``` Low-level writes are still supported: ```json { "kind": "setting", "id": 15, "value": 1 } ``` `kind` supports `panel_state`, `setting`, and `ram_var` (with aliases for each). The result is published to `--mqtt.status_topic` with status `ok` or `error`. ### MQTT Device Orchestration Topics For multi-device deployments on one MQTT broker, `invertergui` now also publishes device-scoped orchestration topics under: - `{topic-root}/devices/{device_id}/state` - `{topic-root}/devices/{device_id}/history/summary` - `{topic-root}/devices/{device_id}/alarms/active` Set `--mqtt.device_id` (or `MQTT_DEVICE_ID`) per inverter instance so each instance publishes to a unique device path. Rolling history depth for the summary window is set by `--mqtt.history_size`. ### Venus-Style MQTT Compatibility Enable Venus-compatible topics with: ```bash --mqtt.venus.enabled ``` When enabled, `invertergui` publishes Venus-style notifications to: - `N/{portal_id}/{service}/...` Defaults: - `portal_id`: `invertergui` (`--mqtt.venus.portal_id`) - `service`: `vebus/257` (`--mqtt.venus.service`) Published paths include common VE.Bus style values such as: - `Dc/0/Voltage`, `Dc/0/Current`, `Dc/0/Power`, `Soc` - `Ac/ActiveIn/L1/V`, `Ac/ActiveIn/L1/I`, `Ac/ActiveIn/L1/F`, `Ac/ActiveIn/L1/P` - `Ac/Out/L1/V`, `Ac/Out/L1/I`, `Ac/Out/L1/F`, `Ac/Out/L1/P` - alarm paths (`Alarms/LowBattery`, `Alarms/HighTemperature`, `Alarms/Overload`, `Alarms/Communication`) Optional write compatibility can be enabled with: ```bash --mqtt.venus.subscribe_writes ``` This subscribes to: - `W/{portal_id}/{service}/#` and maps supported write paths to MK2 control operations: - `Mode` -> remote panel mode - `Ac/ActiveIn/CurrentLimit` -> remote panel current limit - `Settings/Standby` / `RemotePanel/Standby` -> standby control ### Home Assistant Enable Home Assistant auto-discovery with: ```bash --mqtt.ha.enabled ``` When enabled, `invertergui` publishes retained discovery payloads and availability under: - `{topic-root}/homeassistant/availability` (`online`/`offline`) - `{discovery_prefix}/sensor/{node_id}/.../config` - `{discovery_prefix}/binary_sensor/{node_id}/.../config` - `{discovery_prefix}/select/{node_id}/remote_panel_mode/config` (if command topic is configured) - `{discovery_prefix}/number/{node_id}/remote_panel_current_limit/config` (if command topic is configured) - `{discovery_prefix}/switch/{node_id}/remote_panel_standby/config` (if command topic is configured) The discovered entities include battery/input/output sensors, a data-valid diagnostic binary sensor, plus remote panel controls for: - `Remote Panel Mode` (`on`, `off`, `charger_only`, `inverter_only`) - `Remote Panel Current Limit` (AC input current limit in amps) - `Remote Panel Standby` (prevent device sleep while off) 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 /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 /packages/invertergui_mqtt.yaml ``` 3. Copy dashboard file to your HA config: ```text /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. Example ``` -dev=/dev/ttyUSB0 ``` ## Nginx Proxy The following configuration works for Nginx to allow the `invertergui` to be proxied. When using a stand HTTP or HTTPS port to expose the gui: ```Ini location /invertergui { return 302 /invertergui/; } location /invertergui/ { proxy_pass http://localhost:8080/; proxy_set_header Host $host; } location /invertergui/ws { proxy_pass http://localhost:8080/ws; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 86400; proxy_set_header Host $host; proxy_set_header Referer $http_referer; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Port $server_port; } ``` When using a non-stand HTTP or HTTPS port to expose the gui change the HTTP Host description: ```Ini proxy_set_header Host $host:$server_port; ``` The last four lines are optional, but is useful when debugging and logging connections: ```Ini proxy_set_header Referer $http_referer; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Port $server_port; ``` ## Grafana This repos includes a [Grafana](https://grafana.com/) dashboard in the [grafana folder](./grafana/prometheus-dashboard.json) that you can import. This is useful if you are using prometheus to log your data and want to display it in a nice way. ![grafana](./grafana/dashboard.png "Grafana Dashboard")