VE.Direct Protocol

Introduction

Victron products featuring the VE.Direct serial communications interface provide simple access to detailed product information. This document describes how to receive and interpret this information.

For more information on other protocols and products, see the Data communication whitepaper: Whitepaper-Data-communication-with-Victron-Energy-products_EN.pdf.

The VE.Direct interface supports two modes: Text-mode and HEX-mode. Text-mode simplifies information retrieval by periodically transmitting all run-time fields. HEX-mode allows both reading and writing data, such as changing settings.

Implementations of Text-mode and HEX-mode:

• Older implementations: On power-up, the VE.Direct interface defaults to Text-mode, continuously transmitting run-time fields. Upon receiving a valid HEX-message, it switches to HEX-mode and remains in this mode as long as HEX-messages are frequently received. If no valid HEX-messages are received for several seconds, it reverts to Text-mode. Some products send asynchronous HEX-messages starting with ":A" and ending with a newline '\n', which can interrupt regular Text-mode frames.
• Newer implementations: Text-mode remains active regardless of HEX-message activity.

Consult your product's specific VE.Direct protocol document to determine its implementation. This document focuses exclusively on Text-mode.

Further resources include the VE.Direct protocol FAQ and the Open source page on Victron Live, which showcases community projects utilizing the VE.Direct protocol.

Physical Interface

The VE.Direct interface uses a 4-pin connector. The diagram below illustrates its location on a BMV-700.

Connector Pinout:

A diagram shows a 4-pin connector labeled 1, 2, 3, 4. A table lists the pins with 'Producer' and 'Consumer' roles:

Producers, such as BMV battery monitors and MPPT solar chargers, send data. Consumers, like the Color Control GX, receive this data. For connection, the Producer's VE.Direct-TX connects to the Consumer's VE.Direct-RX, and the Producer's VE.Direct-RX connects to the Consumer's VE.Direct-TX. Note that MPPT pins may have alternative functions, such as controlling the charger (VE.Direct-RX) or sending a PWM signal for dimming lights (VE.Direct-TX). Refer to the 'Connector types' section for details.

A VE.Direct to USB interface cable (part number ASS030530000) is available from Victron Energy, providing a virtual comport via USB and galvanic isolation.

A VE.Direct to RS232 interface cable (part number ASS030520500) is also available from Victron Energy.

Serial Port Configuration

The serial port configuration for VE.Direct communication is as follows:

Pins to use when using the VE.Direct to RS232 interface

For communication, use the GND, RX, and TX pins: pin 5, 2, and 3 on the DB9 connector, respectively. The DTR signal (pin 4 on the DB9 connector) and/or the RTS signal (pin 7 on the DB9 connector) must be driven high to power the isolated side of the interface. The method for programming DTR and RTS varies by operating system and hardware.

For more details, see: VE.Direct to RS232 Interface Pin Information.

Message Format

The device transmits data blocks at 1-second intervals. Each field follows this format:

<Newline><Field-Label><Tab><Field-Value>

The identifiers are defined as follows:

Data Integrity

Statistics are grouped into blocks with an appended checksum. The last field in a block is always "Checksum", a single byte that may not be a printable ASCII character. A modulo 256 sum of all bytes in a block should equal 0 if there were no transmission errors. Multiple blocks containing different fields are sent.

For more details, see: How to calculate the text checksum.

Fields

The units used for values sent over the serial interface may differ from those displayed on the LCD.

Note: The BMV-600S has limited VE.Direct Text-mode support. Refer to the BMV-600S Text Protocol document for details: BMV-600S Text Protocol.

Supported Fields and Units:

Notes on Fields:

1. The VE.Direct protocol is available in the MPPT 70/15 since firmware version v1.09 and up, and only in newer type MPPT 70/15s (product ID other than 0x300). Early batches with PID 0x300 support only fields PID, SER, and FW.
2. Available on Phoenix Smart Chargers with triple outputs only.
3. Available when the AUX input is configured as Starter Battery.
4. Available when the AUX input is configured as Mid Point.
5. MPPT 75/15 and 100/15: Since firmware v1.15, "I" reports battery current. Before v1.14, it reported converter output current without specifying if it went to the battery or loads.
6. Available since version v1.15, and only for models with a load output.
7. Available since version v1.12, and only for models with a load output.
8. If no temperature sensor is connected, "---" is sent.
9. Available when the AUX input is configured as Temperature.
10. When the BMV is not synchronized, these statistics are meaningless and "---" is sent.
11. When configured as a DC monitor, "---" is sent.

Additional Fields:

Notes on Additional Fields:

12. When the battery is not discharging, the time-to-go is infinite, represented as -1.
13. Available on SmartSolar mppt chargers since firmware version v1.17.
14. Available on Smart Phoenix Inverter.
15. Available on SmartSolar mppt chargers since firmware version v1.44 (VE.Direct models) and v1.03 (SmartSolar VE.Can models).
16. Available on Phoenix Inverter v1.16.

Further Fields:

Notes on Further Fields:

17. Available on BlueSolar mppt chargers since firmware version v1.16.
18. Available on Phoenix Inverter (some models) since firmware version v1.16.
19. Available on BlueSolar mppt chargers since firmware version v1.37.
20. Available since version v4.08.

Detailed Field Description

/: For MPPTs and BMVs: > 0 indicates charging, < 0 indicates discharging.

Alarm: Indicates the BMV's buzzer alarm state. Normally "OFF", changes to "ON" when an alarm occurs. This refers to the alarm condition itself, not the buzzer's sound. The value remains "ON" until all alarm conditions are cleared, regardless of button presses.

Relay: Shows the relay alarm state. Product-specific descriptions detail factory default behavior. For BMV, it's normally "OFF", changing to "ON" on alarm. For MPPT chargers, it's normally "OFF", changing to "ON" for low battery voltage. Phoenix Smart Inverters show "ON" during normal inverting, and Phoenix Smart Chargers show "ON" during normal charging.

Note for Alarm and Relay: BMV-600s with firmware v2.09 or lower used "On" and "Off" instead of "ON" and "OFF". Case-insensitive string comparison (e.g., stricmp()) is recommended.

FW: Firmware version. Reported as a whole number (e.g., 208 for v2.08). "C208" indicates release candidate C for v2.08. Available in BMV since v2.08.

FWE: Firmware version. Can be up to 6 digits, with optional leading zeros. Examples: "0208FF" or "208FF" for v2.08 (FF indicates official release), "020801" for v2.08-beta-01.

AR (Alarm Reason): Describes the cause of an alarm. Multiple conditions are added together; the total value is sent in decimal notation.

Example: A value of 5 indicates a low SOC alarm and a low Voltage alarm. Available in BMV since v2.08.

WARN (Warning Reason): Implemented for inverters only. Provides the cause of a warning, using the same bit definition as AR. Warnings reflect the current status of measured parameters (temperature/battery voltage/VAC-out). Unlike AR, which remembers the cause of an inverter shutdown until it is switched on again, WARN reflects the immediate status.

OR (Off Reason): Describes why a unit is switched off.

CAP_BLE: Describes why a unit is switched off via BLE.

CS (State of Operation): The state of operation.

ERR (Error Code): The error code of the device during a fault state.

Note 1: Error 19 can often be ignored; it regularly occurs during MPPT charger start-up or shutdown. This error is no longer reported since version 1.15.

Note 2: Error 21 can be ignored for 5 minutes; it also occurs during MPPT charger start-up or shutdown. Since version 1.16, this warning is no longer reported if it is not persistent.

HSDS (Historical Data): Historical data indicating the day sequence number. A change signifies a new day and updated historical data. Range: 0-364. Available in MPPT chargers since v1.16.

SER#: The device's serial number, formatted as LLYYMMSSSSS (LL=location code, YYWW=production date, SSSSS=unique part). Example: HQ1328Y6TF6.

BMV (deprecated): Provides a textual description of the BMV model (e.g., 602S or 702). This field is deprecated; use the PID field instead.

MODE: Possible values for device mode.

(1) Smart only

MPPT: Possible values for tracker operation.

MON: Possible values for DC monitor mode.

Implementation Guidelines

When implementing a VE.Text parser, it is recommended to reserve two buffers: one for the field label (9 bytes) and one for the field value (33 bytes). Parse the value as soon as a single field is received and store it in a temporary record. A block can contain a maximum of 22 fields; maintain at least 22 temporary records. Once the complete block is validated by its checksum, the temporary records can be copied to their final records. If the checksum is invalid, clear the temporary records.

Connector Types

The VE.Direct interface uses JST PH connectors with a 2.0mm pitch. There are 3 through-hole and 2 surface-mount types available.

Connector Details:

Images show four connector types: 'TH top entry', 'TH side entry', 'SMT top entry', and 'SMT side entry'.

VE.Direct Cable

The VE.Direct cable features a molded part for enhanced durability. It is available in straight and 90-degree angle models.

Diagrams illustrate the VE.Direct straight cable connector and the VE.Direct 90-degree cable connector, showing pin numbering (1, 3, 4).

Document History

Product ID (PID) List

The product ID for various Victron devices:

* These models are phased out.