jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-27 03:06:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update docs to explain the turn_on service functionality better

Browse Source
This commit is contained in:
raman325 2021-07-04 12:28:15 -04:00
parent 70d5b265c7
commit 5b10caccd5
No known key found for this signature in database
GPG Key ID: E5FA2EFBCAB83CB7
1 changed files with 30 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/core/entity/siren.md
View File

@ -7,7 +7,7 @@ A siren entity is a device whose main purpose is to control siren devices like a
## Properties
> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
> Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data or build a mechanism to push state updates to the entity class instance.
| Name | Type | Default | Description |
| ----------------------- | ------ | ------------------------------------- | --------------------------------------------------------------------------------------- |
@ -23,23 +23,47 @@ Supported features constants are combined using the bitwise or (`|`) operator.
| Name | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `SUPPORT_TONES` | The device supports different tones (the tone is passed in to `turn_on` service). |
| `SUPPORT_VOLUME_SET` | The device supports setting the volume level of the device (the volume level is passed in to `turn_on` service). |
| `SUPPORT_DURATION` | The device supports setting a duration for the tone (the duration is passed in to `turn_on` service). |
| `SUPPORT_TONES` | The device supports different tones (the tone can be passed in to `turn_on` service). |
| `SUPPORT_DURATION` | The device supports setting a duration for the tone (the duration can be passed in to `turn_on` service). |
| `SUPPORT_VOLUME_SET` | The device supports setting the volume level of the device (the volume level can be passed in to `turn_on` service). |
## Methods
### Turn on
There are three optional input parameters that can be passed into the service call:
- `tone`: `vol.Any(vol.Coerce(int), cv.string)`
- `duration`: `cv.positive_int`
- `volume_level`: `cv.small_float`
Each input parameter is gated by a supported feature flag. If the corresponding flag isn't set when a given input parameter is provided in the service call, it will be filtered out from the service call by the base platform before being passed to the integration. The input parameter to supported feature flag is as follows:
- `tone`: `SUPPORT_TONES`
- `duration`: `SUPPORT_DURATIONS`
- `volume_level`: `SUPPORT_VOLUME_SET`
Only include the parameters that your integration supports in your turn on function definition as the rest will always be `None`
```python
class MySirenEntity(SirenEntity):
# Implement one of these methods.
def turn_on(self, **kwargs):
def turn_on(
self,
tone: int | str = None,
duration: int = None,
volume_level: float = None,
**kwargs
) -> None:
"""Turn the device on."""
async def async_turn_on(self, **kwargs):
async def async_turn_on(
self,
tone: int | str = None,
duration: int = None,
volume_level: float = None,
**kwargs
) -> None:
"""Turn the device on."""
```