A PT100 or PT1000 platinum resistance temperature detector (RTD) is a useful choice when a waterproof probe, a long lead or repeatable temperature measurement matters more than the convenience of a one-wire digital sensor. The ESP32 cannot read a platinum RTD directly with the precision and lead-wire compensation that many installations need. The MAX31865 interface measures the RTD against a precision reference resistor and sends the result to the ESP32 over SPI. ESPHome can then publish temperature to Home Assistant.
This guide builds a working single-probe monitor first, then shows how to adapt it for a PT1000, two-, three- or four-wire cable, and multiple probes. It also explains the most expensive-looking but surprisingly common mistake: setting the probe type correctly while configuring the wrong reference resistor fitted to the MAX31865 breakout.
What the MAX31865 does — and does not do
The RTD itself is a passive resistor whose resistance changes predictably with temperature. A PT100 has a nominal resistance of 100 Ω at 0 °C; a PT1000 is 1000 Ω at 0 °C. The MAX31865 excites the probe, measures its resistance relative to a resistor on the interface board, and provides a digital result over SPI. ESPHome turns that result into a temperature entity.
This is different from a thermocouple interface. A PT100/PT1000 must use an appropriate RTD frontend; a MAX31855 or MAX6675 thermocouple board is not an interchangeable alternative. Likewise, the MAX31865 does not measure humidity or provide a temperature-certified control system just because it reports two decimal places.
| Part | What to check |
|---|---|
| RTD probe | PT100 or PT1000; 2, 3 or 4 lead wires; required temperature range and probe sheath rating |
| MAX31865 breakout | Reference resistor fitted on the actual PCB; terminal-block labels and hardware jumper layout |
| ESP32 board | Available GPIOs for CLK, MOSI, MISO and one CS output; stable 3.3 V power |
| ESPHome | The spi bus plus one max31865 sensor configuration per breakout |
| Home Assistant | A regular temperature entity for graphs, trends and non-safety-critical automations |
PT100 versus PT1000: why the reference resistor matters
An RTD interface does not infer the probe model from its wires. ESPHome needs two independent values: rtd_nominal_resistance describes the probe at 0 °C; reference_resistance describes the precision resistor physically installed on the board. For example, Adafruit sells separate PT100 and PT1000 breakout variants. Their PT100 board uses a 430 Ω reference resistor, while their PT1000 board uses 4300 Ω. Many third-party boards copy one of these combinations, but not all do. Inspect the board listing, schematic or resistor marking rather than assuming the chip itself dictates the resistor.
| Probe and breakout | rtd_nominal_resistance | reference_resistance | Comment |
|---|---|---|---|
| PT100 + 430 Ω board | 100 | 430 | Typical PT100 Adafruit-style combination |
| PT1000 + 4300 Ω board | 1000 | 4300 | Typical PT1000 Adafruit-style combination |
| Any other documented combination | Actual probe nominal value | Actual fitted reference resistor | Verify that the resistor and measurement range suit the probe |
Some surface-mount resistor markings are counterintuitive: an Adafruit board marked 4300 denotes 430 Ω, while its PT1000 board may be marked 4301 for 4300 Ω. The resistor’s marking is not a universal cross-vendor identification rule. When in doubt, consult the exact manufacturer documentation or measure the resistor correctly with power disconnected, taking circuit connections into account.
For perspective, a standard platinum PT100 is approximately 107.8 Ω near 20 °C, and a PT1000 approximately 1078 Ω. These are useful rough continuity checks, not a substitute for calibrating a complete measurement chain. A wrong reference resistance can yield a consistent but entirely implausible temperature even though SPI communication is functioning perfectly.
Two-wire, three-wire and four-wire RTD probes
The probe’s lead count describes how its sensing resistor is brought out, not how many SPI wires the MAX31865 needs. The SPI connection to the ESP32 is always separate from the RTD terminal block.
| Probe wiring | Practical meaning | When to choose it |
|---|---|---|
| 2-wire | The two cable conductors add series resistance to the measured RTD. | Short leads, modest accuracy requirements and simple installations. |
| 3-wire | The interface can compensate for lead resistance when the corresponding leads have similar resistance and the breakout is correctly configured. | Longer industrial-style probes where a third conductor is provided. |
| 4-wire | Separate sense and excitation paths reduce sensitivity to lead resistance. | Higher-accuracy work or long leads when the probe and board support four wires. |
Lead resistance is more significant as a fraction of a PT100’s 100 Ω nominal resistance than of a PT1000’s 1000 Ω. That is one reason a PT1000 can be attractive for a simple two-wire monitor. Three-wire compensation assumes the relevant lead resistances match reasonably well; a damaged connector or mismatched cable can still cause error. Four-wire measurement reduces lead-resistance error, but probe grade, reference-resistor tolerance and thermal installation still matter.
Before wiring a mystery probe, disconnect it from all electronics and measure between its conductors with a multimeter. On a three-wire probe, two leads usually connect to the same end of the RTD and show only cable resistance between themselves; either of those measured to the remaining lead includes the sensing element. On a four-wire probe, identify the two same-end pairs. Colour codes are helpful hints, not a reliable substitute for measurement.
Parts and wiring for an ESP32 DevKit
- ESP32 DevKit based on the classic ESP32-WROOM-32; adapt the chosen GPIOs if using an S3, C3 or board with reserved pins.
- MAX31865 breakout with a verified reference-resistor value and terminals for your probe type.
- Compatible PT100 or PT1000 sensor, 2/3/4-wire as required, with sheath and cable rated for the location.
- USB data cable and a 3.3 V-capable, adequately powered ESP32 setup; short SPI jumpers for initial testing.
- Optional weather-resistant enclosure, strain relief and appropriate cable gland for a permanent installation.
The following wiring uses a 3.3 V-powered breakout that supports 3.3 V logic. On Adafruit’s regulated and level-shifted board, VIN can accept 3–5 V and supplying it from the ESP32’s 3V3 pin keeps its SPI logic compatible. Generic boards differ: some expose a regulator input, some expose the chip’s direct 3.3 V supply, and some have no level shifting. Do not apply 5 V SPI signals to an ESP32 GPIO or assume every pin labelled VCC accepts 5 V.
| MAX31865 pin | ESP32 DevKit connection | Purpose |
|---|---|---|
| VIN / VCC (verify board) | 3V3 | Supply for this 3.3 V wiring example |
| GND | GND | Common ground |
| CLK / SCK | GPIO18 | SPI clock |
| SDO / SO | GPIO19 | SPI MISO: MAX31865 → ESP32 |
| SDI / SI | GPIO23 | SPI MOSI: ESP32 → MAX31865 |
| CS | GPIO5 | Dedicated chip select |
| RDY | Not connected | Not used by ESPHome’s MAX31865 component |
The SDI/SDO labels are from the sensor board’s point of view: connect the sensor’s SDO to ESP32 MISO, and its SDI to ESP32 MOSI. A reversed pair can produce missing-sensor or invalid-reading symptoms. The example pins are convenient on many classic DevKit boards; verify your board pinout, especially when a display, flash-connected pins or other SPI devices share the board.
Important: Wire the RTD to the breakout with power removed. The terminal order and required solder bridges are hardware-specific. ESPHome’s rtd_wires option changes the chip configuration; it cannot close a missing jumper or undo the wrong wiring on the PCB.
Connect the probe to the terminal block
Four-wire probe
For an Adafruit-style four-terminal breakout, find the two pairs of leads connected to the same end of the sensing element. Terminate one pair on the two terminals at one side of the block and the other pair on the opposite side, following the breakout’s F±/RTD± labels and manufacturer drawing. The Adafruit breakout is shipped for four-wire measurement, so its configuration jumpers normally remain unchanged. A different board may have another default.
Three-wire probe
Use a meter to find the two wires that connect to one side of the element. On Adafruit’s breakout these go to F+ and RTD+; the remaining lead goes to the opposite RTD terminal as shown in its wiring guide. The board must also be reconfigured for three-wire operation: the documented jumper requires a small trace cut and solder-bridge changes. Follow photographs for your exact PCB revision rather than copying a jumper pattern from another manufacturer.
Two-wire probe
Each of the two probe wires connects to one end of the RTD input, and the appropriate excitation-to-sense pairs must be bridged. On the Adafruit board you can use the specified solder bridges or short link wires at the terminal block. Simply landing two wires in four isolated terminals without fitting the bridges can cause open-circuit faults. Always check the manufacturer’s terminal labels and recommended bridge pattern.
Complete ESPHome configuration: PT100 with a three-wire probe
This example assumes a classic ESP32 DevKit, a PT100 element, a MAX31865 breakout with a 430 Ω reference resistor, and the three-wire hardware modification described above. Change all three RTD-related settings together if your probe, PCB or jumper configuration differs. Replace the Wi-Fi secrets with the entries from your ESPHome secrets file, and use the API encryption key generated for your device.
esphome:
name: rtd-workshop
friendly_name: RTD Workshop
esp32:
board: esp32dev
framework:
type: arduino
logger:
api:
encryption:
key: !secret rtd_workshop_api_key
ota:
- platform: esphome
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "RTD Workshop Fallback"
password: !secret fallback_ap_password
captive_portal:
spi:
clk_pin: GPIO18
miso_pin: GPIO19
mosi_pin: GPIO23
sensor:
- platform: max31865
name: "Workshop Probe Temperature"
id: workshop_rtd
cs_pin: GPIO5
reference_resistance: 430.0
rtd_nominal_resistance: 100.0
rtd_wires: 3
mains_filter: 50 Hz
update_interval: 10s
accuracy_decimals: 2ESPHome’s official MAX31865 component supports reference_resistance, rtd_nominal_resistance, rtd_wires, mains_filter, update_interval and cs_pin. The SPI bus requires both MISO and MOSI for this sensor. accuracy_decimals: 2 controls the displayed number of decimal places; it does not make the hardware accurate to ±0.01 °C.
The 50 Hz filter is a reasonable starting point for installations in much of Europe, including the UK. Select 60 Hz if the predominant local mains frequency is 60 Hz. This is a mains-interference rejection setting, not a command to sample at 50 or 60 measurements per second. Ten-second updates are suitable for monitoring many water and air temperatures; a probe in a metal thermowell or a large liquid tank may respond much more slowly than ESPHome polls it.
Adapt the YAML for PT1000 or another lead count
If the sensing element is a PT1000 and the actual board has the corresponding 4300 Ω reference resistor, change these values in the sensor block:
reference_resistance: 4300.0
rtd_nominal_resistance: 1000.0
rtd_wires: 4 # Set to 2, 3 or 4 to match probe AND board wiringA two-wire PT100 on a verified 430 Ω board uses rtd_nominal_resistance: 100.0, reference_resistance: 430.0 and rtd_wires: 2, plus the proper board bridges. A four-wire PT100 uses the same resistor values and rtd_wires: 4. Resist the temptation to change the reference value until the display looks plausible: the setting must describe the physical resistor, or any apparent correction will be misleading across the temperature range.
If you bought a generic MAX31865 board advertised for “PT100/PT1000,” verify whether it has a switchable reference resistor, requires replacing that resistor or supports only one sensor type as populated. The MAX31865 integrated circuit can interface with different RTDs, but the complete assembled PCB is not automatically a plug-and-play universal board.
Bring the device online and verify its readings
- With power disconnected, check the breakout supply marking, SPI pin routing, probe lead pairs, jumper state and screw-terminal tightness.
- Power the ESP32 from USB. In the ESPHome dashboard, open the YAML configuration, validate it and install firmware over USB for the first flash.
- Open the live ESPHome logs. Confirm the Wi-Fi connection, API availability and a MAX31865 component with the configured reference resistance, lead count and mains filter.
- Observe the temperature value in Home Assistant. Compare it with a trusted thermometer in a stable, stirred environment rather than touching the metal probe with your fingers and expecting instant agreement.
- Gently warm and cool the probe within its rated limits. The reading should move smoothly in the right direction without bursts of impossible values or lost sensor states.
An ambient-air test is useful for confirming that the measurement chain works, but it is a weak calibration method. Drafts, electronics self-heating, direct sun and the probe sheath’s thermal inertia can explain several degrees of difference. For a water-temperature installation, use a suitable immersion depth and good thermal contact. If the probe is in a thermowell, use the manufacturer-recommended thermal coupling method.
Multiple PT100/PT1000 sensors on one ESP32
SPI allows multiple MAX31865 boards to share clock, MOSI and MISO, while each board receives a different chip-select line. Unlike I²C, you do not need a different I²C address for each sensor. You do need one complete RTD frontend per independent probe; wiring two unrelated RTDs to the same MAX31865 input does not produce two temperatures.
For a second board powered from the same compatible 3.3 V supply, connect its CLK, SDO and SDI to the existing SPI bus and connect its CS to another unused output, such as GPIO17 on an appropriate classic ESP32 DevKit. The second board may have a different RTD reference resistor: configure its own sensor block to match its actual hardware.
spi:
clk_pin: GPIO18
miso_pin: GPIO19
mosi_pin: GPIO23
sensor:
- platform: max31865
name: "Tank Inlet Temperature"
cs_pin: GPIO5
reference_resistance: 430.0
rtd_nominal_resistance: 100.0
rtd_wires: 3
mains_filter: 50 Hz
update_interval: 10s
- platform: max31865
name: "Tank Outlet Temperature"
cs_pin: GPIO17
reference_resistance: 4300.0
rtd_nominal_resistance: 1000.0
rtd_wires: 4
mains_filter: 50 Hz
update_interval: 10sThe snippet above is the spi/sensor portion of a larger ESPHome device configuration; retain the network and API sections from the complete example. Check both breakouts’ power budget and keep SPI wiring short and well grounded. A long remote RTD cable can be appropriate; a long unbuffered SPI cable between the ESP32 and breakout is a different electrical problem and is more vulnerable to signal degradation.
Home Assistant: graphs, alerts and useful entities
After you add the ESPHome device to Home Assistant, the MAX31865 temperature becomes a normal sensor entity with °C as its unit. Pin it to a history graph, display it alongside an SCD40 room-temperature reading, or compare inlet and outlet probes to observe the change through a heat exchanger. Probe positioning and matched calibration matter if you plan to interpret small temperature differences.
For example, an alert for an unusually high but non-critical tank temperature can use a Home Assistant numeric-state trigger. Replace the example entity name and limit with values relevant to your own installation:
alias: Workshop RTD temperature notification
description: Notify if the monitored RTD remains above the chosen threshold
triggers:
- trigger: numeric_state
entity_id: sensor.workshop_probe_temperature
above: 55
for: "00:02:00"
actions:
- action: persistent_notification.create
data:
title: "Workshop temperature above threshold"
message: "Check the RTD sensor and the monitored equipment."
mode: singleThis illustrative Home Assistant automation sends a persistent notification after two minutes above 55 °C. It is not a safety thermostat: a disconnected probe, reboot, Wi-Fi loss or unavailable Home Assistant can prevent it from operating. Do not depend on an ESPHome/HA hobby-grade monitoring chain as the sole high-temperature protection for a boiler, heater, pressurised vessel or any safety-critical process. Retain independent, appropriately rated thermal cut-outs and controls.
Accuracy: what two decimal places really mean
A displayed value of 21.37 °C is not evidence of 0.01 °C accuracy. Total uncertainty is affected by the platinum element’s tolerance class, the reference resistor’s actual resistance and temperature coefficient, analog measurement error, cable and contact resistance, self-heating, thermal gradients, sheath response and mounting. The board’s 50/60 Hz rejection helps suppress line-frequency interference but cannot correct poor mechanical installation.
A practical commissioning check is to compare the probe against a trustworthy thermometer at two stable temperatures within the intended operating range. Keep both sensing tips close together without touching container walls, allow enough time for thermal equilibrium and record the readings. If a consistent offset is verified, ESPHome supports sensor filters, but adjust software only after correcting wrong probe/reference settings and contact problems. A one-point offset does not correct a wrong slope caused by the wrong reference resistor or a nonmatching RTD.
For traceable measurement, use a probe with documented tolerance and an appropriate calibration method. For ordinary monitoring, a reliable, repeatable trend can be more valuable than chasing extra displayed decimal places.
Troubleshooting: identify the fault by its symptom
| Symptom | Likely checks | Next action |
|---|---|---|
| Sensor absent, no useful temperature | Power/GND, SDO↔MISO and SDI↔MOSI, CS GPIO, bad SPI jumpers | Confirm 3.3 V supply and continuity; shorten leads; examine ESPHome logs. |
| ESPHome reports all-zero/all-one SPI read | Breakout not replying, SPI wiring, chip select or power | Test board alone on a short SPI harness; confirm GPIO selection. |
| Open-circuit or reference fault | Probe terminal loose, broken lead, missing 2/3-wire bridge | Power off, check RTD resistance and exact board jumper instructions. |
| Plausible but wildly incorrect °C | Wrong reference resistor or PT100/PT1000 nominal value | Identify populated RREF on PCB and update both settings independently. |
| Constant error with longer two-wire cable | Series resistance of cable and connectors | Use three-/four-wire probe correctly or evaluate PT1000 suitability. |
| Intermittent spikes or unavailable readings | SPI interference, loose screw terminal, moisture or inadequate supply | Secure connections, use an enclosure and strain relief, test a short local probe. |
| One of two boards works | Shared CS or conflicting pins; second board powered incorrectly | Give every MAX31865 a dedicated CS and verify each board separately. |
The ESPHome driver can log an SPI read of all zeros or ones and publish an invalid value for a communication fault; it can also report detected MAX31865 fault conditions. The exact message depends on the failure and ESPHome version. Before concluding that a probe has failed, compare the logs with a multimeter check at the disconnected sensor, then test the breakout with a short known-good probe. Do not measure resistance on an energised circuit.
Why the temperature moves when the cable moves
A reading that jumps whenever the cable is touched commonly points to a loose terminal, broken strand or moisture in a connector, not poor digital filtering. On a three-wire sensor, one damaged conductor can invalidate the lead-resistance compensation. Inspect the entire sensing cable and keep it away from mains wiring, motor drives and high-current switching loops as far as practical.
Why two adjacent probes disagree
Check that each breakout’s reference resistor has been identified correctly, the probes are fully immersed or attached with equal thermal coupling, the sensing tips have had time to stabilise, and one probe is not closer to the heater, pipe wall or air draft. Sensor mismatch may be a real calibration issue, but environmental gradients are often easier to demonstrate first.
Installation tips for a dependable long-term monitor
- Keep the MAX31865 interface and ESP32 dry, powered by a stable low-voltage supply, and away from condensation; use a suitable enclosure for wet or outdoor locations.
- Use a probe sheath, cable insulation and thermowell rated for the temperature, liquid and mechanical environment. A metal probe is not automatically safe for every corrosive fluid or food-contact application.
- Provide strain relief so the screw terminals do not carry the cable’s mechanical load, and avoid routing low-level RTD leads alongside high-current switching cables.
- Keep the SPI wiring short; locate the breakout close to the ESP32 and run the RTD probe cable to the measurement point rather than extending SPI across a building.
- Label each probe with its element type, lead count and location. Record the breakout’s actual reference-resistor value next to the corresponding ESPHome YAML settings.
- For process monitoring, graph sensor availability alongside temperature. An old Home Assistant value should not be mistaken for a fresh live measurement.
MAX31865, DS18B20 or thermocouple: which belongs in this project?
A waterproof DS18B20 is often the simplest digital solution for modest-range water and ambient monitoring. A PT100/PT1000 with MAX31865 is worth the extra wiring when the job calls for an industrial-style probe, interchangeable platinum elements, a particular sheath form or lead-wire compensation. A thermocouple with the correct thermocouple frontend suits other temperature ranges and environments, especially when an RTD’s specifications are unsuitable. Select the probe for the physical job first, then choose the frontend and ESPHome component to match it.
If you are extending a weather station or room-air monitor, a low-cost digital temperature sensor may already be sufficient. If you are instrumenting a hot-water tank, pipe, fermentation vessel or test jig, the MAX31865 is a practical route to a serviceable RTD probe—as long as you treat electrical configuration, mechanical placement and calibration as parts of the same measurement system.
Reference documentation
- ESPHome — MAX31865 platinum RTD sensor: current YAML keys and wiring requirements.
- ESPHome — SPI bus: clock, MOSI/MISO and multiple SPI-device configuration.
- Adafruit — MAX31865 breakout pinouts: supply, logic levels, CS sharing and jumper overview for its boards.
- Adafruit — two-, three- and four-wire RTD wiring: board-specific terminal and jumper instructions.
- Adafruit — MAX31865 Arduino guide: reference-resistor values and hardware diagnostics.