[switch] Add control() method to API

[edwardtfn]

Description:

This is a copy of #5214, but in the new format.
That one should have been merged when esphome/esphome#10118 was merged, but for some reason it was missed.

Related issue (if applicable): N/A

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

• [switch] Add control() method to API esphome#10118 (already merged)

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.

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:

1. Comment on this pull request with the following command, replacing COMPONENT_NAME with your component name in UPPER_CASE format with underscores (e.g., BME280, SHT3X, DALLAS_TEMP):

   @esphomebot generate image COMPONENT_NAME
   

2. The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.

3. Extract the SVG file and place it in the images/ folder of this repository.

4. Use the image in your component's index table entry in /components/index.rst.

Example: For a component called "DHT22 Temperature Sensor", use:

@esphomebot generate image DHT22

[esphome]

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]

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.

Stale

[netlify]

✅ Deploy Preview for esphome ready!

Name	Link
🔨 Latest commit	5d5ea32
🔍 Latest deploy log	https://app.netlify.com/projects/esphome/deploys/68f712a31c2c320008bb16dc
😎 Deploy Preview	https://deploy-preview-5506--esphome.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[coderabbitai]

Walkthrough

Documentation for the switch component is updated to introduce and describe the switch.control API, a unified boolean-based control method. Examples and guidance sections are updated to include control() alongside existing turn_on, turn_off, and toggle methods.

Changes

Cohort / File(s)	Summary
Switch component documentation content/components/switch/_index.md	Adds switch.control API documentation with configuration parameters (id, state), usage examples, and updates existing sections (publish_state example, lambda calls) to reference the new control method as an alternative to traditional on/off/toggle operations

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "[switch] Add control() method to API" is concise, clear, and directly related to the changeset. It accurately summarizes the main objective of the pull request, which is to add documentation for a new control() method in the switch component API. The title uses appropriate formatting with the component name in brackets and a descriptive action phrase, making it easy for teammates reviewing the commit history to understand the primary change.
Description Check	✅ Passed	The description is related to the changeset and provides relevant context about the pull request. It explains that this documentation update corresponds to a feature that was already merged in the main esphome repository (esphome/esphome#10118) but was missed in the documentation repository, and references the original PR #5214. While the description could include more details about what the control() method does, the check is lenient and only requires that the description be related in some way to the changeset, which it clearly is.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6ed85f2 and 5d5ea32.

📒 Files selected for processing (1)

• content/components/switch/_index.md (2 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

• Do not generate or add any sequence diagrams

Files:

• content/components/switch/_index.md

🔇 Additional comments (3)

content/components/switch/_index.md (3)

118-143: Well-structured addition of switch.control action documentation.

The new section is clearly written, follows the established pattern of other action sections (e.g., turn_on, turn_off), and includes both simple and templatable examples. Configuration variables are properly documented with required/optional status and types. The section integrates seamlessly with the existing documentation.

---

177-185: Correctly updates the note to include control() method.

The update to line 185 appropriately adds control() to the list of methods that manipulate actual switch state. The change maintains grammatical correctness and clarity within the NOTE block.

---

209-217: Clear and practical lambda method documentation for control().

The new documentation for the control() lambda method is well-integrated into the existing lambda calls section. The description clearly conveys the method's purpose, and the three examples progress logically from simple boolean calls to conditional usage, effectively demonstrating the method's flexibility. The formatting is consistent with surrounding lambda method documentation.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}