app/docs/reference/node-types.md

Node types

Built-in nodes cover common integrations, timing, and logic. Configure their settings in the node panel; use a Function node for your own Python.

GET /flows/node-types returns this list with each type's full parameter schema, including any connectors installed on your instance.

MQTT and InfluxDB need pip install 'fluksio[server]' on a Python installation. The Docker image includes these dependencies. Run the broker and database separately, or use the development stack's test services.

Function

python — run your own code when its triggering inputs arrive.

The one type with a source file. Its arguments are its input ports and its own settings; its return value is a dict keyed by output ports. See Writing node code.

Settings on a Function node are free-form: you add them by name, and they arrive as keyword arguments.

Integrations

MQTT

mqtt — subscribe to topics, or publish what arrives on its inputs.

A node with outputs only subscribes; a node with inputs publishes.

Setting	Default	Notes
topic	*	one topic for every port, or {"message": "some/topic"} per port
broker_host	localhost
broker_port	1883
username / password	—	password takes a secret reference
client_id	—
qos	0	0, 1 or 2
retain	false	on published messages
keepalive	60	seconds
timeout	10.0	seconds before a broker operation is given up on
publish_queue_size	256	payloads that may wait for the broker; past this the oldest is dropped and the node reports degraded
json_key	—	key to lift out of an object payload; one for every port, or {"port": "key"}

A topic may be a filter: + matches one level, # the rest. Everything a filter matches lands on the same port, so use one port per topic where the difference matters.

Set an explicit topic: the default * is a literal topic, not MQTT's match-all filter.

For {"value": 47}, set json_key to value. Without it, an object is unwrapped only if it contains the port's name as a key.

HTTP

http — receive data on a webhook, or send it to a URL.

Outputs only makes it a webhook: the engine mounts a route at /hooks/{flow}/{url}/{secret} while the flow runs. Inputs make it a sender.

Setting	Default	Notes
url	—	the route path in webhook mode, the full URL in sender mode
method	POST	GET or POST
timeout	30	seconds, sender mode
headers	{}
query	{}	fixed query parameters; a value may be a secret reference
send_inputs	true	off when the inputs only trigger the request
secret	—	shared secret appended to the webhook URL; takes a secret reference

!!! warning "A webhook with no secret is open to anyone who can reach the host."

The canvas flags this as an advisory issue rather than stopping the flow,
because a webhook on a private network is a legitimate thing to want.

WebSocket

websocket — listen on a socket, or send to it, as a client or a server.

The URL picks the role: ws://… or wss://… connects to a server and reconnects when it drops; a path such as /ticker is served at /hooks/{flow}/{url}/{secret} while the flow runs. The ports pick the direction: outputs only make a listener, inputs a sender. A served sender sends to every connected client.

Setting	Default	Notes
url	—	ws:// or wss:// URL, or the path to serve
headers	{}	handshake headers, client only; a value may be a secret reference
on_connect	[]	frames sent after every (re)connect, client only — a subscribe or auth message; an item may be a secret reference
secret	—	shared secret appended to a served socket's URL; takes a secret reference
timeout	10.0	seconds for the handshake, and for a send to one client of a served socket
send_queue_size	256	messages that may wait to be sent; past this the oldest is dropped and the node reports degraded
json_key	—	as on mqtt

Frames are text. An incoming frame is parsed as JSON: an object feeds the ports it names, and a node with a single output takes any other frame whole. A single input is sent as it stands — a string raw, anything else as JSON — and several go as one object keyed by port.

InfluxDB

influxdb — write measurements to a bucket, or read them back.

Setting	Notes
url, token, org, bucket	connection; token takes a secret reference
write_precision	ns, us, ms (default) or s
query_range	default window for queries, e.g. -1h
timeout	operation timeout in seconds; default 10.0
writes	per-input: measurement, field, tags
queries	per-output: measurement, field, tags, range, aggregation

{
  "writes": {
    "living_temperature": {
      "measurement": "environment",
      "field": "temp_c",
      "tags": {"room": "living"}
    }
  }
}

Query passthrough. An incoming object with a flux key supplies the query. The first output receives an object with rows, each containing ts, value, field, measurement, and tags. Use Function nodes to build queries and shape results for charts.

Notification

ntfy — push an incoming value to a phone through ntfy.

Setting	Default	Notes
server	https://ntfy.sh
topic	—	required
title	—
priority	default	min, low, default, high, urgent
tags	—	comma-separated ntfy tags
token	—	for a protected topic; takes a secret reference
timeout	10.0	request timeout in seconds

For engine failures rather than flow messages, configure Alerts.

Timing

Inject

inject — emit a value on request, on a timer, or when the flow starts.

Setting	Default	Notes
payload	current time	what to emit
payloads	{}	per-output-port payloads, keyed by port
interval	0	emit every n seconds; 0 means never on its own
cron	—	a five-field cron expression
at_start	false	emit once when the flow starts
start_delay	1.0	how long to wait before that first emission

Use cron for scheduled emissions, or trigger the node by hand for testing.

Delay & schedule

delay — hold messages back, limit their rate, or emit on a schedule.

Setting	Default	Notes
delay	0	seconds to hold each message, fractional
interval	0	minimum seconds between forwards, per output
mapping	{}	input port → output port; paired in order when empty
cron	—	five-field expression

Order of operations: delay → rate check → forward. A message arriving inside the interval window is held, and when the window ends the latest one held is sent. With a cron and no inputs it emits the current time on each tick; with inputs it emits the last value it received.

Timers wait until their deadline; busy workers can delay execution.

!!! note "Not in a batch flow"

Batch flows reject rate-limited non-streaming ports. Runs have no live
timer to release a held value.

Trigger

trigger — send one value now and another once things go quiet. Despite the name, a debounce and hold rather than a scheduler: everything it sends starts from a value arriving. For a cron tick, see inject.

Setting	Default	Notes
first	true	sent as soon as a value arrives
then	false	sent when the wait expires; empty sends nothing
wait	60	seconds of quiet before the second value
extend	true	a value arriving during the wait starts it over
passthrough	false	send the incoming value instead of first
wait_port	—	an input carrying the wait, when it differs per message

For example: turn a light on when the door opens, then off after two quiet minutes.

Use wait_port when the delay comes from an input. A wait of zero or less cancels the pending second value and schedules nothing new.

Logic

Switch

switch — send a value down one branch or another, by rule.

Each rule names an output port; a matching value leaves through that port. Comparisons: eq, ne, gt, gte, lt, lte, contains, between.

Setting	Default	Notes
rules	[]	checked in order; each names the output it routes to
stop_at_first	true	leave through the first matching rule only
otherwise	—	output for a value that matched nothing

Comparing a string to a number is a mistake in the rule, not a reason to take the flow down: the rule simply does not match.

Change

change — scale, offset, round or map a value on its way past.

Setting	Default	Notes
scale	1.0	multiply numbers by this
offset	0.0	then add this
round_to	—	decimal places
mapping	{}	replace a value with another, looked up as text
default	—	value when the lookup misses; empty passes it through

Filter unchanged

rbe — pass a value on only when it has actually changed.

Setting	Default	Notes
deadband	0.0	ignore numeric changes smaller than this
deadband_percent	false	read the deadband as a percentage

The cheapest fix for a sensor that reports every second and changes every hour.

Join

join — gather several inputs into one object or list.

Setting	Default	Notes
mode	object	object or array

System

Command

exec — run a command where the engine runs and read its output. Adding one or changing its settings requires a superuser.

Setting	Default	Notes
command	—	the command to run
append_payload	false	add the incoming value as one argument
timeout	30	seconds
fail_on_error	false	treat a non-zero exit as a node failure rather than output

Outputs the command's stdout, stderr and exit code.

In Docker, the command runs inside the backend container. Mount host files explicitly if the command needs them.

File

file — read a file into the flow, or write one out of it.

Setting	Default	Notes
path	—	relative to the engine's files directory
mode	read	read, write or append
format	text	text or json
newline	true	end each written record with a newline

Paths stay inside the engine's files directory.

Numeric

Perceptron

mlp — a small neural layer over its numeric inputs.

output = weights @ inputs + biases, with weights drawn from seed so a node reloads identically.

Setting	Default	Notes
seed	0

A worked example of numeric logic, not a modelling tool. To train something, use a batch flow and a Function node.

Language

Wren

wren — turn a typed command into values for the devices wired to it.

Wren is an optional local language model for device commands. Install it in the engine's environment with pip install wren; the node reports a missing dependency if it is absent.

Input	Type	Notes
prompt	str	the command, and the only input that runs the node
presence	str	the area the user is in; anything else reads as away
outdoor	float or int	°C; 20 without it, clamped to −5…30
dark	bool	without it, dark before 07:00 and from 18:00

The outputs are actions, a list of records, and any number of targets. A target is an output named <area>_<kind> and bound to the message its device listens on: living_room_setpoint bound to home.setpoint is the living room's heating. The wiring is the allowlist, so the model can write nothing that is not wired to the node.

• area: living_room, kitchen, bathroom, bedroom, office, garden, patio, garage, driveway, balcony
• kind: light, lamp, brightness for a light; setpoint, heating, heat, boost for heating; media, music, tv; shutter, blind, cover; water, watering, sprinkler

A port naming anything else is refused when the flow is built. A port is named after its message unless it is given a name of its own, in the node panel's port name field or as {"name": "setpoint", "port": "living_room_setpoint"} through the flow API.

Targets of one area and kind are one device to the model, and each takes what a call means for its type. A target's current value is the state the model reads.

Call	bool	number	str
lights.on / off	true / false	100 / 0	on / off
media.play / stop	true / false	—	play / stop
heating.set	—	the temperature	—
heating.boost / off	true / false	—	boost / off
shutters.up / down	true / false	100 / 0	up / down
shutters.stop	—	—	stop
watering.start / stop	true / false	—	on / off

Setting	Default	Notes
apply	false	write to the targets; off, the node only reports
min_confidence	0.93	below this nothing is written

Each record in actions contains message, value, applied, delay_s, call, and confidence. Unwired calls have an empty message and are not applied. Keep apply=false while checking how the model interprets commands.

A call with a delay ("in 10m") is held by the engine's work queue, like the Trigger node's second value: it survives a restart where the queue is in Redis, and not otherwise.

The node adds default devices to the model's view for missing expected devices. They are reported but cannot receive writes unless wired.

!!! note "What the current model cannot do"

Commands are English, such as "turn on the lights in the kitchen".
The model uses the areas above, one device per kind and area, on/off
actions, and whole-minute delays. It does not dim lights or set colors.

The chat's Control tab sends commands by hand.

Connectors

Installed connector packages add types through the fluksio.node_types entry point group. The editor shows the source package. Incompatible contract versions are skipped; installing or upgrading a connector requires an engine restart.

The contract itself is in The connector contract, and Writing a connector walks through building one.

See also

• Payload types — what a port may carry
• Writing node code — the Function node
• The flow editor — placing and configuring them