The MAX31865 lets an ESP32 read a platinum PT100 or PT1000 temperature probe over SPI and publish the temperature directly to Home Assistant through ESPHome. This is useful when a probe needs to be mounted on a pipe, inside a thermowell, beside a boiler or at the end of a cable rather than on a warm electronics PCB.
The part that causes most trouble is not the SPI bus. It is matching the RTD type, the MAX31865 breakout reference resistor, and the 2-, 3- or 4-wire sensor wiring. A perfectly valid SPI connection can report the wrong temperature if any of those three do not match.
This guide starts with a classic ESP32 DevKit and an Adafruit-style MAX31865 breakout, then covers ESPHome YAML, practical commissioning, calibration checks, Home Assistant automations and fault handling. Other breakouts can use different jumper layouts and voltage-regulator circuits; check your exact board before soldering.
What MAX31865, PT100 and PT1000 Actually Do
A platinum resistance temperature detector (RTD) changes resistance as its temperature changes. The numbers in PT100 and PT1000 refer to the nominal resistance at 0°C, not the maximum temperature or operating voltage. The MAX31865 is the measurement interface: it excites the RTD, measures its resistance relative to an onboard reference resistor, applies diagnostics and sends the result digitally to the ESP32 over SPI.
| Part | Meaning |
|---|---|
| PT100 | 100 Ω nominal resistance at 0°C |
| PT1000 | 1,000 Ω nominal resistance at 0°C |
| MAX31865 | RTD interface IC; not a temperature probe by itself |
| Rref | Precision resistor physically fitted to the breakout; sets measurement ratio |
| ESP32 | Reads the MAX31865 SPI data and publishes through ESPHome |
The MAX31865 is not a thermocouple interface: a K-type thermocouple needs a compatible amplifier such as MAX31856, MAX31855 or MAX6675. Do not connect a thermocouple to RTD terminals and expect a meaningful temperature.
Choosing PT100 or PT1000
Both probe types can work with a MAX31865, but you must match the interface board. A PT100 has approximately 0.385 Ω/°C sensitivity near 0°C under the usual IEC platinum curve; a PT1000 has approximately ten times that resistance change. This makes lead resistance particularly consequential with a low-resistance PT100.
| Situation | Practical choice |
|---|---|
| Short cable, existing industrial PT100 | PT100 and the matching 430 Ω board are reasonable |
| Longer cable with only two conductors | PT1000 reduces the relative impact of lead resistance; 3/4 wires are preferable if accuracy matters |
| Existing 3-wire industrial probe | Set up both board hardware and ESPHome for three wires |
| Best lead-resistance rejection | Four-wire probe, four-wire breakout configuration |
| Ordinary room-temperature node | A digital I²C sensor may be simpler than an RTD |
The accuracy of a finished installation depends on probe class, thermal contact, cabling, reference-resistor tolerance and calibration, not simply whether the interface has a 15-bit ADC.
Verify the Reference Resistor Before Wiring
ESPHome requires reference_resistance, and that number describes the resistor physically fitted to your MAX31865 breakout. Adafruit sells two separate configurations: its PT100 breakout uses 430 Ω, and its PT1000 breakout uses 4,300 Ω. Clones may differ; confirm the resistor marking, board schematic or measurement rather than relying on the product title.
PT100 probe + 430-ohm Rref board:
rtd_nominal_resistance: 100 ohm
reference_resistance: 430 ohm
PT1000 probe + 4300-ohm Rref board:
rtd_nominal_resistance: 1000 ohm
reference_resistance: 4300 ohmChanging only the YAML does not change the physical resistor. If you attach a PT1000 to a board built for PT100, changing reference_resistance to 4300 Ω will not turn a 430 Ω resistor into a 4.3 kΩ resistor. Use a properly matched breakout or modify the hardware according to its schematic.
On Adafruit boards, the four-digit resistor marking 4300 means 430 Ω, whereas 4301 means 4,300 Ω. That resistor code is easy to misread as the resistance itself.
MAX31865 to ESP32 Wiring
The MAX31865 communicates using four SPI signals: clock, MOSI, MISO and chip select. The following ESP32 pins are an example for a classic ESP32-WROOM DevKit, not a hardwired ESP32 requirement. The S3, C3 and C6 have different board pinouts.
| MAX31865 breakout | Classic ESP32 DevKit | Purpose |
|---|---|---|
| GND | GND | Common reference |
| 3V3 / 3Vo or supply pin as specified by board | 3V3 when breakout allows direct 3.3 V supply | Check regulator and jumper design |
| CLK / SCK | GPIO18 | SPI clock |
| SDI / MOSI | GPIO23 | Data from ESP32 to MAX31865 |
| SDO / MISO | GPIO19 | Data from MAX31865 to ESP32 |
| CS | GPIO27 | Independent chip select |
| RDY | Unconnected | Not needed by ESPHome max31865 component |
ESP32 3V3 ── MAX31865 3V3 input (if breakout supports it)
ESP32 GND ── MAX31865 GND
ESP32 GPIO18 ── CLK
ESP32 GPIO23 ── SDI / MOSI
ESP32 GPIO19 ── SDO / MISO
ESP32 GPIO27 ── CSOn the genuine Adafruit breakout, VIN feeds an onboard regulator/level-shift arrangement and can take the supported input voltage, whereas its regulated 3Vo pin can be used as specified in the board documentation. Generic boards may lack those protections. Never connect a 5 V SPI output directly to ESP32 GPIO; check the breakout schematic and use a 3.3 V-safe interface.
You can share CLK, MOSI and MISO with additional compatible SPI sensors while giving each device a different CS pin. Keep the RTD lead wires separate from noisy power switching and keep the local SPI wires reasonably short.
How to Connect a Two-Wire RTD
A two-wire PT100 or PT1000 has one lead attached to each end of the sensing element. Connect one conductor on each side of the MAX31865 RTD terminal arrangement, then bridge the extra sense terminals as directed by the breakout manual. On the Adafruit board, this means shorting the appropriate two-wire jumpers or adding short wire links between each pair of terminals.
Set rtd_wires: 2 in ESPHome. With only two leads, the measurement includes the resistance of both wires and connector contacts, so cable length or corrosion can shift the indicated temperature.
For an IEC-style PT100 near 0°C, 1 Ω of added total lead resistance corresponds to roughly 2.6°C of indicated error. With a PT1000, the same extra resistance is closer to 0.26°C. These are approximate near-zero estimates; the resistance–temperature curve is not exactly linear across the full range.
Three-Wire RTD: Match the Board Jumpers
Three-wire probes usually have two conductors connected to the same side of the element and one to the other. The interface can compensate for much of the lead resistance if the lead resistances are similar. It cannot eliminate large errors from unequal or damaged leads.
On the Adafruit breakout, three-wire operation requires specific solder-jumper changes, including the configuration near Rref. Do not copy the jumper procedure to an unbranded module without inspecting its actual layout. Identify the paired conductors with a multimeter and follow the board-specific terminal drawing.
sensor:
- platform: max31865
name: "Pipe Temperature"
cs_pin: GPIO27
reference_resistance: 430 ohm
rtd_nominal_resistance: 100 ohm
rtd_wires: 3
mains_filter: 50 HzSetting three wires in YAML is not a substitute for configuring the hardware jumpers. Both must agree with the physically connected probe.
Four-Wire RTD: Best Option for Cable Resistance
A four-wire RTD uses two conductors to drive measurement current and two high-impedance conductors to sense voltage at the RTD. This greatly reduces the influence of lead resistance. It is particularly valuable for a PT100 on a longer cable or when comparing small temperature differences.
The Adafruit MAX31865 breakout ships configured for a four-wire probe. For that board, do not add the two- or three-wire jumper modifications when using a genuine four-wire sensor. Connect all four conductors to the corresponding terminals and set rtd_wires: 4.
Minimal ESPHome PT100 Configuration
ESPHome has a built-in max31865 platform; an external component is not required. The SPI bus needs both MOSI and MISO, even though the result itself is read back on MISO. The following is a PT100 on a 430 Ω board with a two-wire sensor and 50 Hz mains rejection:
spi:
clk_pin: GPIO18
mosi_pin: GPIO23
miso_pin: GPIO19
sensor:
- platform: max31865
name: "Pipe Temperature"
id: pipe_temperature
cs_pin: GPIO27
reference_resistance: 430 ohm
rtd_nominal_resistance: 100 ohm
rtd_wires: 2
mains_filter: 50 Hz
update_interval: 15sFor a PT1000, change the nominal/reference values to 1,000/4,300 Ω only if the breakout actually contains the matching 4.3 kΩ reference resistor. A 15-second interval is enough for most pipe or tank-temperature graphs; ESPHome defaults to 60 seconds if you omit it.
Complete ESP32 + MAX31865 + Home Assistant YAML
This is a standalone starter configuration for a classic ESP32 DevKit, a 3.3 V-compatible MAX31865 breakout fitted with the 430 Ω reference resistor, and a correctly wired two-wire PT100. Replace the Wi-Fi and API secrets, and change rtd_wires only after configuring the hardware.
esphome:
name: boiler-pipe-probe
friendly_name: Boiler Pipe Probe
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
spi:
id: rtd_spi
clk_pin: GPIO18
mosi_pin: GPIO23
miso_pin: GPIO19
sensor:
- platform: max31865
spi_id: rtd_spi
id: pipe_temperature
name: "Pipe Temperature"
cs_pin: GPIO27
reference_resistance: 430 ohm
rtd_nominal_resistance: 100 ohm
rtd_wires: 2
mains_filter: 50 Hz
update_interval: 15s
filters:
- median:
window_size: 3
send_every: 1
- platform: wifi_signal
name: "RTD Node WiFi RSSI"
update_interval: 60s
entity_category: diagnostic
- platform: uptime
name: "RTD Node Uptime"
entity_category: diagnosticESPHome publishes the RTD as a temperature entity through the Native API, so you do not need a separate MQTT broker. The Wi-Fi and uptime sensors help separate a genuine RTD fault from a node that has simply lost its network connection.
Home Assistant: Displaying the Sensor and Using Thresholds
Once the ESPHome device is added, pin the temperature entity to a Home Assistant dashboard and record a baseline with the probe at room temperature. For a non-safety-critical use, the reading can control a circulation fan, log tank-temperature trends or notify you when a pipe approaches a chosen threshold.
Use two separate thresholds for on/off control; a single threshold near the current reading can chatter as small variations arrive. Use a minimum-on/minimum-off period when your actuator requires it, and check sensor availability explicitly before acting.
# Example Home Assistant trigger for a notification only
triggers:
- trigger: numeric_state
entity_id: sensor.boiler_pipe_probe_pipe_temperature
above: 55
for: "00:02:00"
actions:
- action: persistent_notification.create
data:
title: "Pipe temperature"
message: "The pipe probe is above 55 °C."The entity ID shown is illustrative: use the exact one assigned by your Home Assistant installation. Numeric-state triggers react to threshold crossings, so add a startup/state-reconciliation check if a condition must be evaluated after Home Assistant restarts.
Do not use a hobby ESP32, Wi-Fi link or Home Assistant automation as the only high-temperature safety limiter for a boiler, pressurised vessel, heater or pump. Independent thermostats, thermal cutouts and manufacturer-specified protections must remain in place.
Calibrate the System, Not Just the YAML
Start with an electrical check: a disconnected probe, a shorted lead, wrong reference resistor or the wrong wire-mode setting can create an error that no offset should be allowed to hide. Then test at two stable, known temperatures appropriate to the probe and application.
- Compare the PT100 or PT1000 against a traceable or known-good reference in the same stable medium.
- Make sure the entire intended sensing tip is at the reference temperature and has reached thermal equilibrium.
- Avoid comparing a pipe-clamp sensor against a nearby air thermometer; they are not in the same thermal environment.
- Check the result at a second temperature to distinguish a fixed bias from a slope/reference-resistor problem.
- Only after confirming the electronics and mounting should you add a small
offsetfilter for a consistent, measured bias.
A melting ice-and-water reference can be useful for a suitably sealed probe, but a probe resting on ice or touching a warm container wall may not actually be at 0°C. Do not immerse an unsealed terminal head or breakout board.
Why a Two-Wire PT100 Reads Too Hot
If an extra 2 Ω of cable/contact resistance is added to the RTD measurement, the apparent PT100 error near 0°C is around 5.2°C. With a PT1000 it is about 0.52°C. That simple calculation is a useful diagnostic: if the error grows as you add an extension cable, the issue may be lead resistance rather than bad ESPHome math.
Three-wire compensation works best when conductors match; four-wire is usually preferable for high-accuracy remote PT100 measurements. For an installation that merely decides whether a radiator pipe is warm, a short two-wire PT1000 may already be sufficient.
Setting the Mains Filter: 50 Hz or 60 Hz
The MAX31865 can reject interference associated with the local mains frequency. ESPHome exposes mains_filter: 50 Hz or mains_filter: 60 Hz and defaults to 60 Hz. For a UK or European installation, 50 Hz is the appropriate first choice; use 60 Hz in 60 Hz electricity regions.
This filter does not repair long unshielded sensor wiring routed next to motor power cables. Keep the RTD leads away from variable-frequency-drive outputs and relay contacts, use suitable shielded/twisted cable where warranted and follow grounding recommendations for the actual probe and installation.
Multiple MAX31865 Boards on One ESP32
SPI can share CLK, MOSI and MISO while using a separate chip-select GPIO for each MAX31865 board. Each breakout can have its own RTD type, reference-resistor value and update interval:
spi:
id: shared_spi
clk_pin: GPIO18
mosi_pin: GPIO23
miso_pin: GPIO19
sensor:
- platform: max31865
spi_id: shared_spi
name: "Flow Temperature"
cs_pin: GPIO27
reference_resistance: 430 ohm
rtd_nominal_resistance: 100 ohm
rtd_wires: 4
- platform: max31865
spi_id: shared_spi
name: "Return Temperature"
cs_pin: GPIO26
reference_resistance: 4300 ohm
rtd_nominal_resistance: 1000 ohm
rtd_wires: 3This example intentionally combines a PT100 and a PT1000 to show that the matching reference resistor is a per-board hardware property, not a property of the shared SPI bus. Each breakout also needs to be jumper-configured for the listed number of wires.
Troubleshooting: All Readings Are Missing
- Verify power and ground first; the RTD probe itself does not power the MAX31865 board.
- Check that ESP32 MOSI goes to MAX31865 SDI, and ESP32 MISO goes to MAX31865 SDO. These labels describe the direction relative to the device.
- Check CLK and the actual chip-select GPIO, and ensure two SPI devices are not configured to use the same CS.
- Confirm the breakout logic level is safe for 3.3 V GPIO.
- Start with short SPI wiring and one MAX31865 connected; add other peripherals only after a good reading.
- Check ESPHome logs for SPI or MAX31865 configuration errors before modifying filters or calibration values.
Troubleshooting: Temperature Is Implausibly High or Low
A reading far outside the physical situation can result from the wrong PT100/PT1000 setting, incorrect Rref, a broken/shorted lead, mixed-up two-/three-/four-wire terminals or a poor connection. Check the probe resistance with a multimeter after disconnecting it from the MAX31865 and allowing it to stabilise near a known temperature.
At approximately 0°C, PT100 should measure near 100 Ω and PT1000 near 1,000 Ω, excluding external lead resistance. At room temperature the value will be above the nominal number. Do not expect a temperature probe to have a constant resistance independent of temperature.
If a three-wire probe reads normally until you enable rtd_wires: 3, recheck the breakout jumpers and identify which two conductors terminate at the same side of the sensing element. A wrong hardware strap is not a software-calibration problem.
Troubleshooting: Values Jump When a Motor Starts
Motor switching and long RTD leads can introduce noise or common-mode voltage. Inspect grounding, cable routing and the probe sheath, and consider galvanic isolation or a purpose-built industrial transmitter for harsh electrically noisy environments. Light median filtering can suppress a rare bad sample, but it should not conceal sustained wiring or safety problems.
Troubleshooting: Probe Reads Correctly in Air but Wrong on a Pipe
Thermal contact and insulation are the likely causes. A loosely attached stainless probe can measure the surrounding air as much as the pipe. Use an appropriate clamp or thermowell, thermal coupling suitable for the installation, and insulation around the sensing point where appropriate. Do not strap a sensor onto an exposed unsafe surface or compromise pressure-containing hardware.
MAX31865 vs DS18B20 vs Thermocouple
| Sensor system | Where it is useful | Limitation |
|---|---|---|
| MAX31865 + PT100/PT1000 | Remote metal probes, stable repeatability, 3-/4-wire cable compensation, industrial-style installations | More wiring and configuration; breakout and RTD must match |
| DS18B20 waterproof digital probe | Simple low-cost water/pipe temperatures with 1-Wire bus | Probe quality and genuine sensor sourcing vary; check operating limits |
| K-type thermocouple + matching interface | High-temperature applications beyond the range of common low-cost RTD probes | Different sensor physics and amplifier; needs cold-junction compensation |
For a simple water-tank temperature measurement, the existing ESP32 DS18B20 with Home Assistant guide may be sufficient. Choose MAX31865 when a PT100/PT1000 probe and its cabling provide a real benefit.
Related ESP32 and Home Assistant Guides
- ESP32 DS18B20 with Home Assistant — simpler digital temperature-probe alternative.
- ESP32 Weather Station with ESPHome — temperature/humidity/pressure outdoors; not an RTD replacement for pipe measurements.
- ESPHome Native API vs MQTT — choosing the integration architecture.
- ESPHome Wi-Fi Disconnects — diagnose nodes that go offline while the RTD wiring remains healthy.
Official References
- ESPHome MAX31865 temperature sensor — supported settings, reference resistance, wire count, SPI and 50/60 Hz filtering.
- ESPHome SPI bus — bus wiring and separate chip-select configuration.
- Adafruit RTD wiring and configuration — physical 2-, 3- and 4-wire terminal/jumper requirements.
- Adafruit MAX31865 FAQ — 430 Ω versus 4.3 kΩ reference resistors and identifying board variants.