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.

Author: danobot

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"
 

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.")

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

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):