Skip to the content
2 layers35 × 21 mmTemp node, the printed circuit board in 3D

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

Size
35 × 21 mm
Copper layers
2
Thickness
1.6 mm
Parts
8
Nets
12
Pads
31
Tracks, vias
47, 0
Routed
Yes
KiCad
KiCad 9.0 (file 20241229)
Created
28 Jan 2026
Updated
1 Oct 2026

Overview

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.

README

README.md

Thermux

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.

Features

  • Up to 100 DS18B20 Sensors - Monitor multiple temperature points from a single device on one 1-Wire bus (20 by default; raise CONFIG_MAX_SENSORS in menuconfig, max 100)
  • Optimized Parallel Reads - Uses 1-Wire skip ROM command to read all sensors simultaneously (~1050ms for 20 sensors in 12-bit mode, ~450ms in 9-bit)
  • Home Assistant Integration - MQTT auto-discovery for seamless integration
  • Modbus TCP - Optional read-only Modbus TCP server so PLCs and heat pump controllers can read temperatures directly (see Modbus TCP)
  • BACnet/IP - Optional read-only BACnet/IP server for building-automation systems (see BACnet/IP)
  • Web Interface - Configuration and monitoring via built-in web server
  • Sensor Identification - Change detection highlighting helps identify which physical sensor is which
  • Custom Sensor Names - Assign friendly names to sensors via web UI (persisted in NVS)
  • OTA Updates - Over-the-air firmware updates from GitHub releases or manual upload with progress display, including a native Home Assistant firmware update entity with an Install button and progress bar
  • Ethernet & WiFi - Primary Ethernet with WiFi fallback
  • mDNS - Access via thermux.local (auto-increments on collision: thermux-2.local, etc.)
  • Service Discovery - Discoverable via _thermux._tcp and _http._tcp services
  • Web-based Logs - View system logs without serial connection (16KB circular buffer)
  • Bus Error Tracking - Monitor 1-Wire CRC error rates per sensor and globally via web UI and Home Assistant
  • Runtime Log Level Control - Change log verbosity via web UI without reflashing
  • Session-based Authentication - Optional password protection with login page
  • API Key Authentication - Stateless API access for scripts and automation

Hardware Requirements

  • Board: Olimex ESP32-POE-ISO (or compatible ESP32-POE board)
  • Sensors: DS18B20 1-Wire temperature sensors
  • Connection: Sensors connected to GPIO4 (configurable in menuconfig)
  • PCB (optional): Custom breakout board - see hardware/ for KiCad files and BOM
  • Enclosure (optional): 3D printable case - see enclosure/ for print files

Wiring

DS18B20 PinESP32-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).

Installation

Pre-built Firmware (Recommended)

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.bin
  • partition-table.bin
  • thermux.bin

For 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.

Building from Source

Prerequisites
Build & Flash
bash
# Set target

idf.py set-target esp32

# Build

idf.py build

# Flash

idf.py -p COMx flash monitor

Or use the ESP-IDF VS Code extension build/flash commands.

Configuration

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.

Web Interface Pages

  • / - Dashboard with live temperature readings
  • /config - Configuration settings (MQTT, WiFi, sensor intervals, OTA)
  • /ota - Manual firmware upload

Configuration Options

SettingDescription
MQTT BrokerHome Assistant MQTT broker address
MQTT PortBroker port (default: 1883)
MQTT Username/PasswordAuthentication credentials
WiFi SSID/PasswordFallback WiFi credentials
Read IntervalSensor polling interval (seconds)
Publish IntervalMQTT publish interval (seconds)
OTA URLGitHub releases URL for automatic updates
SecurityEnable/disable password protection

REST API

Full API documentation is available as an OpenAPI 3.1 spec: docs/openapi.yaml

View it interactively: Swagger Editor

Home Assistant Integration

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.

Firmware Update Entity

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):

TopicDirectionPurpose
homeassistant/update/thermux_firmware/configretainedDiscovery config
thermux/update/statedevice → HA (retained)JSON: installed_version, latest_version, release_url, update_percentage, in_progress
thermux/update/installHA → devicePayload 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.

Manual REST Integration (Optional)

You can also poll sensors directly:

yaml
# 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: temperature

Modbus TCP

Thermux 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.

Sensor channels

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:

  • Move a sensor to another channel. If that channel is in use, the two sensors swap.
  • Release the channel of a sensor that has been disconnected, so the channel can be reused. Channels of connected sensors can't be released; they would just be reassigned on the next read.

