Reverse engineering the Mastervolt Master Adjust / Mass Combi communication protocol

[Lomax]

Hello fellow tinkerers!

I have installed a Mastervolt Mass Combi 12-2200-100 on my live-aboard which I'm quite happy with. But I would like to be able to monitor and control it from my on-board computer system, which is based on IBM's Node-RED. Because of its extensible open source nature this system is capable of talking to basically anything, and I am already monitoring the GPS, weather station, PV-array, bilge pumps, cameras, gas & fire alarms and a number of other things through it. It also controls the lighting, entertainment system, heating, ventilation, etc - and it is able to send me status updates and alerts via several different channels (audible, email, SMS). The only device onboard I was unable to talk to was the rather essential, and expensive, Mass Combi inverter/charger.

There's no doubt the Mass Combi is a well engineered piece of kit with many advanced functions, but since Mastervolt have not published any documentation of the communications protocol it's not easy to integrate it with other systems. This is in stark contrast to e.g. Victron, who go to great lengths to make their products easy to talk to from whatever system, and who publish detailed specifications of their communications protocols. It's a great pity that Mastervolt have not understood the value of this, particularly given the poor state of the official (Windows only) software - had I known about this I likely would have opted to buy a charger/inverter from one of their competitors instead.

I found myself with a lot of time on my hands during the last Covid lock-down, and being a stubborn b*****d I decided to start looking at the communication between Mastervolt's official software (Master Adjust) and the Mass Combi to see if I could make it play nice. I've since managed to figure out most of what it does; I think I can now read voltage and current going in and out, as well as battery state, DC and inverter load, and the presence of shore power. I can also read and write most of the configuration options. That all said, there are still many gaps in my knowledge.

I'm starting this thread with the intention of sharing what I've learned so far, and in the hope that there will be others here who may be able to help fill in the gaps - or at least have an interest in my research. Before we start though, I just want to make it clear that most of what follows is guesswork and I make no claim as to the accuracy of the information provided. It could well be that I've fundamentally misunderstood some aspects of the protocol, and that using this information might cause irreversible damage to your Mass Combi. You have been warned!

[Lomax]

Interfacing

The first hurdle I faced was figuring out what kind of serial interface the Mass Combi uses; in the product literature it is referred to as a "QRS232" port, with the "Q" (as in "quasi") meaning it's a 5V TTL RS232 port. The manual for the Mastervolt PC Link adapter helpfully provides both pin-out and voltage of this port:



While RS232 normally signifies a 12V signalling schema, it was not difficult to find a cheap USB <> TTL level RS232 adapter like this one (£4 on the bay):



Hooking up to the Mass Combi through this adapter (via an RJ11 plug) made it possible for the MasterAdjust software (running in a WinXP virtual machine) to talk to the unit:



Now I could start looking at the data. It's a 19200-8-N-1 link, and hooking my scope up to TX (blue) and RX (red) revealed traffic like this:

[Lomax]

Data format

It turns out the MasterAdjust software works by going through all the commands needed to populate the interface with data twice a second, so there is a lot of traffic, and I was a little overwhelmed by this at first. But I assembled a list of requests and responses in a spreadsheet to try and tease things out (requests in red, responses in grey/black):



A few things immediately stood out: requests and responses are always eight bytes followed by a checksum, a request always starts with 0xC1 0xF0 and a response with 0xF0 0xC1. It seems the following byte is the command, and the following four the relevant value(s). The eighth byte appears to be a read/write flag, and the final byte is a modulo 256 checksum. I dug deeper, taking the four "value" bytes, in reverse order (which is common), and turning them into decimal:



"13573", could that be 13.573? Looks like it might be a battery voltage? By comparing values (with different scaling) to what the MasterAdjust software was showing I soon found a handful of commands I was sure of. It turned out that the "13573" above had nothing to do with any voltage, but was actually the "DC Current" scaled by 2560. And so on. Many values were scaled by 2560, but some by 256, some by 100, and many others were at scale 1. So I had a lot of fun. But I made headway and could confirm with 100% certainty that sending (for example)

0xC1 0xF0 0x24 0x00 0x00 0x00 0x00 0x01 0xD6

would reliably give me a value that matched the "DC Current" shown in MasterAdjust (e.g. 13573/2560=5.3019531 when "5.3 A" displayed in MasterAdjust). I now could start building dashboard components in Node-RED to plot and display some things:



This allowed me to graph the changing values while I exposed the unit to various conditions, such as unplugging the shore power, and adding load to the DC or inverter systems, which unlocked a few other secrets.

[Lomax]

The remote control panel


Some of the value bytes were actually individual bits corresponding directly to LEDs on the remote control panel, so

0xC1 0xF0 0x25 0x00 0x00 0x00 0x00 0x01 0xD7

would, for example, return the four value bytes

0xE0 0xF1 0x00 0x00

Taking the bits in the first two bytes 0xE0 0xF1 gives us 1110 0000 and 1111 0001 respectively, where the first byte appeared to match that the lowest (5%) LED for "DC Load" on the remote control panel is lit, and the second byte that all five "State of Charge" are lit. I eventually mapped it out like this:

first byte

  1111 1000  discharged?
  1111 0101  Error mode? 

  1111 1110  100% DC-load (also when switched off)
  1111 1100   75% DC-load
  1111 1000   50% DC-load 
  1111 0000   25% DC-load 
  1110 0000    5% DC-load
  1100 0000    0% DC-load 

  0100 0000  Charger off, inverter off

  0011 1110  100% on inverter
  0011 1100   75% on inverter
  0011 1000   50% on inverter
  0011 0000   25% on inverter
  0010 0000    5% on inverter
  0000 0000  cut off / inverter off

second byte

  1111 0011  ???

  1111 0001  100%

  1110 0011   75% inverter soc
  1100 0011   50% inverter soc
  1000 0011   25% inverter soc
  0000 0011    5% inverter soc
  0000 0010    0% blinking

  1111 0001  charging (float)
  1110 0001  charging (abs 2)
  1100 0001  charging (abs 1)
  1000 0001  charging (bulk 2)
  0000 0001  charging (bulk 1)

This is copied raw from my notes, and as you can see there are still quite a few question marks, but I now knew enough to replicate all of the indicator lights on the remote control panel:




Note that the remote panel picture above is a stock image, and its state does not match what's displayed in the Node-RED dashboard. Here is a clearer breakdown of what I think I know about command 0x25, the response of which drives the remote control panel LEDs:



A few curiosities to note:

• Due to the remote panel using combined LED arrays for "DC Load" / "Inverter Load" and "State of charge" / "Charger Stage", these are not sent as separate blocks of bits, but rather one has to look at the "Charger On" and "Inverter On" bits to determine what the values represent.
• The five "DC/Inverter Load" LEDs are controlled by five bits in reverse order (here showing 5%, or only first LED lit), while the five "State of Charge/Charger Stage" LEDs use just four bits (again in reverse order, here showing 100%, or all five LEDs lit). The first LED in this array will blink when the LSB of the second byte goes low.
• The "AC Input" LED is inverted, and lights up when the LSB of the fourth byte is low.

Edit: I see now that the request & response in my graphic above are only seven bytes plus checksum, while I said they were always eight bytes plus checksum - I think I confused myself (and everyone else) by omitting an empty (0x00) byte in each. Counting from the left it should make no difference.

[Lomax]

Configuration options

The configuration options of the Mass Combi can be accessed with the commands 0x01 to 0x1B, which means there are 27 paramaters (or commands) in total. The last byte before the checksum specifies whether we are reading or writing the setting, with 0x01 to perform a read and 0x00 to perform a write. For example, to read the float voltage setting, the command is:

0xC1  0xF0  0x0A  0x00  0x00  0x00  0x00  0x01  0xBC

The response seems to contain the value in the first two bytes following the command, again in reverse byte order, so a typical response to the above command (on my 12V lead-acid system) would look like this:

0xF0  0xC1  0x0A  0x2D  0x05  0x00  0x00  0x00  0xED

If we take 0x2D and 0x05 in reverse order we get 0x052D, which is 1325 in decimal. Divide by 100 to get the float voltage, 13.25 V. I don't know what the next two bytes are used for, if anything; they always seem to be 0x00 0x00. It's possible that some commands use these for additional values, or higher precision, or that they're just left blank to keep all requests the same length. Here's a list of all the settings I've been able to figure out so far:

dec  cmd  parameter             scaling
---------------------------------------
     ...
 8  0x08  Bulk Voltage              100
 9  0x09  Absorption Voltage        100
10  0x0A  Float Voltage             100
11  0x0B  Return To Bulk Voltage    100
12  0x0C  Force Float Voltage       100
     ... 
15  0x0F  Gel Compensation          100
16  0x10  Return Amperes             10
17  0x11  Max Charge Current         10
18  0x12  Bulk Time                   1
19  0x13  Return To Bulk Time         1
20  0x14  Max Absorption Time         1
21  0x15  Min Absorption Time         1
22  0x16  Dc High On                100
23  0x17  Dc High Off               100
24  0x18  Dc Low On                 100
25  0x19  Dc Low Off                100
     ...

I'm still trying to determine what the commands in the gaps are for - I think some will be to get the serial number and firmware revisions, as well as the DIP-switch settings, since these are all included on the "settings" tab of the official software:



To write a setting we need to perform the conversion to hex in reverse; we take the desired new value and multiply it with the scaling factor for the setting, convert it to an integer and swap the byte order. For example, in JavaScript:

var val = 13.25;
var fac = 100;
var int = parseInt(val * fac);
var buf = Buffer.from(["0xC1","0xF0","0x00","0x00","0x00","0x00","0x00","0x00"]);

buf[2] = 10;                   // the command, 0x0A;
buf[3] = (int & 0x00FF);       // the value, low byte
buf[4] = (int & 0xFF00) >> 8;  // the value, high byte

To complete the command we of course also need to append the (mod256) checksum:

