Skip to content

feat(at581x): Add support fo AT581x RADAR presence sensor (found in esp32-s3-box-3 sensor dock)#644

Merged
finger563 merged 3 commits into
mainfrom
feat/at581x
Jun 21, 2026
Merged

feat(at581x): Add support fo AT581x RADAR presence sensor (found in esp32-s3-box-3 sensor dock)#644
finger563 merged 3 commits into
mainfrom
feat/at581x

Conversation

@finger563

@finger563 finger563 commented Jun 21, 2026

Copy link
Copy Markdown
Contributor

Description

Adds a new espp::At581x component: a driver for the AT581X (AirTouch) 5.8 GHz microwave-radar human-presence / motion sensor. This is the radar found on modules such as the MoreSense MS58-3909S68U4, including the one on the
ESP32-S3-BOX-3 sensor / dock board (I2C SDA=GPIO41, SCL=GPIO40, address 0x28, presence output on GPIO21).

The driver (BasePeripheral<>, header-only) configures the chip over I2C — RF frequency, detection distance/sensitivity (threshold), gain, power consumption, and trigger/protect/self-check timing — following the AT581X datasheet and the
Espressif & ESPHome reference drivers. It exposes runtime setters (set_sensing_distance, set_gain, set_trigger_keep_time), set_rf_enabled, reset, and allowed_frequencies_mhz() / allowed_power_ua() validators. Presence/motion is
reported on the chip's active-high output GPIO (held for trigger_keep_time), so the example wires that pin to an espp::Interrupt.

Included:

  • Component: components/at581x/include/at581x.hpp, CMakeLists.txt, idf_component.yml, README.md.
  • Example: components/at581x/example/ — configures the radar over I2C and reports presence. When the ESP32-S3-BOX-3 hardware profile is selected (default on esp32s3), it additionally uses the esp-box BSP to render live radar status
    on the screen via LVGL (color-coded presence label + detection count + sensing distance). The radar is placed on I2C_NUM_1 in that mode to avoid colliding with the box's internal I2C bus (I2C_NUM_0, GPIO8/18).
  • Docs: new presence category — doc/en/presence/{index.rst, at581x.rst, at581x_example.md} — registered in doc/en/index.rst; doc/Doxyfile updated (INPUT + EXAMPLE_PATH).
  • CI: .github/workflows/build.yml (added the example to the build matrix, target esp32s3) and .github/workflows/upload_components.yml (added components/at581x to the registry upload).

Note on scope: the AT581X is a binary presence/motion detector — its only true output is the presence GPIO; the I2C interface is configuration-only and does not expose distance/velocity/signal-strength. The "sensing distance" is a detection
threshold, not a measurement.

Motivation and Context

The ESP32-S3-BOX-3 sensor dock includes an AT581X radar for human-presence detection, but espp had no driver for it. This adds first-class support so espp users (especially on the BOX-3) can configure the radar and react to presence/motion,
with an on-screen demo for the BOX-3.

How has this been tested?

  • Built the example with ESP-IDF (v6.0) for esp32s3:
    • ESP32-S3-BOX-3 profile (default): builds clean with the esp-box BSP + LVGL display path active (radar on I2C_NUM_1 @ 41/40, output interrupt on GPIO21). Binary fits the app partition.
    • Custom profile (no display): builds clean with the display code compiled out (radar on I2C_NUM_0).
  • Verified the new example is picked up by build.yml and that the Doxyfile INPUT/EXAMPLE_PATH entries resolve the \snippet reference.

Screenshots (if appropriate, e.g. schematic, board, console logs, lab pictures):

image image
I (188) main_task: Calling app_main()
[at581x example/I][0.188]: Starting AT581X radar example
[At581x/I][0.190]: Writing config: freq=5800MHz, sensing_distance=700, gain=3, power=70uA, trigger_base=500ms, trigger_keep=1000ms, protect=1000ms, selfcheck=2000ms
[At581x/I][0.193]: Resetting RF frontend
[at581x example/I][0.196]: Watching radar output on GPIO 21
[at581x example/I][0.196]: Radar presence DETECTED
[Interrupt/W][0.197]: ISR service already installed, not installing again
W (199) ledc: the binded timer can't keep alive in sleep
[at581x example/I][2.322]: Radar presence cleared
[at581x example/I][5.057]: Radar presence DETECTED
[at581x example/I][7.838]: Radar presence cleared
[at581x example/I][14.645]: Radar presence DETECTED
[at581x example/I][16.186]: Radar presence cleared

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation Update
  • Hardware (schematic, board, system design) change
  • Software change

Checklist:

  • My change requires a change to the documentation.
  • I have added / updated the documentation related to this change via either README or WIKI

Software

  • I have added tests to cover my changes.
  • I have updated the .github/workflows/build.yml file to add my new test to the automated cloud build github action.
  • All new and existing tests passed.
  • My code follows the code style of this project.

@github-actions

github-actions Bot commented Jun 21, 2026

Copy link
Copy Markdown

✅Static analysis result - no issues found! ✅

@finger563 finger563 self-assigned this Jun 21, 2026
@finger563 finger563 added enhancement New feature or request at581x labels Jun 21, 2026
@finger563 finger563 merged commit 2082ff9 into main Jun 21, 2026
114 of 115 checks passed
@finger563 finger563 deleted the feat/at581x branch June 21, 2026 22:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

at581x enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant