Merge pull request #865 from raman325/siren

Add entity doc for siren platform
This commit is contained in:
Charles Garwood 2021-07-11 19:51:10 -04:00 committed by GitHub
commit 395f1e0fa3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 66 additions and 0 deletions

65
docs/core/entity/siren.md Normal file
View File

@ -0,0 +1,65 @@
---
title: Siren Entity
sidebar_label: Siren
---
A siren entity is a device whose main purpose is to control siren devices like a doorbell or chime. Derive entity platforms from [`homeassistant.components.siren.SirenEntity`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/siren/__init__.py)
## 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 or build a mechanism to push state updates to the entity class instance.
| Name | Type | Default | Description |
| ----------------------- | ------ | ------------------------------------- | --------------------------------------------------------------------------------------- |
| is_on | bool | `NotImplementedError()` | Whether the device is on or off. |
### Tones
A device can have different tones that are played. Integrations are responsible for providing the available tones when supported.
### Supported features
Supported features constants are combined using the bitwise or (`|`) operator.
| Name | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `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, each 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.
| Parameter Name | Data Validation | Supported Feature Flag |
|---------------- |--------------------------------------- |------------------------ |
| `tone` | `vol.Any(vol.Coerce(int), cv.string)` | `SUPPORT_TONES` |
| `duration` | `cv.positive_int` | `SUPPORT_DURATIONS` |
| `volume_level` | `cv.small_float` | `SUPPORT_VOLUME_SET` |
```python
class MySirenEntity(SirenEntity):
# Implement one of these methods.
def turn_on(self, **kwargs) -> None:
"""Turn the device on."""
async def async_turn_on(self, **kwargs) -> None:
"""Turn the device on."""
```
### Turn off
```python
class MySirenEntity(SirenEntity):
# Implement one of these methods.
def turn_off(self, **kwargs):
"""Turn the device off."""
async def async_turn_off(self, **kwargs):
"""Turn the device off."""
```

View File

@ -163,6 +163,7 @@ module.exports = {
"core/entity/remote",
"core/entity/select",
"core/entity/sensor",
"core/entity/siren",
"core/entity/switch",
"core/entity/vacuum",
"core/entity/water-heater",