Mathematical formulas and deadband logic

Mathematical formulas and deadband logic are available in most numeric cards and numeric fields. Instead of entering only a fixed number or a single Homey tag, you can use a calculated expression. The expression is resolved when the Flow runs.

Important:

• Flow Gadgets formulas are entered directly into supported numeric fields. You do not need Homey-style double curly brackets `{{ ... }}`.

• Single curly brackets `{ ... ; ... ; ... }` are only used for Flow Gadgets deadband blocks.

• Leading, trailing and extra spaces inside formulas are ignored.

Example:
Instead of using only a tag like `#Load`, you can enter a formula such as: `(#Load - #PV) + {#GridPower; -10; 10}`
This calculates the difference between load and PV production, and adds the grid power only when it is outside the deadband range from `-10` to `10`.

Formula rules:

Formulas support:

• numbers

• resolved numeric Homey tags

• +, - , * ,  / and ^

• nested parentheses

• decimal dot or decimal comma

• supported functions

• deadband blocks

Dot & comma decimals and semicolons for arguments:

• 10.5 or 10,5 are decimals

• Do not use thousands separators. Write `1000`, not `1,000` or `1.000`.

• Function arguments are separated with semicolons, not commas.

Examples:

• 10 + 5

• (10 + 5) * 2

• ((10.5 + 12) * -3) + #PV

• 1,5 + 2,5

