Merge of fast on functionality

HISTORY.md

@@ -10,6 +10,12 @@
   MQTT light change for dimmers ([Issue #88][I88]).
 
 ### Additions
+- Support for fast on and off commands and reporting has been added.  The
+  on/off mode (normal, fast, instant) is now a command input as well as an
+  output flag in the state templates.  This allows double-clicking of
+  switches to be used in automation triggers (thanks @NickWaterton).
+  ([Issue #66][I66]).
+
 - New command 'get_model' added to the command line tool to retrieve and save
   the Insteon device cat, sub_cat, and firmware revision (thanks @krkeegan).
   ([Issue #55][I55]).
@@ -204,6 +210,7 @@
 [I55]: https://github.com/TD22057/insteon-mqtt/issues/55
 [I59]: https://github.com/TD22057/insteon-mqtt/issues/59
 [I63]: https://github.com/TD22057/insteon-mqtt/issues/63
+[I66]: https://github.com/TD22057/insteon-mqtt/issues/66
 [I69]: https://github.com/TD22057/insteon-mqtt/issues/69
 [I70]: https://github.com/TD22057/insteon-mqtt/issues/70
 [I76]: https://github.com/TD22057/insteon-mqtt/issues/76

README.md

@@ -88,7 +88,6 @@ future enhancements:
 
 - Finish commenting all of the code.
 - Full suite of unit tests.
-- PIP packaging and installation.
 - YAML input configuration validation.
 - Heal network (remove records for missing devices, fix missing links).
 - Modem and device scene management.  Define all the links (scenes) in

config.yaml

@@ -193,14 +193,18 @@ mqtt:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
     #   on = 0/1
-    #   on_str = 'off', 'on'
+    #   on_str = 'off'/'on'
+    #   mode = 'normal'/'fast'/'instant'
+    #   fast = 0/1
+    #   instant = 0/1
     state_topic: 'insteon/{{address}}/state'
     state_payload: '{{on_str.upper()}}'
 
     # Input on/off command.  Similar functionality to the cmd_topic
     # but only for turning the device on and off.  The output of
     # passing the payload through the template must match the following:
-    #   { "cmd" : 'on'/'off', ["instant" : 0/1] }
+    #   { "cmd" : 'on'/'off', ["mode" : 'normal'/'fast'/'instant'],
+    #     ["fast" : 1/0], ["instant" : 1/0] }
     # Available variables for templating are:
     #   value = the input payload
     #   json = the input payload converted to json.  Use json.VAR to extract
@@ -237,17 +241,21 @@ mqtt:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
     #   on = 0/1
-    #   on_str = 'off', 'on'
+    #   on_str = 'off'/'on'
     #   level_255 = 0-255
     #   level_100 = 0-100
+    #   mode = 'normal'/'fast'/'instant'
+    #   fast = 0/1
+    #   instant = 0/1
     state_topic: 'insteon/{{address}}/state'
     state_payload: >
        { "state" : "{{on_str.upper()}}", "brightness" : {{level_255}} }
 
     # Input on/off command.  Similar functionality to the cmd_topic
     # but only for turning the device on and off.  The output of
     # passing the payload through the template must match the following:
-    #   { "cmd" : "on"/"off", ["instant" : 0/1] }
+    #   { "cmd" : "on"/"off", ["mode" : 'normal'/'fast'/'instant'],
+    #     ["fast" : 1/0], ["instant" : 1/0] }
     # Available variables for templating are:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
@@ -260,10 +268,11 @@ mqtt:
     on_off_payload: '{ "cmd" : "{{value.lower()}}" }'
 
     # Input dimming on/off command.  Similar functionality to the cmd_topic
-    # but only for turning the device on and off and setting the
-    # level.  The output of passing the payload through the template
-    # must match the following:
-    #   { "cmd" : "on"/"off", "level" : LEVEL, ["instant" : 0/1] }
+    # but only for turning the device on and off and setting the level.
+    # fast/instant is ignored since that is only for levels 0 or 255.  The
+    # output of passing the payload through the template must match the
+    # following:
+    #   { "cmd" : "on"/"off", "level" : LEVEL, ["is_instant" : 0/1] }
     # where:
     #   LEVEL = 0->255 dimmer level
     # Available variables for templating are:
@@ -311,7 +320,7 @@ mqtt:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
     #   on = 0/1
-    #   on_str = 'off', 'on'
+    #   on_str = 'off'/'on'
     state_topic: 'insteon/{{address}}/state'
     state_payload: '{{on_str.upper()}}'
 
@@ -321,7 +330,7 @@ mqtt:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
     #   is_low = 0/1
-    #   is_low_str = 'off', 'on'
+    #   is_low_str = 'off'/'on'
     low_battery_topic: 'insteon/{{address}}/battery'
     low_battery_payload: '{{is_low_str.upper()}}'
 
@@ -345,10 +354,10 @@ mqtt:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
     #   is_dawn = 0/1
-    #   is_dawn_str = 'off', 'on'
+    #   is_dawn_str = 'off'/'on'
     #   is_dusk = 0/1
-    #   is_dusk_str = 'off', 'on'
-    #   state = 'dawn', 'dusk'
+    #   is_dusk_str = 'off'/'on'
+    #   state = 'dawn'/'dusk'
     dawn_dusk_topic: 'insteon/{{address}}/dawn'
     dawn_dusk_payload: '{{is_dawn_str.upper()}}'
 
@@ -377,10 +386,10 @@ mqtt:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
     #   is_wet = 0/1
-    #   is_wet_str = 'off', 'on'
+    #   is_wet_str = 'off'/'on'
     #   is_dry = 0/1
-    #   is_dry_str = 'off', 'on'
-    #   state = 'wet', 'dry'
+    #   is_dry_str = 'off'/'on'
+    #   state = 'wet'/'dry'
     wet_dry_topic: 'insteon/{{address}}/wet'
     wet_dry_payload: '{{is_wet_str.upper()}}'
 
@@ -422,7 +431,7 @@ mqtt:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
     #   on = 0/1
-    #   on_str = 'off', 'on'
+    #   on_str = 'off'/'on'
     smoke_topic: 'insteon/{{address}}/smoke'
     smoke_payload: '{{on_str.upper()}}'
 
@@ -440,7 +449,7 @@ mqtt:
   #------------------------------------------------------------------------
 
   # The thermostat has a lot of available states and commands
-  # 
+  #
   #
   # In Home Assistant use MQTT climate sensor with a configuration like:
   # climate:
@@ -455,13 +464,13 @@ mqtt:
   # The current Home Assistant mqtt hvac component is not great.  It lacks
   # a lot of functionality offered by the thermostat.  At some point I will
   # submit a PR to Home Assistant to try and fix this.
-  # Major issues: 
+  # Major issues:
   #   - no concept of separate heat and cool set points
   #   - no humidity state
   #   - no status state
-  
+
   thermostat:
-    # Output state change topic and payload.  Available variables for 
+    # Output state change topic and payload.  Available variables for
     # templating in all cases are:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
@@ -470,11 +479,11 @@ mqtt:
     #   temp_c = temperature in celsius
     #   temp_f = temperature in farenheit
     ambient_temp_topic: 'insteon/{{address}}/ambient_temp'
-    ambient_temp_payload: ''{"temp_f" : {{temp_f}}, "temp_c" : {{temp_c}}}''
+    ambient_temp_payload: '{"temp_f" : {{temp_f}}, "temp_c" : {{temp_c}}}'
     cool_sp_state_topic: 'insteon/{{address}}/cool_sp_state'
-    cool_sp_state_payload: ''{"temp_f" : {{temp_f}}, "temp_c" : {{temp_c}}}''
+    cool_sp_state_payload: '{"temp_f" : {{temp_f}}, "temp_c" : {{temp_c}}}'
     heat_sp_state_topic: 'insteon/{{address}}/heat_sp_state'
-    heat_sp_state_payload: ''{"temp_f" : {{temp_f}}, "temp_c" : {{temp_c}}}''
+    heat_sp_state_payload: '{"temp_f" : {{temp_f}}, "temp_c" : {{temp_c}}}'
     #   fan_mode = "ON", "AUTO"
     #   is_fan_on = 0/1
     fan_state_topic: 'insteon/{{address}}/fan_state'
@@ -484,16 +493,16 @@ mqtt:
     mode_state_payload: '{{mode}}'
     #   humid = humidity percentage
     humid_state_topic: 'insteon/{{address}}/humid_state'
-    humid_state_payload: ''{{humid}}''
+    humid_state_payload: '{{humid}}'
     #   status = "OFF", "HEATING", "COOLING"
     #   is_heating = 0/1
     #   is_cooling = 0/1
     status_state_topic: 'insteon/{{address}}/status_state'
-    status_state_payload: ''{{status}}''
-    # Caution, there is no push update for the hold or energy state.  ie, if 
-    # you press hold on the physical device, you will not get any notice of 
-    # this unless you run get_status().  There is also no way to programatically 
-    # change the hold state or energy state 
+    status_state_payload: '{{status}}'
+    # Caution, there is no push update for the hold or energy state.  ie, if
+    # you press hold on the physical device, you will not get any notice of
+    # this unless you run get_status().  There is also no way to programatically
+    # change the hold state or energy state
     #   hold_str = 'OFF', 'TEMP'
     #   is_hold = 0/1
     hold_state_topic: 'insteon/{{address}}/hold_state'
@@ -512,12 +521,12 @@ mqtt:
     #   json = the input payload converted to json.  Use json.VAR to extract
     #          a variable from a json payload.
     #
-    # Mode state command.  The output of passing the payload through the 
+    # Mode state command.  The output of passing the payload through the
     # template must match the following:
     #   { "cmd" : "auto"/"off"/"heat"/"cool","program" }
     mode_command_topic: 'insteon/{{address}}/mode_command'
     mode_command_payload: '{ "cmd" : "{{value.lower()}}" }'
-    # Fan state command.  The output of passing the payload through the 
+    # Fan state command.  The output of passing the payload through the
     # template must match the following:
     #   { "cmd" : "auto"/"on" }
     fan_command_topic: 'insteon/{{address}}/fan_command'
@@ -543,7 +552,10 @@ mqtt:
     #   name = 'device name'
     #   button = 1...n  (button number 1-4 or 1-8)
     #   on = 0/1
-    #   on_str = 'off', 'on'
+    #   on_str = 'off'/'on'
+    #   mode = 'normal'/'fast'/'instant'
+    #   fast = 0/1
+    #   instant = 0/1
     state_topic: 'insteon/{{address}}/state/{{button}}'
     state_payload: '{{on_str.upper()}}'
 
@@ -577,9 +589,9 @@ mqtt:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
     #   on = 0/1
-    #   on_str = 'off', 'on'
-    #   level = 0, 1, 2, 3
-    #   level_str = 'off', 'low', 'medium', 'high'
+    #   on_str = 'off'/'on'
+    #   level = 0/1/2/3
+    #   level_str = 'off'/'low'/'medium'/'high'
     fan_state_topic: 'insteon/{{address}}/fan/state'
     fan_state_payload: '{{on_str.upper()}}'
 
@@ -607,8 +619,8 @@ mqtt:
     # passing the payload through the template must match the following:
     #   { "cmd" : SPEED }
     # where
-    #   SPEED = 0, 1, 2, 3 (for off, low, medium, high)
-    #      or = "off", "low", "medium", "high"
+    #   SPEED = 0/1/2/3 (for off, low, medium, high)
+    #      or = "off"/"low"/"medium"/"high"
     # Available variables for templating are:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
@@ -664,7 +676,10 @@ mqtt:
     #   name = 'device name'
     #   button = 1-8
     #   on = 0/1
-    #   on_str = 'off', 'on'
+    #   on_str = 'off'/'on'
+    #   mode = 'normal'/'fast'/'instant'
+    #   fast = 0/1
+    #   instant = 0/1
     btn_state_topic: 'insteon/{{address}}/state/{{button}}'
     btn_state_payload: '{{on_str.upper()}}'
 
@@ -674,17 +689,22 @@ mqtt:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
     #   on = 0/1
-    #   on_str = 'off', 'on'
+    #   on_str = 'off'/'on'
     #   level_255 = 0-255
     #   level_100 = 0-100
+    #   mode = 'normal'/'fast'/'instant'
+    #   fast = 0/1
+    #   instant = 0/1
     dimmer_state_topic: 'insteon/{{address}}/state/1'
     dimmer_state_payload: >
        { "state" : "{{on_str.upper()}}", "brightness" : {{level_255}} }
 
     # Input on/off command.  For button 1, this will set the load.  For other
     # buttons, it just set the button LED.  The output of passing the payload
     # through the template must match the following:
-    #   { "cmd" : 'on'/'off', "button": button }
+    #   { "cmd" : 'on'/'off', "button": button,
+    #     ["mode" : 'normal'/'fast'/'instant'], ["fast" : 1/0],
+    #     ["instant" : 1/0] }
     # Available variables for templating are:
     #   value = the input payload
     #   json = the input payload converted to json.  Use json.VAR to extract
@@ -695,9 +715,10 @@ mqtt:
     # Input dimming on/off command for button 1.  Similar functionality to
     # the cmd_topic but only for turning the group 1 on and off and setting
     # the level.  This topic can be the same as the btn_on_off_topic in which
-    # case either command format is valid. The output of passing the payload
-    # through the template must match the following:
-    #   { "cmd" : "on"/"off", "level" : LEVEL, ["instant" : 0/1] }
+    # case either command format is valid. fast/instant is ignored since that
+    # is only for levels 0 or 255.  The output of passing the payload through
+    # the template must match the following:
+    #   { "cmd" : "on"/"off", "level" : LEVEL, ["is_instant" : 0/1] }
     # where:
     #   LEVEL = 0->255 dimmer level
     # Available variables for templating are:
@@ -752,7 +773,7 @@ mqtt:
     #   address = 'aa.bb.cc'
     #   name = 'device name'
     #   on = 0/1
-    #   on_str = 'off', 'on'
+    #   on_str = 'off'/'on'
     state_topic: 'insteon/{{address}}/state'
     state_payload: '{{on_str.upper()}}'
 
@@ -800,14 +821,19 @@ mqtt:
     #   name = 'device name'
     #   button = 1 (top outlet) or 2 (bottom outlet)
     #   on = 0/1
-    #   on_str = 'off', 'on'
+    #   on_str = 'off'/'on'
+    #   mode = 'normal'/'fast'/'instant'
+    #   fast = 0/1
+    #   instant = 0/1
     state_topic: 'insteon/{{address}}/state/{{button}}'
     state_payload: '{{on_str.upper()}}'
 
     # Input on/off command.  Similar functionality to the cmd_topic
     # but only for turning the device on and off.  The output of
     # passing the payload through the template must match the following:
-    #   { "cmd" : 'on'/'off', "button": button, ["instant" : 0/1] }
+    #   { "cmd" : 'on'/'off', "button": button,
+    #     ["mode" : 'normal'/'fast'/'instant'], ["fast" : 1/0],
+    #     ["instant" : 1/0] }
     # Available variables for templating are:
     #   value = the input payload
     #   json = the input payload converted to json.  Use json.VAR to extract