Add support for Frequency variable in AddChangeHandler (#1853)

* add support for frequency variable in AddChangeHandler

* bl0942 frequency variable rounding correction

* move frequency to last args for VCPPublishThreshold

* frequency selftest precision adjustments

---------

Co-authored-by: kcstonacek <[email protected]>

Author: kcstonacek

docs/commandExamples.md

@@ -27,6 +27,11 @@ This will create a new repeating events with 1 repeat count and 60 seconds delay
 
 
 
+This will Change Handler will turn off Channel 1 if the BL0XXX driver's Frequency is over 52.95hz
+<br>```addChangeHandler Frequncy > 5295 setChannel 1 0```<br>
+
+
+
 This is another approach to sending GET for change. As you can see, it's using addEventHandler instead of addChangeHandler. This will fire with every change. The index 1 here is a channel index. The $CH1 macro in URL will get expended to current channel value, usually 1 or 0
 <br>```addEventHandler OnChannelChange 1 http://192.168.0.112/cm?cmnd=Power0%20$CH1```<br>
 

docs/commands-extended.md

@@ -8,8 +8,8 @@ Do not add anything here, as it will overwritten with next rebuild.
 | AB_Map | [int] | Sets margines for ADC button codes. For given N margins, there are N+1 possible ADC button values (one should be reserved for 'no button').<br/><br/>See also [AB_Map on forum](https://www.elektroda.com/rtvforum/find.php?q=AB_Map). | File: drv/drv_adcButton.c<br/>Function: Cmd_ADCButtonMap |
 | ACMode | CMD_ACMode | .<br/><br/>See also [ACMode on forum](https://www.elektroda.com/rtvforum/find.php?q=ACMode). | File: driver/drv_tclAC.c<br/>Function: NULL); |
 | ADCSmoother | [Pindex] [TotalSamples] [SampleIntervalMS] [TargetChannelADCValue] [MarginValue] [TargetChannel0or1] | Starts the ADC smoother with given configuration.<br/><br/>See also [ADCSmoother on forum](https://www.elektroda.com/rtvforum/find.php?q=ADCSmoother). | File: driver/drv_adcSmoother.c<br/>Function: NULL); |
-| AddChangeHandler | [Variable][Relation][Constant][Command] | This can listen to change in channel value (for example channel 0 becoming 100), or for a voltage/current/power change for BL0942/BL0937. This supports multiple relations, like ==, !=, >=, < etc. The Variable name for channel is Channel0, Channel2, etc, for BL0XXX it can be 'Power', or 'Current' or 'Voltage'.<br/><br/>See also [AddChangeHandler on forum](https://www.elektroda.com/rtvforum/find.php?q=AddChangeHandler). | File: cmnds/cmd_eventHandlers.c<br/>Function: CMD_AddChangeHandler |
-| AddChannel | [ChannelIndex][ValueToAdd][ClampMin][ClampMax][bWrapInsteadOfClamp] | Adds a given value to the channel. Can be used to change PWM brightness. Clamp min and max arguments are optional.<br/><br/>See also [AddChannel on forum](https://www.elektroda.com/rtvforum/find.php?q=AddChannel). | File: cmnds/cmd_channels.c<br/>Function: CMD_AddChannel |
+| AddChangeHandler | [Variable][Relation][Constant][Command] | Trigger based on change in channel value (for example channel 0 becoming 100), or for a voltage/current/power/frequency change for BL0942/BL0937. This supports multiple relations, like ==, !=, >=, < etc. The Variable name for channel is Channel0, Channel2, etc, for BL0XXX it can be 'Power', 'Current', 'Voltage' or 'Frequency'.<br/><br/>Example: Values are compared as integers.  This affects Current (*1000) and Frequency (*100). Example handler where Current is greather than 2Amps:<br/> `AddChangeHandler Current > 2000 SetChannel 1 0`<br/><br/>See also [AddChangeHandler on forum](https://www.elektroda.com/rtvforum/find.php?q=AddChangeHandler). | File: cmnds/cmd_eventHandlers.c<br/>Function: CMD_AddChangeHandler |
+| AddChannel | [ChannelIndex][ValueToAdd][ClampMin][ClampMax][bWrapInsteadOfClamp] | Adds a given value to the channel. Can be used to change PWM brightness. Clamp min and max arguments are optional.<br/><br/>See also [AddChannel on forum](https://www.elektroda.com/rtvforum/find.php?q=AddChannel). | File: cmnds/cmd_channels.c<br/>Function: CMD_AddChannel | | addClockEvent | [TimerSeconds or Time or sunrise or sunset] [WeekDayFlags] [UniqueIDForRemoval][Command] | Schedule command to run on given time in given day of week. NTP must be running. TimerSeconds is seconds from midnight, Time is a time like HH:mm or HH:mm:ss, WeekDayFlag is a bitflag on which day to run, 0xff mean all days, 0x01 means sunday, 0x02 monday, 0x03 sunday and monday, etc, id is an unique id so event can be removed later. (NOTE: Use of sunrise/sunset requires compiling with ENABLE_NTP_SUNRISE_SUNSET set which adds about 11k of code).<br/><br/>See also [addClockEvent on forum](https://www.elektroda.com/rtvforum/find.php?q=addClockEvent). | File: driver/drv_ntp_events.c<br/>Function: CMD_NTP_AddClockEvent |
 | addClockEvent | [TimerSeconds or Time or sunrise or sunset] [WeekDayFlags] [UniqueIDForRemoval][Command] | Schedule command to run on given time in given day of week. NTP must be running. TimerSeconds is seconds from midnight, Time is a time like HH:mm or HH:mm:ss, WeekDayFlag is a bitflag on which day to run, 0xff mean all days, 0x01 means sunday, 0x02 monday, 0x03 sunday and monday, etc, id is an unique id so event can be removed later. (NOTE: Use of sunrise/sunset requires compiling with ENABLE_NTP_SUNRISE_SUNSET set which adds about 11k of code).<br/><br/>See also [addClockEvent on forum](https://www.elektroda.com/rtvforum/find.php?q=addClockEvent). | File: driver/drv_ntp_events.c<br/>Function: CMD_NTP_AddClockEvent |
 | AddEventHandler | [EventName][EventArgument][CommandToRun] | This can be used to trigger an action on a button click, long press, etc.<br/><br/>See also [AddEventHandler on forum](https://www.elektroda.com/rtvforum/find.php?q=AddEventHandler). | File: cmnds/cmd_eventHandlers.c<br/>Function: CMD_AddEventHandler |
 | addI2CDevice_ADS1115 |  | .<br/><br/>See also [addI2CDevice_ADS1115 on forum](https://www.elektroda.com/rtvforum/find.php?q=addI2CDevice_ADS1115). | File: i2c/drv_i2c_ads1115.c<br/>Function: NULL); |
@@ -248,7 +248,7 @@ Do not add anything here, as it will overwritten with next rebuild.
 | SetStartValue | [Channel][Value] | Sets the startup value for a channel. Used for start values for relays. Use 1 for High, 0 for low and -1 for 'remember last state'.<br/><br/>See also [SetStartValue on forum](https://www.elektroda.com/rtvforum/find.php?q=SetStartValue). | File: cmnds/cmd_main.c<br/>Function: CMD_SetStartValue |
 | SetupEnergyStats | [Enable1or0][SampleTime][SampleCount][JSonEnable] | Setup Energy Statistic Parameters: [enable 0 or 1] [sample_time[10..90]] [sample_count[10..180]] [JsonEnable 0 or 1]. JSONEnable is optional.<br/><br/>See also [SetupEnergyStats on forum](https://www.elektroda.com/rtvforum/find.php?q=SetupEnergyStats). | File: driver/drv_bl_shared.c<br/>Function: BL09XX_SetupEnergyStatistic |
 | SetupIR2 | [myPeriodUs] [dutyOnFrac] [dutyOffFrac] [txPin] | Init IR2 pin and interrupt.<br/><br/>See also [SetupIR2 on forum](https://www.elektroda.com/rtvforum/find.php?q=SetupIR2). | File: driver/drv_ir2.c<br/>Function: NULL); |
-| SetupTestPower | [fakeVoltage] [FakeCurrent] [FakePower] [bAllowRandom] | Starts the fake power metering driver.<br/><br/>See also [SetupTestPower on forum](https://www.elektroda.com/rtvforum/find.php?q=SetupTestPower). | File: driver/drv_test_drivers.c<br/>Function: TestPower_Setup |
+| SetupTestPower | [fakeVoltage] [FakeCurrent] [FakePower] [FakeFrequency] [bAllowRandom] | Starts the fake power metering driver.<br/><br/>See also [SetupTestPower on forum](https://www.elektroda.com/rtvforum/find.php?q=SetupTestPower). | File: driver/drv_test_drivers.c<br/>Function: TestPower_Setup |
 | SGP_cycle | [int] | Change cycle of measurement by default every 10 seconds 0 to deactivate.<br/><br/>Example: SGP_Cycle 60<br/><br/>See also [SGP_cycle on forum](https://www.elektroda.com/rtvforum/find.php?q=SGP_cycle). | File: drv/drv_sgp.c<br/>Function: SGP_cycle |
 | SGP_GetBaseline |  | SGP Get baseline.<br/><br/>Example: SGP_GetBaseline<br/><br/>See also [SGP_GetBaseline on forum](https://www.elektroda.com/rtvforum/find.php?q=SGP_GetBaseline). | File: drv/drv_sgp.c<br/>Function: SGP_GetBaseline |
 | SGP_GetVersion |  | SGP : get version.<br/><br/>Example: SGP_GetVersion<br/><br/>See also [SGP_GetVersion on forum](https://www.elektroda.com/rtvforum/find.php?q=SGP_GetVersion). | File: drv/drv_sgp.c<br/>Function: SGP_GetVersion |
@@ -359,10 +359,10 @@ Do not add anything here, as it will overwritten with next rebuild.
 | uartSendASCII | [AsciiString] | Sends given string by UART.<br/><br/>See also [uartSendASCII on forum](https://www.elektroda.com/rtvforum/find.php?q=uartSendASCII). | File: driver/drv_uart.c<br/>Function: CMD_UART_Send_ASCII |
 | uartSendHex | [HexString] | Sends raw data by UART, can be used to send TuyaMCU data, but you must write whole packet with checksum yourself.<br/><br/>See also [uartSendHex on forum](https://www.elektroda.com/rtvforum/find.php?q=uartSendHex). | File: driver/drv_tuyaMCU.c<br/>Function: CMD_UART_Send_Hex |
 | UCS1912_Test |  | .<br/><br/>See also [UCS1912_Test on forum](https://www.elektroda.com/rtvforum/find.php?q=UCS1912_Test). | File: driver/drv_ucs1912.c<br/>Function: UCS1912_Test |
-| VCPPrecision | [VoltageDigits][CurrentDigitsAmpers][PowerDigitsWats][EnergyDigitsWh] | Sets the number of digits after decimal point for power metering publishes. Default is BL09XX_VCPPrecision 1 3 2 3. This works for OBK-style publishes.<br/><br/>See also [VCPPrecision on forum](https://www.elektroda.com/rtvforum/find.php?q=VCPPrecision). | File: driver/drv_bl_shared.c<br/>Function: BL09XX_VCPPrecision |
-| VCPPublishIntervals | [MinDelayBetweenPublishes][ForcedPublishInterval] | First argument is minimal allowed interval in second between Voltage/Current/Power/Energy publishes (even if there is a large change), second value is an interval in which V/C/P/E is always published, even if there is no change.<br/><br/>See also [VCPPublishIntervals on forum](https://www.elektroda.com/rtvforum/find.php?q=VCPPublishIntervals). | File: driver/drv_bl_shared.c<br/>Function: BL09XX_VCPPublishIntervals |
-| VCPPublishThreshold | [VoltageDeltaVolts][CurrentDeltaAmpers][PowerDeltaWats][EnergyDeltaWh] | Sets the minimal change between previous reported value over MQTT and next reported value over MQTT. Very useful for BL0942, BL0937, etc. So, if you set, VCPPublishThreshold 0.5 0.001 0.5, it will only report voltage again if the delta from previous reported value is largen than 0.5V. Remember, that the device will also ALWAYS force-report values every N seconds (default 60).<br/><br/>See also [VCPPublishThreshold on forum](https://www.elektroda.com/rtvforum/find.php?q=VCPPublishThreshold). | File: driver/drv_bl_shared.c<br/>Function: BL09XX_VCPPublishThreshold |
-| VoltageSet | Voltage | Measure the real voltage with an external, reliable power meter and enter this voltage via this command to calibrate. The calibration is automatically saved in the flash memory.<br/><br/>See also [VoltageSet on forum](https://www.elektroda.com/rtvforum/find.php?q=VoltageSet). | File: driver/drv_pwrCal.c<br/>Function: NULL); |
+| VCPPrecision | [VoltageDigits][CurrentDigitsAmpers][PowerDigitsWats][EnergyDigitsWh][Frequency] | Sets the number of digits after decimal point for power metering publishes for BL09XX. Default is `VCPPrecision 1 3 2 3 3`. This works for OBK-style publishes.  Only the first argument is required, others are optional.<br/><br/>See also [VCPPrecision on forum](https://www.elektroda.com/rtvforum/find.php?q=VCPPrecision). | File: driver/drv_bl_shared.c<br/>Function: BL09XX_VCPPrecision |
+| VCPPublishIntervals | [MinDelayBetweenPublishes][ForcedPublishInterval] | First argument is minimal allowed interval in second between Voltage/Current/Power/Energy publishes (even if there is a large change), second value is an interval in which V/C/P/E is always published, even if there is no change.  Frequency is published with Voltage.<br/><br/>See also [VCPPublishIntervals on forum](https://www.elektroda.com/rtvforum/find.php?q=VCPPublishIntervals). | File: driver/drv_bl_shared.c<br/>Function: BL09XX_VCPPublishIntervals |
+| VCPPublishThreshold | [VoltageDeltaVolts][CurrentDeltaAmpers][PowerDeltaWats][EnergyDeltaWh][Frequency] | Sets the minimal change between previous reported value over MQTT and next reported value over MQTT. Very useful for BL0942, BL0937, etc. So, if you set, `VCPPublishThreshold 0.25 0.002 0.5 0.25 0.25 0.01` (the default), it will only report voltage again if the delta from previous reported value is larger than 0.25V. Remember, that the device will also ALWAYS force-report values every N seconds (default 60).  The last there arugments are optional.<br/><br/>Example: `VCPPublishThreshold 0.5 0.02 1`<br/><br/>See also [VCPPublishThreshold on forum](https://www.elektroda.com/rtvforum/find.php?q=VCPPublishThreshold). | File: driver/drv_bl_shared.c<br/>Function: BL09XX_VCPPublishThreshold |
+| VoltageSet | Voltage | Measure the real voltage with an external, reliable power meter and enter this voltage via this command to calibrate. The calibration is automatically saved in the flash memory.<br/><br/>See also [VoltageSet on forum](https://www.elektroda.com/rtvforum/find.php?q=VoltageSet). | File: driver/drv_pwrCal.c<br/>Function: CalibrateVoltage |
 | waitFor | [EventName] [Argument] | Wait forever for event. Can be used within script. For example, you can do: waitFor MQTTState 1 or waitFor NTPState 1. You can also do waitFor NoPingTime 600 to wait for 600 seconds without ping watchdog getting successful reply.<br/><br/>See also [waitFor on forum](https://www.elektroda.com/rtvforum/find.php?q=waitFor). | File: cmnds/cmd_script.c<br/>Function: CMD_waitFor |
 | WebServer | [0 - Stop / 1 - Start] | Setting state of WebServer.<br/><br/>See also [WebServer on forum](https://www.elektroda.com/rtvforum/find.php?q=WebServer). | File: cmnds/cmd_main.c<br/>Function: CMD_WebServer |
 | widget_clearAll |  | Removes all registered widgets.<br/><br/>See also [widget_clearAll on forum](https://www.elektroda.com/rtvforum/find.php?q=widget_clearAll). | File: driver/drv_widget.c<br/>Function: NULL); |