Skip to content

Commit 1ba3f00

Browse files
authored
Update README configuration section for new config flow (#486)
1 parent e742a40 commit 1ba3f00

1 file changed

Lines changed: 24 additions & 30 deletions

File tree

README.md

Lines changed: 24 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -82,38 +82,32 @@ Note: Restart Home Assistant manually if you did not use the `--restart` flag.
8282

8383
The integration can be configured in three ways:
8484

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.
90104

91105
### Method 2: Manual Configuration (Direct Connection)
92-
1. Go to Settings > Devices & Services
93-
2. Click "Add Integration"
94-
3. Search for "Victron MQTT Integration"
95-
4. Enter the following details:
96-
- 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.
117111

118112
### Method 3: Using Home Assistant MQTT Broker (Bridged Configuration)
119113
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

Comments
 (0)