Channels and Modbus settings are included in backups (Settings → Backup), so a replacement Thermux can serve the same register map.

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.

AddressContents
0Map version (currently 1)
1–3Firmware version: major, minor, patch
4Channel capacity (always 100)
5Read-cycle counter. Goes up by one after every scheduled read attempt, including failed ones; wraps at 65535
6–7Uptime in seconds (32-bit, register 6 is the high word)
8–10Ethernet MAC address, two bytes per register (register 8 = byte 0 << 8 | byte 1)
11Firmware sensor limit (CONFIG_MAX_SENSORS)
12Number of channels in use
13Number of sensors found on the bus
14Result of the last read cycle: 0 OK, 1 some sensors failed, 2 bus failure, 3 no sensors
15Read interval in seconds
100 + channelTemperature in hundredths of a °C, signed 16-bit (2150 = 21.50 °C, 0xFF38 = −2.00 °C). 0x8000 whenever the status isn't OK
200 + channelStatus (see below)
300 + channelSeconds since the last successful read (capped at 65534). 65535 if the sensor has never been read or isn't connected
1000 + 4 × channelROM 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:

ValueMeaning
1Unassigned: no sensor in this channel
2Missing: the sensor wasn't found in the latest bus scan
3Read error: the sensor's latest read failed, or the whole read cycle failed
4Stale: never read successfully, or the last good reading is older than 3 × the read interval (at least 30 s)
0OK

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.

Reading a consistent set

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.

Unit ID and errors

  • Address requests to the configured unit ID (default 1). Unit ID 0 is also answered.
  • Requests for any other unit ID get exception 0x0B (gateway target device failed to respond).
  • Unit ID 255 isn't answered: the Modbus library Thermux uses (esp-modbus 2.1.3) drops it before it reaches the server. A fix has been submitted upstream (espressif/esp-modbus#190).
  • Every function code other than 04, including all writes, gets exception 0x01 (illegal function).
  • Up to 3 clients can be connected at once.

Discovery

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.

Examples

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:

bash
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 registers

mbpoll, temperatures of channels 0–5 (-0 makes addresses zero-based):

bash
mbpoll -m tcp -a 1 -0 -t 3 -r 100 -c 6 -1 thermux.local

Python with pymodbus 3.9 or later (older versions use slave= instead of device_id=):

python
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")

BACnet/IP

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.

SettingDefaultNotes
UDP port47808 (0xBAC0)The standard BACnet/IP port. Can't be the web server's port
Device instanceDerived from the Ethernet MAC0–4194302. Must be unique on the BACnet network, so set it by hand if your site has a numbering plan
Device nameThe hostnameUp 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.

Objects

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.

PropertyValue
Object nameThe 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
DescriptionThe sensor's ROM ID, for example 281491BA00000069
Present valueTemperature in °C. If a reading fails, the last good value stays and Reliability shows the fault
Unitsdegrees-Celsius
Reliabilityno-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 flagsfault is set whenever Reliability isn't no-fault-detected
COV increment0.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.

Services

  • Who-Is / I-Am and Who-Has / I-Have
  • ReadProperty and ReadPropertyMultiple
  • SubscribeCOV (confirmed and unconfirmed), up to 16 subscriptions at once. Thermux sends a notification whenever a temperature changes by 0.1 °C or more, or its status flags change.

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.

Example

The repo includes scripts/thermux_bacnet.py, which needs BAC0 2025 or later (pip install BAC0):

bash
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 port

Add --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.

OTA Updates

Thermux can update three ways: the native Home Assistant update entity (above), the built-in web interface, or a manual .bin upload.

Automatic Updates (Recommended)

The web interface can automatically download and install updates from GitHub releases:

  1. Configure the OTA URL in web settings: https://api.github.com/repos/sslivins/thermux/releases/latest
  2. Go to the OTA page and click "Check for Updates"
  3. If a newer version is available, click "Update Now"
  4. The device downloads, flashes, and reboots automatically - no manual file download needed

Manual Upload

To install a specific version or older version, use the manual upload feature:

  1. Download the desired thermux.bin from any release
  2. Navigate to /ota page
  3. Select the .bin firmware file
  4. Click "Upload & Flash"

Security

By default, the web interface is open (no authentication required). To enable password protection:

  1. Go to /config → Security section
  2. Check "Enable password protection"
  3. Set username and password
  4. Click "Save Security Settings"

When enabled, unauthorized access redirects to a login page. Sessions are stored in a cookie and expire after 7 days.

API Key Authentication

For scripts and automation, use the API key instead of session cookies:

bash
# 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/status

The API key is:

  • Auto-generated when authentication is first enabled
  • Visible in Settings → Security section (click 📋 to copy)
  • Regeneratable if compromised (click 🔄 to generate new key)
  • Persisted across reboots in NVS flash

Session Authentication

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.

Auth Endpoints
EndpointMethodDescription
/loginGETLogin page (no auth required)
/api/auth/loginPOSTAuthenticate with {"username":"...", "password":"..."}
/api/auth/logoutPOSTDestroy session
/api/auth/statusGETCheck if logged in
/api/config/authGETGet auth config (includes API key)
/api/config/auth/regenerate-keyPOSTGenerate new API key

Home Assistant Integration

With API key authentication, REST integrations are straightforward:

yaml
# 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).

Technical Notes

Optimized Temperature Reading

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):

SensorsSequential (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).

Log Buffer

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.

Hardware Design

This repository includes open-source hardware designs:

PCB (hardware/)

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

Enclosure (enclosure/)

3D printable cases, in two parts:

  • ESP32-POE-ISO Case - the main enclosure; houses the ESP32-POE-ISO with the Sensor Bus Hat plugged on
  • Temperature Node - two-part case (PCB + enclosure) for a distributed DS18B20 sensor node on the 1-Wire bus

Each is provided as:

  • Fusion 360 (.f3d / .f3z) - Parametric source files
  • STEP (.step) - Universal CAD interchange format
  • Print files (.3mf, .stl) - Ready for slicing

Version History

See GitHub Releases for changelog.

License

MIT License - See LICENSE for details.

Parts

8
QtyValueFootprintReferences
2MountingHole_2.2mm_M2MountingHole:MountingHole_2.2mm_M2H0, H1
10.1uFCapacitor_SMD:C_0805_2012MetricC2
110uFCapacitor_SMD:C_0805_2012MetricC1
1PTC 54mA/100mA (resettable)Fuse:Fuse_0805_2012MetricF1
1TEMP_BUS_AMJ3225_88_0:GCT_MJ3225-88-0_REVAJ1
1TEMP_BUS_BMJ3225_88_0:GCT_MJ3225-88-0_REVAJ3
1TEMP_SENSORConnector_JST:JST_XH_S3B-XH-A_1x03_P2.50mm_HorizontalJ2

More from sslivins/thermux

1
  • 2 layers16.5 × 26.5 mmSensor bus hat, the printed circuit board in 3D

    Sensor bus hat

    sslivins/thermux

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

    3 parts

Similar boards

  • 2 layers20.5 × 24.8 mmPi interface, the printed circuit board in 3D

    Pi interface

    opulo-inc/lumenpnp

    The LumenPnP is an open source pick and place machine.

    8 parts3.7k
  • 2 layers59.9 × 25.7 mmBuffer, the printed circuit board in 3D

    Buffer

    hoglet67/RGBtoHDMI

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

    8 parts1kGPL-3.0
  • 2 layers52 × 12.6 mmUSB, the printed circuit board in 3D

    USB

    shanteacontrols/OpenDeck

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

    8 parts960Apache-2.0
  • 2 layers87.5 × 48.5 mm7 input macropad, the printed circuit board in 3D

    7 input macropad

    hackclub/OnBoard

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

    8 parts915
  • 2 layers36.2 × 63.1 mmPicoMemcard pico, the printed circuit board in 3D

    PicoMemcard pico

    dangiu/PicoMemcard

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

    8 parts694GPL-3.0
  • 2 layers36 × 10 mmPCB4-PWR BTN Rev.A, the printed circuit board in 3D

    PCB4-PWR BTN Rev.A

    OLIMEX/DIY-LAPTOP

    Do It Yourself Open Source Hardware and Software Modular Hacker's Friendly Laptop

    8 parts578Apache-2.0

Questions

How big is the Temp node PCB?

It measures 35 × 21 mm and has 2 copper layers, 1.6 mm thick.

What parts does the Temp node use?

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.

Where can I download the Temp node KiCad files?

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.

Can I use the Temp node design in my own project?

Its repository states no licence, so its author keeps all rights: ask sslivins before reusing the design.