function addCsum(buf) {
    var sum = 0;
    for(var i = 0; i < buf.length; i++) {
        sum += buf[i];
    }
    var csum = Uint8Array.from([(sum % 256)]);
    return Buffer.concat([buf, csum]);
}

var cmd = addCsum(buf);

Our command buffer is now ready to send to the Mass Combi, which would set the float voltage to 13.25 V:

0xC1  0xF0  0x0A  0x2D  0x05  0x00  0x00  0x00  0xED

[Lomax]

And that's about as far as I've come.

[goboatingnow]

Did you craft this screen

[Lomax]

Originally Posted by goboatingnow

Did you craft this screen Attachment 247525

I did indeed, though the Node-RED dashboard components make it quite easy - once you've got the data!

[Lomax]

I'm also working on a "settings" screen for the Mass Combi, though there's still a lot of work left on that one.

[goboatingnow]

Originally Posted by Lomax

I did indeed, though the Node-RED dashboard components make it quite easy - once you've got the data!

I like the dash board very nice. Must look at node -red

[Lomax]

Then you might like these as well Node-RED is fantastic!

[SV__Grace]

Wow, Lomax, your back end programming is amazing, I could never do that.

We refit our boat with all Mastervolt products and my electrician set it all up for me so everything spoke to each other and worked together nicely.

You may be interested that-

1. My chart plotter/MFD is B&G (Zeus, but Vulcan works too) and through CZone I'm able to access most of the normal electrical functions through digital switches on the screen for daily use. (I have dual helms so the inside MFD is easily accessible for me)

2. I mounted a USB plug (female) on my AC/DC switch panel that is connected to the Combi that allows me to easily plug in my computer to access Master Adjust for all the setting and functions that CZone doesn't have.

3. A couple of years after the initial install I recently added a Master View unit that allows me to easily access important functions without using the MFD or plugging in my computer. For example, if my compass, chart plotter, depth sounder, etc starts getting wiggy and I need to reset the Navigation system/devices, I can turn it off and back on using the Master View with one digital button without using the computer. To save power I can have important data show up on the Master View instead of having the MFD on, etc. The Master View is pretty cheap and makes some functions more convenient for me so I decided it was worth it.

4. You may have figured this out already but being able to program the functions of switches/buttons means that you can combine functions. In the example above, all my navigation devices can be turned on and off with one button. When I turn on my bow/stern lights my steaming light automatically gets turned on, and if I turn the motor off to sail and turn on the tri-color, the bow/stern lights and steaming light automatically turn off. Pretty cool!

[jacktheflyer]

Thankyou for posting this. I spent a fair bit of time trying to access my Mastervolt unit without success. I will give this a go. Genius.

[Lomax]

@SV__Grace Thank you for the kind words! It's an interesting detective work, driven as much by curiosity as it is by frustration at the lack of support from Mastervolt. I've looked at their MasterView/EasyView products, and other MasterBus options, but it seems none of them would make integration with Node-RED possible. I'm sure they are good solid products, but I really want the flexibility Node-RED offers.

Just as one example, this allows me to set up alerts via SMS and email when the boat loses shore power, so I can ask marina staff or one of the neighbouring boats to investigate and if possible restore it. I run a local instance of Node-RED on a Raspberry Pi which does all the data gathering and processing. This is installed in a fan cooled enclosure together with a 3G modem/router, a five port gigabit switch, a 12V 17Ah SLA battery and an OpenUPS board. Everything inside the enclosure will continue to run for about 15 hours (total power draw is a measly 0.6A!) even in the event of a house bank failure, and it is mounted in the forward part of the cabin, well away from any sources of fire and high enough that the boat would have to sink before it gets submerged. The Raspberry Pi keeps a VPN link to a cloud server which runs a separate Node-RED instance, passing all data to it via MQTT. This allows me to view the dashboards without directly accessing the Pi and provides permanent data storage in an independent location. My work means I often have to spend months away from the boat and this set-up gives me peace of mind and at-a-glance status updates of everything on board. I get notifications and pictures when there is movement on board, if the boat makes any sudden movements or if any of the alarms are triggered. I can control lighting, ventilation and (soon) heating remotely, and a multitude of sensors let me check the weather situation, temperature and humidity inside the boat, whether any doors or hatches are open, how often and how long the bilge pumps have been running, etc, etc, etc. I also have two tiny cameras which take high resolution still images in visible and infrared, one with a view of the cabin, the other the wheelhouse and deck. All of this is integrated in a single set of easy to use graphical dashboards with an infinitely configurable alert system. I've even set up an SMS gateway in Node-RED that lets me check and execute some critical stuff also in the event that the Internet connection goes down. I don't know of any off-the-shelf system that comes even close to this level of integration and functionality. If one existed it would cost an absolute fortune.

I'm sure many of you will think this is total overkill, and it probably is, but I do enjoy tinkering with things

[Lomax]

Originally Posted by jacktheflyer

Thankyou for posting this. I spent a fair bit of time trying to access my Mastervolt unit without success. I will give this a go. Genius.

Awesome! Don't hesitate to ask if you're wondering about something - I'm always happy to help!