Monitoring and controlling a JUDO i-Soft plus via LAN

| Mario

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 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 the 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. My 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. Write down your selected username and password as well as your device serial number, since you need both for remote access.

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. This is absolutely sufficient for what I need though, since local network access will be granted anyways. Only the access by iPad/phone from external places will be blocked since that would need to be re-routed over the company server and then tunneled to the unit.

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 actual file which is served here 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/SSL, but there might also be an additional trick involved for high-speed-ish 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/software versions, automatic 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 water stop valve with the appropriate command works like a charm, but you should keep in mind that the person showering at the moment might not see this as a classy joke.

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

It has come to my attention that several people have stumbled across this post (see here @ knx-user-forum.de) and compressed the control concept into a functional plugin for FHEM (here @ fhem.de) – thumbs up for this! So, this might be a faster way to try out.

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

No related posts.

31 thoughts on “Monitoring and controlling a JUDO i-Soft plus via LAN”

  1. My goal is to integrate my Judo device into HomeAssistant. I have a Judo i-soft plus connected with WIFI with the following version:
    EI. Steuerung
    Software: 02.09.h
    Hardware: 5.10
    Betriebssystem:
    Software 02.20
    Anzeigemodul
    Paket: 1.0.63
    Software: 1.0.22
    Hardware: 1.40

    In the App, even though slow, I can see and control the device.

    But I cannot bring up the debug page on port 8000 nor the login.

    Any advice? Would be a shame to not use the device in HA.

    Thanks
    Ravi

    Reply

  3. Hi, thanks for the info. It helped me to connect my home automatio to the Judo system and it has worked for some years but my home automation cannot do https connections so I have an intermediate web server with php to handel the translation. I would like to remove this intermediate step.
    Have you been able to access the api via http, no encryption? I have anyway the Judo firewalled so it has no internet access. It would not be a security issue.

    Reply

  4. Hallo Mario,
    durch einen Firmware Bug ist die Verbindung zur i-soft Plus lokal nicht mehr möglich.
    Judo hat mir die FW mit Anleitung zugeschickt. Die musste dann neu installiert werden und seit dem geht die Verbindung zum Portal wenigstens wieder. Nur kann man sich lokal nicht mehr anmelden. Hast Du einen Tip, was ich da eventuell neu konfigurieren müsste?

    Die Rückmeldung beim Login Versuch mit userid und Passwort sieht wie folgt aus:
    {“group”:”register”,”command”:”login”,”msgnumber”:”1″,”name”:”login”,”user”:””,”password”:”*”,”role”:”customer”,”status”:”error”,”data”:”login failed”}

    VG
    Christian

    Reply

    1. Hi Christian, hast du das Problem gelöst? Ich habe auch einen Firmware Bug das die Verbindung zum Server nucht richtig funktioniert auch direkt via LAN.
      Kannst du mir die letzt Firmware senden? g.resch@gmx.at

      Reply

  5. Thanks for the shared information. I’m about to buy a JUDO SOFTwell S with Connectivity Module.
    Any idea, if this also works for this model? I don’t need the i-Soft-Plus, so paying €1000 more, just for the interface and being able to actually change values, would be too expensive.

    JUDO couldn’t even tell me, if the advertised web interface means, I could open the information page in my LAN. They kept responding on how to use the app.

    Reply

    1. Hab mit dem Kundendienst von Judo gesprochen, die haben mir die Softwar zugeschickt. Diese habe ich dann neu installiert und dann habe ich bei der erneuten Registrierung die Datenschutzerklärung abgelehnt.

      Reply

  7. Hallo,

    Erstmal Danke für die Infos zur Judo.
    Ich möchte das ganze unter openhab verwenden, hab hier aber das Problem mit einem abgelaufenen SSL-Zertifikat, da https-Anfragen mit abgelaufenem Zertifikat scheitern.
    Hat jemand eine Idee wie man evtl. das Zertifikat erneuern kann?

    Ist das Zertifikat bei Euch auch schon seit 31.07.2014 abgelaufen?

    Reply

  8. Hallo zusammen und vielen Dank für die Vorarbeit. Ich habe das ganze in FHEM definiert, jedoch ist da noch etwas unklar.

    – wie kann ich die Datumswerte in ein lesbares Format umwandeln?
    service-date 1589868875 => TT.MM.YYYY
    – gibt es eine Stelle um mehr über die Wasser Szenen zu erfahren?
    – Habt Ihr bereits geschafft die aktuelle Scene auszulesen und eine Andere zu setzen?

    Gruß
    Christian

    Reply

    1. Hi Christian,
      eines kann ich dir direkt sagen: Das Service Date ist Unix-Time in Sekunden seit dem 1.1.1970 (epoch). Dekodiert wäre das der 19.05.2020 – 08:14:35 (https://www.unixtime.de/).

      Zu den Szenen kann ich leider nichts sagen weil meiner das noch nicht unterstützt, wie es scheint.
      Gruß Mario

      Reply

      1. Hallo Mario,
        vielen Dank für die Information, ich schau mal wie ich das in FHEM formatieren kann.
        Gruß
        Christian

        Reply

  9. Danke Mario für diesen Artikel!

    Eine Frage zur i-soft plus habe ich noch. Kann man die Anlage auch dazu überreden, die Daten rauszurücken, wenn sie nicht am Internet hängt, sondern nur im lokalen Netzwerk?

    Viele Grüße

    Reply

    1. Gute Frage! Ich meine, dass das gehen müsste. Dummerweise gibt das Gerät erstaunlich wenig Feedback zum Ablauf des Prozesses, aber um einen lokalen Account anzulegen benötigt sie ja keinen Zugang zum Netz. Ich würde es so machen wie in der Anleitung beschrieben, wenn man keine Online-Anbindung haben möchte. Ich musste neulich nach einem Austausch der Displayeinheit (Chip defekt) den Account neu eintragen, und da war die Firewall für den iSoft auch zu, ergo formell kein Internet. Manchmal braucht es aber zwei-drei Versuche, habe ich schon gemerkt, bis das Interface dann auch reagiert.

      Reply

      1. Ich komme auf die Seite http://xxx:8000 nicht wenn ich die Internetverbindung der judo trenne, ich erhalte hier nur die Fehlermeldung “An error has occurred: {“code”:”ECONNREFUSED”,”errno”:”ECONNREFUSED”,”syscall”:”connect”}”

        Ich wäre sehr an einer Lösung ohne Anbindung ans Internet interessiert.
        Hat es schon mal jemand geschafft die genaue Kommunikation auszulesen?
        Könnte man so nicht die Anbindung auf einen eigenen Webserver umleiten so der judo vorgaukeln sie wäre mit dem Internet verbunden?

        Tom

        Reply

        1. Es funktioniert jetzt ohne Internetverbindung. siehe meinen Eintrag oben.
          Jetzt habe ich nur noch das Problem mit dem abgelaufenen SSL-Zertifikat.
          Wenn jemand eine Idee hat wie man das evtl. austauschen kann würde ich mich freuen. :-)

          Reply

  10. Hi Mario,
    thanks for the detailed information!
    I just read out my i-soft plus.
    I also implemented the setting of opening and closing the valve.

    Now I want to set also the waterscene on my i-soft plus.
    Therefore I need the judo knmtoken.
    How can I get this token? In WebUI of the Judo i-soft I see it in the url. But I don’t found out how to get this knmtoken via coding.

    The call to set the waterscene is e.g. for normal or showering this one’s (browser debugging):
    https://www.myjudo.eu/interface/?group=register&command=set_optisoft_waterscene&serialnumber=&token=&parameter=normal&time=
    https://www.myjudo.eu/interface/?group=register&command=set_optisoft_waterscene&serialnumber=&token=&parameter=shower&time=

    Further more I’d like to read the actual waterscene. In the browser debugging I don’t find any information about this.

    May be you have some forther information for me.

    Kind regards
    Bernd

    Reply

    1. … one further point in addition.

      To read the data Init-Date and the Service-Date of the i-soft, there are two calls, I found in the overview page of the functions:
      Init-Date
      https://:8124/?group=contract&command=init%20date&msgnumber=2&token=

      Service-Date
      https://:8124/?group=contract&command=service%20date&msgnumber=2&token=

      The Init-Date ist correct, when I transfer it to my home automation.
      The Service-Date has the same date as the Init-Date in the reply. This is very strange. When I check the date in the Judo-WebUI I get the next service date this year in September.

      What could be the problem here?

      Kind regards
      Bernd

      Reply

    2. Hello Bernd,

      Did you ever find a way to programmatically get the access token? The JUDO tech that I was forwarded to told me that accessing the API is impossible without the App, which we know is not true.

      If not do you know how long the tokens live after a manual logon? Mine lasted over 24 hours so far and I will keep using it until is stops working and decide what my next steps are.

      My hope is to integrate this into my Home Assistant to trigger water scenes from KNX and MQTT as well as alert on maintenance actions.

      Thank you,
      Adam

      Reply

  11. Ich hab es bishr leider nicht geschafft ohne Inernetverbindung überhaupt Kontakt zu meiner Judo zu bekommen.
    Wahrscheinlich hast Du recht, dass die Ereignisinformationen direkt vom Judo-Server kommen und deswegen nicht über diese API zur Verfügung stehen. Aber ein Versuch war es wert ;-)

    Beste Grüße
    Christian

    Reply

    1. Die Ereignis-Liste ist direkt vom Gerät abrufbar:
      https://xxx.xxx.xxx.xxx:8124/?group=state&command=event%20list&line=0&offset=0&token=xxxxxxxxxx

      Allerdings kriegt man so anscheinend nur eine ID für das Ereignis und nicht den Klartext. Bei mir z.B. für die frisch in Betrieb genommene Anlage zwigt die Ereignisliste an der anlage “Start Aktivierung” und ich kriege mit dem request oben wie unten zu sehen für den korrekten Zeitstempel nur die ID 51 zurück: “1525512345, 51, 0”. Habe bisher noch keine Übersetzungstabelle gefunden…

      Volle Response:
      {
      “command”:”event list”,
      “data”:”1525512345, 51, 0″,
      “group”:”state”,
      “line”:1,
      “maxlines”:1,
      “offset”:0,
      “status”:”ok”,
      “token”:”xxxxxxxxxx”,
      “wtuType”:”i-soft plus”,
      “serial number”:”xxxxxx”,
      “tftStarted”:1525542682197
      }

      Reply

  12. Thank you very much for this nice solution. I adapted this for me and it works like a charm.
    But do you have an idea how to get the event list (e.g. “23.09.2017, 12:06 Wasserstopp geschlossen”) like you can see in the judo manager app?

    Thanks in advance!

    Best Regards,
    Christian

    Reply

    1. Not yet, but I can check later today if there has been any update to the interface which I did not notice yet :-) Maybe the command simply is not documented in the web control frontend, in which case I will find it in the script file on the JUDOs disk.

      By the way, if you happen to have any suggestions for improving the query speed – advice is always welcome. Although I suspect that any other method would easily be faster than PHP, the query module seems to be really old-fashioned.

      Best, Mario

      Reply

      1. Thanks! I am looking forward to hear from you about new features ;-)

        Regarding query speed: I do not think, that PHP is the reason for the slow performance. If you look on the debugging user interface or directly in the judo app, you can see the same slow behaviour. I think, it is because of issues inside judo infrastructure.

        Best Regards,
        Christian

        Reply

        1. Okay, maybe it is my PHP instance which is the problem ;-)
          Unfortunately the remote commands will have to wait for the weekend, I can’t find my backup of the SD card contents right now. I’ll just pull a new dump.

          Deutsch ist übrigens auch okay, wenn gewünscht :-) Im Nachhinein ist der Artikel außerhalb Deutschland vermutlich eh nicht sonderlich relevant…

          Mario

          Reply

        2. Hm, so far I could not find anything which relates to the event queue. If you have an Apple device linked with your Judo, could you check if the events can be read if no internet connection is available, but the device can be reached directly? Maybe the events are queried from the Judo webservice, since maintenance data is transferred most certainly.

          I still need to check some other files, these commands could be handled differently.

          Reply

Leave a Reply

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