Added a much needed notice for capacitive touch setup for some ESP32-… #5692
Conversation
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughExpanded ESP32 touch sensor documentation for S2/S3 variants with explicit tuning starting points for measurement_duration and voltage_attenuation, plus diagnostic guidance when threshold-finding logs show "Event received, mask = 0x10". Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used📓 Path-based instructions (1)**⚙️ CodeRabbit configuration file
Files:
🧠 Learnings (1)📓 Common learnings🪛 LanguageToolcontent/components/binary_sensor/esp32_touch.md[grammar] ~253-~253: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
🔇 Additional comments (3)
Tip 📝 Customizable high-level summaries are now available in beta!You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.
Example instruction:
Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
content/components/binary_sensor/esp32_touch.md (1)
258-271: Example configuration uses outdated timing—consider updating to reflect new guidance.The example YAML at lines 260–264 uses
measurement_duration: 0.25msandsleep_duration: 0.5ms. Given the new guidance recommending0.01msor lower for some ESP32-S3 variants, consider whether this example should be revised to reflect the more aggressive starting point, or clarify in a comment that0.25msis a conservative fallback if0.01msdoes not work.Apply this diff to add clarifying context:
> ```yaml > esp32_touch: > setup_mode: false >- measurement_duration: 0.25ms # Much lower than the 8ms default >- sleep_duration: 0.5ms >+ measurement_duration: 0.25ms # Much lower than the 8ms default; try 0.01ms for some S3 variants >+ sleep_duration: 0.5ms
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
content/components/binary_sensor/esp32_touch.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
- Do not generate or add any sequence diagrams
Files:
content/components/binary_sensor/esp32_touch.md
🧠 Learnings (1)
📓 Common learnings
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
🪛 LanguageTool
content/components/binary_sensor/esp32_touch.md
[grammar] ~253-~253: Ensure spelling is correct
Context: ...ement duration required** - the default 8ms is often too high for S2/S3. > > On so...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build
🔇 Additional comments (1)
content/components/binary_sensor/esp32_touch.md (1)
253-272: Recommended starting-point values lack documented verification across ESP32-S3 variants.The suggested 0.01ms measurement_duration and 1.5V voltage_attenuation are technically feasible per Espressif specifications (1.5V is a standard attenuation option; 0.01ms ≈ 80 charge/discharge cycles at the 8 MHz timer), but official documentation indicates no universal starting values exist. Espressif recommends ~1ms measurement time and emphasizes per-pad, per-hardware tuning in the actual deployment environment due to noise and accuracy trade-offs. ESPHome's own example uses 0.25ms (less aggressive than the suggested 0.01ms). Without documented testing across specific variants (ESP32-S3, ESP32-S3-WROOM, ESP32-S3-MINI), users applying these values risk suboptimal or unstable configurations.
Clarify whether these are empirically validated for the stated variants, and consider linking to Espressif's touch-sensor tuning methodology or noting that these are aggressive starting points requiring adjustment per hardware.
| > On some ESP32-S3 variants, a value of **0.01ms** or lower with the use of **voltage_attenuation: 1.5V** seems a good starting point | ||
| > If you see some `Event received, mask = 0x10` messages during threshold finding, it means the sensor value being read is too high, and you should raise voltage attenuation, or lower the measurement duration. | ||
| > |
There was a problem hiding this comment.
Add missing period and clarify diagnostic guidance.
Line 256 is missing a closing period: "seems a good starting point" should end with a period before the next sentence begins. Additionally, the diagnostic guidance on line 257 could be clearer—the explanation "sensor value being read is too high" may need elaboration. Consider rephrasing to explicitly connect the mask=0x10 event to what it signifies (e.g., "event detected during calibration") and why raising attenuation or lowering measurement duration resolves it.
Apply this diff to fix the punctuation and improve clarity:
- On some ESP32-S3 variants, a value of **0.01ms** or lower with the use of **voltage_attenuation: 1.5V** seems a good starting point
- If you see some `Event received, mask = 0x10` messages during threshold finding, it means the sensor value being read is too high, and you should raise voltage attenuation, or lower the measurement duration.
+ On some ESP32-S3 variants, a value of **0.01ms** or lower with the use of **voltage_attenuation: 1.5V** seems a good starting point.
+ If you see `Event received, mask = 0x10` messages during threshold finding, reduce the measurement duration or increase voltage attenuation to lower the sensor readings.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| > On some ESP32-S3 variants, a value of **0.01ms** or lower with the use of **voltage_attenuation: 1.5V** seems a good starting point | |
| > If you see some `Event received, mask = 0x10` messages during threshold finding, it means the sensor value being read is too high, and you should raise voltage attenuation, or lower the measurement duration. | |
| > | |
| > On some ESP32-S3 variants, a value of **0.01ms** or lower with the use of **voltage_attenuation: 1.5V** seems a good starting point. | |
| > If you see `Event received, mask = 0x10` messages during threshold finding, reduce the measurement duration or increase voltage attenuation to lower the sensor readings. | |
| > |
🤖 Prompt for AI Agents
In content/components/binary_sensor/esp32_touch.md around lines 255 to 257, add
a missing period at the end of the sentence "seems a good starting point." and
reword the diagnostic guidance so it explicitly states that the `Event received,
mask = 0x10` message indicates the touch sensor triggered an event during
threshold calibration because the measured value is too high; instruct the
reader to raise voltage_attenuation (to reduce the measured signal) or shorten
the measurement duration (to lower the measured value) to prevent the
calibration event, and ensure the sentences are punctuated and flow clearly.
2 participants
…S3 variants
Description:
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable):
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/components/index.rstwhen creating new documents for new components or cookbook.New Component Images
If you are adding a new component to ESPHome, you can automatically generate a standardized black and white component name image for the documentation.
To generate a component image:
Comment on this pull request with the following command, replacing
COMPONENT_NAMEwith your component name in UPPER_CASE format with underscores (e.g.,BME280,SHT3X,DALLAS_TEMP):The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.
Extract the SVG file and place it in the
images/folder of this repository.Use the image in your component's index table entry in
/components/index.rst.Example: For a component called "DHT22 Temperature Sensor", use: