ESPHome S3KM1110 mmWave Presence Sensor

ESPHome firmware for the Waveshare S3KM1110 24GHz mmWave presence sensor on an ESP32-S3-DevKitC-1 N16R8 (16MB Flash, 8MB Octal PSRAM).

Features

• mmWave Presence Detection via patched LD2420 component (protocol-compatible with S3KM1110)
• Bluetooth Proxy for Home Assistant BLE integrations
• Zigbee Bridge to ESP32-C5 Coordinator via UART (JSON Lines protocol)
• GPIO Presence Output (hardware pin, no UART parsing needed)
• Web Server for local status/control
• Full Gate Configuration (16 gates, move/still thresholds)

Hardware

Component	Board	Module
Main MCU	SparkleIoT XH-S3E N16R8	ESP32-S3 (16MB Flash, 8MB Octal PSRAM)
mmWave Sensor	Waveshare HMMD	S3KM1110 (24GHz)
Zigbee Coordinator	Waveshare ESP32-C5-WiFi6-KIT-NXRX 16R8	ESP32-C5 (optional)

Full pinout diagrams and wiring details: PINOUT.md

Wiring Summary

mmWave Sensor (S3 right header -> Sensor J2):

S3 Pin	Sensor Pin (J2)
3V3	3V3 (1)
GND	GND (2)
GPIO17 (TX)	RX (4)
GPIO18 (RX)	TX (3)
GPIO8	OT2 (5)

Zigbee Bridge (S3 right header -> C5 left header):

S3 Pin	C5 Pin	Cable
GPIO15 (TX)	IO6 (RX)	Orange
GPIO16 (RX)	IO7 (TX)	White
3V3	3V3	Purple
GND	GND	Brown

Note: GPIO35-37 are NOT available (used by Octal PSRAM on N16R8).

Patched LD2420 Component

The stock ESPHome LD2420 component fails to initialize the S3KM1110 after software reboots (OTA, API restart, watchdog). The sensor becomes unresponsive because GPIO17 (UART TX) drops LOW during the ESP32 bootloader phase, which the sensor interprets as a UART break condition and enters an unrecoverable state.

Fixes applied

1. gpio_hold_en on shutdown — Before any software restart, GPIO17 is detached from the UART peripheral, driven HIGH, and latched via gpio_hold_en(). The RTC hold keeps the pin HIGH through the entire reboot sequence (bootloader + app init), preventing the UART break.

2. gpio_hold_dis on setup — At the start of LD2420 setup(), the hold is released so the UART driver can take control of the pin.

3. UART RX buffer flush — Drains any buffered sensor data before attempting command mode, preventing streaming data from corrupting command framing.

4. get_firmware_int crash fix — Prevents stoi crash when the sensor returns non-numeric version strings.

5. Retry logic — If initial config mode fails, retries with full UART driver reset.

Hardware reset button: The gpio_hold_en fix only covers software restarts. For hardware reset (EN pin), add an external 10kOhm pull-up resistor from GPIO17 to 3V3.

Installation

Via ESPHome Dashboard (recommended)

Add this as an external component source in your ESPHome YAML:

external_components:
  - source:
      type: git
      url: https://github.com/moag1000/esphome-s3km1110
      ref: main
    components: [ld2420, zigbee_bridge]

Local development

Clone and compile directly:

git clone https://github.com/moag1000/esphome-s3km1110.git
cd esphome-s3km1110
esphome run esp32-s3-mmwave.yaml

Configuration

Copy esp32-s3-mmwave.yaml and adjust:

• substitutions — device name
• api.encryption.key — generate a new key
• ota.password — set your OTA password
• wifi — your network credentials
• mqtt — broker address (if using Zigbee bridge)

License

MIT