
Sensor bus hat
sslivins/thermux
A multi-sensor temperature monitoring system for ESP32-POE boards with Home Assistant integration via MQTT auto-discovery.

A multi-sensor temperature monitoring system for ESP32-POE boards with Home Assistant integration via MQTT auto-discovery.
Temp node is an open-source printed circuit board by sslivins, from the sslivins/thermux repository on GitHub. It is a 2-layer board of 35 × 21 mm with 8 parts on 12 nets, routed with 47 tracks and 0 vias.
Its parts include 3 connectors, 2 capacitors and 1 fuse.
A multi-sensor temperature monitoring system for ESP32-POE boards with Home Assistant integration via MQTT auto-discovery. Supports 20 DS18B20 sensors on a single 1-Wire bus by default, configurable up to 100 (CONFIG_MAX_SENSORS) - perfect for monitoring multiple zones, equipment, or environments from one device.
CONFIG_MAX_SENSORS in menuconfig, max 100)thermux.local (auto-increments on collision: thermux-2.local, etc.)_thermux._tcp and _http._tcp services| DS18B20 Pin | ESP32-POE |
|---|---|
| VCC (Red) | 3.3V |
| GND (Black) | GND |
| DATA (Yellow) | GPIO4 |
Note: A 4.7kΩ pull-up resistor is required between DATA and VCC. For 10+ sensors, use 2.2kΩ or 1.5kΩ to ensure reliable bus communication (the ESP32's internal pull-up is too weak for 1-Wire).
Download the latest firmware from GitHub Releases and follow the FLASHING.md guide.
For brand new ESP32-POE devices, you'll need all three files:
bootloader.binpartition-table.binthermux.binFor OTA updates on devices already running Thermux, use the web interface at http://thermux.local/ota - it downloads and installs updates automatically (no manual file download needed). You can also manually upload a specific thermux.bin version if desired.
See FLASHING.md for detailed instructions.
# Set target
idf.py set-target esp32
# Build
idf.py build
# Flash
idf.py -p COMx flash monitorOr use the ESP-IDF VS Code extension build/flash commands.
After flashing, access the web interface at http://thermux.local or the device IP.
Note: If multiple devices are on the network, subsequent devices will be
thermux-2.local,thermux-3.local, etc.
| Setting | Description |
|---|---|
| MQTT Broker | Home Assistant MQTT broker address |
| MQTT Port | Broker port (default: 1883) |
| MQTT Username/Password | Authentication credentials |
| WiFi SSID/Password | Fallback WiFi credentials |
| Read Interval | Sensor polling interval (seconds) |
| Publish Interval | MQTT publish interval (seconds) |
| OTA URL | GitHub releases URL for automatic updates |
| Security | Enable/disable password protection |
Full API documentation is available as an OpenAPI 3.1 spec: docs/openapi.yaml
View it interactively: Swagger Editor
The device automatically registers sensors with Home Assistant via MQTT discovery. Each sensor appears as a temperature entity. Diagnostics include network status, uptime, seconds since the last successful bus read, consecutive failed bus cycles, and a rolling error rate across the most recent 1,000 reads. Lifetime read counters remain available as disabled-by-default engineering diagnostics.
Thermux publishes a native Home Assistant update entity (device class firmware) via MQTT discovery. It shows the installed version, the latest available GitHub release, a link to the release notes, and an Install button that triggers the OTA download with a live progress bar — the same experience as updating any other HA device, no automation or REST command needed.
The entity is backed by these MQTT topics (base topic configurable, default thermux):
| Topic | Direction | Purpose |
|---|---|---|
homeassistant/update/thermux_firmware/config | retained | Discovery config |
thermux/update/state | device → HA (retained) | JSON: installed_version, latest_version, release_url, update_percentage, in_progress |
thermux/update/install | HA → device | Payload install starts the OTA |
The device checks GitHub for new releases periodically (see OTA_CHECK_INTERVAL_HOURS) and updates the entity whenever availability or download progress changes.
You can also poll sensors directly:
# configuration.yaml
rest:
- resource: http://thermux.local/api/sensors
scan_interval: 60
sensor:
- name: "Temperature Sensor 1"
value_template: "{{ value_json[0].temperature }}"
unit_of_measurement: "°C"
device_class: temperatureThermux can run a small, read-only Modbus TCP server so a PLC or heat pump controller can read temperatures without HTTP or JSON. It's off by default: turn it on under Settings → Modbus TCP, where you can also set the port (default 502) and unit ID (default 1).
Modbus has no password. Anyone on the network can read the registers, but nothing can be changed over Modbus, so only enable it on a network you trust.
Each sensor gets a channel (0–99) the first time it's seen, keyed by its ROM ID. A sensor keeps its channel when other sensors are added or removed, so a register address (and BACnet object) always refers to the same physical sensor. New sensors fill the lowest free channels, in ROM ID order. Modbus TCP and BACnet/IP share the same channels: channel N is input register 100+N and BACnet Analog Input N.
The Settings → Sensor Channels section shows each channel's Modbus register, BACnet object, sensor, and the status and temperature clients are currently reading. From there you can:
Channels and Modbus settings are included in backups (Settings → Backup), so a replacement Thermux can serve the same register map.
All registers are input registers, read with function code 04. Addresses are zero-based. All 100 channels are always mapped, whatever CONFIG_MAX_SENSORS is set to, so the map never changes between builds.
| Address | Contents |
|---|---|
| 0 | Map version (currently 1) |
| 1–3 | Firmware version: major, minor, patch |
| 4 | Channel capacity (always 100) |
| 5 | Read-cycle counter. Goes up by one after every scheduled read attempt, including failed ones; wraps at 65535 |
| 6–7 | Uptime in seconds (32-bit, register 6 is the high word) |
| 8–10 | Ethernet MAC address, two bytes per register (register 8 = byte 0 << 8 | byte 1) |
| 11 | Firmware sensor limit (CONFIG_MAX_SENSORS) |
| 12 | Number of channels in use |
| 13 | Number of sensors found on the bus |
| 14 | Result of the last read cycle: 0 OK, 1 some sensors failed, 2 bus failure, 3 no sensors |
| 15 | Read interval in seconds |
| 100 + channel | Temperature in hundredths of a °C, signed 16-bit (2150 = 21.50 °C, 0xFF38 = −2.00 °C). 0x8000 whenever the status isn't OK |
| 200 + channel | Status (see below) |
| 300 + channel | Seconds since the last successful read (capped at 65534). 65535 if the sensor has never been read or isn't connected |
| 1000 + 4 × channel | ROM ID, 4 registers per channel, two bytes per register in the same order as the address shown in the UI and API |
Channel status, checked in this order:
| Value | Meaning |
|---|---|
| 1 | Unassigned: no sensor in this channel |
| 2 | Missing: the sensor wasn't found in the latest bus scan |
| 3 | Read error: the sensor's latest read failed, or the whole read cycle failed |
| 4 | Stale: never read successfully, or the last good reading is older than 3 × the read interval (at least 30 s) |
| 0 | OK |
Use the age registers if you need a stricter freshness limit than the stale rule.
Each block (0–15, 100–199, 200–299, 300–399, 1000–1399) is separate. A read that covers an address outside those blocks, or runs from one block into the next, returns exception 0x02 (illegal data address). A single read can cover at most 125 registers, so the ROM block takes four reads.
A reading cycle can finish between two of your requests. To be sure the values you read all come from the same cycle, read register 5, read the blocks you need, then read register 5 again. If it changed, read again.
While the server is running, Thermux advertises it over mDNS as _mbap._tcp, with TXT records unit (unit ID), id (MAC address) and map (map version). Most PLCs don't use mDNS, so you'll usually enter the IP address and port by hand; give Thermux a DHCP reservation so the address doesn't change.
The repo includes a small reader, scripts/thermux_modbus.py (needs pip install pymodbus). With just an address it decodes the whole map; channel reads specific channels; raw reads any range from any Modbus TCP device:
python scripts/thermux_modbus.py thermux.local # device info + every channel
python scripts/thermux_modbus.py thermux.local --watch 5 # repeat every 5 s
python scripts/thermux_modbus.py thermux.local channel 3 # one channel: temperature, status, age, ROM ID
python scripts/thermux_modbus.py thermux.local channel 3 7 # several channels
python scripts/thermux_modbus.py thermux.local channel 3 --value # just the °C value, for scripts
python scripts/thermux_modbus.py 192.168.1.50 --port 502 --unit 1 raw 100 6 # input registers
python scripts/thermux_modbus.py 192.168.1.50 raw 0 10 --fc 3 # holding registersmbpoll, temperatures of channels 0–5 (-0 makes addresses zero-based):
mbpoll -m tcp -a 1 -0 -t 3 -r 100 -c 6 -1 thermux.localPython with pymodbus 3.9 or later (older versions use slave= instead of device_id=):
from pymodbus.client import ModbusTcpClient
client = ModbusTcpClient("thermux.local", port=502)
client.connect()
def read(address, count):
result = client.read_input_registers(address, count=count, device_id=1)
if result.isError():
raise RuntimeError(result)
return result.registers
while True:
cycle = read(5, 1)[0]
temps = read(100, 10)
status = read(200, 10)
if read(5, 1)[0] == cycle:
break
for channel, (raw, st) in enumerate(zip(temps, status)):
if st == 0:
celsius = (raw - 65536 if raw >= 32768 else raw) / 100
print(f"channel {channel}: {celsius:.2f} °C")Thermux can also run a read-only BACnet/IP server, for building-automation systems that speak BACnet rather than Modbus. It's off by default: turn it on under Settings → BACnet/IP. Modbus and BACnet can run at the same time and serve the same sensor channels.
| Setting | Default | Notes |
|---|---|---|
| UDP port | 47808 (0xBAC0) | The standard BACnet/IP port. Can't be the web server's port |
| Device instance | Derived from the Ethernet MAC | 0–4194302. Must be unique on the BACnet network, so set it by hand if your site has a numbering plan |
| Device name | The hostname | Up to 63 characters |
Like Modbus, BACnet has no password. Anyone on the network can read the objects, but nothing can be changed, so only enable it on a building-controls network you trust.
The Device object reports vendor and model Thermux, the firmware version, and an object list.
Each assigned sensor channel is an Analog Input, and the instance number is the channel number. AI 3 is always channel 3, which is Modbus register 103. Unassigned channels have no object, so the object list only shows channels with a sensor.
| Property | Value |
|---|---|
| Object name | The sensor's friendly name, or Channel N if it has none. If two sensors have the same name, the second gets (N) added, because BACnet object names must be unique |
| Description | The sensor's ROM ID, for example 281491BA00000069 |
| Present value | Temperature in °C. If a reading fails, the last good value stays and Reliability shows the fault |
| Units | degrees-Celsius |
| Reliability | no-fault-detected when OK; no-sensor when the sensor is missing; communication-failure on a read error; unreliable-other when the reading is stale |
| Status flags | fault is set whenever Reliability isn't no-fault-detected |
| COV increment | 0.1 °C |
When sensors are added, removed or renamed, the object list changes and the device's Database Revision goes up, so clients that cache the object list know to read it again.
All write and management services (WriteProperty, CreateObject, ReinitializeDevice, DeviceCommunicationControl and so on) are rejected with unrecognized-service.
If the device's IP address changes (a new DHCP lease, for example), Thermux notices within a few seconds and sends a new I-Am. You don't need to restart anything.
The repo includes scripts/thermux_bacnet.py, which needs BAC0 2025 or later (pip install BAC0):
python scripts/thermux_bacnet.py --discover # Who-Is on the local network
python scripts/thermux_bacnet.py 192.168.1.50 # device info and every Analog Input
python scripts/thermux_bacnet.py 192.168.1.50 --cov 60 # watch COV notifications for a minute
python scripts/thermux_bacnet.py 192.168.1.50 --try-write # check that writes are rejected
python scripts/thermux_bacnet.py 192.168.1.50 --port 47809 # non-standard portAdd --local 192.168.1.32/24 (your PC's address) if the script picks the wrong network interface. Who-Is discovery only finds devices on port 47808. On another port, I-Am replies are broadcast to that port, so give the address and --port instead.
Thermux can update three ways: the native Home Assistant update entity (above), the built-in web interface, or a manual .bin upload.
The web interface can automatically download and install updates from GitHub releases:
https://api.github.com/repos/sslivins/thermux/releases/latestTo install a specific version or older version, use the manual upload feature:
thermux.bin from any release/ota page.bin firmware fileBy default, the web interface is open (no authentication required). To enable password protection:
/config → Security sectionWhen enabled, unauthorized access redirects to a login page. Sessions are stored in a cookie and expire after 7 days.
For scripts and automation, use the API key instead of session cookies:
# Get sensor readings
curl -H "X-API-Key: YOUR_API_KEY" http://thermux.local/api/sensors
# Get device status
curl -H "X-API-Key: YOUR_API_KEY" http://thermux.local/api/statusThe API key is:
For browser-based access, the web UI uses session cookies. Protected API endpoints return 401 Unauthorized with JSON body containing {"login_required": true} when not authenticated.
| Endpoint | Method | Description |
|---|---|---|
/login | GET | Login page (no auth required) |
/api/auth/login | POST | Authenticate with {"username":"...", "password":"..."} |
/api/auth/logout | POST | Destroy session |
/api/auth/status | GET | Check if logged in |
/api/config/auth | GET | Get auth config (includes API key) |
/api/config/auth/regenerate-key | POST | Generate new API key |
With API key authentication, REST integrations are straightforward:
# configuration.yaml
rest:
- resource: http://thermux.local/api/sensors
headers:
X-API-Key: "your-api-key-here"
sensor:
- name: "Pool Temperature"
value_template: "{{ value_json.sensors[0].temperature }}"
unit_of_measurement: "°C"Alternatively, use the built-in MQTT integration with Home Assistant auto-discovery (no API key needed for MQTT).
The firmware uses the 1-Wire skip ROM command (0xCC) to trigger temperature conversion on all DS18B20 sensors simultaneously, then reads each sensor individually. This reduces read time from O(n × delay) to O(delay + n × read):
| Sensors | Sequential (12-bit) | Parallel (12-bit) | Parallel (9-bit) |
|---|---|---|---|
| 1 | ~800ms | ~800ms | ~100ms |
| 5 | ~4000ms | ~850ms | ~150ms |
| 10 | ~8000ms | ~900ms | ~250ms |
| 20 | ~16000ms | ~1050ms | ~450ms |
The conversion delay depends on resolution: 12-bit = 750ms, 11-bit = 375ms, 10-bit = 188ms, 9-bit = 94ms. The parallel read overhead per sensor is minimal (~25ms for bus communication).
A 16KB circular buffer captures ESP-IDF logs for web display. Noisy system components (HTTP server internals, Ethernet MAC, etc.) are filtered to keep logs useful. The buffer can be viewed, cleared, and downloaded from the config page.
This repository includes open-source hardware designs:
Two open-source KiCad boards:
Sensor Bus Hat - plugs onto the ESP32-POE-ISO and breaks the 1-Wire bus out to RJ45 (carries the bus pull-up resistor)
Temperature Node - DS18B20 breakout with RJ45 connectors for daisy-chaining sensors
KiCad project files - Full schematic and PCB layout
Gerber files - Ready for fabrication (JLCPCB, PCBWay, etc.)
Bill of Materials - DigiKey part links
3D printable cases, in two parts:
Each is provided as:
See GitHub Releases for changelog.
MIT License - See LICENSE for details.
| Qty | Value | Footprint | References |
|---|---|---|---|
| 2 | MountingHole_2.2mm_M2 | MountingHole:MountingHole_2.2mm_M2 | H0, H1 |
| 1 | 0.1uF | Capacitor_SMD:C_0805_2012Metric | C2 |
| 1 | 10uF | Capacitor_SMD:C_0805_2012Metric | C1 |
| 1 | PTC 54mA/100mA (resettable) | Fuse:Fuse_0805_2012Metric | F1 |
| 1 | TEMP_BUS_A | MJ3225_88_0:GCT_MJ3225-88-0_REVA | J1 |
| 1 | TEMP_BUS_B | MJ3225_88_0:GCT_MJ3225-88-0_REVA | J3 |
| 1 | TEMP_SENSOR | Connector_JST:JST_XH_S3B-XH-A_1x03_P2.50mm_Horizontal | J2 |

sslivins/thermux
A multi-sensor temperature monitoring system for ESP32-POE boards with Home Assistant integration via MQTT auto-discovery.


joeycastillo/Sensor-Watch
A board replacement for the classic Casio F-91W wristwatch

rusefi/rusefi
rusefi - GPL internal combustion engine control unit

hoglet67/RGBtoHDMI
Bare-metal Raspberry Pi project that provides pixel-perfect sampling of Retro Computer RGB/YUV video and conversion to HDMI

shanteacontrols/OpenDeck
A platform for building interactive control and sensing devices using MIDI and OSC built with Zephyr RTOS.

hackclub/OnBoard
💡 Join 1,000 teenagers and make your first PCB with a $100 grant!

dangiu/PicoMemcard
Emulating PSX Memory Card (or controller) using a Raspberry Pi Pico

OLIMEX/DIY-LAPTOP
Do It Yourself Open Source Hardware and Software Modular Hacker's Friendly Laptop
It measures 35 × 21 mm and has 2 copper layers, 1.6 mm thick.
8 parts. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.
From the sslivins/thermux repository on GitHub, at the commit this page was made from: the board is hardware/temp_node/kicad/temp_node.kicad_pcb and its schematic hardware/sensor_bus_hat/kicad/sensor_bus_hat.kicad_sch. PCBKit opens the board in the browser, with nothing to install.
Its repository states no licence, so its author keeps all rights: ask sslivins before reusing the design.