Convert

The Convert operation coerces a single input value into a chosen target type. It is the canonical way to turn MQTT payload strings into numbers, booleans into labels, or numeric results into formatted strings — all through one explicit node with a single On Error verb.

Inputs

Port	Type	Required	Description
>	Boolean	No	Optional gate. When closed, the path stops without an error signal.
In	String | Binary | Number | Boolean | Map | Array	Yes	The value to convert. Binary is decoded as UTF-8 before further rules apply, except for the JSON text target, which takes a Binary as base64. A Map or an Array is read by the JSON text target only.

Outputs

Port	Type	Default	Description
Out	follows Output Format	Nil	The converted value, typed per the selected Output Format.

Properties

Name	Type	Default	Description
Output Format	StackedDataSet	Strict Integer	The target type and branch-specific fields (see table below).
Strict Integer			Input must be integer-valued; any fractional content fails the Node.
Truncated Integer			Fractional inputs truncate toward zero (-2.9 → -2).
Rounded Integer			Fractional inputs round half-away-from-zero (0.5 → 1).
Float			Any numeric-parsable input becomes a double-precision Number.
String			Rendered via fmt format spec. Boolean inputs bypass fmt — see True text / False text.
Format	String	"{}"	fmt-style format string. Default {} emits each input’s natural form.
True text	String	"true"	Emitted when the input is Boolean true.
False text	String	"false"	Emitted when the input is Boolean false.
Boolean			String / Binary inputs are matched against True / False value lists. Numeric input != 0 is true.
True values	String	"true,1,yes,on"	Comma-separated list of strings that map to true.
False values	String	"false,0,no,off"	Comma-separated list of strings that map to false.
Case sensitive	Boolean	false	Off = case-insensitive ASCII match.
JSON text			The input as JSON, through the one mapping every egress uses: integers as digits, floats shortest round-trip, binary as base64, an address as its text. Any input.
On Error	Combo	Stop this branch	Per-op On Error verb (Stop this branch / Continue with the last value / Continue with the fallback). See the Error Handling guide.

State on Reload

Output values are preserved across restarts within the configured time window.

---

Conversion Rules

Input	Strict Integer	Truncated Integer	Rounded Integer	Float	String	Boolean	JSON text
Integer 42	42	42	42	42.0	via Format	!= 0	JSON
Float 42.0	42	42	42	42.0	via Format	true	JSON
Float 42.7	fail	42	43	42.7	via Format	true	JSON
Float -42.7	fail	-42	-43	-42.7	via Format	true	JSON
Float NaN / ±Inf	fail	fail	fail	pass-through	via Format	fail	JSON
Boolean true / false	1 / 0	1 / 0	1 / 0	1.0 / 0.0	True text / False text	true / false	JSON
String "42"	42	42	42	42.0	via Format	match lists	JSON
String "42.7"	fail	42	43	42.7	via Format	match lists	JSON
String "42abc"	fail	fail	fail	fail	via Format	match lists	JSON
String "hello"	fail	fail	fail	fail	via Format	match lists	JSON
String empty / whitespace	fail	fail	fail	fail	via Format (empty OK)	fail	JSON
Binary (valid UTF-8)	decode → String rules	decode → String rules	decode → String rules	decode → String rules	decode → Format	decode → match lists	JSON
Binary (invalid UTF-8)	fail	fail	fail	fail	fail	fail	JSON
Map	fail	fail	fail	fail	fail	fail	JSON
Array	fail	fail	fail	fail	fail	fail	JSON

“fail” rows fail the Node, and its On Error verb resolves the failure.

Rounding mode

Rounded Integer uses half-away-from-zero rounding (C std::round semantics), NOT banker’s rounding. 0.5 → 1, -0.5 → -1, 2.5 → 3, -2.5 → -3. If you need banker’s rounding, pre-process with a small JavaScript node.

String output and Boolean input

When Output Format is String and the input is a Boolean, the Format field is bypassed — the True text / False text fields are emitted directly. This lets you render "Yes" / "No" or locale-specific labels without writing custom fmt formatters. Non-Boolean inputs always go through fmt::format(Format, value).

Boolean value lists

Comma-separated list fields accept any number of entries. The server trims whitespace on each entry and drops empty entries. No escape mechanism exists for literal commas — boolean-like keywords never contain commas. Case sensitive = false lowercases the ASCII letters only (locale-independent); full-Unicode-aware case folding for boolean keywords isn’t needed in practice.

---

Examples

String → Integer

Output Format: Strict Integer   In: "42"

Out: 42

Float → Integer (rounded)

Output Format: Rounded Integer   In: 3.7

Out: 4

Integer → formatted String

Output Format: String   Format: "Temperature: {}°C"   In: 23

Out: "Temperature: 23°C"

Float → fixed-precision String

Output Format: String   Format: "{:.3f}"   In: 3.14159

Out: "3.142"

Boolean → labelled String

Output Format: String   True text: "Yes"   False text: "No"

In: true → Out: "Yes"   In: false → Out: "No"

String → Boolean

Output Format: Boolean   True values: "true,1,yes,on"   False values: "false,0,no,off"   Case sensitive: false

In: "YES" → Out: true   In: "off" → Out: false   In: "maybe" → fail

---

Use Cases

• MQTT payload parsing — the MQTT Subscription passes payloads as strings; feed into a Convert node to get a typed value ready for Math, Compare, or Hysteresis.
• Display formatting — turn an intermediate number or boolean into a user-facing string with fmt specifiers or custom labels.
• Normalising truthy strings — collapse “yes” / “true” / “1” / “enabled” from different producers into a single Boolean for downstream Gates.

---

Error Handling

Convert can hit these errors: an unconnected input, a Nil value, an unparseable string / binary, an out-of-range numeric result (for Integer targets), an invalid UTF-8 byte sequence (for Binary input), or a Format spec that doesn’t match the input type (for String output).

Any of these triggers the On Error verb you picked. See the Error Handling guide for the common On Error model; Convert’s options are:

Verb	What it does
Stop this branch (default)	This Node and its dependents stop; Out keeps its value and reads as a failed update.
Continue with the last value	Dependents run on the value Out already holds, not stamped as new; it reads as a failed update.
Continue with the fallback	Dependents run on Out’s per-output Fallback, stamped as this run’s value; it reads as a failed update. The Editor refuses a Task where the Fallback is unset.

The per-output Fallback editor (Settings panel, under the Out port) lets you pick the fallback type — Boolean / Integer / Float / String — and enter the value. Match the type to the chosen Output Format so downstream type-mask checks accept the fallback. For Float outputs, you can enter a NaN literal directly into the Float fallback field for the classic divide-by-zero detection pattern downstream.

---

Limitations

• Only one transformation per operation; for chained conversions (e.g. trim → parse int), chain a StringOperations node into a Convert node.
• ASCII-only case folding for Boolean value-list matching. If you need to accept Unicode-cased truthy strings (e.g. Turkish i/ı), pre-normalise with StringOperations’ Lowercase transform.
• NaN and ±Inf are not accepted as literal strings on the wire for Float output; if you genuinely need to emit NaN, use the NaN fallback branch, or use a Constant node.