The Geyserwala Connect is designed for open and local integration. The low-level API documentation is here.

The Geyserwala Connect includes its own built-in control loop, which manages the baseline timers and other behaviour. However, depending on your automation needs, you can offload part or even all of the logic onto your own system.

These are the key signals that have been designed for automation:

• external-disable: Logically disable the element from switching on. Great if you have a mid-sized inverter but want to keep your geyser system online during grid outages. Use this signal to protect your inverter or your battery, when it is below a chosen SoC. If you have a pumped solar collector system this permits pumped-solar heating during load shedding outages. And it also prevents the load shedding induced thermal stress cycles on your solar collector, where it can overheat during the outage, and then rapidly cools when the grid returns.
• external-setpoint: Input an automation target temperature, from 30 to 75 ℃.
• external-demand: Input an automation signal for when the Geyserwala Connect should heat to the external-setpoint.

When timers are set (and active) they will be honoured when in TIMER mode. Switching to SOLAR/STANDBY mode simply ignores the timers. If heating is fully automated, then use SOLAR/STANDBY mode as the default, reserving TIMER, SETPOINT and HOLIDAY mode as manual overrides. In HOLIDAY mode automation inputs are ignored, which is a convenient way to temporarily disable automations.

NOTE: It is disadvised to automate user signals such as mode, boost-demand, or setpoint, as this overrides app control and bypasses the built-in hysteresis that protects the heating element and relay. See Hysteresis below for details.

A heating controller typically uses a small temperature margin, or hysteresis, to prevent rapid on-off cycling once the target temperature is reached. This reduces wear on both the control relay and the heating element, extending their service life.

The Geyserwala Connect applies this principle with a 6 ℃ hysteresis and a minimum three-hour holdoff after switching off, unless the tank temperature drops by more than 6 ℃. To stay responsive to automation, if the setpoint is more than 6 ℃ above the tank temperature, the holdoff is reduced to 10 minutes. As a general guideline, avoid frequent or abrupt value changes, especially the user signals, to protect the relay and heating element and ensure reliable long-term operation.

The Geyserwala Connect makes its operational values available on MQTT and REST for you to use as you please. If you want to graph the data then the TIG stack (Telegraf, InfluxDB, Grafana) is a popular choice and fairly easy to setup.

The tank-temp and collector-temp are probably the first two values you'd want to graph.

If you're interested in energy usage then element-seconds is a running total of the time your element has been on since factory reset or the counters were reset.

The Geyserwala Connect is built with fully local, open APIs and can operate entirely cloud-free, with no vendor lock-in. It enables intelligent control of compatible third-party geyser controllers, including models such as the Geyserwise MAX, Delta T, Dual, TSE1, and TSE.

Home Assistant is an open source home automation that puts local control and privacy first.

Here is a custom integration github.com/thingwala/geyserwala-ha for automating your Geyserwala Connect.

If you are new to home automation an easy way in is to setup Home Assistant OS on a Raspberry Pi.

Node-RED is a programming tool for wiring together hardware devices.

Here is a @thingwala/node-red-contrib-geyserwala-connect palette to integrate with your Geyserwala Connect. The easyest way to install is by adding nodes.

Victron products are designed to be easy to integrate with. Victron has provided a @victronenergy/node-red-contrib-victron palette. They even provide a way to install and run Node-RED directly on your Victron (no extra hardware required), see: Venus OS Large.

The Python Bindings consume the REST API, the project is here: github.com/thingwala/geyserwala-py

The Geyserwala Connect exposes many of its operational values on both the REST and MQTT API, so that it is possible to monitor and control the way it operates. On the MQTT API <bool> types are represented by ON | OFF.

The timed latches act as a fail safe, in the event that for some reason the restore signal is not received, the <int> value will be the maximum time in seconds that the signal is considered active.

The MQTT API is disabled by default, it can be configured on the Settings page of the Local app. At present the Home Assistant integration can only consume the REST API.

By default the topic template is geyserwala/%prefix%/%mac%. A full topic will take the form <topic template>/<value>. There are several placeholders that can be used to define your topic template:

By default the topic template is geyserwala/%prefix%/%mac%. The %mac%, %ip% and %hostname% templates described above can be used.

Topics where %prefix% is stat. These are output topics which give information about the state of the device.

Topics where %prefix% is cmnd. These are input topics you can use to control the device.

If you have set a Local app password, all requests will require this session token header:

• Authorization: Bearer <token>

Requests that send JSON data will require this header:

• Content-Type: application/json

The API is fairly simplistic, status codes of 200 are good and others are bad. Bad responses will return a JSON dict e.g.: {"success": <bool>, "message": <string> }. If you are polling, keep the interval >= 2 seconds, to allow for good performance of other clients.

Session login requests return a JSON dict with a success field, and if successful a token string.

Value manipulation requests return the new state of the object.

Command requests return a JSON dict with a success field and a message.

The Local app has a widget capability where you can selectively show individual items from the status page. This allows you to display these items on your own custom dashboard, using an iframe. Keep in mind that browser security will prevent a HTTP iframe from loading within a HTTPS web page.

The Geyserwala Connect now offers Modbus support, both TCP over WiFi and RTU over RS485. The Sivula controller has an existing integration which will operate using either TCP or RTU. For further details regarding integration, please see Product Support for assistance.