Building your own BoilerBuddy

Would you rather build something yourself, with a Raspberry Pi, an ESP32 or other hardware? Then you send your readings to the same portal as the BoilerBuddy Alpo, with the same charts and alerts. Below is how to set it up, and what isn't possible yet.

What you need#

• Hardware that speaks HTTPS with certificate checks and JSON, with a clock kept in sync by NTP. Every reading needs a timestamp.
• A subscription. A device you built costs the same as any other: €3.95 per month, VAT included, after your account's trial (30 days). Without a subscription it keeps uploading, but its charts and alerts are closed. See Subscription.

Step 1: create the device#

1. In the portal, go to Devices and choose New device.
2. Give it a name and choose Own hardware as the Device type.
3. Leave Pairing code (optional) empty, unless your device can pair itself: see Pairing with hello.
4. Choose Add device. The device's API key is shown at the top of the next page. You see it once: copy it now.

With a personal account you can have at most 5 devices.

Step 2: choose a circuit#

The circuit determines which sensor codes the server knows and how it shows them. For each circuit you see its sensors with their codes (see also Circuit and installation details). What you need to know:

• All circuits are schemes of OEG's KSW controllers. Other brands and your own sensors aren't available yet. Choose what matches what you measure; 201 is the simplest solar water heater: T1 collector, T2 tank bottom, T3 tank top, R2 pump.
• The codes are T1 to T6 for temperatures and R1 to R3 for outputs such as pumps, valves and heating elements. Which ones exist differs per circuit; any other code goes into quarantine.
• Send every sensor of the circuit. If one is missing, the Sensor sends no reading alert follows. You can switch that rule off under Alerts for the device, in Rules, but then it is off for all its sensors.
• Send outputs the way the KSW controller reports them. A pump or other output is on above 0.5, and the value divided by 10 is its speed: 0 is off, 10 is 100%. A valve: 0 is position A, 128 is position B.
• Choose before you start uploading. After a switch, the history stays with the old sensors and no longer shows in your charts.

If you don't read the controller yourself, ignore controller and address in the configuration.

Step 3: put the token on your device#

Use the key from step 1. You create a new one on the device page, on Settings under Connection, with Create key or New key; the old one stops working immediately.

Keep the key secret, because whoever has it can upload as your device. Read it from a file or an environment variable, not from a public repository.

Step 4: test first, then build#

1. Fetch the configuration with curl and check the sensor codes. See Example: curl.
2. Send one reading. Check that Last seen changes and the reading appears in the chart on the Dashboard.
3. Then build the rest: a buffer, retries and a status every few minutes. See Buffering and the clock.

Which hardware fits#

• Raspberry Pi or another Linux computer: with Python and an SQLite buffer, your readings survive a restart and an outage of days. See Example: Python.
• ESP32: Wi-Fi, TLS and enough memory for small batches, but a buffer in RAM is gone after a restart, unless you write to flash. See Example: ESP32.
• Something else works too, but small microcontrollers without TLS or a clock are hard work.

A DS18B20 sensor is cheap, but measures up to 125 °C, and a collector can get hotter when it stagnates. There, a PT1000 with a converter such as a MAX31865 is more common.

Stuck, or want to connect a controller that isn't supported yet? Get in touch.