Skip to content

CST328 Touchscreen #5188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: next
Choose a base branch
from
Open

CST328 Touchscreen #5188

wants to merge 5 commits into from

Conversation

latonita
Copy link
Contributor

Description:

Related issue (if applicable): fixes esphome/feature-requests#2895

Pull request in esphome with YAML changes (if applicable):

Checklist:

  • I am merging into next because this is new documentation that has a matching pull-request in esphome as linked above.
    or

  • I am merging into current because 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.rst when creating new documents for new components or cookbook.

@Copilot Copilot AI review requested due to automatic review settings July 30, 2025 13:52
esphome[bot]
esphome bot previously requested changes Jul 30, 2025
Copy link

@esphome esphome bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As this is a feature matched with a PR in https://github.com/esphome/esphome, please target your PR to the next branch and rebase.

@esphome esphome bot marked this pull request as draft July 30, 2025 13:53
@esphome
Copy link

esphome bot commented Jul 30, 2025

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

Copy link

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This pull request updates the ESPHome documentation from version 2025.7.4 to 2025.8.0-dev. The changes include several new component additions, documentation improvements, and version updates across multiple files.

  • Addition of CST328 touchscreen controller documentation for Waveshare ESP32-S3 Touch LCD 2.8 board
  • Introduction of new components including NRF52 platform support, runtime statistics, factory reset, and packet transport sensor/binary sensor
  • Enhanced documentation for existing components with new features like MIPI DSI displays, ESP32 variant configuration, and LWIP optimization options

Reviewed Changes

Copilot reviewed 31 out of 36 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
components/touchscreen/cst328.rst Complete documentation for new CST328 touchscreen controller
components/nrf52.rst New platform documentation for NRF52 microcontrollers
components/runtime_stats.rst New debugging component for performance analysis
components/factory_reset.rst New component for device factory reset functionality
components/display/mipi_dsi.rst New display driver documentation for MIPI DSI displays
guides/troubleshooting.rst Added performance troubleshooting section with runtime_stats reference
components/esp32.rst Enhanced documentation with variant-first configuration and LWIP options
components/sensor/index.rst Added throttle_with_priority filter documentation
conf.py Version bump to 2025.8.0-dev
multiple files Various documentation improvements and version updates

Comment on lines 69 to 70
- platform: mipi_dsi
model: WAVESHARE-P4-NANO-10.1
Copy link
Preview

Copilot AI Jul 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The YAML example uses a list syntax for display configuration, but based on the context this should be a single display component, not a list. Remove the dash to make it a single component configuration.

Suggested change
- platform: mipi_dsi
model: WAVESHARE-P4-NANO-10.1
platform: mipi_dsi
model: WAVESHARE-P4-NANO-10.1

Copilot uses AI. Check for mistakes.

Comment on lines 29 to 31
At least one of ``board`` or ``variant`` must be specified. If ``variant`` alone is specified (the recommended practice),
the board configuration will be automatically filled using a standard Espressif devkit board
suitable for that variant. Both may be specified (for backwards compatibility) but they must define the same variant.
Copy link
Preview

Copilot AI Jul 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] The note explains that 'at least one of board or variant must be specified' but the documentation structure suggests variant is now the primary/recommended approach. Consider clarifying that variant is the preferred method and board is maintained for backwards compatibility.

Suggested change
At least one of ``board`` or ``variant`` must be specified. If ``variant`` alone is specified (the recommended practice),
the board configuration will be automatically filled using a standard Espressif devkit board
suitable for that variant. Both may be specified (for backwards compatibility) but they must define the same variant.
At least one of ``board`` or ``variant`` must be specified. ``variant`` is the preferred method for specifying the ESP32 configuration,
as it provides a more streamlined and modern approach. If ``variant`` alone is specified (the recommended practice),
the board configuration will be automatically filled using a standard Espressif devkit board suitable for that variant.
``board`` is maintained for backward compatibility and may be specified alongside ``variant`` if needed, but they must define the same variant.

Copilot uses AI. Check for mistakes.

@latonita latonita changed the base branch from current to next July 30, 2025 13:54
@esphome esphome bot added the next label Jul 30, 2025
@esphome esphome bot dismissed their stale review July 30, 2025 13:54

Base branch has been corrected - dismissing previous review.

Copy link

netlify bot commented Jul 30, 2025

Deploy Preview for esphome ready!

Name Link
🔨 Latest commit f5ffd95
🔍 Latest deploy log https://app.netlify.com/projects/esphome/deploys/688e0c805b713c0008958a9c
😎 Deploy Preview https://deploy-preview-5188--esphome.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copy link
Contributor

