From 9f7ec54d321fabfeb3b735789eebece43c60f64f Mon Sep 17 00:00:00 2001 From: Daniel Mason Date: Fri, 4 Sep 2020 12:21:52 +0800 Subject: [PATCH] feat!: rename stay mode to make the feature easier to understand (#176) (#177) BREAKING CHANGE: Check the docs for new `stay_mode` configuration field and the name changes to the related services. --- README.md | 33 ++++++------------- .../entity_controller/__init__.py | 6 ++-- custom_components/entity_controller/const.py | 4 +-- .../entity_controller/entity_services.py | 20 +++++------ 4 files changed, 23 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 3d52f9a..ec8a2c7 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,7 @@ Maintaining and improving this integration is very time consuming because of the [![donate gofundme](https://img.shields.io/badge/donate-GoFundMe-orange?style=flat-square)](https://gf.me/u/w62k93) # :boom: Recent Breaking Changes :boom: +* `v7.0.0` The configuration entry for stay mode was renamed from `stay` to `stay_mode`. Entity services have been renamed as well for consistency (see docs) [PR #176](https://github.com/danobot/entity-controller/pull/176), [Issue #143](https://github.com/danobot/entity-controller/issues/143). * `v6.0.0` introduces a breaking change if you are relying on the entities `friendly_name` in other automations. See [#153](https://github.com/danobot/entity-controller/pull/153). The release PR is [#156](https://github.com/danobot/entity-controller/pull/156). # Features @@ -128,14 +129,14 @@ motion_light_sun: end_time: sunrise + 00:30:00 # required ``` -# Stay on -This simple option will keep EC in **active_stay_on** state indefinitely until the control entity is manually turned off. +# Stay Mode +This simple option will make EC give up control of entities after the initial trigger. EC will stay in `active_stay_on` state state indefinitely until the control entity is manually turned off. ```yaml override_example: sensor: binary_sensor.lounge_motion entity: light.lounge_lamp delay: 5 - stay: true + stay_mode: on ``` ### Overrides @@ -354,7 +355,7 @@ motion_light: ``` ### Block Mode Time Restriction -When `block_timeout` is defined, the controller will start a timer when the sensor is triggered and exit `blocked` state once the timeout is reached, thereby restricting the time that a controller can stay `blocked` mode. This is useful when you want the controller to turn off a light that was turned on manually. +When `block_timeout` is defined, the controller will start a timer when the sensor is triggered and exit `blocked` state once the timeout is reached, thereby restricting the time that a controller can remain in `blocked` mode. This is useful when you want the controller to turn off a light that was turned on manually. The state sequence is as follows: @@ -440,21 +441,21 @@ mtn_lounge: The entity controller support a few services that can be used to extend the customization of the entity. -#### Stay +#### Stay Mode ```yaml -service: entity_controller.set_stay_on +service: entity_controller.enable_stay_mode entity_id: entity_controller.motion ``` -This service takes an entity id and will set the stay flag to on +This service takes an entity id and will enable stay mode which means that control entities will not be turned off once EC is triggered. All control entities must be manually turned off (or via other automations) before EC will return to `idle` state. ```yaml -service: entity_controller.set_stay_off +service: entity_controller.disable_stay_mode entity_id: entity_controller.motion ``` -This service takes an entity id and will clear the stay flag. +This service takes an entity id and will disable stay mode. This does not transition EC to `idle` state if it is already in `active_stay_on` state. In this case you must turn off all entities manually. **Note:** There is no attribute that exposes the stay flag state at this time. @@ -526,20 +527,6 @@ self.OVERRIDE_OFF_STATE = config.get("override_states_off", DEFAULT_OFF) self.STATE_ON_STATE = config.get("state_states_on", DEFAULT_ON) self.STATE_OFF_STATE = config.get("state_states_off", DEFAULT_OFF) ``` -### Drawing State Machine Diagrams (not supported yet in `v2`) - -You can generate state machine diagrams that update based on the state of the motion light. These produce a file in the file system that can be targeted by `file` based cameras. -```yaml -diagram_test: - sensors: - - binary_sensor.motion_detected - entities: - - light.tv_led - draw: True # required, default is False - image_path: '/conf/temp' # optional, default shown - image_prefix: '/fsm_diagram_' # optional, default shown - -``` ### Customize which attribute changes are considered "manual control" diff --git a/custom_components/entity_controller/__init__.py b/custom_components/entity_controller/__init__.py index 06700b4..7848087 100644 --- a/custom_components/entity_controller/__init__.py +++ b/custom_components/entity_controller/__init__.py @@ -353,8 +353,8 @@ async def async_setup(hass, config): class EntityController(entity.Entity): from .entity_services import ( async_entity_service_clear_block as async_clear_block, - async_entitiy_service_set_stay_on as async_set_stay_on, - async_entitiy_service_set_stay_off as async_set_stay_off, + async_entity_service_enable_stay_mode as async_enable_stay_mode, + async_entity_service_disable_stay_mode as async_disable_stay_mode, async_entity_service_set_night_mode as async_set_night_mode, ) @@ -1083,7 +1083,7 @@ def config_other(self, config): self.image_prefix = config.get("image_prefix", "/fsm_diagram_") self.image_path = config.get("image_path", "/conf/temp") self.backoff = config.get("backoff", False) - self.stay = config.get("stay", False) + self.stay = config.get("stay_mode", False) if self.backoff: self.log.debug("config_other :: setting up backoff. Using delay as initial backoff value.") diff --git a/custom_components/entity_controller/const.py b/custom_components/entity_controller/const.py index bdab5ff..b51043e 100644 --- a/custom_components/entity_controller/const.py +++ b/custom_components/entity_controller/const.py @@ -21,8 +21,8 @@ # services SERVICE_CLEAR_BLOCK = "clear_block" -SERVICE_SET_STAY_ON = "set_stay_on" -SERVICE_SET_STAY_OFF = "set_stay_off" +SERVICE_ENABLE_STAY_MODE = "enable_stay_mode" +SERVICE_DISABLE_STAY_MODE = "disable_stay_mode" SERVICE_SET_NIGHT_MODE = "set_night_mode" #configuration diff --git a/custom_components/entity_controller/entity_services.py b/custom_components/entity_controller/entity_services.py index 65940b0..b730a48 100644 --- a/custom_components/entity_controller/entity_services.py +++ b/custom_components/entity_controller/entity_services.py @@ -35,8 +35,8 @@ from .const import ( SERVICE_CLEAR_BLOCK, - SERVICE_SET_STAY_ON, - SERVICE_SET_STAY_OFF, + SERVICE_ENABLE_STAY_MODE, + SERVICE_DISABLE_STAY_MODE, SERVICE_SET_NIGHT_MODE, CONF_START_TIME, CONF_END_TIME, @@ -49,8 +49,8 @@ def async_setup_entity_services(component: EntityComponent): component.logger.debug("Setting up entity services") component.async_register_entity_service(SERVICE_CLEAR_BLOCK, {}, "async_clear_block") - component.async_register_entity_service(SERVICE_SET_STAY_ON, {}, "async_set_stay_on") - component.async_register_entity_service(SERVICE_SET_STAY_OFF, {}, "async_set_stay_off") + component.async_register_entity_service(SERVICE_ENABLE_STAY_MODE, {}, "async_enable_stay_mode") + component.async_register_entity_service(SERVICE_DISABLE_STAY_MODE, {}, "async_disable_stay_mode") component.async_register_entity_service( SERVICE_SET_NIGHT_MODE, { vol.Optional(CONF_START_TIME): cv.string, vol.Optional(CONF_END_TIME): cv.string }, @@ -67,16 +67,12 @@ def async_entity_service_clear_block(self): self.model.log.debug("Clearing Blocked state") self.model.block_timer_expires() -def async_entitiy_service_set_stay_on(self): - """ Changes the stay attribute with a custom value """ - - self.model.log.debug("Changing stay to on") +def async_entity_service_enable_stay_mode(self): + self.model.log.debug("Enable stay mode - Control entities will remain on until manually turned off") self.model.stay = True -def async_entitiy_service_set_stay_off(self): - """ Changes the stay attribute with a custom value """ - - self.model.log.debug("Changing stay to off") +def async_entity_service_disable_stay_mode(self): + self.model.log.debug("Disable stay mode - Control entities will be managed by EC") self.model.stay = False def async_entity_service_set_night_mode(self, start_time=None, end_time=None):