app-value

Description

The app-value block is used to share one numeric value between the project logic and the user interface. It can act as a temperature setpoint, a percentage value, a plain numeric value, or a time value.

The block has one input and one output. It does not require the use of inputs labeled with the tag block.

The current value can be changed in two ways:

• by events delivered to the block input
• from the mobile application or the web interface associated with this block

The block stores one current value. Every valid change updates the description shown below the block and the state presented in the mobile application and in the web interface.

Configuration parameters

Parameter name	Value
name	Optional parameter. Defines the name visible to the user in the mobile application and in the web interface. The absence of this parameter does not prevent the block from working.
value_type	Required parameter defining the value type. Supported values are: temperature, percentage, numeric, time.
extended_precision	Required parameter for temperature, percentage, and numeric types. When set to true, the block operates with 0.1 precision. When set to false, it accepts only whole numbers. For the time type this parameter is not used, because time is always handled with 1 second precision.
minimum_value	Required parameter defining the minimum allowed value. For temperature, percentage, and numeric, the allowed range is from -20000000.0 to 20000000.0. For time, the allowed range is from 0 to 864000 seconds, which is up to 240 hours. The value must match the selected precision: whole numbers for extended_precision = false or multiples of 0.1 for extended_precision = true.
maximum_value	Required parameter defining the maximum allowed value. The same limits apply as for minimum_value. The maximum_value must be greater than minimum_value.
step_value	Required parameter for temperature, percentage, and numeric types. Defines the adjustment step exposed to the user interface. It must match the selected precision, so it must be either a whole number or a multiple of 0.1. For the time type, the step is not configurable and is always 1 second.
persistent_state	Optional boolean parameter with values true or false. When set to true, the block tries to restore the last persisted value after the project is restarted. The state is not saved immediately, but about 10 minutes after the last change. If a restart or power loss happens earlier, an older value may be restored.
block_pass_thru_io	Optional boolean parameter with values true or false. Its default value is false. When set to false, a valid change received on the input updates the current value and is forwarded to the output. When set to true, a valid change received on the input updates the current value, but is not forwarded to the output from that input event.

Input handling

The block reacts only to numeric values. This means it accepts numeric inputs, including temperature and percentage values. Non-numeric values such as text, true, false, or null are ignored.

Detailed operating rules:

• the received value is first rounded according to the precision resulting from the configuration
• for extended_precision = true, rounding is done to 0.1
• for extended_precision = false, rounding is done to a whole number
• for the time type, rounding is always done to a whole second
• if the value after rounding is smaller than minimum_value or greater than maximum_value, the block ignores that event
• if the new valid value differs from the previous one, the block stores it as the current value and updates the description below the block as well as the state visible in the mobile application and in the web interface
• if block_pass_thru_io = false, a valid change received on the input is additionally sent to the block output
• if block_pass_thru_io = true, a change received on the input is not emitted on the output, but it still changes the current block value

The block does not require an input connection to operate. It may also be used only as a setpoint controlled from the mobile application or the web interface.

If persistent_state is enabled and the block state was successfully persisted earlier, then after the project starts the block restores that value and emits it again on the output.

Block outputs

The block has one output.

The output carries the current block value in the type resulting from the value_type parameter:

• for temperature, it is a temperature value
• for percentage, it is a percentage value
• for numeric, it is a plain numeric value without a unit
• for time, it is a time value

The description visible below the block shows the current value in its standard text representation. For example, it may be:

• 21.5°C for temperature
• 55% for a percentage value
• 12.3 for a plain numeric value
• 1h 30m 0s for time
• null if the block does not yet have a current value

Errors returned by the block

The block can return the following errors:

Error code	Error description
Invalid value type configuration.	The value_type parameter was not provided or has a value other than temperature, percentage, numeric, or time.
Invalid extended precision configuration.	No valid value of the extended_precision parameter was provided for the temperature, percentage, or numeric type.
Invalid minimum value configuration.	The minimum_value parameter is invalid, has the wrong type, is outside the allowed range, or does not match the selected precision.
Invalid maximum value configuration.	The maximum_value parameter is invalid, has the wrong type, is outside the allowed range, or does not match the selected precision.
Minimum value greater/equal than maximum.	The minimum_value is greater than or equal to maximum_value.
Invalid step configuration.	The step_value parameter is invalid or does not match the selected precision.

Usage examples

• If value_type = temperature, extended_precision = true, minimum_value = 18.0, maximum_value = 25.0, and the input receives the value 21.26, the block stores and emits the value 21.3°C.
• If value_type = numeric, extended_precision = false, minimum_value = 0, maximum_value = 10, and the input receives the value 7.6, the block rounds it to 8.
• If value_type = time, minimum_value = 0, maximum_value = 3600, and the input receives the value 90.8, the block rounds it to 91 seconds and shows the description 1m 31s.
• If block_pass_thru_io = true and the input receives a valid new value, the current block value is changed, but that input event is not forwarded to the output.
• If the input receives an out-of-range value, for example 120 with the configuration minimum_value = 0 and maximum_value = 100, the event is ignored.