coderabbitai bot commented Jul 30, 2025

Caution

Review failed

Failed to post review comments.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ebb2193 and e4d5957.

⛔ Files ignored due to path filters (5)
  • components/sensor/images/airthings_wave_radon.jpg is excluded by !**/*.jpg
  • components/touchscreen/images/cst328.jpg is excluded by !**/*.jpg
  • images/cst328.jpg is excluded by !**/*.jpg
  • images/nrf52.svg is excluded by !**/*.svg
  • images/tab5.jpg is excluded by !**/*.jpg
📒 Files selected for processing (31)
  • Makefile (1 hunks)
  • _static/version (1 hunks)
  • components/api.rst (1 hunks)
  • components/binary_sensor/packet_transport.rst (1 hunks)
  • components/button/factory_reset.rst (1 hunks)
  • components/display/ili9xxx.rst (1 hunks)
  • components/display/mipi_dsi.rst (1 hunks)
  • components/display/mipi_spi.rst (6 hunks)
  • components/display/st7789v.rst (1 hunks)
  • components/esp32.rst (2 hunks)
  • components/esp32_camera.rst (3 hunks)
  • components/factory_reset.rst (1 hunks)
  • components/index.rst (4 hunks)
  • components/nrf52.rst (1 hunks)
  • components/output/index.rst (3 hunks)
  • components/remote_receiver.rst (1 hunks)
  • components/runtime_stats.rst (1 hunks)
  • components/sensor/adc.rst (5 hunks)
  • components/sensor/airthings_ble.rst (1 hunks)
  • components/sensor/index.rst (2 hunks)
  • components/sensor/packet_transport.rst (1 hunks)
  • components/sensor/sensor-filter-throttle_with_priority.rst (1 hunks)
  • components/switch/factory_reset.rst (1 hunks)
  • components/touchscreen/cst328.rst (1 hunks)
  • components/udp.rst (1 hunks)
  • components/wifi.rst (1 hunks)
  • conf.py (1 hunks)
  • cookbook/lambda_magic.rst (0 hunks)
  • guides/installing_esphome.rst (5 hunks)
  • guides/troubleshooting.rst (1 hunks)
  • schema_doc.py (3 hunks)
💤 Files with no reviewable changes (1)
  • cookbook/lambda_magic.rst
🧰 Additional context used
📓 Path-based instructions (1)
**

⚙️ CodeRabbit Configuration File

  • Do not generate or add any sequence diagrams

Files:

  • components/touchscreen/cst328.rst
  • components/output/index.rst
  • components/runtime_stats.rst
  • components/esp32.rst
  • components/api.rst
  • components/udp.rst
  • guides/installing_esphome.rst
  • components/nrf52.rst
  • components/display/mipi_dsi.rst
  • components/remote_receiver.rst
  • components/esp32_camera.rst
  • schema_doc.py
  • components/sensor/airthings_ble.rst
  • Makefile
  • components/sensor/index.rst
  • _static/version
  • components/sensor/packet_transport.rst
  • components/index.rst
  • components/display/st7789v.rst
  • components/display/ili9xxx.rst
  • components/button/factory_reset.rst
  • components/switch/factory_reset.rst
  • components/wifi.rst
  • components/binary_sensor/packet_transport.rst
  • conf.py
  • guides/troubleshooting.rst
  • components/display/mipi_spi.rst
  • components/factory_reset.rst
  • components/sensor/sensor-filter-throttle_with_priority.rst
  • components/sensor/adc.rst
🧠 Learnings (5)
📓 Common learnings
Learnt from: jesserockz
PR: esphome/esphome-docs#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.
components/esp32.rst (1)

Learnt from: jesserockz
PR: #4901
File: changelog/2025.4.0.rst:124-126
Timestamp: 2025-05-12T00:02:50.869Z
Learning: In the ESPHome changelog structure, the "All changes" section should have the :open: attribute to be expanded by default, but the "Dependency Changes" section should NOT have this attribute as it should remain collapsed by default.

guides/installing_esphome.rst (5)

Learnt from: clydebarrow
PR: esphome/esphome-docs#0
File: :0-0
Timestamp: 2025-05-05T05:08:25.575Z
Learning: In ESPHome documentation, leading slashes in doc references are necessary when the source document is not at the root of the tree, as absolute paths to referenced documents are required in this context.

Learnt from: jesserockz
PR: #4901
File: changelog/2025.4.0.rst:124-126
Timestamp: 2025-05-12T00:02:50.869Z
Learning: In the ESPHome changelog structure, the "All changes" section should have the :open: attribute to be expanded by default, but the "Dependency Changes" section should NOT have this attribute as it should remain collapsed by default.

Learnt from: jesserockz
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.

Learnt from: clydebarrow
PR: #4874
File: guides/yaml.rst:324-324
Timestamp: 2025-05-05T05:12:25.536Z
Learning: When reviewing Sphinx documentation in the ESPHome project, leave the leading slashes in doc references (:doc:/path) intact, as they provide absolute paths which are required when the source document is not at the root of the tree.

Learnt from: trip5
PR: #4411
File: guides/beginners_guide_docker_desktop.rst:76-81
Timestamp: 2024-11-04T17:44:47.417Z
Learning: In the 'Beginner's Guide to Installing ESPHome on Docker Desktop' (guides/beginners_guide_docker_desktop.rst), when using Docker Desktop on Windows, it's unnecessary to add memory limits to the container, as Windows already handles resource limiting.

Makefile (3)

Learnt from: jesserockz
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.

Learnt from: clydebarrow
PR: esphome/esphome-docs#0
File: :0-0
Timestamp: 2025-05-05T05:08:25.575Z
Learning: In ESPHome documentation, leading slashes in doc references are necessary when the source document is not at the root of the tree, as absolute paths to referenced documents are required in this context.

Learnt from: clydebarrow
PR: #4874
File: guides/yaml.rst:324-324
Timestamp: 2025-05-05T05:12:25.536Z
Learning: When reviewing Sphinx documentation in the ESPHome project, leave the leading slashes in doc references (:doc:/path) intact, as they provide absolute paths which are required when the source document is not at the root of the tree.

components/index.rst (1)

Learnt from: jesserockz
PR: #4901
File: changelog/2025.4.0.rst:124-126
Timestamp: 2025-05-12T00:02:50.869Z
Learning: In the ESPHome changelog structure, the "All changes" section should have the :open: attribute to be expanded by default, but the "Dependency Changes" section should NOT have this attribute as it should remain collapsed by default.

🔇 Additional comments (28)
components/esp32_camera.rst (3)

488-497: I²C bus block looks good

The switch to an explicit i2c declaration plus i2c_id is clear and consistent with the updated style. No further comments.


502-502: Explicitly showcasing frame_buffer_location in the example is useful

Including frame_buffer_location: DRAM right after introducing the option is a helpful cue for users.


535-544: Example updated correctly for Waveshare board

The dedicated I²C bus and matching i2c_id make the snippet copy-paste friendly. Looks good.

components/output/index.rst (2)

104-111: Addition looks good

Explicitly listing ac_dimmer here improves discoverability and keeps the platform list up-to-date. No further action needed.


129-189: Verify cross-referencing for the new actions

Great to see runtime tuning for min_power/max_power. Ensure these anchors are linked from any autogenerated “Actions” index (e.g. actions.rst) so users can navigate to them directly via the sidebar search.

If the global actions index is generated manually, add:

* :ref:`output-set_min_power_action`
* :ref:`output-set_max_power_action`

otherwise the anchors risk being “orphaned” and harder to discover.

components/sensor/index.rst (1)

217-218: Include looks good – alphabetical order preserved

.. include:: sensor-filter-throttle_with_priority.rst is inserted right after the other throttle-family filters and before timeout, which keeps the list alphabetically ordered. No action needed.

components/udp.rst (1)

40-41: LGTM! Good documentation formatting improvement.

The addition of code formatting to the action name enhances readability and aligns with ESPHome documentation standards.

components/binary_sensor/packet_transport.rst (1)

30-31: LGTM! Documentation formatting consistency improvement.

Adding the colon to the section header improves consistency across ESPHome documentation files.

components/sensor/packet_transport.rst (1)

23-24: LGTM! Consistent documentation formatting.

This formatting change aligns with the improvements made across related packet transport documentation files.

schema_doc.py (3)

153-155: LGTM! Proper schema configuration for packet transport component.

The new entry follows the established pattern in CUSTOM_DOCS and correctly maps the "Packet Transport Component" documentation to its schema definition.


766-779: LGTM! Improved error handling for schema generation.

The addition of the fail_silently parameter enhances the robustness of the schema generation process by allowing graceful handling of property lookup failures while preserving existing properties.


844-844: LGTM! Consistent usage of enhanced error handling.

The call to find_props_previous_title(True) properly utilizes the new fail_silently parameter to suppress errors during property lookup fallback.

guides/troubleshooting.rst (1)

115-126: Solid addition – headline length matches underline, links resolve

The new section integrates cleanly and drives readers to the right tool. No issues spotted.

_static/version (1)

1-1: Version bump looks correct

Document version advanced to 2025.8.0-dev, matching the dev cycle noted elsewhere. No further action required.

components/remote_receiver.rst (1)

83-90: Double-check max-idle constants (off-by-one risk).

65536us looks suspicious for a 16-bit counter – most RMT regs saturate at 0xFFFF (65535).
Please confirm with the SDK header or reduce the literal by 1 to avoid an out-of-range recommendation.

Makefile (1)

2-2: Lock ESPHOME_REF to a fixed commit for reproducible builds

Using ESPHOME_REF = dev always pulls the tip of esphome/dev, so historical builds can change over time. Pin this to the commit that introduced CST328 support—for example:

- ESPHOME_REF = dev
+ ESPHOME_REF = <COMMIT_SHA>   # dev as of 2025-07-14

• File: Makefile (line 2)
• Replace <COMMIT_SHA> with the actual SHA (e.g., 4c2f1e3) and update it periodically as new features land.

Please verify and supply the correct commit SHA for CST328 support to ensure deterministic docs builds.

components/button/factory_reset.rst (1)

43-43: Good addition – cross-link improves discoverability.

components/switch/factory_reset.rst (1)

43-43: Good addition – cross-link improves discoverability.

components/display/ili9xxx.rst (1)

44-48: Cross-reference anchor might be wrong

:ref:mipi_spiassumes that the target document defines an explicit.. _mipi_spi:anchor. If the anchor in *components/display/mipi_spi.rst* is different (for example.. _display_mipi_spi:``) the link will break at build time.

Please verify the actual anchor name and adjust if needed:

-This component has been made redundant since this class of displays is now supported by the :ref:`mipi_spi`.
+This component has been made redundant since this class of displays is now supported by the :ref:`mipi_spi`.

(no change needed if the anchor really is mipi_spi).

conf.py (1)

74-76: Version bump looks consistent

The short version and long release strings were bumped together – no issues spotted.

components/display/st7789v.rst (1)

30-32: Good deprecation notice

Clear warning + migration hint – nicely done.

Also applies to: 38-38

components/index.rst (3)

86-87: Factory Reset component link looks good

Entry, icon and path are consistent – no further action.


763-764: Verify new “MIPI DSI Displays” documentation exists

Broken link here would hide the new docs from the site navigation.
Please run a quick linkcheck to confirm components/display/mipi_dsi.rst is present.


1064-1065: CST328 successfully added to touchscreen list

Looks correct and alphabetically placed.

components/factory_reset.rst (1)

16-21: Good safety emphasis – the warning block is clear and well-placed.

components/display/mipi_spi.rst (1)

162-181: Great explanation of buffer–performance trade-off – this section adds the necessary depth without overwhelming the reader.

components/display/mipi_dsi.rst (2)

105-106: Default of pclk_inverted is surprising

You state “default is True”; most options default to false when the feature is off. Confirm that the code really treats the absence of the key as true, and explicitly mention the rationale (DSI spec?).


124-136: Section is crystal-clear – nice, concise example and caveats.

Walkthrough

This update introduces documentation and configuration support for the CST328 touchscreen controller, specifically targeting the Waveshare ESP32-S3 Touch LCD 2.8 board. A new documentation file for the CST328 is added, and the component index is updated to reflect this addition. No code or API changes are present.

Changes

Cohort / File(s) Change Summary
CST328 Touchscreen Documentation
components/touchscreen/cst328.rst
New documentation file for CST328 touchscreen controller, including configuration, usage, and example for Waveshare ESP32-S3 Touch LCD 2.8.
Component Index Update
components/index.rst
Adds CST328 touchscreen to the list of supported components in the documentation index.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Assessment against linked issues

Objective Addressed Explanation
Add documentation and configuration support for CST328 touchscreen controller (Issue #2895)

Assessment against linked issues: Out-of-scope changes

No out-of-scope changes found.

Possibly related PRs

Suggested labels

has-parent, next

Suggested reviewers

  • jesserockz
  • clydebarrow

Note

⚡️ Unit Test Generation is now available in beta!

Learn more here, or try it out under "Finishing Touches" below.

✨ Finishing Touches
  • 📝 Generate Docstrings
🧪 Generate unit tests
  • Create PR with unit tests
  • Post copyable unit tests in a comment

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.

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Explain this complex logic.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai explain this code block.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and explain its main purpose.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @coderabbitai generate unit tests to generate unit tests for this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

@latonita latonita marked this pull request as ready for review August 3, 2025 10:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Touch controller CST328
1 participant