• (#PV - #Load) / 1000

• 2 ^ 3

Supported functions:

• abs(value)

• min(value ; value ; ...)

• max(value ; value ; ...)

• clamp(value ; min ; max)

• round(value)

• round(value ; decimals)

• floor(value)

• floor(value ; decimals)

• ceil(value)

• ceil(value ; decimals)

• time(string)

Function examples:

• abs(-5) returns 5

• min(30 ; 10 ; 20) returns 10

• max(30 ; 10 ; 20) returns 30

• clamp(#Brightness ; 10 ; 80) limits the brightness value to the range from 10 to 80

• round(12.345 ; 2) returns 12.35

• floor(12.349 ; 2) returns 12.34

• ceil(12.341 ; 2) returns 12.35

• time(15:10:10) returns 55810 - in formulas, seconds since midnight

• time(#Time) > time(15:30) - in expressions, returns true or false.

Deadband logic:
A deadband is a numeric range that is treated as `0`. This is useful when values fluctuate around zero and would otherwise make a Flow switch back and forth too often.
A deadband block is written like this: {value; minimum deadband value; maximum deadband value}
If the value is inside the deadband range, the result is `0`. If the value is outside the range, the original value is returned unchanged. Deadband limits are inclusive.

Examples:

• {20; -10; 10} returns 20

• {9; -10; 10} returns 0

• {-6; -10; 10} returns 0

• {-11; -10; 10} returns -11

Tags, formulas and functions can also be used inside deadband blocks.

Examples:

• {#GridPower; -50; 50}

• {#PV - #Load; -20; 20}

• round({#Temperature - #TargetTemperature; -0.2; 0.2} ; 1)

Deadband blocks can be used inside formulas, and they can also be nested. For readability, avoid overly complex nested formulas when a Flow would be easier to understand with separate cards.

To avoid confusion between (#Temperature  + 10%) and (#Temperature  +  (#Temperature  *  10%)) the `%` symbol is not used in Flow Gadgets formulas. For percentage calculations, use normal math such as *0.8 for 80% or the dedicated percentage cards.

Complex formulas

Flow Gadgets can handle complex formulas, for example:
round(clamp((#Load - #PV) * #Efficiency + {#GridPower; -20; 20} + abs(#RoomTemp - #TargetTemp) * 50; -3000; 3000); 1)
This formula combines normal math, Homey tags, a deadband block, the `abs()` function, `clamp()` and `round()` in one expression. This can be very powerful, but complex formulas may become hard to read and maintain. For power users Flow Gadgets can pack a lot of logic into one card, but for lambda users it is better to use a few extra cards to keep your Advanced Flow understandable.

This card inverts a numeric value. The card accepts:

• One numeric value.

At runtime, it outputs the inverted value as a numeric tag.

Examples:

• 10 becomes -10.

• -25 becomes 25.

Typical use case:
Your battery power is negative while charging, but you want to use the same value as a positive number in another Flow.

This card rounds a numeric value to a defined number of decimal places. The card accepts:

• One numeric value.

• The number of decimal places to keep.

• A rounding mode.

At runtime, it outputs the rounded value as a numeric tag.

Rounding modes:

• Standard: rounds normally. Values with the next digit 5 or higher are rounded up.

• Round down: always rounds down.

• Round up: always rounds up.

Examples:

• Standard rounding: 12.56 with 1 decimal becomes 12.6.

• Down rounding: 12.59 with 1 decimal becomes 12.5.

• Up rounding: 12.51 with 1 decimal becomes 12.6.

This card returns the absolute difference between two numbers. The absolute difference is always positive or zero. The card accepts:

• A first numeric value.

• A second numeric value.

At runtime, it outputs the absolute difference between both values as a numeric tag.

Examples:

• The absolute difference between 20 and 12 is 8.

• The absolute difference between 12 and 20 is also 8.

This card limits a numeric value to a defined minimum and maximum range. The card accepts:

• A value to clamp.

• The lowest allowed value.

• The highest allowed value.

At runtime, it outputs the clamped value as a numeric tag.

Rules:

• If the value is inside the allowed range, the original value is returned.

• If the value is lower than the lowest allowed value, the lowest allowed value is returned.

• If the value is higher than the highest allowed value, the highest allowed value is returned.

Example:
With a minimum of 0 and a maximum of 100:

• 50 returns 50.

• -20 returns 0.

• 150 returns 100.

This card calculates the average value from a list of numbers. The card accepts:

• A list of numbers separated by a pipe character: |

At runtime, it outputs the average value as a numeric tag.

Example:

• 40|10|15 returns 21.67

Error handling:
If the list contains invalid values or non-numeric entries, a hard error is thrown and the Flow stops at this card.

This card returns the lowest and highest value from a list of numbers. The card accepts:

• A list of numbers separated by a pipe character: |

At runtime, it outputs two numeric tags:

• Min: the lowest value in the list.

• Max: the highest value in the list.

Example:
10|5|30|12 returns:

• Min = 5

• Max = 30

Error handling:
If the list contains invalid values or non-numeric entries, a hard error is thrown and the Flow stops at this card.

This card calculates the percentage change between a start value and an end value. The card accepts:

• A start value.

• An end value.

At runtime, it outputs the percentage change as a numeric tag.

Formula:
((end value - start value) / start value) * 100

Examples:

• From 100 to 120 returns 20.

• From 100 to 80 returns -20.

This means the value increased by 20% in the first example and decreased by 20% in the second example.

Error handling:
If the reference value is 0, the percentage cannot be calculated. To avoid a division-by-zero error, the app internally treats 0 as 1.

This card maps a numeric value to a scale value using a list of thresholds. It is useful when you want to transform a continuous value into a fixed level, for example:

• Temperature to heating level

• Humidity to ventilation level

• Wind speed to warning level

The card accepts:

• A numeric value.

•  A list of numeric thresholds, separated by a pipe `|` character.

•  A list of numeric scale values, also separated by a pipe `|` character.

At runtime, it outputs the matching scale value as a tag.

The thresholds must be strictly ascending or descending. The scale must always contain exactly one more value than the thresholds.

Example:

• Thresholds: 20 | 50 | 70 | 90

• Scale: 1 | 2 | 3 | 4 | 5

This means:

• Values below 20 return 1

• Values from 20 up to below 50 return 2

• Values from 50 up to below 70 return 3

• Values from 70 up to below 90 return 4

• Values from 90 and above return 5

Error handling:

• If the value is not numeric, a hard error is thrown and the Flow stops at this card.

• If the thresholds or scale contain empty or non-numeric entries, a hard error is thrown and the Flow stops at this card.

• If the thresholds are not strictly ascending or descending, a hard error is thrown and the Flow stops at this card.

• If the scale does not contain exactly one more entry than the thresholds, a hard error is thrown and the Flow stops at this card.

This card converts common units and direction conventions using fixed conversion factors. It is intended for conversions that are not always easy to remember or that are based on specific conventions.

The card accepts:

• A numeric value.

• A dropdown selection defining the conversion.

At runtime, it outputs the converted value as a number tag.

Supported conversions include:

• Compass 0–360° to signed compass -180…+180° / Signed compass -180…+180° to compass 0–360°

• Compass 0–360° to PVGIS azimuth -180…+180° / PVGIS azimuth -180…+180° to compass 0–360°

• Fahrenheit to Celsius / Celsius to Fahrenheit

• Miles to kilometers / Kilometers to miles

• US gallons to liters / Liters to US gallons

• Imperial gallons to liters / Liters to Imperial gallons

• mph to km/h / km/h to mph

• m/s to km/h / km/h to m/s

• kJ/m² per hour to W/m² / W/m² to kJ/m² per hour

• kJ/m² per hour to kW/m² / kW/m² to kJ/m² per hour

Radiation note:
The conversions from kJ/m² to W/m² or kW/m² assume that the kJ/m² value represents an energy sum over one hour. This is why the dropdown explicitly says “per hour”.

Error handling:

• If the input value is not numeric, a hard error is thrown and the Flow stops at this card.

• If the conversion type is invalid or missing, a hard error is thrown and the Flow stops at this card.

• If the calculation would result in an invalid numeric result, a hard error is thrown and the Flow stops at this card.

This card converts a boolean value into one of two text values. This is useful when you want to display a readable text on a dashboard, in a notification, or in another app. The card accepts:

• One boolean value.

• A text value to return when the boolean is true.

• A text value to return when the boolean is false.

At runtime, it outputs the matching text value as a tag.

Example:
A window contact returns true or false, but you want to display “Open” or “Closed”.

The Flow continues on the “Then” path if the value is inside the defined range. It continues on the “Else” path if the value is outside the range. The condition can also be inverted in Homey to check whether the value is not inside the range.

Example:
If the range is 10 to 20:

• 15 returns true.

• 5 returns false.

• 25 returns false.

Note:
The exact handling of the range borders depends on the selected inclusion mode.

This condition card checks a list of boolean values and continues on the true or false path depending on the selected mode. It is useful when several boolean values belong together and should be evaluated as one logical group. A typical example is a room or zone with multiple window contacts. Instead of checking every contact separately, you can put all contact alarm tags into one boolean list and check whether the whole zone is closed or open.

The card accepts:

• A list of boolean values separated by a pipe `|` character.

• A dropdown selection defining how the list should be evaluated.

Supported modes:

• All true

• All false

• At least one true

• At least one false

• Most true

• Most false

The flow continues on the blue path if the selected condition is true. The flow continues on the orange path if the selected condition is false.

Example:
Boolean list (window alarm contacts) : false | false | false | false
Mode: All false
Result: The condition is true, because all values are false.

Tie handling:
For the modes Most true and Most false, a tie returns false.

Error handling:

• If the boolean list is empty, a hard error is thrown and the Flow stops at this card.

• If the list contains empty entries, a hard error is thrown and the Flow stops at this card.

• If one of the entries is not a valid boolean value, a hard error is thrown and the Flow stops at this card.

This card works like a dynamic deadband with a stored reference value. Its purpose is to stabilize fast-changing numeric values by only allowing larger, meaningful changes to continue the Flow. A typical example is a PV system that reports power values in watts and changes very often in small steps, for example by 1 W. The card accepts:

• one numeric value

• a minimum increase value

• a minimum decrease value

• a storage ID

• a reference mode

• a first-run behavior

At runtime, the card compares the current value with the stored reference value for the selected storage ID. If no reference value exists yet, the card stores the current value as the first reference value. You can choose whether the card should return true or false on this first run.

Reference modes:

• Last accepted value: the reference value is only updated when the card returns true.

• Last checked value: the reference value is updated every time the card is checked, even when the card returns false.

The card returns true when:

• the current value is at least the configured minimum increase higher than the stored reference value

• or the current value is at least the configured minimum decrease lower than the stored reference value

If the value has not changed enough, the card returns false and the Flow continues on the “Else” path.

Example with “Last accepted value”:

• Minimum increase: 10

• Minimum decrease: 10

• First-run behavior: False path

First run: 

• Value = 236. Result: false. The value 236 is stored as the reference value.

Next runs:

• Value = 239. Difference from 236 is only +3. Result: false. The stored reference value stays 236.

• Value = 245. Difference from 236 is only +9. Result: false. The stored reference value stays 236.

• Value = 248. Difference from 236 is +12. Result: true. The value 248 is stored as the new reference value.

Example with “Last checked value”:

• Minimum increase: 10

• Minimum decrease: 10

• First-run behavior: False path

First run: 

• Value = 236. Result: false. The value 236 is stored as the reference value.

Next runs:

• Value = 239. Difference from 236 is only +3. Result: false. The value 239 is stored as the new reference value.

• Value = 245. Difference from 239 is only +6. Result: false. The value 245 is stored as the new reference value.

• Value = 258. Difference from 245 is +13. Result: true. The value 258 is stored as the new reference value.

Note:

• If the minimum increase is set to 0, upward changes are ignored.

• If the minimum decrease is set to 0, downward changes are ignored.

• If both values are set to 0, the card stores the current value as the new reference value and returns true. This can be used to reset the reference value.

• Stored reference values are kept in memory for up to 48 hours. They are also cleared when the app or Homey restarts.

• The numeric fields also accept simple formulas with +, -, *, /, nested parentheses and deadband blocks.

This condition card checks one or more expressions and returns true or false. It is useful when you want to combine several checks in one compact condition card without building a long chain of separate AND cards. The card accepts one expression field.

Expression logic:

• Use | for AND.

• Use || for OR groups.

Example:
#Temperature > 22 | #Humidity < 60 || #Mode = "Away"

This means: (#Temperature > 22 AND #Humidity < 60) OR (#Mode = "Away") The card returns true when the full expression result is true. It returns false when the full expression result is false. Supported expression types: Expressions can compare numbers, booleans and text.

Numeric comparisons can also use Flow Gadgets formula logic, including +, -, *, /, ^, nested parentheses, decimal dot or comma, functions and deadband blocks.

Allowed comparators:

• For numbers: >, >=, <, <=, =, ==, !=, <>

• For booleans: =, ==, !=, <>

• For text: =, ==, !=, <>, *=

The text comparator *= means “contains”. The comparators != and <> both mean “is not”.

Example:
round(#Temperature ; 1) > #TargetTemperature | {#GridPower; -20; 20} = 0

Important:
Do not mix trigger-specific tags from different source trigger cards in the same expression field. Homey only resolves the tags of the trigger that actually started the Flow.

Error handling:
If an expression is invalid, a hard error is thrown and the Flow stops at this card.

The card accepts:

• A unique ID.

• A numeric value.

• A timeout value.

The temporary value is intended to be released when it is no longer needed. If it is not released manually, it is automatically deleted after the selected timeout. This prevents temporary values from staying in memory forever if a Flow is incomplete or stops unexpectedly.

Unique ID
The unique ID works like the name of a temporary variable. It allows different Flows, or different parallel runs of the same Flow, to use separate temporary values without overwriting each other.

Example:
A Flow calculates a value and calls another Flow to process it. If this value were stored in a global Homey variable, another Flow running at the same time could overwrite it. With a temporary value, each calling Flow can use its own unique ID. The called Flow receives this unique ID and only reads or changes the value stored under that specific ID.

Timeout value
The timeout defines how long the temporary value stays in memory if it is not released manually. Each time the value is set again with the same unique ID, the timeout timer is restarted. The timeout is a safety mechanism. It prevents memory from being filled over time if a Flow forgets to release a temporary value.

Available timeout values:

• 3 minutes

• 15 minutes

• 60 minutes

Longer times are intentionally not provided, because these values are meant to be temporary.

This card reads a temporary number from memory without deleting it. The card accepts:

• The unique ID of the temporary value.

At runtime, it outputs the stored number as a numeric tag.

Use this card when you need to read the value but still want to keep it available for later use.

This card reads a temporary number from memory and releases it immediately afterwards. The card accepts:

• The unique ID of the temporary value.

At runtime, it outputs the stored number as a numeric tag. After the value has been read, the temporary value is deleted from memory.

Use this card when you need to read the value for the last time and do not need it anymore afterwards.

Strict read cards vs default read cards

Flow Gadgets provides two types of read cards for temporary values.

Strict read cards:

• Get temporary number

• Get temporary text

• Get temporary boolean

• Get and release temporary number

• Get and release temporary text

• Get and release temporary boolean

These cards expect the temporary value to exist. If the value does not exist or has expired, the card throws an error and the Flow stops at that card.

Default read cards:

• Get temporary number or default

• Get temporary text or default

• Get temporary boolean or default

• Get and release temporary number or default

• Get and release temporary text or default

• Get and release temporary boolean or default

These cards continue safely if the temporary value does not exist or has expired. Instead of throwing an error, they return the configured default value. Use strict read cards when a missing temporary value means that something is wrong in your Flow logic. Use default read cards when a missing temporary value is expected and should simply be treated as a normal fallback state.

Example: manual shutter override until evening
This example shows how temporary boolean values can be used as temporary states.
Goal: A manual shutter action should block the automatic shading logic until 22:00. After that time, the block should disappear automatically.

Flow 1: Manual shutter action
The user manually opens or changes a shutter. The Flow stores a temporary boolean value. Temporary ID: shutter_livingroom_manual_override. Value: true. Until time: 22:00. Time mode: Today only

Flow 2: Automatic shading logic
Before changing the shutter position, the Flow reads the temporary boolean value. Temporary ID: shutter_livingroom_manual_override. Default value: false. If the returned value is true, the shading logic should not move the shutter. If the returned value is false, no manual override is active and the shading logic may continue normally.
Why “Today only” is useful here: If the manual action happens before 22:00, the override stays active until 22:00. If the Flow runs after 22:00, the override is not stored for the next day by accident. Use “Next occurrence” when the temporary value should always stay active until the next matching time, even if that means tomorrow.

This card is used together with the Expression trigger captured card. It is typically connected to one or more trigger cards. When the card runs, it checks one or more expressions. If the full expression result is true, it triggers the matching Expression trigger captured card. This is useful when several different events should lead to one clean trigger, but only when the required conditions are valid.

The card accepts:

• A unique Trigger ID.

• One expression field.

• A trigger mode.

Expression logic:

• Use | for AND.

• Use || for OR groups.

Example:
#Azimuth > 90 | #Azimuth < 270 | #Luminance > 20000 || #Mode = "Manual"

This means:
(#Azimuth > 90 AND #Azimuth < 270 AND #Luminance > 20000) OR (#Mode = "Manual")

If the full expression result is true, the card triggers Expression trigger captured with the same Trigger ID. The Trigger ID connects this Then card with the matching When card. Example: trigg_ShaderEast
The Expression trigger captured card must use the same Trigger ID. Only matching Trigger IDs will fire.

Trigger mode:

• Every time expressions match. The When card is triggered every time this card runs and the full expression result is true.

• Only when result changes from false to true. The When card is only triggered when the full expression result changes from false to true. This prevents repeated triggers while the conditions stay true.

Numeric comparisons:
For numbers, the following operators are supported:

• > greater than

• > =  greater than or equal to

• <   lower than

• <=  lower than or equal to

• = or ==  equal to

• != or <>  not equal to

Numeric comparisons can also use Flow Gadgets formula logic, including +, -, *, /, ^, nested parentheses, decimal dot or comma, functions and deadband blocks.

Boolean comparisons:
Boolean values are normalized internally. 

• The following values are accepted as true: true, yes, ✓

• The following values are accepted as false: false, no, ⨯

For booleans, the following operators are supported:

• = or ==  equal to

• != or <>  not equal to

Text comparisons:
Text comparisons are intentionally simple and case-sensitive. For text, the following operators are supported:

• = or ==  equal to

• != or <>  not equal to

• *=  contains

!!! IMPORTANT note about Homey trigger tags
Do not mix trigger-specific tags from different source trigger cards in the same Capture trigger card. Homey only resolves the tags from the trigger card that actually started the Flow. If the Flow is started by a temperature trigger, a tag from an azimuth trigger card may not exist in that Flow run. In that case Homey may throw an error before Flow Gadgets can evaluate the expressions. Use global app tags, device tags, or values that are always available in the current Flow run.

Error handling:
If an expression is invalid, a hard error is thrown and the Flow stops at this card. Typical causes are:

• An empty expression.

• A missing left or right value.

• An unsupported operator or formula

• A numeric comparison with non-numeric values.

• A missing or unavailable Homey tag.

• An unclosed text quote.

The Continue Flow cards help you split large Advanced Flows into smaller, clearer sections. They work with a simple key. One card says where the Flow should continue, and another card marks the place where the Flow continues. This is useful when a Flow becomes too large or when the same follow-up section should be reused from different places.

Cards

• Continue Flow with key. This is a Then card. It tells Flow Gadgets to continue at every matching Continue Flow trigger card that uses the same key.

• Continue Flow with key here. This is a When card. It starts this part of the Flow when a matching Continue Flow key is used.

Why this is useful ?

You can use Continue Flow cards to:

• make large Advanced Flows easier to read, without crossing lines

• move follow-up logic to another part of the canvas

• reuse the same follow-up section from multiple places

• create a simple multi-trigger setup

• use it like the "Start flow" card but with a startpoint for a subset inside an advanced flow.

Important notes

• The Continue Flow card does not wait for the continued section to finish.

• If multiple Continue Flow trigger cards use the same key, all matching sections can be started.

• If no matching Continue Flow trigger card exists, nothing happens.

• Be careful not to create loops where a continued section calls the same Continue Flow key again.

Basic Example of the logic: