VE - Direct HEX Protocol Phoenix Inverter
VE - Direct HEX Protocol Phoenix Inverter
Direct protocol
www.victronenergy.com
Rev 5
VE.Direct Protocol
Phoenix Inverters
VE.Direct commands
The frame format of the VE.Direct protocol has the following general format:
: [command] [data][data][…] [check]\n
Where the colon indicates the start of the frame and the newline is the end of frame. The sum of all
data bytes and the check must equal 0x55. Since the normal protocol is in text values the frames are
sent in their hexadecimal ASCII representation, [‘0’ .. ’9’], [‘A’ .. ’F’], must be uppercase. There is no
need to escape any characters.
: [command] [dataHighNibble, dataLowNibble][……] [checkHigh, checkLow] \n
Note: The command is only sent as a single nibble. Numbers are sent in Little Endian format. An error
response with value 0xAAAA is sent on framing errors.
Command Description
0 Enter boot 0x51FA51FA51FA51FA51FA as payload will enable bootloader mode.
Check for presence, the response is an ‘Rsp ping’ containing version
1 Ping
and firmware type. See the response ping message.
App Returns the version of the firmware as stored in the header in an ‘Rsp
3
version Done’ message.
Returns the Product Id of the firmware as stored in the header in an
4 Product Id
‘Rsp Done’ message.
6 Restart Restarts the device, no response is sent.
Returns a get response with the requested data or error is returned.
7 Get uint16 the id of the value to get
uint8 flags, should be set to zero
Returns a set response with the requested data or error is returned.
uint16 the id of the value to set
8 Set
uint8 flags, should be set to zero
type depends on id value
Asynchronous data message. Should not be replied.
uint16 the id of the value being returned
A Async
uint8 flags, defined below
type depends on id value
2, 5, 9, B-F reserved
3
VE.Direct responses are formatted in the same manner as commands, but use response codes.:
Response Description
1 Done Successful execution of the received command. Payload depends on
command.
3 Unknown Unknown command, data is the unknown command.
4 Error Frame error (payload=0xAAAA), unable to enter bootloader
(payload=0).
5 Ping The version number is directly interpreted from the hex representation,
e.g. 0x0101 is version 1.01. The two most significant bits indicate the
firmware type:
b00: bootloader
b01: application
b10: tester
b11: release candidate
In case of release candidate the lowest two bits of the highest nibble
together with type indicate the release candidate number. E.g. 0xD101
represents release candidate D of version 1.01.
Note that there can only be 4 release candidates per version.
uint16 id: of the value being returned
7 Get uint8 flags: defined below
type depends on id value
uint16 id of the value which was set
8 Set uint8 flags: defined below
type depends on id value
4
Product ID values
The product ID (PID) defines whether firmware is compatible with the device.
Next a list of all VE.Direct and Smart inverters who support the VE.Direct Protocol as described in this
document.
5
Device Name Remark
A2A1 Phoenix Inverter Smart 12V 3000VA 230Vac 64k Smart, integrated Bluetooth
A2A2 Phoenix Inverter Smart 24V 3000VA 230Vac 64k Smart, integrated Bluetooth
A2A4 Phoenix Inverter Smart 48V 3000VA 230Vac 64k Smart, integrated Bluetooth
A2B1 Phoenix Inverter Smart 12V 5000VA 230Vac 64k Smart, integrated Bluetooth
A2B2 Phoenix Inverter Smart 24V 5000VA 230Vac 64k Smart, integrated Bluetooth
A2B4 Phoenix Inverter Smart 48V 5000VA 230Vac 64k Smart, integrated Bluetooth
A2E1 Phoenix Inverter 12V 800VA 230Vac 64k HS redesign (replaces A261)
A2E2 Phoenix Inverter 24V 800VA 230Vac 64k HS redesign (replaces A262)
A2E4 Phoenix Inverter 48V 800VA 230Vac 64k HS redesign (replaces A264)
A2E9 Phoenix Inverter 12V 800VA 120Vac 64k HS redesign (replaces A269)
A2EA Phoenix Inverter 24V 800VA 120Vac 64k HS redesign (replaces A26A)
A2EC Phoenix Inverter 48V 800VA 120Vac 64k HS redesign (replaces A26C)
A2F1 Phoenix Inverter 12V 1200VA 230Vac 64k HS redesign (replaces A271)
A2F2 Phoenix Inverter 24V 1200VA 230Vac 64k HS redesign (replaces A272)
A2F4 Phoenix Inverter 48V 1200VA 230Vac 64k HS redesign (replaces A274)
A2F9 Phoenix Inverter 12V 1200VA 120Vac 64k HS redesign (replaces A279)
A2FA Phoenix Inverter 24V 1200VA 120Vac 64k HS redesign (replaces A27A)
A2FC Phoenix Inverter 48V 1200VA 120Vac 64k HS redesign (replaces A27C)
6
Message examples
\n at the end of the message is implied.
Ping Set Battery Maximum Current
:154 Set to 10.0A = 0x0064
:51641F9 :8F0ED0064000C
0x4116 = talking to application version 1.16 :8F0ED0064000C
Acknowledged with the new value returned.
Application version
:352 Unsupported command
:11641FD :253
Like ping, application version 1.16 :3020050
Unknown response
Product Id
:451 Invalid frame (checksum wrong)
:1000351 :452
0x300 = BlueSolar MPPT 70|15 :4AAAAFD
Error response
Restart
:64F Asynchronous message
No response, restarted :A0102000543
The unit reports register 0x0201 (device state)
Get Battery Maximum Current with value 0x05 (float).
:7F0ED0071
:7F0ED009600DB
Value = 0x0096 = 15.0A
Text Protocol
When no VE.Direct queries are sent to the device, the charger periodically sends human readable
(TEXT) data to the serial port. See the "VE.Direct Protocol" document for a detailed description of the
contents and availability of the information.
7
2 Inverter register description
The register in this chapter can be accessed for reading and/or writing by using the :Get (read) and
:Set (write) commands of the VE.Direct Protocol. Whether the connection is established by using the
actual VE.Direct-USB cable, or via a Bluetooth Dongle makes no difference.
After changing one or more settings it is required to execute the NvmSave command via
0xEB99. Until this command is executed the registers will revert to the old (last saved) value after a
power down cycle or reset.
When a write message is addressed to register Id 0x0004 all user settings of the device are restored
to the factory default values. Factory calibration data is preserved. The data part of this message is
not required and ignored.
8
Product information registers
Read only registers with static information about the device
ID Register name R/W Type Scale Unit Note
0x0100 VE_REG_PRODUCT_ID R un32 - -
0x0101 VE_REG_PRODUCT_REVISION R un24 - -
Hardware version
0x0102 VE_REG_APP_VER R un32 - -
Software version
0x010A VE_REG_SERIAL_NUMBER R string - -
0x010B VE_REG_MODEL_NAME R string - -
0x2203 VE_REG_AC_OUT_RATED_POWER R sn16 1 VA 1)
0x0140 VE_REG_CAPABILITIES1 R un32 - - 2)
0x0150 VE_REG_CAPABILITIES_BLE R/(W) un32 - 3)
0x2202 VE_REG_AC_OUT_NOM_VOLTAGE R un8 1 V 1)
0xEDEF VE_REG_BAT_VOLTAGE R un8 1 V 1)
Note 1) Available since version 1.10
Note 2) Available since version 1.15
Note 3) Available since version 1.17 for Smart inverters only
Struct Description
un8 0
un16 ID number of the device (PID)
un8 0xFE
Struct Description
un8 0
un16 HW revision number
Byte Description
0 0
1 Minor
2 Major, + bits 7 and 6 indicate SW type:
00=bootloader
01=application (released)
02=tester
03=release candidate(beta)
9
2.2.4 Capabilities (register 0x0140)
Bit Description of the option bit Small Small 64k Smart
32k <= 1200VA
note1)
8 Remote input available 1 1 1
17 Built in user-relay available and support of registers: 0 0 1
VE_REG_RELAY_MODE and
VE_REG_RELAY_CONTROL
27 OpenPaygo token compatible 0 version version
>=1.17 >=1.17
28 Support of device hibernation: 0 0 1
VE_REG_DEVICE_MODE
= VE_REG_MODE_HIBERNATE (0xFD)
29 Improved load current measurement and support of 0 revision >= 1
registers: 7,
VE_REG_AC_OUT_APPARENT_POWER and see register
VE_REG_AC_LOAD_SENSE_POWER_THRESHOLD 0x0101
VE_REG_AC_LOAD_SENSE_POWER_CLEAR
Note 1) Small 32k devices (PID A20x, A21x or A22x ) are obsolete, production stopped in November
2016
10
2.3.1 Device state values (register 0x0201)
State Name Meaning
0 Off Not inverting. When due to a protection the inverter will
automatically start again when the cause is solved.
1 Low Power Eco load search active
2 Fault Not inverting due to a fatal active protection. A turn OFF-ON
cycle is required to enable the device again.
9 Inverting Normal operating
Note 2: A “High AC-output voltage” alarm occurs when the AC-output of the inverter is connected to
mains while the inverter is turned on.
11
Generic device control registers
Registers to control the mode of operation of the device
Note 3) Since version 1.17. Time in Unix-timestamp format. Default = 0xFFFFFFFF. External
applications can read and write to this register. It is not controlled by and has no effect on the
operation of the inverter.
Set 0 to disable the Bluetooth transceiver (BLE) of the Smart Inverters. When it is disabled it can be
enabled via VE.Direct only.
Note 2) Available since version 1.15, see §2.2.4 Capabilities (register 0x0140). The Hibernate mode
has impact on the VE.Direct functionality. Communication can only be started when the device sends
a text frame, at least once per 30 seconds, or after pressing the User-button. As long as a VE.Direct
message is received every 24 seconds the device will not enter the hibernation mode.(Note that
communication via Bluetooth is not affected)
12
Inverter operation registers
Read only registers with measured information about the device
ID Register name R/W Type Scale Unit Note
0x1040 VE_REG_HISTORY_TIME R un32 1 s 1)
0x1041 VE_REG_HISTORY_ENERGY R un32 0.01 kVAh 1)
0x2201 VE_REG_AC_OUT_CURRENT R sn16 0.1 A
0x2200 VE_REG_AC_OUT_VOLTAGE R sn16 0.01 V
0x2205 VE_REG_AC_OUT_APPARENT_POWER R sn32 1 VA 2)
0xEB4E VE_REG_INV_LOOP_GET_IINV R sn16 0.001 A
0xED8D VE_REG_DC_CHANNEL1_VOLTAGE R sn16 0.01 V
(battery voltage)
Note 1) Since version 1.17, lifetime data
Note 2) Eco search mode threshold based on AC-current (only for version 1.00 up to 1.14, see note 5)
Note 3) Interval of the power test bursts when the Eco load search mode is active.
Note 4) Since version 1.17. Duration of a power test burst, when Eco load search mode is active,
expressed in number of periods of the AC-out frequency (either 50 or 60Hz). For some loads with a
delayed “turn-on” response, like dimmable LED-lightbulbs, it is required to enlarge the default value in
order to detect the load.
Note 5) Since version 1.15, see Capabilities in §2.2.4 Capabilities (register 0x0140).
Eco search mode threshold with hysteresis based on apparent power. Replaces
VE_REG_INV_OPER_ECO_MODE_INV_MIN. Available in Smart Inverters and in all VE-Direct
inverters with a product revision >= 7 (see Product Revision (register 0x0101))
13
2.6.1 Load sense power hysteresis (register 0x2206 0x2207)
14
User battery control registers
ID Register name R/ Type Scale Unit
W
0x2210 VE_REG_SHUTDOWN_LOW_VOLTAGE_SET W un16 0.01 V 1)
0x0320 VE_REG_ALARM_LOW_VOLTAGE_SET W un16 0.01 V 2)
0x0321 VE_REG_ALARM_LOW_VOLTAGE_CLEAR W un16 0.01 V 3)
0x2211 VE_REG_VOLTAGE_RANGE_MIN R un16 0.01 V 4)
0x2212 VE_REG_VOLTAGE_RANGE_MAX R un16 0.01 V 4)
0xEBBA VE_REG_INV_PROT_UBAT_DYN_CUTOFF_ENABLE W un8 5)
0xEBB7 VE_REG_INV_PROT_UBAT_DYN_CUTOFF_FACTOR W un16 5)
0xEBB5 VE_REG_INV_PROT_UBAT_DYN_CUTOFF_FACTOR2000 W un16 5)
0xEBB3 VE_REG_INV_PROT_UBAT_DYN_CUTOFF_FACTOR250 W un16 5)
0xEBB2 VE_REG_INV_PROT_UBAT_DYN_CUTOFF_FACTOR5 W un16 5)
0xEBB1 VE_REG_INV_PROT_UBAT_DYN_CUTOFF_VOLTAGE R un16 0.001 V 5)
Note 1) Low battery voltage shutdown threshold.
Note 2) Low battery warning threshold, also below this level the inverter will not start-up after a shut-
down.
Note 3) Charge detect threshold after a long-term low voltage shut down. If the battery voltage
exceeds this level the alarm is cleared, and the inverter will restart.
Note 4) Limits for all battery user threshold settings, e.g. VE_REG_ALARM_LOW_VOLTAGE_SET.
Out of range input levels will be clamped to these levels.
Note 5) Since version 1.03.
15
Relay control registers
ID Register name R/W Type Scale Unit Note
0x034E VE_REG_RELAY_CONTROL R/W un8 1)
0x034F VE_REG_RELAY_MODE W un8 1)
Note 1) Since version 1.15, see §2.2.4 Capabilities (register 0x0140)
16
Revision Log
1) 2018-05-24
Initial document
2) 2018-9-13
Replaced "device id" with "product id"
3) 2018-11-22
Added changes for Smart Inverters supported since FW version 1.15
4) 2019-09-27
Added instructions on saving settings
Added 50Hz/60Hz setting
Added new features since FW version 1.17
Support Bluetooth on/off
Enhanced ECO load search mode timing
5) 2021-09-06
Add Product-ID for 5000VA Smart Inverters
Added description CAPABILITIES1 bit 27
Fix type of 0xEBBA 'VE_REG_INV_PROT_UBAT_DYN_CUTOFF_ENABLE' is un8
17