flowchart LR
P1[Probe tank 1] --- B
P2[Probe tank 2] --- B
P3[...] --- B
P5[Probe tank 5] --- B
B[Wago banks<br/>one 1-Wire bus] --- H[ESP32 hub<br/>reads every 60 s]
H -- "HTTPS POST + token<br/>over Wi-Fi" --> R[Gannet<br/>DSM reverse proxy :8443]
R --> C[Docker container<br/>Python receiver]
C --> D[(CSV files<br/>one per hub per day)]
INTRO
We need continuous temperature records for the tanks in the SHORE tank room. The plan, laid out in this GitHub Issue (GitHub), is to build two “hubs”. Each hub is an ESP32 microcontroller reading five waterproof DS18B20 temperature probes, one per tank, so two hubs cover 10 tanks.
This post covers:
- the hardware and wiring;
- the hub firmware;
- the receiver that collects the data on our Synology server, Gannet;
- how to get the receiver container running on Gannet.
So far, one hub has been built and tested on the bench with three probes. The receiver is running on Gannet. The upload from hub to Gannet hasn’t been tested end to end yet (see RESULTS).
All code is in the shore_temps/ directory (GitHub) of our code repo.
MATERIALS & METHODS
How it all fits together
- Once a minute, each hub reads all five of its probes over a single data wire.
- The hub sends the readings to Gannet over HTTPS. Each request carries a secret token unique to that hub.
- On Gannet, the DSM reverse proxy handles HTTPS and passes each request to a small Python program running in a Docker container.
- The receiver checks the token, adds the time it received the reading, and appends the reading to a CSV file.
Why the hubs send data to Gannet
The original plan in the Issue was for a collector on the UW network to fetch each hub’s readings. That only works if the hubs have fixed IP addresses. UW’s MPSK device Wi-Fi service doesn’t offer DHCP reservations, so the hubs’ addresses can change and a collector can’t reliably find them. Having the hubs send to Gannet avoids the problem: the hubs only need to make outgoing connections, and Gannet’s address never changes.
Why a container and not PHP
PHP can’t be used on Gannet because of a recent security vulnerability. Instead, the receiver is about 130 lines of Python that uses only the standard library, so there’s nothing to install with pip. It runs in DSM’s Container Manager (Docker).
Hardware
From the Issue (GitHub):
| Item | Qty | Use |
|---|---|---|
| ESP32 dev board (ESP32-DevKitC style, with CP2102 USB chip) | 3 | 2 hubs + 1 spare |
| DS18B20 waterproof probe, 316 stainless, 3 m | 12 | 10 tanks + 2 spares |
| ESP32 screw-terminal breakout | 2 | One per hub, so nothing needs soldering |
| 4.7 kΩ resistor | 1 per hub | Pull-up resistor for the data line |
| Wago 221 lever connectors | pack | Join the probe wires |
| 3-conductor 22 AWG shielded cable | 15 m | Short leads, jumpers and extensions |
| 5 V 2 A USB power supply + USB cable | 2 + 3 | Power (the extra cable is for flashing the spare) |
Every DS18B20 has its own unique 64-bit ID, so all five probes on a hub share one data pin. Each reading is labeled with the ID of the probe that took it.
Wiring
| Probe wire | Breakout terminal |
|---|---|
| Red (power) | 3V3 (not 5V / VIN) |
| Black (ground) | GND |
| Yellow (data) | GPIO 4 |
- One 4.7 kΩ pull-up resistor per hub, connected between 3V3 and GPIO 4 at the breakout. Not one per probe.
- Five probes per hub. Each wire color goes to its own bank of Wago connectors: one bank for all the reds, one for the blacks, one for the yellows. Each bank also takes one conductor of the short lead that runs to the breakout. That makes 6 connections per color, and a Wago 221 holds at most 5, so each bank is two Wagos joined by a short jumper.
- Probe conductors are thinner than the Wagos are rated for, so fold the stripped end back on itself before inserting it, and tug-test every wire.
- Check the probe wire colors first. Some probes use white or blue for data. Swapping power and ground makes the probe hot and usually kills it.
The breakout’s female headers and labels didn’t line up with the ESP32’s pins:
- These breakouts are made to fit several ESP32 board sizes (30-pin and 38-pin, narrow and wide), so they have extra header rows.
- Their labels are printed for one particular board, which may not be ours.
- Different makers name the same pin differently:
D4,IO4,G4andP4all mean GPIO 4.
What matters is which ESP32 pin sits in which socket, not what the labels say. Find the right terminals with a multimeter in continuity mode, with USB unplugged. Touch one lead to the top of the ESP32’s D4 pin and touch terminals with the other until it beeps. Do the same for 3V3 and GND, and mark those three terminals.
Firmware
The firmware is a PlatformIO project (shore_temps/, GitHub). It was developed in VS Code with the PlatformIO IDE extension, building for the ESP32 Dev Module board using the Arduino framework. The OneWire and DallasTemperature libraries are listed in platformio.ini, and PlatformIO downloads them automatically on the first build.
Every 60 s, the hub:
- Re-scans the 1-Wire bus, so a probe that was unplugged and plugged back in is found again, and reads every probe.
- Builds a JSON reading with the hub name, uptime, a timestamp (once the clock is set) and each probe’s ID and temperature. Failed reads, and DS18B20’s 85.0 °C power-on value, are reported as
null. - Adds the reading to a queue in memory and POSTs the queue to Gannet. Readings that Gannet accepts are removed from the queue.
Other details:
- HTTPS with certificate checking.
include/gannet_ca.hholds the root certificate that Gannet’s certificate is issued under (USERTrust RSA, valid until 2038). This means the hub only sends its token to the real Gannet. - Timestamps. The clock is set from NTP at startup. Until it’s set, readings are sent without a timestamp, and Gannet’s arrival time is the only time recorded for them.
- Buffering. If Gannet can’t be reached, up to 180 readings (about 3 hours) wait in memory. Once Gannet answers again, they’re sent oldest first, 30 per request.
- WiFi recovery. The board reboots itself after 60 minutes without WiFi. Rebooting clears the buffer, so the wait is set long on purpose.
- Diagnostics in the Serial Monitor. At startup the hub prints its MAC address, whether it can see the configured network, and the reason for every failed connection attempt.
Secrets
The Wi-Fi network name, Wi-Fi password and the hub’s token are kept in include/secrets.h, which git ignores. A template, include/secrets.h.example, is committed so it’s clear what needs filling in. Each hub is set up by editing two things before flashing:
HUB_NAMEinsrc/main.cpp(shore-temps-aorshore-temps-b)HUB_TOKENininclude/secrets.h(that hub’s token, from Gannet’s.envfile)
The name and token have to be the pair listed in Gannet’s .env.
Problems hit along the way
- The MAC address printed as
00:00:00:00:00:00. In the current ESP32 Arduino core,WiFi.macAddress()returns zeros until WiFi has started. The firmware now reads the address straight from the chip withesp_read_mac(). The original draft sketch in the Issue has this same bug. - “Not getting an IP address” on a home network. The startup network list showed the network’s real name had a trailing space. That’s invisible on phones and laptops, but the ESP32 matches names exactly. Also remember that the ESP32 only works on 2.4 GHz and can’t use WPA3-only networks.
- Occasional garbled characters (
�) in the Serial Monitor. These are bytes damaged on the way over USB, not a firmware problem. The readings themselves are unaffected. - PlatformIO couldn’t find a working Python. Ubuntu’s system Python was missing its
venvmodule. Fixed withsudo apt install python3-venv.
Receiver on Gannet
The receiver is in shore_temps/gannet/ (GitHub), and full instructions are in its readme.txt (GitHub).
| File | Purpose |
|---|---|
receiver/app.py |
The receiver (Python standard library only) |
receiver/Dockerfile |
Builds the container from python:3.12-slim |
docker-compose.yml |
Project definition that Container Manager reads |
.env.example |
Template for .env: DSM user/group IDs and the hub tokens |
What the receiver accepts:
GET /health: no token needed. Returns{"status": "ok"}.POST /ingest: requires the headerAuthorization: Bearer <token>. The body is one reading or a list of readings. Each token can only write data for its own hub. Malformed requests are rejected with a400, and bad tokens with a401.
How it’s locked down:
- The container runs as an ordinary DSM user, not as root.
- Its filesystem is read-only except for the
data/folder. - It only accepts connections from Gannet itself (
127.0.0.1:8080). The only way in from outside is through DSM’s HTTPS reverse proxy.
Data format
There’s one CSV file per hub per day, data/raw/<hub>/<YYYY-MM-DD>.csv (the UTC date the reading arrived):
received_utc,reading_utc,hub,uptime_s,probe_id,temp_c
2026-11-04T17:28:59Z,2026-11-04T17:28:58Z,shore-temps-a,61,28CC7DBC79250B81,18.69
| Column | Meaning |
|---|---|
received_utc |
When Gannet received the reading |
reading_utc |
When the hub took the reading (from NTP). Empty if the hub’s clock wasn’t set |
hub |
Hub name |
uptime_s |
Seconds since the hub last started. Use it to spot duplicate readings and reboots |
probe_id |
The DS18B20’s unique ID |
temp_c |
Temperature in °C, uncalibrated. Empty if the probe failed to read |
These are raw files. Tank names and calibration offsets (from the ice-bath check described in the Issue) aren’t applied here. They’ll be applied in a separate processing step, so a mistake in the probe → tank table never damages the original data.
Setting up the container on Gannet (Synology Container Manager)
Copy the files. Put the contents of
shore_temps/gannet/into a folder on Gannet (for example/volume1/<share>/shore-temps/), including the hidden.env.example. Create an emptydata/subfolder.Get user and group IDs. SSH into Gannet as the user who owns the folder and run
id. Note theuidandgid. Use your own group (usually100,users) rather thanadministrators, which gives the container no more access than it needs.Create
.env.cp .env.example .env chmod 600 .envFill in
PUID,PGIDandHUB_TOKENS=shore-temps-a:<token>,shore-temps-b:<token>. Generate each hub’s token once with:python3 -c "import secrets; print(secrets.token_urlsafe(32))"The command gives a new random string every time it runs. That’s expected, because it’s a password generator. A token only takes effect once the same string is in both Gannet’s
.envand that hub’ssecrets.h.Create the project. In Container Manager, go to Project → Create:
- Name:
shore-temps - Path: the folder from step 1
- Source: “Use existing docker-compose.yml”
Skip the Web Station settings and finish. The container log should show
Listening on port 8080; hubs: shore-temps-a, shore-temps-b.- Name:
Test on Gannet: run
curl http://127.0.0.1:8080/health.Set up the reverse proxy. Go to Control Panel → Login Portal → Advanced → Reverse Proxy → Create:
- Source: HTTPS,
gannet.fish.washington.edu, port8443 - Destination: HTTP,
localhost, port8080
Then go to Control Panel → Security → Certificate → Settings and assign Gannet’s certificate to the new entry. Leave HSTS off. Browsers apply HSTS to every port on the hostname, so it would affect Gannet’s other services, and the hubs ignore HSTS anyway.
- Source: HTTPS,
Open the firewall. If DSM’s firewall is on, allow TCP
8443.Test from outside Gannet: open
https://gannet.fish.washington.edu:8443/healthfrom the network the hubs will use.
After changing .env (to add a hub or change a token), rebuild the project: Project → shore-temps → Action → Build.
RESULTS
Probes: a bench hub with three probes on one bus, sharing one pull-up resistor, read all three at a plausible 17–19 °C. That confirms the wiring, pull-up resistor and probe detection all work:
{"hub":"shore-temps-a","uptime_s":214,"probes":[{"id":"28CC7DBC79250B81","temp_c":18.75}, {"id":"28B27FB379250B13","temp_c":17.19},{"id":"282107B179250BAF","temp_c":17.25}]}Wi-Fi: once the network-name issue was fixed, the hub joined a home 2.4 GHz network and got an IP address.
Receiver: running on Gannet.
https://gannet.fish.washington.edu:8443/healthreturns{"status": "ok"}, both through the UW VPN and from an off-campus connection without the VPN.Receiver logic: tested locally with valid uploads, a backlog upload,
nullreadings, a bad token, a hub name that didn’t match its token, invalid JSON and bad probe IDs. All behaved as expected.Not yet tested:
- the full path from hub to Gannet (the upload firmware builds but hasn’t run on a board yet);
- the hubs on UW’s device Wi-Fi.
SUMMARY
The pieces are in place: probes wired to an ESP32 hub, firmware that sends readings to Gannet over HTTPS, and a locked-down receiver on Gannet that stores the raw readings as CSV files. Switching from the server fetching data to the hubs sending it avoided the problem of having no DHCP reservations on UW’s device Wi-Fi. Running the receiver in a container avoided needing PHP.
Next steps:
- Run the upload firmware on a hub and confirm that rows appear in
data/raw/. - Register both hubs with UW’s MPSK device Wi-Fi (they print their MAC addresses at startup), and confirm they can reach Gannet on port 8443 from that network.
- Wire and flash the second hub. Then identify each probe, label it with its tank, and do the ice-bath check (see the Issue).
- Write the processing step: apply the probe → tank map and offsets, and produce
data/tanks.jsonfor the dashboard. - Add monitoring: a DSM Task Scheduler job that emails when a hub’s CSV goes quiet or a tank’s temperature leaves its range.