From ca4ea0f652ad72e59a8215604bf8d37de5b06382 Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Sat, 22 Jul 2023 17:56:12 +0200 Subject: [PATCH] Add scene entity developer documentation (#1850) --- docs/core/entity/scene.md | 41 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/core/entity/scene.md diff --git a/docs/core/entity/scene.md b/docs/core/entity/scene.md new file mode 100644 index 00000000..956f3aaf --- /dev/null +++ b/docs/core/entity/scene.md @@ -0,0 +1,41 @@ +--- +title: Scene Entity +sidebar_label: Scene +--- + +A scene entity is an entity that [can reproduce a wanted state](/docs/core/platform/reproduce_state/) for a group of entities. A scene entity can activate the scene towards a group of devices but remains stateless from the Home Assistant perspective. + +A scene entity is derived from [`homeassistant.components.scene.Scene`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/scene/__init__.py). + +If you want to represent something that can be turned on and off (and thus have an actual state), you should use a `switch` entity instead. + +Scene entities can also [be created by the user via the Scene editor or YAML](https://www.home-assistant.io/integrations/scene). + +## Properties + +As this integration is stateless, it doesn't provide any specific properties for itself. +Other properties that are common to all entities such as `icon` and `name` etc are still applicable. + +## Methods + +### Activate + +Activate the scene. + +```python +class MySwitch(Scene): + # Implement one of these methods. + + def activate(self, **kwargs: Any) -> None: + """Activate scene. Try to get entities into requested state.""" + + async def async_activate(self, **kwargs: Any) -> None: + """Activate scene. Try to get entities into requested state.""" +``` + +The activate method can be used to activate the scene towards a device or service. +It is called by Home Assistant when the user presses the scene `activate` button or when the `scene.turn_on` service is called to activate the scene. + +### Available device classes + +There are no specific device classes. The `device_class` attribute is not set on the scene entity.