Abstandsmessung mit wasserdichtem Sensorkopf: JSN-SR04T am ESP32

Von Frank Braun · veröffentlicht am 27. August 2026

Für die Umsetzung dieses Setups wird ein funktionsfähiges Home-Assistant-System mit installiertem ESPHome-Add-on benötigt. Die Schritte zur Ersteinrichtung des Mikrocontrollers sind im Beitrag ESP32 NodeMCU mit ESPHome in Home Assistant einrichten detailliert beschrieben.

Der JSN-SR04T besitzt einen wasserdichten Sensorkopf und eignet sich unter anderem für berührungslose Abstandsmessungen an Zisternen oder Regentonnen. Die separate Steuerplatine muss jedoch trocken und vor Witterung geschützt untergebracht werden. Wie zuverlässig die Messung funktioniert, hängt außerdem von der Einbausituation und der Oberfläche des Messobjekts ab. Da der Echo-Ausgang vieler JSN-SR04T-Versionen etwa 5 Volt liefert, muss sein Pegel vor dem ESP32 auf maximal 3,3 Volt reduziert werden. In diesem Aufbau kommt dafür ein bidirektionaler 4-Kanal-MOSFET-Pegelwandler zum Einsatz. Solche Module sind zwar hauptsächlich für Open-Drain-Schnittstellen wie I²C verbreitet, lassen sich bei den vergleichsweise langsamen Trigger- und Echoimpulsen dieses Sensors in der Regel ebenfalls verwenden. In diesem Beitrag erfährst du, wie du die Komponenten verbindest und in ESPHome konfigurierst.

Die Kernkomponenten für das Projekt

Für den Aufbau der Füllstandsmessung kommen vier wesentliche Bauteile zum Einsatz:

ESP32 NodeMCU Development Board

Dieses ESP32 NodeMCU Development Board* (Werbung) bildet die Steuereinheit unseres Setups. Es verarbeitet die Sensorsignale, berechnet die Abstände und überträgt die Messwerte drahtlos per WLAN an dein Smart Home.

Für diesen Beitrag wird die weit verbreitete 30-Pin-Variante mit ESP32-Chip verwendet. Da die internen GPIO-Pins des ESP32 mit einer Logikspannung von 3,3 Volt arbeiten, ist beim Anschluss von externer 5-Volt-Hardware Vorsicht geboten, um die empfindlichen Eingänge des Mikrocontrollers nicht zu beschädigen.

JSN-SR04T Wasserdichter Ultraschallsensor

Der JSN-SR04T Ultraschallsensor* (Werbung) besteht aus einer Steuerplatine und einem über ein langes Koaxialkabel angeschlossenen, wasserdichten Sensorkopf. Er sendet Ultraschallwellen aus und misst die Zeit, bis das reflektierte Echo wieder eintrifft.

Die verbreiteten JSN-SR04T-Versionen werden üblicherweise mit 5 Volt versorgt und geben am Echo-Ausgang einen für den ESP32 zu hohen Pegel aus. Da unter derselben Produktbezeichnung verschiedene Platinenrevisionen angeboten werden, solltest du vor dem Anschluss die aufgedruckte Versionsnummer und die Angaben des Händlers beziehungsweise Datenblatts prüfen. Insbesondere Messbereich, Triggerdauer und unterstützte Betriebsarten können abweichen.

4-Kanal Pegelwandler (Logic Level Converter)

Der verwendete bidirektionale 4-Kanal-MOSFET-Pegelwandler* (Werbung) passt die Signale zwischen der 3,3-Volt-Logik des ESP32 und der 5-Volt-Seite des Sensors an.

Eine galvanische Trennung stellt ein solcher Pegelwandler nicht her. Das Modul besitzt eine Hochspannungsseite (HV für High Voltage, hier 5V) und eine Niederspannungsseite (LV für Low Voltage, hier 3,3V). Die Signalpegel werden dabei an die jeweilige Logikspannung angepasst.

ESP32 30-Pin Expansion Board

Für eine übersichtlichere Verkabelung verwenden wir ein 30-Pin Expansion Board* (Werbung - Set: ESP32 mit Board). Der ESP32 wird passgenau in die beiden Buchsenleisten gesteckt. Das Expansion Board führt die GPIOs und Versorgungsanschlüsse anschließend auf gut zugängliche Stiftleisten heraus.

Die GPIO-Anschlüsse sind in einer G-V-S-Struktur angeordnet: G steht für Masse, V für die über den Jumper gewählte Versorgungsspannung und S für das eigentliche GPIO-Signal. Für dieses Projekt verbinden wir GPIO25 und GPIO26 jeweils über ihren S-Pin. Die benötigten 3,3-Volt-, 5-Volt- und Masseleitungen werden über das separate Versorgungsfeld des Expansion Boards angeschlossen.

Warum der Echo-Pegel angepasst werden muss

Mikrocontroller wie der ESP32 arbeiten intern mit einer Logikspannung von 3,3 Volt. Die GPIOs des ESP32 sind nicht für 5-Volt-Signale ausgelegt. Ein Echo-Signal mit diesem Pegel liegt außerhalb der zulässigen Betriebsbedingungen und kann den Eingang oder den Mikrocontroller beschädigen.

Viele JSN-SR04T-Versionen werden mit 5 Volt betrieben und geben auch das Echo-Signal, das die gemessene Laufzeit abbildet, mit ungefähr 5 Volt aus. Ein direkter Anschluss dieser Echo-Leitung an den ESP32 würde den Mikrocontroller außerhalb seiner Spezifikationen betreiben.

Der Pegelwandler löst dieses Problem elegant: Er besitzt zwei getrennte Spannungsversorgungen (3,3V für die Niederspannungsseite "LV", 5V für die Hochspannungsseite "HV") und schaltet über kleine Feldeffekttransistoren (MOSFETs) die Logikpegel sicher zwischen beiden Welten hin und her.

Schritt-für-Schritt-Verkabelung

Für den Aufbau verwenden wir farbige Female-to-Female-Jumperkabel. Die Farben sind technisch nicht vorgeschrieben, helfen aber dabei, die einzelnen Verbindungen später nachzuvollziehen. Führe die gesamte Verkabelung bei getrennter Stromversorgung durch. Da der Pegelwandler ohne montierte Anschlüsse geliefert wurde, müssen zuerst die Stiftleisten eingelötet werden.

Schritt 1: ESP32 auf das Expansion Board stecken

Stecke den ESP32 passgenau in die beiden Buchsenleisten des Expansion Boards. Der USB-Anschluss des ESP32 zeigt dabei in dieselbe Richtung wie die Stromanschlüsse des Expansion Boards. Kontrolliere vor dem Herunterdrücken, dass keine Pinreihe seitlich versetzt sitzt.

Schritt 2: Niederspannungsseite des Pegelwandlers anschließen

Die mit LV gekennzeichnete Seite des Pegelwandlers gehört zur 3,3-Volt-Logik des ESP32:

• Verbinde den separaten 3,3-V-Anschluss des Expansion Boards über das gelbe Kabel mit LV.
• Verbinde einen GND-Anschluss des Expansion Boards über das braune Kabel mit GND auf der LV-Seite.
• Verbinde den mit S bezeichneten Pin der Reihe D25 über das grüne Kabel mit LV1.
• Verbinde den mit S bezeichneten Pin der Reihe D26 über das blaue Kabel mit LV2.

Schritt 3: Hochspannungsseite des Pegelwandlers anschließen

Die mit HV gekennzeichnete Seite arbeitet in diesem Aufbau mit 5 Volt und zeigt zum Sensor:

• Verbinde den separaten 5-V-Anschluss des Expansion Boards über das rote Kabel mit HV.
• Verbinde einen weiteren GND-Anschluss des Expansion Boards über das orangefarbene Kabel mit GND auf der HV-Seite.

Schritt 4: Trigger und Echo über den Pegelwandler führen

Für Trigger und Echo verwenden wir die Kanäle 1 und 2. Anschlüsse mit derselben Nummer gehören jeweils zusammen; zwischen LV1 und HV1 beziehungsweise LV2 und HV2 ist kein zusätzliches Kabel erforderlich.

• Verbinde HV1 über das graue Kabel mit Trig am JSN-SR04T. Das Trigger-Signal läuft damit von GPIO25 über LV1 und HV1 zum Sensor.
• Verbinde Echo am JSN-SR04T über das weiße Kabel mit HV2. Das Echo-Signal läuft anschließend über LV2 zum GPIO26 des ESP32.

Schritt 5: JSN-SR04T mit Spannung versorgen

Die Versorgung des Sensors läuft nicht über einen Signalkanal des Pegelwandlers:

• Verbinde den separaten 5-V-Anschluss des Expansion Boards über das violette Kabel mit 5V am JSN-SR04T.
• Verbinde einen GND-Anschluss des Expansion Boards über das schwarze Kabel mit GND am JSN-SR04T.

Alle Verbindungen in der Übersicht

Schritt 6: Verkabelung vor dem Einschalten kontrollieren

Kontrolliere noch einmal alle Verbindungen. Insbesondere dürfen der Echo-Ausgang des Sensors und GPIO26 nicht direkt miteinander verbunden sein. Erst wenn 3,3 Volt an LV, 5 Volt an HV und alle Masseleitungen korrekt angeschlossen sind, wird der Aufbau mit Strom versorgt.

Detaillierte ESPHome-Konfiguration

Nachdem die physische Verkabelung abgeschlossen ist, binden wir den Sensor in ESPHome ein. Die Plattform ultrasonic ist in ESPHome integriert. Sie misst die Dauer des Echo-Impulses und berechnet daraus die Entfernung in Metern. Die Parameter timeout und pulse_time solltest du an den Messbereich und die Revision deines Sensors anpassen.

Gehe wie folgt vor, um den Code einzupflegen:

• Öffne das ESPHome-Dashboard in Home Assistant.
• Klicke bei dem entsprechenden ESP32-Gerät auf 'EDIT'.
• Navigiere zum Ende der YAML-Datei.
• Füge den untenstehenden Konfigurationsblock ein. Achte dabei penibel auf die korrekte Einrückung mit Leerzeichen.

esphome:
  name: esp32-wasserstand-sensor

# ... (WLAN und API Einstellungen bleiben unverändert)

sensor:
  - platform: ultrasonic
    trigger_pin: GPIO25
    echo_pin: GPIO26
    name: "Zisterne Rohwert Abstand"
    id: zisterne_raw
    update_interval: 10s
    # An Messbereich und Modulversion anpassen
    timeout: 4m
    pulse_time: 10us
    unit_of_measurement: "m"
    accuracy_decimals: 2
    
    # Filter zur Stabilisierung der Messwerte
    filters:
      - filter_out: nan
      - median:
          window_size: 5
          send_every: 3
          send_first_at: 3

Erklärung der Filter-Parameter

Ultraschallsensoren neigen in engen Röhren, Zisternen oder durch Kondenswasserbildung gelegentlich zu Fehlmessungen (sogenannten Ausreißern oder "NaN"-Werten, also "Not a Number"). Um ungültige Werte auszusortieren und einzelne Ausreißer zu reduzieren, nutzen wir zwei ESPHome-Filter:

• filter_out: nan: Sortiert ungültige Messungen sofort aus, noch bevor sie verarbeitet werden.
• median: Bildet aus einem gleitenden Fenster (hier die letzten 5 Messungen) den Median. Dadurch werden einzelne extreme Ausreißer häufig unterdrückt. Treten mehrere fehlerhafte Messungen innerhalb des Fensters auf, können sie den ausgegebenen Wert dennoch beeinflussen.

Messwerte im ESPHome-Protokoll kontrollieren

Nach dem Start kannst du die Messungen über 'LOGS' im ESPHome-Dashboard verfolgen. Bei einem unveränderten Abstand sieht eine typische Ausgabe beispielsweise so aus:

[09:28:57.254][D][ultrasonic.sensor:087]: 'Zisterne Rohwert Abstand' - Got distance: 1.781 m
[09:29:07.237][D][ultrasonic.sensor:087]: 'Zisterne Rohwert Abstand' - Got distance: 1.781 m
[09:29:17.242][D][ultrasonic.sensor:087]: 'Zisterne Rohwert Abstand' - Got distance: 1.785 m
[09:29:17.357][S][sensor]: 'Zisterne Rohwert Abstand' >> 1.78 m
[09:29:27.247][D][ultrasonic.sensor:087]: 'Zisterne Rohwert Abstand' - Got distance: 1.783 m
[09:29:37.244][D][ultrasonic.sensor:087]: 'Zisterne Rohwert Abstand' - Got distance: 1.789 m
[09:29:47.247][D][ultrasonic.sensor:087]: 'Zisterne Rohwert Abstand' - Got distance: 1.781 m
[09:29:47.359][S][sensor]: 'Zisterne Rohwert Abstand' >> 1.78 m

Obwohl der Name in zwei unterschiedlich gekennzeichneten Meldungen erscheint, handelt es sich nicht um zwei Sensoren. Die Zeilen mit [D][ultrasonic.sensor] zeigen die einzelnen internen Abstandsmessungen. In dieser Konfiguration erfolgt alle 10 Sekunden eine solche Messung.

Die Zeilen mit [S][sensor] zeigen dagegen den Zustand, den ESPHome nach Anwendung der Filter veröffentlicht. Da der Medianfilter mit send_every: 3 konfiguriert ist, wird nur nach jeweils drei Messungen – also ungefähr alle 30 Sekunden – ein gefilterter Wert ausgegeben und an Home Assistant übertragen. Der angezeigte Wert ist der Median des aktuellen Messfensters und muss deshalb nicht mit der unmittelbar vorherigen Einzelmessung übereinstimmen.

Nach dem Einfügen klickst du auf 'INSTALL', um die Firmware drahtlos auf den ESP32 zu flashen. Der Sensor misst in diesem Beispiel alle 10 Sekunden. Durch send_every: 3 wird jedoch nur ungefähr alle 30 Sekunden ein gefilterter Abstandswert an Home Assistant ausgegeben.

Praxis-Erweiterung: Füllstand in Prozent berechnen

Die reine Angabe des Abstands zur Wasseroberfläche ist im Smart-Home-Dashboard wenig intuitiv. Für das Dashboard ist eine Angabe des Füllstands in Prozent häufig anschaulicher. Den Prozentwert berechnen wir in diesem Beispiel mit einem Template-Sensor in Home Assistant. Für eine Ausgabe in Litern werden zusätzlich die nutzbare Tankgeometrie oder passende Kalibrierpunkte benötigt.

Berechnungsbeispiel für eine Zisterne

Für das Beispiel nehmen wir an, dass der Sensor bei leerer Zisterne einen Abstand von 2,00 Metern misst. Als maximalen Füllstand legen wir einen Abstand von 0,20 Metern fest, da viele JSN-SR04T-Versionen innerhalb dieser Totzone keine zuverlässigen Messwerte liefern. Diese beiden Werte solltest du nach dem Einbau praktisch ermitteln, da Sensorposition, Totzone und Tankgeometrie das Ergebnis beeinflussen.

Nach der Einbindung des ESP32 stellt Home Assistant den Abstand als Sensorentität bereit. Die genaue Entity-ID hängt vom Gerätenamen ab. In diesem Aufbau lautet sie sensor.esphome_web_3e3990_zisterne_rohwert_abstand. Du findest deine Entity-ID unter Einstellungen → Geräte & Dienste → Entitäten oder unter Entwicklerwerkzeuge → Zustände.

Füge anschließend den folgenden Block direkt in deine configuration.yaml ein und ersetze die im Beispiel verwendete Entity-ID bei Bedarf durch die Entity-ID deines Abstandssensors:

template:
  - sensor:
      - name: "Zisterne Prozent"
        unique_id: zisterne_prozent
        unit_of_measurement: "%"
        state_class: measurement
        icon: "mdi:water-percent"

        availability: >
          {{ is_number(states('sensor.esphome_web_3e3990_zisterne_rohwert_abstand')) }}

        state: >
          {% set abstand = states('sensor.esphome_web_3e3990_zisterne_rohwert_abstand') | float %}
          {% set prozent = (2.00 - abstand) / (2.00 - 0.20) * 100 %}
          {{ ([0, ([prozent, 100] | min)] | max) | round(0) }}

Beim gemessenen Abstand von 1,78 Metern ergibt sich mit den Beispielwerten ein Füllstand von rund 12 Prozent:

(2,00 m − 1,78 m) ÷ (2,00 m − 0,20 m) × 100 ≈ 12 %

Die Begrenzung im Template verhindert Werte unter 0 oder über 100 Prozent. Liefert der Abstandssensor keinen numerischen Zustand, wird auch der Prozentsensor als nicht verfügbar gekennzeichnet, anstatt einen irreführenden Wert auszugeben.

Visualisierung in Home Assistant

Nach dem Neuladen der Template-Entitäten stehen in Home Assistant der von ESPHome bereitgestellte Abstandssensor und der neu angelegte Sensor sensor.zisterne_prozent zur Verfügung. Die Entity-ID des Abstandssensors kann abhängig vom Namen des ESPHome-Geräts abweichen.

Für die optische Darstellung im Dashboard eignet sich beispielsweise eine Gauge-Karte. Die konfigurierte Farbanzeige kennzeichnet Werte unter 20 Prozent rot, Werte von 20 bis 49 Prozent gelb und Werte ab 50 Prozent grün. Im gezeigten Beispiel beträgt der berechnete Füllstand 12 Prozent und wird deshalb rot dargestellt.

Die Gauge-Karte mit diesen Farbgrenzen kannst du im Dashboard über den YAML-Editor der Karte wie folgt konfigurieren:

Copy

type: gauge
entity: sensor.zisterne_prozent
name: Zisterne Füllstand
min: 0
max: 100
severity:
  red: 0
  yellow: 20
  green: 50

Verwendete Hardware-Komponenten

Folgende Komponenten kamen in diesem Projekt zum Einsatz:

• ESP32 NodeMCU Development Board* (Werbung) – Das bewährte Mikrocontroller-Board mit integriertem WLAN fungiert als Rechen- und Sendeeinheit.
• Set: ESP32 mit 30-Pin Expansion Board* (Werbung) – Führt GPIOs, Versorgungsspannungen und Masse auf übersichtlich angeordnete Stiftleisten heraus.
• JSN-SR04T Wasserdichter Ultraschallsensor* (Werbung) – Robustes Ultraschall-Messkit mit abgesetzter, wetterfester Sonde, ideal für feuchte Umgebungen.
• 4-Kanal Pegelwandler (Logic Level Converter)* (Werbung) – Zum Anpassen der Signale zwischen 5V und 3,3V.
• AZDelivery Jumper Wire Kabel Female to Female* (Werbung) – Verbinden die Module nach dem Einlöten der Stiftleisten miteinander.

Weitere Praxisprojekte

Aufbauend auf der ESP32 Ersteinrichtung können verschiedene Hardware-Komponenten und Sensoren an den Mikrocontroller angebunden werden. Bisher dokumentierte Projekte:

Ansteuerung eines 3-Farben RGB-LED-Moduls

Schritt-für-Schritt-Anleitung zum Anschluss mehrerer RGB-LED-Module mittels G-V-S Expansion Board und der Erstellung individueller Lichteffekte in ESPHome.

Temperaturmessung mit dem DS18B20 am ESP32

Schritt-für-Schritt-Anleitung zum Anschluss wasserdichter DS18B20-Sensoren und zum Auslesen mehrerer Fühler über den 1-Wire-Bus in ESPHome.

Schwimmschalter am ESP32: Füllstand mit ESPHome überwachen

Schritt-für-Schritt-Anleitung zum Anschluss eines mechanischen Schwimmschalters. Erfahre, wie du einen definierten Wasserstand überwachst, mehrere Schalter für eine Min/Max-Erkennung kombinierst und kurze Zustandswechsel durch Wellenbewegungen filterst.

GPS-Tracker mit dem Beitian BE-220 am ESP32

Schritt-für-Schritt-Anleitung zur Einbindung des GPS-Moduls BE-220 in ESPHome und Visualisierung der Standortdaten in Home Assistant.