feature-requests
feature-requests copied to clipboard
esphome
Read and control Gecko spa controller (in.YE, in.XM, etc.)
Describe the problem you have/What new integration you would like
The Gecko IN.YE Spa main controller has the option to be controlled via an external IN.Touch2 WiFi connected device (official link broken, a random example here ). There is an extensive discussion ongoing in the Home Assistant feature-request forum but it's a mix of hijacking and reverse-engineering the C0 interface and integrating the OEM IN.Link2 device. So let's try to split the hijacking part to another discussion.
Please describe your use case for this integration and alternatives you've tried:
Find a way to interact with the IN.YE spa controllers without having to buy an IN.Touch2. RS485 on the C0 port seem like the best bet at the moment but looking around on the main-board there are also I2C mentioned on some connectors.
Even if the discussion is posted in the ESPHome forum I don't see the need to restrict it for ESPHome only. Arduino sketches or even PC communication could be helpful to share, and eventually it should be portable to ESPHome which in my opinion has the widest usability and good interaction with Home Assistant.
Additional context
Useful links from the other forum. https://community.home-assistant.io/t/gecko-in-touch2-integration-spa-wireless-remote-control-module/150764/102 https://community.home-assistant.io/t/gecko-in-touch2-integration-spa-wireless-remote-control-module/150764/143
I took some photos of the additional soldering points in the main-board, unfortunate for me the RS485 (and remote relays for whatever might be used for) pins seem a no-go since no components mounted. But the I2C could maybe work. Still the C0 - C2 ports are maybe the better bet since they are for communication the external devices.
Following this... If anyone figures out the RS485 pins (GND, A, B), I'm willing to try to sniff some data.
There's a lot of info scattered around, but I don't think anyone's gotten very far in Gecko reverse engineering. Here's some useful info on pin probing work that agittins had done over in the geckolib repo: https://github.com/gazoodle/geckolib/issues/8#issuecomment-876631237
Thanks, had missed that thread, more or less a kick-start to my planned investigations. Right now I'm stuck on getting a proper cabling to extend the ports to a decent working height (recessed spa in deck and can't do the probing laying up-side-down), but now realize I might actually want a break-out cabling to connect between the main-board and keypad.
It might be worth trying to get a hold of a broken spa side gecko unit. If nothing else for the cable. You linked to the post on the Hass forums with the google photos of the internals of the gecko unit. Maybe the OP would part with that, or could be convinced to map out the cable and get some closer pictures around the 8 pin connector.
Howdy - wow hadn't realised it had been 3 years since I did that initial probing about! I haven't got further since then, however I have been donated a faulty in.touch unit which means I should be able to gather more authorative info on the pinouts.
Re making connections - the header pins are standard IDC / DuPont / PCB Header pins in a 4x2 layout. My spa pack has a "port cover" thingy to fill the empty comms ports - it's just a plastic shell without keying on it so it will fit into any empty port to protect it from water ingress.
The shell is hollow, and you can actually jam a 2x4 header block right into it. I drilled a 6mm hole in the outer plate, threaded a cat5 cable through it, and terminated a 2x4 block on the end, which then pushes into the front end of the shell. This gives a solid, easy connector to the spa pack that can be used on any of the control ports. One could put another 2x4 at the other end and you'd have an extender / breakout / interception cable pretty easily.
I'll take photos of the plug I made to make it easier to understand - if you have one of the spare port covers it's very simple, but explaining it makes it sound complicated! 😅 Right now though it's cold and raining, and I'm pretty sure the cable is sitting under the hot tub outside 😆
Whoo! Good news - I dug out the dead in.touch-2 unit that was donated to me and I think I have a pretty confident answer on pinout and protocol!
I traced out the pins and most appear not-connected in the in.touch-2, (which is great, actually) and the only ones that seem connected are GND, 12v supply, SDA/SCL for i2c and a 5v line which might be able to provide supply, but might just be an ENABLE line, as the in.touch-2 only uses it for ESD clamping the i2c and for turning on it's 12v VREGs, it seems.
This is the relevant part of the blended photos of the front and back of the in.touch-2 pcb I used to help trace, and identify the mcu etc:
- The i2c pins are connected to two sets of i2c pins on the mcu, just paralelled. I don't know why, maybe their code switches to the second bus if the first one dies of ESD or something, or maybe they're using the other pair of pins for generating interrupts to help timing, no idea.
- I'm a bit surprised at the complexity of the supply section (everything right of the P1 header). I haven't traced it, but the SHAB looks like a 750mA step-down regulator, the PCN chip might be a bigger reg, not sure. There are parts with that code that are wimpy little vregs (like 100mA or so) and others that are 5A!
- The voltage rails I actually went out and measured on my hot-tub since there was no way to infer them from the board. Note how the 5v3 rail on pin 4 runs to the TVS ESD protection CR1 and a bypass cap, then runs up to the middle pin on Q1 - which might be a fet or a "voltage detection chip" going by what looks like P0n or P0 then a sideways-C.
So, I think this means we have enough info that for the CO port at least, people could hook up something to sniff i2c and see if they get anything useful coming through.
I suspect that there is probably handshaking that needs to go on first, so just passively sniffing may or may not get anywhere, but it's worth a shot. Anyone with a working in.touch-2 has a decent shot at capturing the entire protocol though, so I think this is definitely a viable project when someone with the time also has the resources :-)
My next steps are...
- See if I can get the in.touch-2 I have working. It was known faulty originally (hence why I now have it), but my initial poking around on it found that the "inside" unit was trying to contact a nonexistant dns name, so it was stuck in a boot-loop trying to initialise. I haven't hooked it up to my hot tub yet, but when I was first messing with it creating a faked dns definitely made it... "happier" in that it completed some sort of handshake (ping2, for anyone playing along) with the gecko server, so maybe the unit will work. If so...
- I plan to set up a passive i2c listener to sniff the traffic between the spa pack and the spa-side of the in.touch. I'm hoping I can use an esp32 and do it over wifi, because it's a pain hacking outside at midnight :-) For low-level stuff there's a sigrok sink for esp32: https://github.com/Ebiroll/esp32_sigrok and for proper i2c decoding and logging there seems to be https://github.com/WhitehawkTailor/I2C-sniffer - but both projects have been pretty quiet of late, and the sniffer one doesn't have built-in wifi sending but the
main-send.cppversion has part of that plumbing present.
Anyone who knows of an easy, via-wifi way to sniff i2c please let me know! I've got esp32's, and a raspberri pi Zero W (the old one) which might be a better option, as it can probably bit-bang a lot harder than the esp32.
Of course if I can fix my dead in.touch-2 I won't necessarily need a native esphome version myself, but I'd love to see it happen because $300 is robbery, hacking is fun and the dead unit was sent to me by someone for free in the hopes of making this happen for everyone 🚀
This is the full board of the spa-side pcb of the in.touch-2. I will probably set up a repo to upload the full-res versions of this and my notes, but wanted to get this out here in case people are ready to jump on the next step!
Quick and dirty pics of how I made a connector using the empty port covers and a 2x4F pcb header connector.
@agittins - This is all great info! Thanks for sharing your work. Nice job on building that cable!
I have a working in.touch2 unit. I had posted on 2023-11-18 about the DNS problem in the Hass forum.
My unit didn't stop working with Home Assistant, I only noticed that the clock on the spa was wrong. However my unit was already fully "provisioned". I don't know whether it was a missed update/corrupted firmware or something. I suspect/hope you should be able to resurrect that in.touch2 pair. Very curious to hear whether that fixes your unit.
EDIT/UPDATE -- It looks like my gecko unit is still doing a DNS query for intouch.geckoal.com rather than intouch2, so my work around of having a host table entry on my router for intouch that returns the IP address of intouch2 is still needed.
@agittins - A possibly tangential thought if you want to do some hacking from the comfort of your desk. The microchip RF board mrf89xam9a is SPI. Might be interesting to get an SPI sniffer going attached to the network side in.touch2 unit's RF board, particularly If your unit ever seems to sync with your spa. Some clues about what's going over the RF connection might yield clues about how much smarts are in the in.touch.
A spa installer went broke here recently, and I got 3 in.touch2 units cheap from the liquidation sale. Happy to sacrifice one to the cause. Either by taking it apart or sending to an expert to investigate. The latter would probably be more productive.
@rct
@agittins - A possibly tangential thought if you want to do some hacking from the comfort of your desk. The microchip RF board mrf89xam9a is SPI. Might be interesting to get an SPI sniffer going attached to the network side in.touch2 unit's RF board, particularly If your unit ever seems to sync with your spa. Some clues about what's going over the RF connection might yield clues about how much smarts are in the in.touch.
Yes that could be helpful at some point. My main focus is on being able to interface directly with the controller pack though, so that folks don't need an in.touch at all. But yes, if we can't sniff the i2c it's a next-best-step.
@nickrout
I got 3 in.touch2 units cheap from the liquidation sale.
Nice score! I wouldn't have use of one yet myself (on the assumption that my current issue is the controller's firmware) but if my in.touch turns out to be truly faulty maybe we could work something out (being we share a hemisphere!)
@rct
my work around of having a host table entry on my router for intouch that returns the IP address of intouch2 is still needed.
Thanks for the tip on the dns - I had forgotten who it was I should credit for that discovery! That got me from the home unit flashing RED through flashing GREEN then finally flashing BLUE, indicating that everything was good except for its connection to the Spa transmitter.
This LED status chart from the touch2 techbook is the only comprehensive status table I've seen, so worth popping in here I think:
Worth mentioning that when the home unit is in pairing mode (fast-flash YELLOW) it still lights the LED based on network status as well, so you get some awkward combinations of colour!
For the home unit, I think a more accurate diag is:
- Any yellowish (red+green) fast flashing: pairing mode in progress
- Any slow flashing: no comms between spa sender and home receiver
- Red: no DHCP reply received, check basic local networking
- Green: LAN ok, searching for Gecko server. If stuck here, rct DNS fix might be required (alias intouch.geckoal.com to intouch2.geckoal.com)
- Blue: comms established to Gecko server OK.
For the Spa sender unit:
- Any flashing: No connection to home receiver unit
- Yellow: pairing mode
- Red: No comms to pack controller. Software version of controller too old, power cycle required, or possible hardware fault.
- Blue: Normal ops.
My spa sender doesn't flash yellow at all, only red. So my guess (hope) is that it will only pair after it has good comms to the controller, and I just need a firmware update for my in.XM2.
Given the RED sender led, my next step is to try and get a software update from Gecko. Fingers are crossed, hopes are not all that high. The blurb they have on in.stik (their update device, a thumbdrive-like dongle for the CO port) is that they are keyed to a specific spa pack's serial. However, given that they also say that dealers can update spas during provisioning etc (and resellers indicate the same) my guess is that they are simply keyed to a model's revision level, and that there must be an in.stik programmer that dealers use, or they simply get sent a batch of stiks for each model at each firmware release (which would make sense given the in.stiks seem to have a durable label/tag attached to them).
I'll contact our local pool mob too, maybe they'll have a suitable in.stik already.
Gah! Oh no... after taking a proper look at the labels on my unit, it turns out I have.... an in.XM1 😱
As far as I know these are not compatible with the in.touch-2, regardless of firmware. 😭
This means that for my part at least, my hopes of reverse engineering the in.touch2 protocol are almost certainly dashed. I'm sending an enquiry to Gecko anyway to find out if there's any hope of an update, but I expect it's pretty unlikely.
Hopefully though, the pinout and board analysis will help someone else sniff the i2c data and work out how to emulate it with an esp32 or similar. Given it's just i2c this should be completely possible, given enough time to work out the protocol - but it will have to be done with an existing, working in.touch because there will be master/slave determination as well as address, handshaking etc to work out. Once it's worked out though it should be possible to replicate without any in.touch.
For my part, I'll now switch to reverse engineering the keypad and IR interface instead! I have a crusty old remote for the spa (pretty sure it's this model here, now reduced from a bargain AU$440 to a run-out special of AU$110!), so as long as corrosion (both spa water and battery electrolyte) hasn't completely destroyed the board it should be fairly easy to record the IR codes out of it.
Getting the IR codes will allow an esp8266 or esp32 to control the spa functions (either by sending IR via LEDs or perhaps by direct connection to the IR port), but not monitor the status. It's a start.
Reverse-engineering the in.K600 keypad might allow full two-way control. If anyone has a spare / dead keypad I'll gladly accept ~~victims~~ tributes for the cause (I'm in Australia though, shipping might be exorbitant).
My in.K600 keypad seems to be the "MD" or "Menu-Driven" variant, which has a full dot-matrix display and menu system, versus the in.K600 "SI" or "Streamlined Interface"(!) which has a custom LCD with a series of status icons and a big 7-digit display. The fact that two very different keypads (with the same model number!) exist suggests to me that it's likely the comms is a low-level protocol and all the screen drawing etc is handled at the display unit itself.
Oh, and just noticed in the techbook for both XM1 and XM2 that the 5v rails seem to be split, one rail for C1/CO and one rail for C2/IO, and each is rated for a max of 125mA.
The 12v rail seems to be common over each port, and the techbook states the total combined load on the 12v rail is 300mA max.
This will be worth keeping in mind when designing a module to hang off one of the ports, as the power budget looks pretty tight. Options might be to just include a decent-sized cap on the power rail if the average load will be low enough, or even include a LiPo cell and controller so that the controller can trickle-charge the cell, or using the 12v rail with an efficient DC-DC module. My esp32 modules look to draw about 110mA on average while idling, and will peak over that during wifi, I am sure. I guess this is why the in.touch-2 only uses the 5v rail for i2c ESD protection, and draws all of its power from a (moderately complex) on-board step-down circuit.
Another option is that the L1 light port is rated at 9.5V AC at 1Amp. One could run off a lipo and then get the controller to turn on the light periodically to power a charging circuit! 😅 Beware that isolation etc might be a big issue there - no idea what the internal power supply looks like and what constitutes "ground" in reference to the 9VAC supply. Given it's a human sous vide machine (not sui-cide machine) it will almost certainly be referenced to earth, but still..
Anyway, here's the bit from the techbook about the low-volage load limits:
Another point of interest is that the IR receiver pin is stated as being available on every low-voltage port except L1 (Light) and RH (Remote Heater), so this might make it very easy to intercept or inject IR signals. Also I've noticed that some keypads have the purple CO connector on them while others have the orange C1/C2 connector. I wonder if the ports are actually identical, or maybe the controller only expects certain device addresses (assuming they're all i2c) on certain ports? For that matter we don't know yet if the controller acts as a master or if it acts as an i2c slave on all or some ports.
I'm not sure if any of this is remotely helpful but I'll share what I have.
I have the original XM1 and it has an accessory device called in.watch that plugs into the CO port, then sends a 433mhz signal to a remote receiver. The remote receiver then displays water temperature and a few diag codes. You all may already have this but this is what I found when disassembling the transmitter, I found it's using 4 wires. 5+, Grd, SDA, SCL. (I2C) The pin out I have is: 1 - N/C 2 - SCL 3 - SDA 4 - 5vdc 5 - N/C 6 - N/C 7 - N/C 8 - GRD
I think the XM2 has the 485 populated on the board near the CO port, and the XM1 uses only I2C. The reason I say this is because none of the add-on Wifi modules will work on the XM1 while they work fine on the XM2 and Y series. When I contacted Gecko they said basically the same thing.
I haven't done any further testing. I need to get a long PS2 cable to extend this where it's easier to access. I can try and start simple with a logic probe and protocol analyzer to see if any of the byte data makes sense. My problem is that I'm already working two full time jobs!
Edit - After I typed this I found the picture of the connectors pin out! So this is info you already had......
I'm also in this same "hot tub" lets say . I have the IN.XM1 and the K600 (With the segment display not menu) would love to see if you guys make any more progress on this! Home Assistant awaits spa control! Unfortunately I don't have any spares I can donate to the cause but if moral support is accepted, I can supply that in 22gal drums!
To determine which is master or slave I would think on the CO port. the Spa Pack would be the slave and the remote devices would be the master right?
If the remote device (In.Watch) is powered up and I2C pins monitored, but not connected, wouldn't we see a request sent to the Spa Pack for the requested data, if the remote device was the master (Start, Address, and Data addresses requested)? I don't mess with I2C much but I do Modbus and CAN/J1939 a lot so forgive me if it's a dumb question.
For that matter we don't know yet if the controller acts as a master or if it acts as an i2c slave on all or some ports.
Some really interesting work so far here, and the pinout confirmations are really useful.
When the ink1000 touchscreen on my swim spa started to delaminate, I was able to get a replacement under warranty, and hold on to the old unit. So I have a C0 (I think) client device that's functional and easy to test with, take photos etc.
I'd been toying around with the interface under the assumption that it was RS485, and getting confused as to why I wasn't seeing any paired signals on any of the pins. Knowing now that it's probably I2C instead is really helpful.
With it being winter now, it's hard to observe live comms from the spa itself, but I have been powering up the old ink1000 unit in isolation to try to see what it does during boot time. It certainly does seem to initiate some comms on the data lines, but while looking for RS485 I wasn't getting very far.
Hopefully I'll be able to attach a primitive I2C sniffer in the next couple of weeks, and after that I should have a more sophisticated protocol analyzer arriving, and I should be able to do some proper analysis with sigrock.
Once the basic parameters of the comms are understood, and as the weather gets warmer, it should be a lot easier to really get stuck into some reverse engineering. I'll report back as soon as I have anything useful.
@rwskinner my gut instinct would be that the spa pack might be master, and it would scan the bus(es) at boot to init/discover any peripherals it supports. But you could certainly be right, and also right I think that the in.touch alone might reveal itself under some bus sniffing.
@dccourt awesome! Very interested to keep up with your progress!
I've just come across this https://github.com/etienne4313/spa_bluetooth_controller I'm not too sure on how this is actually connected to the in.xm though, I couldn't see any wiring diagram.
It looks like it's wired directly to the buttons on the control pad (or via relays) given that the outputs seem to be mapped to physical pins rather than some sort of serial, and the functions that turns the main relay on and off are identical, and work by pulsing the output for 500ms.
That's just from looking at the code though, i could easily be misinterpreting what I'm looking at.
I finally got a logic analyser hooked up to the in.k1000, unplugged from the spa pack.
It's looking a lot like this is an I2C slave - from power up until "there's an error communicating with the spa pack, check your connections" I see only the following brief activity on SDA and SCL, the rest of the time they're high:
It's going to be a while before I can spy on the actual comms between the spa pack and my other in.k1000, because currently the spa is almost buried in snow. I'll see if I can find an I2C scanner from somewhere.
Bah. Verified that my esp8266-based i2c scanner works via the logic analyser, but it doesn't find anything at addresses 1-127 on the i2c lines on the in.k1000.
I suspect there's some additional handshake on some of the other pins, but I'm not seeing anything particularly obvious being initiated by the in.k1000, beyond the startup pulse:
At this point, I think I need to wait until I can sniff the live lines, which might be a month or two.
I just stumbled upon this great thread after having the same idea. I have an older Gecko M-Class spa. It has an I2C connector, but after reading this thread, I think the best approach is to read the lines between the mainboard and the controller display. I hope the weather is okay this weekend so I can connect my logic analyzer to some pins.
I emailed Gecko support and kindly asked if they could provide information on interfacing with the I2C, but they politely declined my request.
I will keep you guys posted on my progress.
Well. i got my mainboard out of the spa and on my workbench, i see some continuous data but cannot make any scense of it..
Watching this thread eagerly. I have a Gecko Yj controller in my spa:
It appears to have CO port as well, so I'm wondering if this will lead to something that I can also use.
I've just done some continuity testing between the two ports and it seems that they at least share some of the same pins.
Top is CO (as marked on the silk screen), bottom is C.
This is the result of my continuity testing:
Seems to line up with the pinout in the image above?
Thanks for your analysis, and i hope you are correct since it would mean there is no need for break-out y-cables to sniff or inject data between the control-board and key-pad. Now pin-numbering is a head-ache and whether you look at the pins or the connector. But what worries me that something is wrong in your aligning of pins and connector in last image is that the GND (8) pin is not shared. Also I see something that look like pin-numbering printed on the board which would invert some of the aligning.
Well. i got my mainboard out of the spa and on my workbench, i see some continuous data but cannot make any scense of it..
@tommievanlent, your image of signal-levels look like it's coming from PulseView, did you try running any of the decoders on it? Or do you have the raw data stored and can share for others to try. (I attempted to send your image to ChatGPT for decoding but ran out of quota before an answer was given :-) )
But what worries me that something is wrong in your aligning of pins and connector in last image is that the GND (8) pin is not shared. Also I see something that look like pin-numbering printed on the board which would invert some of the aligning.
Right! I was worried about that too hence the open question. But I think you are right about the numbering, here's a slightly less blurry view. I took a couple of pictures yesterday but have buttoned it all up since. Can't have it out of commission or I will get in trouble with my partner. :) The silkscreen definitely seems to indicate the orientation you have pointed out.
All that said, here is a picture with the shroud installed that gives some clues to orientation of the connector. The key bits are on the right side.
Well. i got my mainboard out of the spa and on my workbench, i see some continuous data but cannot make any scense of it..
@tommievanlent, your image of signal-levels look like it's coming from PulseView, did you try running any of the decoders on it? Or do you have the raw data stored and can share for others to try. (I attempted to send your image to ChatGPT for decoding but ran out of quota before an answer was given :-) )
I gave up and went the arduino way. I removed the main board and gone fully DIY
I got a brief opportunity to do some protocol sniffing on my in-situ In.YE controller yesterday. I had my logic analyser connected to what I believe is the in.touch port (C0?) while I interacted with my in.key controller plugged into the other port (C1?). Not certain about port names because I was using a cable I'd fitted a few months ago, then re-sealed the controller unit, so I didn't actually look inside the In.YE this time.
Anyway, I didn't see any traffic on any of the 5 non-power/non-GND pins with that set up - so looks like I'll need to create a man-in-the-middle patch cable to sniff on the in.key's line directly. Conceivably once the protocol is understood, I'll be able to switch back to the other port, although I think it would also be acceptable to continue the man-in-the-middle approach if necessary.