From bbfc6ac654fb5be56c8a2f6b8cdbcdc09e724e10 Mon Sep 17 00:00:00 2001 From: raman325 <7243222+raman325@users.noreply.github.com> Date: Thu, 25 Mar 2021 00:59:56 -0400 Subject: [PATCH 1/6] Add entity doc for siren platform --- docs/core/entity/siren.md | 87 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/core/entity/siren.md diff --git a/docs/core/entity/siren.md b/docs/core/entity/siren.md new file mode 100644 index 00000000..e2b46bc4 --- /dev/null +++ b/docs/core/entity/siren.md @@ -0,0 +1,87 @@ +--- +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. + +| Name | Type | Default | Description | +| ----------------------- | ------ | ------------------------------------- | --------------------------------------------------------------------------------------- | +| volume_level | float | `None` | The volume level for the device. | +| active_tone | string | `NotImplementedError()` | The active tone for the device. Requires `SUPPORT_TONES`. | +| available_tones | list | `NotImplementedError()` | The available tones for the device. Requires `SUPPORT_TONES`. | +| 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. | +| `SUPPORT_VOLUME_SET` | The device supports setting the volume level of the device. | + + +## Methods + +### Set volume level + +```python +class MySirenEntity(SirenEntity): + # Implement one of these methods. + + def set_volume_level(self, volume_level: float): + """Set new volume level.""" + + async def async_set_volume_level(self, volume_level: float): + """Set new volume level.""" +``` + +### Set active tone + +This should only be implemented if the tone can be changed. + +```python +class MySirenEntity(SirenEntity): + # Implement one of these methods. + + def set_active_tone(self, tone: str): + """Set new active tone.""" + + async def async_set_active_tone(self, tone: str): + """Set new active tone.""" +``` + +### Turn on + +```python +class MySirenEntity(SirenEntity): + # Implement one of these methods. + + def turn_on(self, **kwargs): + """Turn the device on.""" + + async def async_turn_on(self, **kwargs): + """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.""" +``` From 70d5b265c7a9e553a353b22e274e5a7559d88ec4 Mon Sep 17 00:00:00 2001 From: raman325 <7243222+raman325@users.noreply.github.com> Date: Fri, 25 Jun 2021 18:14:35 -0400 Subject: [PATCH 2/6] Update docs based on core PR review and changes --- docs/core/entity/siren.md | 40 +++++---------------------------------- 1 file changed, 5 insertions(+), 35 deletions(-) diff --git a/docs/core/entity/siren.md b/docs/core/entity/siren.md index e2b46bc4..ba45757b 100644 --- a/docs/core/entity/siren.md +++ b/docs/core/entity/siren.md @@ -11,9 +11,6 @@ A siren entity is a device whose main purpose is to control siren devices like a | Name | Type | Default | Description | | ----------------------- | ------ | ------------------------------------- | --------------------------------------------------------------------------------------- | -| volume_level | float | `None` | The volume level for the device. | -| active_tone | string | `NotImplementedError()` | The active tone for the device. Requires `SUPPORT_TONES`. | -| available_tones | list | `NotImplementedError()` | The available tones for the device. Requires `SUPPORT_TONES`. | | is_on | bool | `NotImplementedError()` | Whether the device is on or off. | ### Tones @@ -24,42 +21,15 @@ A device can have different tones that are played. Integrations are responsible Supported features constants are combined using the bitwise or (`|`) operator. -| Name | Description | -| ------------------------- | -------------------------------------------------------------- | -| `SUPPORT_TONES` | The device supports different tones. | -| `SUPPORT_VOLUME_SET` | The device supports setting the volume level of the device. | +| 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). | ## Methods -### Set volume level - -```python -class MySirenEntity(SirenEntity): - # Implement one of these methods. - - def set_volume_level(self, volume_level: float): - """Set new volume level.""" - - async def async_set_volume_level(self, volume_level: float): - """Set new volume level.""" -``` - -### Set active tone - -This should only be implemented if the tone can be changed. - -```python -class MySirenEntity(SirenEntity): - # Implement one of these methods. - - def set_active_tone(self, tone: str): - """Set new active tone.""" - - async def async_set_active_tone(self, tone: str): - """Set new active tone.""" -``` - ### Turn on ```python From 5b10caccd5d827f742d4aa1763633bf9b7b5efdb Mon Sep 17 00:00:00 2001 From: raman325 <7243222+raman325@users.noreply.github.com> Date: Sun, 4 Jul 2021 12:28:15 -0400 Subject: [PATCH 3/6] Update docs to explain the turn_on service functionality better --- docs/core/entity/siren.md | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/core/entity/siren.md b/docs/core/entity/siren.md index ba45757b..345c557c 100644 --- a/docs/core/entity/siren.md +++ b/docs/core/entity/siren.md @@ -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.""" ``` From 553150b8740d30587228090f6a2ce7e440d49600 Mon Sep 17 00:00:00 2001 From: raman325 <7243222+raman325@users.noreply.github.com> Date: Wed, 7 Jul 2021 00:16:43 -0400 Subject: [PATCH 4/6] feedback --- docs/core/entity/siren.md | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/docs/core/entity/siren.md b/docs/core/entity/siren.md index 345c557c..1db8c2a6 100644 --- a/docs/core/entity/siren.md +++ b/docs/core/entity/siren.md @@ -42,28 +42,14 @@ Each input parameter is gated by a supported feature flag. If the corresponding - `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, - tone: int | str = None, - duration: int = None, - volume_level: float = None, - **kwargs - ) -> None: + def turn_on(self, **kwargs) -> None: """Turn the device on.""" - async def async_turn_on( - self, - tone: int | str = None, - duration: int = None, - volume_level: float = None, - **kwargs - ) -> None: + async def async_turn_on(self, **kwargs) -> None: """Turn the device on.""" ``` From 2cef84ae810051b1ea4f1809f8aa9d325b21d9a5 Mon Sep 17 00:00:00 2001 From: raman325 <7243222+raman325@users.noreply.github.com> Date: Wed, 7 Jul 2021 00:17:46 -0400 Subject: [PATCH 5/6] Add siren to sidebar --- sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.js b/sidebars.js index 6f318484..be72054b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -160,6 +160,7 @@ module.exports = { "core/entity/number", "core/entity/remote", "core/entity/sensor", + "core/entity/siren", "core/entity/switch", "core/entity/vacuum", "core/entity/water-heater", From 565a8efc11434a4f1ea204a07711f39e4714d5a8 Mon Sep 17 00:00:00 2001 From: raman325 <7243222+raman325@users.noreply.github.com> Date: Wed, 7 Jul 2021 00:21:38 -0400 Subject: [PATCH 6/6] improve formatting --- docs/core/entity/siren.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/core/entity/siren.md b/docs/core/entity/siren.md index 1db8c2a6..416d4610 100644 --- a/docs/core/entity/siren.md +++ b/docs/core/entity/siren.md @@ -32,15 +32,13 @@ Supported features constants are combined using the bitwise or (`|`) operator. ### 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` +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. -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` +| 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):