Monitoring and controlling a JUDO i-Soft plus water softening device via LAN

Some time ago, a water softening device was installed in my home main water supply line. Such a device contains one or multiple gel capsules that act as ion exchangers, replacing the calcium and magnesium in the fresh water supply with sodium. In regions with a rather hard water, this can save you a lot of trouble with maintenance of valves and the lifetime of water-consuming devices like washing machines and dishwashers.

Fig. 1: JUDO i-Soft plus unit with LCD touchscreen user interface.

For regulation, a conductivity sensor determines the hardness of the incoming water. After running through the gel exchanger, the residual hardness is assumed to be around 0.5 °dH which allows the mixing ratio of raw and processed water to be calculated. I won’t go further into details here, the bottom line is: It works like a charm, water is as soft as it needs to be. The device at hand is built by JUDO and is available in several configurations. Basic models contain a two-capsule exchanger for seamless switchover/regeneration cycles and an integrated electronic control unit for automatic regeneration of the gel. A more advanced “i-Soft plus” model is extended by a touchscreen user interface complete with LAN/WLAN network access. This enables monitoring through a specialized iPad application where the interested user can view total water consumption per day, week, month or year as well as change different system parameters. As a nice bonus, the plus unit has an integrated main line valve which is closed automatically whenever user-set time, volume or flow rate limits are exceeded. This already saved my ass once when a pipe became leaky inside a wall. Unfortunately, the exact protocol for communication with the device is not disclosed, which is where this story begins.

The integrated metering feature is pretty cool as it spares me the effort to tap into the original water meter, which is analog and would therefore require something like a reflective infrared sensor. Access by hand or iPad is not what I had in mind, though. Instead it would have been nice to access the monitoring data through a Raspberry Pi which already monitors and controls the gas heating equipment and solar thermal system, but this seems not to have been anticipated by the programmers. Aside from statistical purposes, this would also allow me to trigger much more audible alerts or even an eMail whenever something bad happens. But how to get the data?

Fig. 2: Backside of the LCD user interface module, with LAN connection and the microSD card on the right.

First I had a look at the front panel module. It consists of a single board computer which looks custom-made and runs linux. Finding out the OS was pretty much intuitive and easily verified by pulling out the microSD card sticking out of the LCD module. I dumped its contents to disk before returning it and poked around the image.

Some interesting facts I learned from puzzling through the bundle of scripts:

  • The data for the iPad app is exchanged through HTTP/HTTPS.
  • Several ports are used for communication: 8000/TCP and 8124/TCP.
  • HTTP on 8000 supplies a rudimentary user interface for the command set.
  • Commands are queried through HTTPS on 8124.
  • There is also an open interface on 8833/TCP. No idea what for, though.
  • If enabled, there is a KNX-IP-Interface available. The command set is documented in /Judo/app/judoserver/knx.js.
  • I managed to find a service code which allows access to the hidden parts of the configuration menu, but in fairness towards the very helpful customer service of the company I will not disclose that, and I do not recommend just trying out numbers. There are several PIN codes some of which, upon entering, instantly perform service operations. It has however served me well in diagnosing a fault that was – unfortunately – not detected by the firmware and even misled my service technician.  This specific error was caused by a loose electrode cable for the “saline level low” sensor. In consequence, the unit would start regenerating and not notice that the saline level drops below the level where fresh water should be supplied to the tank. Instead, it would run on until the “tank empty” signal caused it to trigger an error. It seems like the programmers missed a plausibility check in the software here, which checks if the low signal is absent when the high signal is present. Aside from regions of inverted gravity, this should never happen 😉 No harm done though, and after reconnecting the unit works nicely again.
  • From an engineer’s point of view, the unit is rugged and pretty well designed. As for the display module, I like that they took care to disable all unused and security-critical ports which are so often found on linux devices. All communication with the company server is handled through SSL encryption.

