implement some features of Venus OS

README.md

@@ -29,6 +29,56 @@ docker run --name invertergui --device /dev/ttyUSB0:/dev/ttyUSB0 -p 8080:8080 re
 
 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
@@ -48,13 +98,28 @@ Application Options:
       --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]
       --loglevel=       The log level to generate logs at. ("panic", "fatal", "error", "warn", "info", "debug", "trace") (default: info) [$LOGLEVEL]
 
 Help Options:
@@ -84,6 +149,26 @@ services:
     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:
@@ -336,10 +421,16 @@ The MQTT client will publish updates to the given broker at the set topic.
 --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]
@@ -402,6 +493,60 @@ Low-level writes are still supported:
 `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: