Pascal Nohl

FLOW GADGETS

User Guide & Examples

Version 1.0.0

What is Flow Gadgets

Flow Gadgets is a collection of helper cards for Homey Flows and Advanced Flows. The app provides small, reusable cards that make Flow creation easier. Some cards replace several standard Homey cards with one single card. Others add helper functions that are not available as built-in Homey cards.

Flow Gadgets also provides temporary values. These values are created on demand, stored in memory for a limited time, and can be shared between Flows without creating global Homey variables.

Single card action helpers

The cards in this section can be used on their own. They do not require other Flow Gadgets cards to work.

For simplicity, the examples often use fixed numbers, text values or boolean values. In real Flows, these inputs will usually be Homey tags. The value inside a tag may not always be obvious when the Flow runs, so these helper cards can also be useful for debugging and value transformation.

Calculate Formula & Compare

This card calculates the result of a mathematical formula and can optionally compare the result with another value or formula.

The card accepts:

One mathematical formula as text.
One optional comparator.
One optional comparison value or comparison formula.

At runtime, the card outputs two tags:

Result: the calculated numeric result.
Comparison result: true or false, depending on the optional comparison.

Examples:

10 + 5
(10 + 5) * 2
((10.5 + 12) * -3) + #PV Power
(#PV Power - #House Load) / 1000

Deadband logic is also supported inside formulas. See the chapter “Deadband Logic”.

Comparison:
The comparison is optional. If a comparator and comparison value are defined, the card compares the calculated result against the comparison value. The comparison value can be either a fixed number, a numeric tag, or another formula.
If no comparison is defined, the Result tag is still returned, but the Comparison result tag returns false.

Error handling:
If the formula contains invalid characters, text values, an invalid tag value, a division by zero, or any other invalid expression, a hard error is thrown and the Flow stops at this card.

Deadband Logic

The Calculate Formula card and the Conditional Comparison card support deadband logic inside formulas. A deadband is a numeric range that is treated as zero. This is useful when values fluctuate around zero and would otherwise make a Flow switch back and forth too often.

In formulas, a deadband is written with curly braces: {value; minimum deadband value; maximum deadband value} The parameters are separated by semicolons. If the value is inside the deadband range, the result is 0. If the value is outside the deadband range, the original value is returned unchanged.

Examples:

{20;-10;10} returns 20
{9;-10;10} returns 0
{-6;-10;10} returns 0
{-11;-10;10} returns -11

Tags can also be used inside a deadband definition.

Example:

{#PV Production;-50;50}

Multiple deadbands can be used inside the same formula. Deadbands can also be nested inside other deadbands.

Examples:

({#PV Production;-50;50} - {#House Load;-20;20}) + #Battery Power
{{#PV Production;-50;50} - {#House Load;-20;30};-20;60} + #Grid Power

Invert number

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.

Generate random integer

This card generates a random integer within a defined range. The card accepts:

A minimum value.
A maximum value.

At runtime, it outputs the generated random integer as a numeric tag.

Example:
If the minimum value is 20 and the maximum value is 100, the card returns a random whole number between 20 and 100.

Round value

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.

Return absolute value

This card returns the absolute value of a number. The absolute value is always positive or zero. The card accepts:

One numeric value.

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

Examples:

-10 becomes 10.
10 stays 10.
0 stays 0.

Return absolute difference

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.

Apply deadband

This card stabilizes fluctuating numeric values by treating a defined range as zero. This is useful for values that fluctuate around zero. A typical example is a PV system where the grid value may switch frequently between small imports and small exports. The card accepts:

One numeric value.
A negative offset.
A positive offset.

At runtime, it outputs the processed result as a numeric tag.

Rules:

If the value is between the negative offset and the positive offset, the output is 0.
If the value is outside that range, the original value is passed through unchanged.

Example:
With a negative offset of -50 and a positive offset of 50:

25 returns 0.
-30 returns 0.
80 returns 80.
-120 returns -120.

Clamp a value

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.

Calculate median from list

This card calculates the median value from a list of numbers. The median is the middle value of a sorted list. Compared to an average, the median is less affected by extreme spikes or outliers. This can be useful for sensor values.

The card accepts:

A list of numbers separated by a pipe character: |

Note: the list can be unordered, the app orders the list internally before processing the values.

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

Examples:

20|10|30 returns 20.
10|20|30|1000 returns 25, because the two middle values are 20 and 30, and their average is 25.

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

Calculate average from list

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.

Get min / max

This card compares two numbers and returns both the lower and the higher value. The card accepts:

A first numeric value.
A second numeric value.

At runtime, it outputs two numeric tags:

Min: the lower value.
Max: the higher value.

Example:
If the values are 20 and 300, the card returns:

Min = 20
Max = 300

Get min / max from a list

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.

Calculate percentage of

This card calculates what percentage one value represents of another value. The card accepts:

A value to compare.
A reference value.

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

Formula:
(value / reference value) * 100

Example:
If the value is 25 and the reference value is 100, the result is 25. This means 25 is 25% of 100.

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.

Calculate percentage change

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.

Map ranges

This card maps a value from one numeric range to another numeric range. The card accepts:

The value to map.
The minimum value of the original range.
The maximum value of the original range.
The minimum value of the target range.
The maximum value of the target range.

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

Examples:

In an original range from 0 to 100, the value 50 is in the middle of the range. Mapped to a target range from 0 to 1000, the result is 500.
In an original range from 0 to 100, the value 75 becomes 1500 when mapped to a target range from 0 to 2000.

This card can also be used with reversed ranges if supported by the card configuration.

Invert boolean

This card inverts a boolean value. The card accepts:

One boolean value.

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

Rules:

true becomes false.
false becomes true.

Example:
A window contact may return true when the window is open. If your Flow needs the opposite logic, this card can convert it to false.

Convert boolean to Text

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”.

Map tag to text

This card converts a text value into another text value by using two matching lists. It is useful when a device returns technical, unclear, untranslated or unwanted text values, and you want to convert them into cleaner text. The card accepts:

Map: the input text value or text tag.
From: a list of source values separated by a pipe character: |
To: a list of replacement values separated by a pipe character: |
Respect case: defines whether the comparison is case-sensitive.

At runtime, the card outputs a text tag.

How it works:
The card compares the input value with the entries in the From list. If it finds a match, it returns the value at the same position in the To list. If no match is found, the original input value is returned unchanged.

Example:
From: Away|Sleep|Home
To: Not at home|Sleeping|At home
If the input value is Sleep, the card finds Sleep at the second position in the From list and returns the second value from the To list: Sleeping.

Case handling:
If Respect case is enabled, Sleep and sleep are treated as different values.
If Respect case is disabled, Sleep and sleep are treated as the same value.

Error handling:
If the input value is a boolean value or a pure number, a hard error is thrown and the Flow stops at this card. If the number of entries in the From list is different from the number of entries in the To list, a hard error is thrown and the Flow stops at this card.

Single card conditional helpers

The cards in this section are condition cards. They return true or false and control whether the Flow continues on the “Then” path or the “Else” path. These cards can be used on their own. They do not require other Flow Gadgets cards to work. For simplicity, the examples often use fixed numbers or boolean values. In real Flows, these inputs will usually be Homey tags.

Conditional Comparison

This condition card checks whether the result of a formula matches a comparison. The card accepts:

One mathematical formula or numeric value.
One comparator.
One comparison value or comparison formula.

Formula rules:
The formula is limited to basic mathematical operations. It accepts numbers, numeric tags, the operators +, -, * and /, and parentheses. Nested parentheses are supported. Negative numbers are supported. Decimal values must use a dot as the decimal separator. The comparison value can also be a formula. Deadband logic is supported inside formulas. See the chapter “Deadband Logic”.

Example:
((10.5 + 12) * -3) + #PV Power

The Flow continues on the “Then” path if the comparison returns true. It continues on the “Else” path if the comparison returns false.

Is in Range

This condition card checks whether a numeric value is inside a defined range. The card accepts:

The value to check.
The lower range value.
The upper range value.
An inclusion mode.

At runtime, the card returns true or false.

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.

Is Positive

This condition card checks whether a numeric value is positive. The card accepts:

One numeric value.

At runtime, the card returns true or false.

The Flow continues on the “Then” path if the value is positive. It continues on the “Else” path if the value is not positive.

The condition can also be inverted in Homey.

Example:

10 returns true.
-5 returns false.

Cards that work in a group

The features in this section require two or more Flow Gadgets cards to work together. These cards are mainly used to store a temporary value, read it later, and optionally release it again. The order of the cards is important:

Set a temporary value.
Use the same unique ID in another card or Flow.
Read the temporary value.
Release the temporary value when it is no longer needed.

Set temporary number

This card stores a temporary number in memory. If the unique ID does not exist yet, it is created. If it already exists, the stored value is overwritten and the timeout timer is restarted.

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.

Get temporary number

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.

Get and release temporary number

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.

Temporary text values

These cards store temporary text values. They work the same way as the temporary number cards:

Set temporary text stores a text value under a unique ID.
Get temporary text reads the stored text value without deleting it.
Get and release temporary text reads the stored text value and deletes it afterwards.

The same unique ID and timeout rules apply.

Temporary boolean values

These cards store temporary boolean values. They work the same way as the temporary number cards:

Set temporary boolean stores a true or false value under a unique ID.
Get temporary boolean reads the stored boolean value without deleting it.
Get and release temporary boolean reads the stored boolean value and deletes it afterwards.

The same unique ID and timeout rules apply.

Example of usage

The following example is intentionally simple. It is mainly meant to explain how temporary values work.
A first Flow creates a temporary value and stores it under a unique ID. It then starts a second Flow and passes the same unique ID to it. The second Flow uses this unique ID to read the temporary value, modifies the value, and stores the modified result again under the same unique ID. When the second Flow has finished, the first Flow reads the modified value and can use it in a notification, calculation or another card.

Important:
The second Flow should not release the temporary value if the first Flow still needs to read it afterwards.

Typical sequence:

The first Flow creates a temporary value.
The first Flow starts another Flow and passes the unique ID.
The second Flow reads the temporary value using that unique ID.
The second Flow modifies the value.
The second Flow stores the modified value again under the same unique ID.
The first Flow reads the modified value.
The first Flow releases the temporary value.

Example of the first flow:

Example of the second flow:

Note:
Temporary values can also be useful inside a single Flow.

Example:
You may want to store an original value, modify the value during the Flow, and later compare the modified value with the original one. In that case, you can store the original value as a temporary value, continue with your calculations, and read the original value again later in the same Flow.

Page updated

Google Sites

Report abuse