Victron VE.Direct¶
Purpose¶
The XREG-010 listens (RX-only) to a Victron VE.Direct serial stream on UART_RX1 and reads voltage, current, battery temperature, and solar/MPPT data from a Victron device (BMV battery monitor, SmartShunt, or MPPT charge controller).
Field regulation and every protection run on the regulator's own sensors, never on VE.Direct. Over-voltage, load-dump, the maintenance (zero-net-amps) mode, and the battery charge-current ceiling all read the shunt wired to the regulator. Two kinds of VE.Direct data can reach charging: battery temperature, and the state of charge and current of a battery monitor you turn on with Use as Battery Monitor. There are three specific uses:
- Solar / MPPT stats — panel power and voltage, charge state, tracker mode, error code, and today's and yesterday's yield and peak power are shown on the dashboard and logged.
- Battery monitor — with Use as Battery Monitor on (Setup → Integrations → Victron VE.Direct), a BMV or SmartShunt's own state of charge (the VE.Direct
SOCfield) becomes the state of charge the regulator shows, alarms on, and uses to hold off a rebulk near full. The regulator never re-counts it from the monitor's current. With no shunt wired to the regulator, the monitor's current also ends absorption on taper current and triggers the current rebulk. Both are minute-scale decisions, so the 1 to 2 s VE.Direct lag does not matter for them; the fast paths stay off without the regulator's own shunt. The current is used only from a device that sendsSOC, so an MPPT on this port can never end absorption. - Battery temperature — a BMV or SmartShunt fitted with a temperature sensor sends a
Tfield, and the regulator uses it as a battery-temperature source. With Battery Temperature left on Automatic (Setup → Battery → Battery Temperature) it is used when no battery probe and no NMEA 2000 battery temperature is available; it can also be selected outright. Battery temperature drives the cold-charge and hot-charge lockouts and the voltage-loop gain temperature correction, so this value does affect charging.
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 |
|---|---|---|---|---|---|
| 2 | RJ5 — right 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: Cable 3 carries no ground wire, and the only ground on Cable 2 (pin 12) is the spare analog input AIN3, grounded only by a removable link (R28).
- 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: the regulator's VE.Direct port is fixed at 19200 and has no setting to change it, so check the Victron device's port configuration and the wiring |
| Data stops when alternator engages | EMI pickup on unshielded cable — use a shielded twisted-pair extension, ground the shield at the Victron end only |