Part 1: Requirements and Overview

This is, at long last, intended to be the definitive guide to how I connected a PC to my heat pump using a wired modbus connection, currently for monitoring, and, hopefully in the near future, for controlling the heat pump. It is not the only way a connection can be made, of course, but it is a real world example of how one person did it, and my aim is to provide enough how to detail to mean that anyone who follows the steps to be detailed below will end up with a reliable connection. This first post will list the requirements, and provide an overview of the whole setup.

Hardware Requirements

1. A heat pump/heat pump controller with an available modbus connection. This is a sine qua non, if you can't make a connection, it is game over. All Midea and Midea clone heat pumps and (I believe) at least one LG heat pump have this connection available out of the box, Samsung heat pumps have it with an add on board, and others may well have it. Physically, what you need is two connections, normally but not always (Midea is a case in point, they are labelled H1 and H2) labelled A- (or just A) and B+ (or just B). Use the technical manual for your heat pump to determine whether these connections are available, and if the manual says they are (and gives details of the modbus protocol), then make sure you can gain physical access to the terminals without either electrocuting yourself (you will turn the heat pump off while you make the connection) and/or blowing up your heat pump.

2. A small form factor 'headless' PC, headless meaning it normally runs without a keyboard or monitor, though these are needed temporarily for setup (and so you need to have a keyboard and monitor you can use during setup, perhaps borrowed from another PC). The exact model doesn't matter, as long as it has enough computing power (pretty much a given these days) and memory (specific requirements to be detailed later, this is just an overview), the emphasis is more on small form and low power consumption. It also needs to have (you would be hard pressed to find one that doesn't have these) USB port(s), network cable (RJ45) port(s) and display and keyboard (or another USB) ports for temporary use during setup. I happen to have ended up with have Dell Wyse PC, about a foot square on the long sides and two inches deep, and it is fanless, which keeps the power consumption low. It also needs the ability to turn itself back on after a power cut, which most small form factor PCs will have, but check it does have it, and how to turn the setting on, in case it is off (read the specs/ask the seller). 

3. A USB to modbus (or more accurately, RS-485) converter. This takes the wire from your heat pump (and any other optional modbus sensors you have), and allows you to plug it into a USB port. RS-485, like USB, is just another serial connection 'dialect', which is more suited to long cable runs, which USB is not. Such connectors are cheap, and widely available on ebay and elsewhere.

4. A router, normally your broadband router, with two spare network cable (RJ45) ports. You use this to make the connection to your headless PC (item (2) above) from your main PC (next item below).

5. A desktop PC, laptop or at a pinch, a tablet with a decent sized screen. All this item actually needs is the ability to run a browser, some sort of file manager eg Windows Explorer or equivalent, and a wired network (RJ45) port. I do not like smart phones, and don't have one, but I suppose you might be able to use one, making do with a wifi connection rather than a wired connection, but I do not recommend it, the screen is too small, the OS is too painful to use, and if you choose that route, you are on your own.

6. Cables to make the connections: two standard network cables, to connect desktop PC to router and router to headless PC, plus a long enough run of standard shielded twisted pair cat 5e network cable to reach from your headless PC to your heat pump modbus connection terminals. You also need a 120 ohm resistor, to connect across these terminals (a modbus requirement, said by some not to be essential, but it is not difficult to add it, so why not do so).

7. A USB stick, used for transfers during initial setup. Any reasonably current USB stick will be fine (ie have enough storage on it).

8. Optionally, other sensors. I added an room temp sensor, as the Midea controller senses the room temp wherever it is situated, which in my case is in the airing cupboard, which doesn't accurately reflect main living room air temperatures. I may also at some stage add an outside air temp sensor, as the Midea ambient temp sensor is in the heat pump, and is perhaps affected by the local effect the heat pump has on local ambient air temp, though in practice the effect doesn't appear to be great (comparing the Midea ambient temp with other independent sources doesn't show big differences).

9. Last but not least, small electrical screwdrivers, wire strippers, and whatever tools you need to run the cable from the headless PC to the heat pump. My cable goes along one wall (against the skirting board, like an old fashioned telephone cable), through an existing hole in another wall, then under the floorboards to the Midea wired controller in the airing cupboard. The cable is small, and can almost always use existing cable/pipe cutouts to get from A to B.

The total cost of everything should be comfortably under £100, depending on what you already have, and the exact detail of what you buy. I spent about £80, and that included a relatively high spec as new headless PC (£50). Had I gone for a cheaper more obviously used one, I could probably have halved the cost 

Software Requirements

1. As already mentioned, the ability to run a browser and a file manager on you main desktop/laptop PC. These are bound to be already present on any modern PC.

2. The core requirement on the headless PC is python (and of course an operating system to run python). Python is a ubiquitous programming language with an almost infinite number of add on packages, or modules, that means it can do almost anything a computer can do. In and of itself, in its basics, python is not complicated, even if that doesn't stop some folk from making it infinitely painfully complicated, but fear not, we do not need to descend into that computing version of Dante's Inferno. If you can read and write English, you can read and write the sort of python code we will use, once you have grasped the basics of the language.

3. The headless PC operating system: it doesn't actually matter what it is, as long as it can run python. In the event, for historical reasons, I have a hacked Alpine Linux version installed by Home Assistant, the historical reason being that I started on this journey trying to use Home Assistant, only to find Home Assistant and I are not best buddies, and I therefore decided to go down another route (basic python plus modbus). But, as Home Assistant had left a usable OS on the headless PC, why not use it? That's what I have done, and will describe how to do in future posts; it also means you can try out Home Assistant, and see whether it is for you. I have to confess I do occasionally use its its History Explorer Card add on, and, because it's there, I also use it's Samba add on (provides local networking) and an enhanced terminal add on (provides command line access to the headless PC). Yes, I could have set these things up in other ways, but, as I say, for historical reasons, they got added inside Home Assistant, and being lazy, I am not going to strip them out and start all over again.

4. You will also need to have python installed, and add some modules. Home Assistant comes with python, in fact it is largely written in python, and it also includes many python modules, or add ons, but not all the ones you will need. At a minimum you need to add the minimalmodbus module, which, as its name suggests, is a minimalist (ie simple yet capable) module that enables modbus connections in python.   

5. Charting software. You are spoilt for choice here. My system logs the modbus/heat pump data to csv files (text files, comma separated variables), meaning you can use anything that can chart csv data. Home Assistant can do it, but it is a long and winding (and very tedious) road, using a so called file sensors to get there, and I do not recommend it. Instead, use either a spreadsheet (Excel, Libre/Open Office Calc, Google Sheets) or if you want something a bit more fancy, either highcharts.js or one of the charting and plotting add on modules in python. Many of these more fancy options will provide interactive browser based charts that can be zoomed and panned, have data value popups, and can also save charts in high quality print ready vector pdf format, as well as save then as normal raster graphics (png/jpg format). I currently use highcharts.js and, in python, plotly express. Full details will be given later.

6. A large text file editor (large text file, not large editor). The csv data files need to be checked and occasionally edited from time to time, and sometimes a simple edit is needed to a python file (which are also text files). I use Notepad++, freely available and very capable, especially with extra plugins.

7. You can use your text editor of choice as the only way to edit python files, but I prefer to use a more dedicated python editor, in my case the bog standard IDLE editor that I already have installed on my desktop PC (it comes with a standard python installation). This means I can edit the python files on the headless PC from my desktop in a more convenient environment, but I still have to run then from the headless PC (via the terminal/command line). Don't worry if this is all starting to go over your head, all will be explained later. The bottom line at this point is that you will almost certainly want to install python on your desktop PC, if you don't already have it installed.

Human Requirements (what you need to bring to the party)

1. A willingness to learn. It is pretty much a given that you will not know everything you need to know at the start of this process, so you will need to learn some things. But learning new things can be fun and rewarding, and the level of complexity is not daunting. If I had to put a level on it, I would say it is at about the level of what used to be O levels in my day, less than A level, and certainly less than degree level. Embrace the learning, and enjoy it!

2. An ability to use tools without damaging either yourself or whatever it is you are working on. The most delicate tasks will be stripping the cables and screwing the connections, because the wires are small, and the most arduous, should it be needed to run the cables, drilling holes in walls and joists. Everything is well within the capabilities of normal DIY. If on the other hand you have a tendency to strip the conductor as well as the insulation from cables, and invariably drill through live conductors and pipes when using a drill, then maybe this project is not for you.

Overview: why modbus, and how it works

I chose to use a wired modbus connection, because at the end of the day, it is simple and robust, and can readily be controlled using python. There are other ways, and you are free to use them, of course, but I like simple and robust, and for that reason, chose a wired modbus connection. I would go so far as to say this is by far the simplest setup, and yet it works very well. The same reasoning applied to using python and minmalmodbus to do the heavy lifting: once set up, which, trust me, is not that arduous, now that I have worked out how to do it, it is simple and very robust. It can even restart itself after a power cut. 

Modbus itself is a protocol/language that allows us humans to connect to and 'talk' to machines, with the ability to read (get) and write (set) values. For example, I can read (get) the current leaving water temperature (LWT) from my heat pump, and I can can also write (set) a desired the LWT. This happens over the wired connection, with the headless PC being the controller, or so called master, and the device(s) being read being so called slaves, each of which has it's own ID (a number). Inside each slave there is an array of pigeon holes, or registers, each of which has an address (again a number), that store the data, meaning the master can address a particular register in a particular slave to get, or set, the value in that register. In our wired setup, the modbus dialect is called modbus RTU, and the communication standard, or protocol, is called RS-485. RS-485 is like but not the same as USB (both are so called serial connections, serial because the data goes serially, ie one bit after the other, rather than in parallel), but the two can be readily translated from one to the other, allowing us, given such a converter, to connect a computer with a USB port to a modbus setup. This does involve setting some parameters eg the speed of transmission, but these parameters are 'set and forget'; once done, they stay done, and this is all easily done in python, in a few lines of code.

If you want an analogy, the whole setup is a bit like an old telegraph that uses Morse code. In each, the wire carries a serial message in a code back and forth between two terminals. In the telegraph setup, I might ask, in Morse code, having connected to an address elsewhere, what the temperature is at that other location, and that other locations then sends back a message, again in (Morse) code, saying the temperature is so many degrees. I could then optionally send another message, asking the other location to turn up the heat a bit, or cool things down a bit. At its heart, that is all and everything the modbus connection does. 

Schematically (full details later on individual bits of hardware), my setup looks like this:

More posts will follow, but just as Rome wasn't built in a day, this thread won't be written all in one go, but in stages.