You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+24-30Lines changed: 24 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -82,38 +82,32 @@ Note: Restart Home Assistant manually if you did not use the `--restart` flag.
82
82
83
83
The integration can be configured in three ways:
84
84
85
-
### Method 1: Automatic Discovery
86
-
1. Your Victron device should be automatically discovered if it has MQTT enabled
87
-
2. Go to Settings > Devices & Services
88
-
3. Look for the "Victron MQTT Integration" in the discovered section
89
-
4. Follow the configuration flow
85
+
### Method 1: Automatic Discovery (Recommended)
86
+
87
+
Your Victron GX device is automatically discovered on the local network. Go to **Settings > Devices & Services** and look for the integration in the "Discovered" section, then confirm to set it up.
88
+
89
+
> **TL;DR:** On Venus OS v3.80 or newer, just follow the discovery flow — no preparation needed. On older versions, enable MQTT access on the GX device first (*Settings > Integrations > MQTT Access*) — otherwise the device will not be discovered.
90
+
91
+
#### Details per security profile and Venus OS version
92
+
93
+
The configuration flow depends on the configured **Local Network Security Profile** of your GX device (under *Settings > General > Access & Security > Local Network Security Profile*) and the Venus OS version:
94
+
95
+
| Security Profile | Venus OS v3.80 or newer | Venus OS older than v3.80 |
96
+
|---|---|---|
97
+
|**Unsecured**| If MQTT access was not turned on manually, uses **MQTT pairing mode** (see below) and connects via SSL on port 8883 (recommended). If MQTT is already on, connects automatically without credentials on port 1883. | MQTT must be enabled manually on the GX device beforehand (*Settings > Integrations > MQTT Access*). Connects automatically without credentials on port 1883. |
98
+
|**Weak**| Asks you to activate **MQTT pairing mode** on the GX device before pressing Submit (see below). No need to manually enable MQTT — token pairing takes care of it automatically. Connects via SSL on port 8883. | MQTT must be enabled manually on the GX device beforehand (*Settings > Integrations > MQTT Access*). Asks for the **GX Password**¹. Connects via SSL on port 8883. |
99
+
|**Secured**| Same as above. | Same as above. |
100
+
101
+
¹ The GX Password is printed on the sticker on the GX device, or it is what was set when configuring the Local Network Security Profile (*Settings > General > Access & Security*).
102
+
103
+
**Activating MQTT pairing mode (v3.80+ only):** Via the GX user interface under *Settings > Integrations > MQTT Devices > Pairing mode*, or by quickly double-pressing the built-in button on GX devices without a screen. Pairing mode stays active for 120 seconds.
- Host: Your Victron device's hostname or IP (default: venus.local)
97
-
- Port: (See below)
98
-
- Username: (See below)
99
-
- Password: (See below)
100
-
- SSL: (See below)
101
-
102
-
Your Victron can be configured to use different levels of security. On the Victron Console (or Remote console) go to the Settings / General menu. The option “Local Network Security Profile” can have one of three options: “Unsecured”, “Weak” or “Secured”. If it is set to “Weak” or “Secured” you will have had to specify a password when setting the option.
103
-
104
-
Specify values for the Port, Username, Password and SSL options based on the setting of this security profile.
105
-
106
-
- If the security profile is set to Unsecured”, use the following values:
107
-
- Port: The unsecure MQTT port number (usually 1883)
108
-
- User name: Leave blank
109
-
- Password: Leave blank
110
-
- SSL: Disabled
111
-
112
-
- If the security profile is either “Weak” or “Secured”, use the following values:
113
-
- Port: The secure MQTT port number (usually 8883)
114
-
- User name: Leave blank
115
-
- Password: The password defined when setting the security profile
116
-
- SSL: Enabled
106
+
1. Go to **Settings > Devices & Services**
107
+
2. Click **Add Integration** and search for "Victron MQTT Integration"
108
+
3. Enter the connection details (host, port, credentials, SSL, etc.)
109
+
110
+
The recommended settings use SSL on port 8883, `remoteconsole` as username and the *GX Password* as password. If your security profile is "Unsecured", use port 1883 with SSL disabled and leave credentials blank.
117
111
118
112
### Method 3: Using Home Assistant MQTT Broker (Bridged Configuration)
119
113
Some users prefer to reduce the direct load on their Victron server and use bridge from the Venus device to a local mosquitto server running as add-on on the HAOS.
0 commit comments