Now we can simply try to access these ports from any web browser (with javascript enabled!) by calling up http://192.168.0.xxx:8000. In my case, the first attempts were not successful until I noticed that the remote access needs to be unlocked first. To do that, you need to access the settings menu from the touchscreen and register as a JUDO user. Remember your username and password, as well as your device serial number. Your will need it! After registering you are asked to accept the terms of service for remote data monitoring. This might bring you a benefit because the company grants you a longer support period, but I personally don’t like it very much if my appliances phone home all the time, so I declined. Note that it is absolutely sufficient to decline, since local access will be granted anyways.

After registration, a call to port 8000 brought up this very promising page:

Fig. 3: Command webpage served on port 8000 after activation.

This appears to be a debugging user interface for the data protocol which uses HTTPS (!) on 8124. Maybe it was forgotten there? The file served is /Judo/app/judoserver/tst.html on the SD card. You can enter all necessary data into this form, click on the command to the left and it will send the data to the correct port and show the reply once it arrives. It took me some time to understand what needs to be done, but here is the sequence:

LOGIN. This requires your username and password as given in the registration form. Your role is customer. This will send the query

https://192.168.0.xxx:8124?group=register&command=login&msgnumber=2&name=login&user=username&password=password&role=customer

and, after some time, return something like

{“group”:”register”,”command”:”login”,”msgnumber”:”1″,”name”:”login”,”user”:”***”,”password”:”***”,”role”:”customer”,”status”:”ok”,”token”:”d07524f55a5469ae58bb5ab2c6d146f60129e8613938036543bdd4bc02f27dc9″}

 

CONNECT. You received a token in the login step which is automatically entered into the correct boxes below. Besides the token, you need the device serial number. The device type is i-soft plus. This will generate the query:

https://192.168.0.xxx:8124?group=register&command=connect&msgnumber=5&token=token&parameter=i-soft%20plus&serial%20number=serial

Note that %20 escapes whitespaces. A reply will look like this:

{“group”:”register”,”command”:”connect”,”msgnumber”:”3″,”token”:”d07524f55a5469ae58bb5ab2c6d146f60129e8613938036543bdd4bc02f27dc9″,”parameter”:”i-soft plus”,”serial number”:”***”,”status”:”ok”}

 

Now that we have authenticated with the device and have a valid session running, commands and requests can be executed using the token as authentication. These come in a wide variety, ranging from “what is the current salt status?” to “lock the main line valve!”. Interestingly, the remote access also allows the original (measured) raw water hardness to be read out, which is not available though the LCD without entering service mode. Strong deviations of this value can serve as an indicator for a faulty sensor (had one fail on me so far), in which case the regeneration cycle and mixing will no longer work properly.

To obtain any value from the interface module, we send a request string using the previously stored token as identification:

https://192.168.0.xxx:8124?group=info&command=natural%20hardness&msgnumber=1&token=token

will generate a response like

{“command”:”natural  hardness”,”data”:”17″,”group”:”info”,”msgnumber”:”1″,”status”:”ok”,”token”:”d07524f55a5469ae58bb5ab2c6d146f60129e8613938036543bdd4bc02f27dc9″,”wtuType”:”i-soft plus”,”serial number”:”***”,”tftStarted”:***}

The data field containing the “natural hardness” variable can be easily identified since the array headers are included in the response, giving a value of 17°dH. The list of commands can be taken from the web interface listing.

For diagnostic purposes, I have written a small PHP script which gets several status values from the device and displays them in a somewhat readable fashion. You may download the file here:  JUDO iSoft plus – PHP interface

However, because of the low response time of the interface, page loading takes between one and two minutes. I am pretty certain though that the timing is mainly caused by PHP, but there might also be an additional trick involved for high-speed communication.

Fig. 4: Output of the PHP script after connecting to the i-Soft.

Here you can see the data returned for natural and selected hardness, saline reserves, average and current water consumption, hardware versions, water stop config and status, as well as some of the water usage history values. The unit stores those, and you can select and download any period of time in any resolution you want. So far I did not implement any remote commands in the UI, but this is a minor feat. Triggering the main line valve with the appropriate command works like a charm.

Also, the server app on the unit seems to drop out from time to time. A power-off reset helps in that case.

German title: “Ansteuerung einer JUDO i-Soft plus Wasserenthärtungsanlage per Netzwerk”

Leave a Reply

Your email address will not be published. Required fields are marked *

*