Victron VE.Direct¶
Purpose¶
The regulator listens (RX-only) to a Victron VE.Direct serial stream on UART_RX1 and reads voltage, current, and solar/MPPT data from a Victron device (BMV battery monitor, SmartShunt, or MPPT charge controller).
This data is display and logging only — it does not drive any charging or safety decision. Every control and protection loop (field regulation, over-voltage, load-dump, tail-current, rebulk, the maintenance / zero-net-amps mode, and the battery charge-current ceiling) reads the regulator's onboard INA228 shunt directly, regardless of what VE.Direct reports. There are two specific uses:
- Solar / MPPT stats — panel power and voltage, charge state, tracker mode, error code, and daily/lifetime yield are shown on the dashboard and logged.
- Battery-monitor readout — if you set Battery Current Source to Victron in Setup → Battery → Battery Monitor → Other Settings, the state-of-charge display uses the Victron monitor's current instead of the onboard shunt. This affects the SoC readout only. It is deliberately not used for charging: VE.Direct updates at about 1 Hz and lags real current by 1–2 s, which is too slow to close a control loop against. The onboard INA228 stays mandatory, and the battery charge-current ceiling only arms when the source is the onboard shunt.
VE.Direct is off by default; enable it with the VE.Direct Data toggle in Setup → Integrations → Victron VE.Direct.
There is no TX path; the regulator only listens — it does not send commands to the Victron device.
For the input protection stage (HCPL2531 optocoupler, current-limiting resistors, clamp diodes, pull-ups), see UART Input Protection Circuit. This page covers the protocol-level configuration and physical wiring.
Managed-battery coordination (DVCC-style) — over CAN, not VE.Direct¶
Charge-limit follow is in the firmware, but it runs on the NMEA 2000 / VE.Can port, not on this VE.Direct input. With Follow BMS Charge Limits on (Setup → Integrations → Charge-Limit Follow; off by default), the regulator decodes the charge limits a Victron system or an RV-C BMS publishes on the CAN bus and clamps its own targets down to them. An RV-C battery master broadcasts both a voltage and a current limit. A Victron GX broadcasts its charge voltage set-point to the whole bus, and the regulator follows it today. Venus OS 3.00 changed that broadcast so no recognition of the listening device is needed — nothing has to be registered, paired or approved for the regulator to hear it.
What the GX side has to be set to. A GX only publishes that set-point when DVCC is enabled and the system has a battery that reports its own charge voltage — a managed or smart battery, or an ESS system. With DVCC off, or with an ordinary battery that reports nothing, there is no number for the GX to publish and nothing to follow: the regulator waits and runs on its own targets, which is correct behaviour, not a fault. The Maximum Charge Voltage setting in the DVCC menu lowers the number the battery asked for; on its own, with no battery supplying one, it does not create a set-point to send.
The per-device current allocation a GX hands out is a separate thing: it is addressed to one charger at a time and goes only to regulators Victron has added support for on their side. It never raises a target, and every local protection still outranks the received limit. Details are in External Interfaces.
One caveat worth knowing before you rely on it: the charge-voltage register the decoder reads is confirmed — register, scale, and the value that means "no limit" — but the remaining Victron registers are built from Victron's published register documentation and have not yet been confirmed against a capture from a real GX device. The RV-C dialect follows the published RV-C application layer, and matches the published protocol of a shipping RV-C BMS field for field. The settings page shows the decoded limits and a trust state, and carries a raw-frame capture tool for confirming the decode on your own boat. A decoded limit has to arrive in range for a settling period before it is allowed to clamp anything, and an implausible value latches the authority untrusted until you reset it by hand.
Planned integration¶
Deeper Victron integration is on the roadmap but not in the shipped firmware today:
- Bidirectional VE.Direct — adding a transmit path (VE.Direct HEX protocol) so the regulator can query and command the Victron device, not just listen.
- A charge current target from a Victron GX — see the charge-limit section above. The charge voltage set-point is already followed. Being sent a current allocation is different: a GX sends those only to charging devices it has built-in support for, and that support does not exist for this regulator today. We are in touch with Victron about it.
- Acting on BMS warnings and requested charge state — the charge-state and warning fields are decoded and displayed. One is already acted on: an explicit stop — an RV-C do not charge request, or a Victron not-allowed-to-charge flag — is obeyed as a charge-current limit of zero. The rest of the charge-state detail and the warning bits are display only.
If either of these matters for your install, email joe@xengineering.net.
Electrical¶
| Parameter | Value | Notes |
|---|---|---|
| Signal level (Victron side) | 3.3 V or 5 V TTL UART | Victron VE.Direct ports are typically 3.3 V logic |
| Baud rate | 19200 baud | VE.Direct standard, not configurable |
| Data format | 8 data bits, no parity, 1 stop bit (8N1) | Standard |
| Frame timing | TEXT frames sent ~once per second | See Victron VE.Direct protocol documentation |
| Input stage | HCPL2531 optocoupler — protection and level shifting, common ground | Not galvanic isolation — see UART Input Protection Circuit |
| Receive polarity | Inverted at the ESP32 | The protection stage inverts; the firmware receives this UART with inverted polarity, so everything cancels out |
| Internal pull-up | 13 kΩ to 3.3 V on UART_RX1_ISOL | With no device connected, the line idles HIGH |
Connector Pins¶
UART_RX1 is broken out at two physical locations, in parallel — use whichever is most convenient for your install. Do not wire both at once.
| Cable | Connector | Pin | Wire color (T568B) | Signal | ESP32 GPIO |
|---|---|---|---|---|---|
| 1 | RJ5 — left port | 15 | Brown/White | UART_RX1 | GPIO7 |
| 3 | RJ3 — left port | 1 | Orange/White | UART_RX1 | GPIO7 |
Both pins land on the same trace inside the board, so connecting wires to both will short the two Victron-side cables together — that is electrically OK but mechanically pointless and may cause cable strain.
Wiring to a Victron Device¶
Victron VE.Direct cables (VE.Direct to bare-wire, part numbers ASS030530200, ASS030530300, etc.) expose three wires:
| Victron wire color | Function | Connects to |
|---|---|---|
| Yellow | TX from Victron device | RJ5 pin 15 (or RJ3 pin 1) — the regulator's UART_RX1 |
| Red | RX to Victron device | Not connected — regulator does not transmit |
| Black | GND | Leave unconnected in a typical install — see Grounding below |
Tape off the Victron red wire; leaving it floating near the regulator harness is fine, but do not let it touch 3.3 V or 5 V — it is an input on the Victron side and could be damaged.
Grounding¶
The receive circuit needs a current path from the regulator's board ground back to the Victron device's ground, but it does not need a wire in this cable to get one. The VE.Direct GND pin is internally tied to the Victron device's battery-minus terminal, and the regulator's board ground is also battery-minus — so on a normal boat the two are already connected through the DC negative bus. Leave the black wire unconnected and tape it off.
- If you prefer a dedicated return, land the black wire on the boat's negative bus, or on the regulator's ground return — Cable 4's Brown wire (RJ3 pin 16, on the right-hand RJ3 jack). Do not use any other pin for ground: neither Cable 1 nor Cable 3 carries a ground wire.
- If the Victron device is powered from an isolated supply and does not share the boat's battery negative (rare), the black wire becomes mandatory — without it there is no return path and nothing will be received.
Why Yellow goes to a pin labelled "RX"¶
A common confusion. The pin label on the regulator is from the regulator's perspective: UART_RX1 is the regulator's receive input. The Victron device's TX (yellow) is what the regulator wants to receive. So Victron TX → regulator RX is correct.
Software Notes¶
The firmware parses VE.Direct TEXT frames (~1 Hz) and ignores HEX frames; acceptance is gated by the per-frame checksum. Which fields are read, how the stream is drained, and how freshness is tracked are covered in External Interfaces.
Troubleshooting¶
| Symptom | Likely cause |
|---|---|
| No VE.Direct data appearing in regulator console | Wrong wire — confirm Victron Yellow goes to UART_RX1, not Red. Common installer mistake. |
| Data appears intermittently | Long cable run picking up engine RFI — keep the VE.Direct cable away from alternator wiring, or shorten it |
| Console shows correct frame structure but field values are wrong/stale | Victron device firmware version may report different field IDs — confirm against current Victron VE.Direct field documentation |
| Garbled characters | Baud rate mismatch — unlikely since VE.Direct is fixed at 19200, but verify the firmware is configured for 19200 and not 4800 |
| Data stops when alternator engages | EMI pickup on unshielded cable — use a shielded twisted-pair extension, ground the shield at the Victron end only |