Guide / Controls / Reference

Actions

How controls send commands — the outbound half of the standardized connection block. The payload vocabulary ({{value}} and friends) is identical across transports; method picks the wire.

Symbol
bolt.fill
Docs
Docs complete

Fields

25 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
methodmethodtext—

How the action travels

Picks the wire the action goes out on: meshsocket, mqtt, http or local (the on-device store).

modemodetext—

Wait for a reply or not

broadcast sends and moves on; request waits for the reply, which only a route_msg command ever gets (meshsocket only).

eventeventtext—

The message type sent

Sent as-is as the MeshSocket frame type, so it must be a relay verb such as broadcast_request; the command name goes in the payload instead.

payloadpayloadobject—

The data to send

The body sent with the action, with {{value}} replaced by the control's current value.

sourcesourcetext—

Which connection to use

Sends through the layout's named source (mqtt, http or local) instead of spelling out the address.

topictopictext—

Where to publish

The MQTT topic the message is published to.

retainretainon / offfalse (off)

Keep the last message

Publishes with the MQTT retained flag so new subscribers get the last value straight away.

urlurltext—

The full web address

The absolute address an http action requests.

pathpathtext—

The part after the host

The path added to the source's base address for an http action.

httpMethodhttpMethodtext—

GET, POST and so on

The HTTP verb used; it is POST when there is a payload and GET when there is not.

headersheadersobject—

Extra request headers

Adds these headers to this action's http request only.

opopchoiceone of 9—

What to do to the data

Chooses the on-device store operation the action runs: write, change, remove or read rows, or adjust a single saved value.

  • insertadds a new entry to the collection
  • updatechanges the fields you name on the entry with this id
  • upsertupdates the entry if it exists, otherwise adds it
  • deleteremoves the entry with this id
  • selectmoves the collection's selection to the entry with this id
  • setpatches the named fields of a singleton collection's one row
  • incrementadds the step to a number field of a singleton collection
  • decrementsubtracts the step from a number field of a singleton collection
  • toggleflips a true or false field of a singleton collection
collectioncollectiontext—

Which list to change

The on-device collection the operation reads or writes.

ididtext—

Which entry

The entry the operation acts on; {{selected}} uses the collection's current selection.

setsetobject—

The values to save

The field values written by insert, update, upsert or a singleton set, with {{value}} and the store tokens filled in first.

fieldfieldtext—

Which saved value

The single field of a singleton collection that increment, decrement or toggle changes.

bybynumber1

How much to add or take

The step an increment or decrement applies, 1 when unset; a decrement subtracts it, and whole-number fields only take whole steps.

Confirm firstconfirmchoiceone of 1—

Ask before sending

Shows the app's own confirmation dialog first; the action goes out only when the user taps the confirm button. It applies to taps, form submits and drags in the app; a widget, Live Activity, Control Center or Siri press cannot draw the dialog, so those never fire it.

  • dialoga dialog drawn by the app that names this layout and where the action goes; Cancel sends nothing; widgets, the Dynamic Island, Control Center and Siri never fire it, so a tile bound to it is not offered
Dialog titleconfirmTitletext—

The dialog's question

The headline of the confirmation dialog; without it the control's label is used.

Dialog messageconfirmMessagetext—

More detail under the question

A line or two under the headline that says what will happen.

Confirm buttonconfirmLabeltext—

The word on the confirm button

The text on the button that sends the action, such as Remove or Restart; Confirm when unset.

Destructivedestructiveon / offfalse (off)

Mark it as hard to undo

Draws the dialog's confirm button in red, for removals and other changes that cannot be taken back.

Expand groupexpandtext—

Open a group's expanded view

Expands the group (or, from a control inside a list row, that list's row) with this id, as if its card was tapped. No transport is used, so method can be left out.

Collapse groupcollapsetext—

Close a group's expanded view

Closes the expanded view when it was opened from the group (or list row) with this id; nothing happens otherwise.

Toggle expandtoggleExpandtext—

Open or close a group's expanded view

Closes the group's expanded view when it is open, opens it when it is not.

Examples

3 examples, each one a control you can paste into a layout.

Remove with a confirmation dialog

Asks first, then tells the hub to remove an item only if the user confirms.

JSON 7 lines
{
  "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request",
  "payload": { "msg_type": "item.remove", "id": "{{value}}" },
  "confirm": "dialog", "confirmTitle": "Remove this item?",
  "confirmMessage": "It is removed from the hub.", "confirmLabel": "Remove",
  "destructive": true
}

Count a tap in the local store

Adds 1 to the saved count on the phone each time the control is tapped.

JSON 1 line
{ "method": "local", "op": "increment", "collection": "counter", "field": "count" }

Open a group from a button

Opens the expanded view of the group with this id, with no transport involved.

JSON 1 line
{ "expand": "pkg" }

Edit hint — the Binding view. The fields marked edit: data (method, the address for each method: event, topic, url, collection; payload, with {{value}}) are the ones the edit pose's binding view edits up front as what using the control sends. A payload must be a JSON object; the other keys (mode, headers) stay as written.

Edit hint — Ask first. confirm names edit: ask: the binding view's send card asks what a tap does (Send, or one of the edit: pick-control / axis: group fields here, expand, collapse, toggleExpand, with a group picked from the layout) and whether it asks first: Never, Undo after (the control's own confirm: true pill, offered when the control's doc has it) or Ask before (confirm: "dialog"), with the app's dialog drawn live so confirmTitle, confirmMessage and confirmLabel are typed on it and destructive turns its button red.

Definition

"action": {
  "method": "meshsocket",
  "mode": "broadcast",
  "event": "broadcast_request",
  "payload": { "msg_type": "set_power", "state": "{{value}}" }
}

event vs msg_type (meshsocket)

The app sends event verbatim as the MeshSocket frame type, and the relay only dispatches its own verbs — broadcast_request (fan-out to every other member of the channel), route_msg (targeted request/reply) and route_msg_noreply (targeted fire-and-forget). Any other name (set_power, broadcast, arm, …) is silently dropped: nothing errors, no server handler ever runs, the control does nothing.

So the command name never goes in event. Put it in payload.msg_type — the relay re-emits a broadcast_request to the channel as a broadcast frame, and servers demux on msg_type (carterkit's Hub.on("set_power") and bind.command("set_power") are the two halves of exactly this shape).

Targeted send, when you hold a live relay-assigned target_id (a name is not resolved here — use route_msg_noreply with target_name for that):

"action": {
  "method": "meshsocket",
  "mode": "request",
  "event": "route_msg",
  "payload": { "target_id": "<relay id>", "type": "set_power",
               "payload": { "state": "{{value}}" } }
}

The same command over other transports (see Data Sources):

{ "method": "mqtt", "topic": "power/set", "payload": "{{value}}" }
{ "method": "http", "path": "/api/power", "httpMethod": "POST",
  "payload": { "state": "{{value}}" } }
{ "method": "local", "op": "insert", "collection": "events",
  "set": { "kind": "power", "state": "{{value}}", "at": "{{now}}" } }

Modes (meshsocket)

Mode Behavior
broadcast Fire and forget — the mode for broadcast_request and route_msg_noreply
request Send + await response — only meaningful with route_msg (the relay routes the target's reply back); on a broadcast_request nothing ever replies, so the tap just waits out the timeout

Need an answer to a broadcast command? Use the round trip instead: fire the command, and Sync the control to the state broadcast the server sends back.

MQTT publishes and HTTP requests are fire-and-forget; failures surface in the connection console. Ack'd commands (layout state.acks) are a MeshSocket contract and don't apply to mqtt/http actions.

Substitution

{{value}} in any string becomes the current control value: - Knob shadow: true / false - Track roundness: 75.0 - Border thickness: "Ocean"

A string that is exactly "{{value}}" keeps the value's native type (numbers stay numbers, bools stay bools). Over MQTT, a string payload publishes as raw bytes (ON, not "ON"); objects publish as JSON.

{{secret:name}} fills in a credential from the phone's Keychain when the action is sent, never earlier (Secrets). It works in an HTTP action's url path/query, headers and payload, an MQTT action's payload, and a MeshSocket action's payload. Only the text you wrote in the action is filled in; a {{secret:…}} that arrives inside {{value}} is sent as plain text. The secret must be allowed at the destination:

  • an HTTP or MQTT action goes to its host, which must be a declared source's host or listed in the secret's hosts. An absolute url on any other host needs "hosts": ["that.host"] in the declaration;
  • a MeshSocket action goes to every peer in the room, so the secret needs "mesh": true. Without it the action is not sent and the console logs secret <name> not allowed for the mesh.

Local store

With method: "local" an action writes the layout's on-device Local Store instead of sending anything. op is one of insert, update, upsert, delete or select; collection names the target; id picks the row for update/upsert/delete/select ("{{selected}}" uses the collection's selection cursor) and set maps declared fields to values for insert/update/upsert. payload is not used. Tokens are substituted into set and id first — {{value}} and the control's own tokens plus {{now}}, {{today}}, {{startOfWeek}}, {{startOfMonth}}, {{startOfYear}} and {{selected}} — and an exact-token string keeps its native type, so "pages": "{{value}}" from a Symbol color stores a number. Values are validated against the declared types (reject, never coerce); a failure is a console line and a red Local pipe, never an alert. Delete is by id only.

A Form's submit action also gets {{form}} (the whole draft object) and {{form.<field>}} (one draft field), on any transport: "set": "{{form}}" for a local insert/update, "payload": "{{form}}" for http or meshsocket.

A collection declared singleton: true holds exactly one row, and four more ops write it without an id: set patches the named fields, increment / decrement add or subtract by (default 1) from a number or integer field, and toggle flips a bool field. Each creates the row from the collection's defaults on its first write.

These four are what the editor's Action tab writes: its verbs Record time, Add 1, Subtract 1 and Set to… compile to set with {"field": "{{now}}"}, increment, decrement (no by) and set with one literal field.

Confirmation and Undo

A control with "confirm": true (the editor's Show confirmation, on the Action tab; off by default) shows a short pill after each of its local writes lands: what changed and an Undo button, e.g. Count · 84 [Undo]. The pill stays for 3 seconds; the control's next write replaces it, and a write from a control without confirm takes it down. Undo is one level:

  • a singleton op (set / increment / decrement / toggle) puts the touched fields back to their prior values (a first write goes back to the default, else null) through an ordinary set;
  • an insert removes the new entry, a delete brings the entry back from Recently deleted, and an update / upsert restores the row exactly.

A Form's submit follows the submitting button's confirm. Without confirm a write is silent. The entry sheet and the data browser always offer Undo for their own adds, edits and deletes.

{ "method": "local", "op": "update", "collection": "books", "id": "{{selected}}",
  "set": { "rating": "{{value}}" } }
{ "method": "local", "op": "increment", "collection": "counter", "field": "count" }
{ "method": "local", "op": "toggle", "collection": "settings", "field": "muted" }

Confirm dialog

"confirm": "dialog" on an action asks first: the app draws its own confirmation dialog over the whole screen and sends the action only when the user taps the confirm button. Cancel, or 60 seconds without an answer, sends nothing, and a Knob shadow the tap already flipped goes back. It works on any action and any transport (a Long Press action, a row or chart tap, a local write). The dialog is app chrome, not layout styling: it names the layout and where the action goes (Workshop over Layout · Connect+ · lights), with confirmTitle (default the control's label), confirmMessage, confirmLabel (default Confirm) and destructive: true for a red confirm button.

"action": {
  "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request",
  "payload": { "msg_type": "item.remove", "id": "{{value}}" },
  "confirm": "dialog", "confirmTitle": "Remove this item?",
  "confirmMessage": "It is removed from the hub.", "confirmLabel": "Remove",
  "destructive": true
}

This is a different option from the control's "confirm": true (the Undo pill above): the pill reports a local write after it lands, the dialog stops an action before it is sent. Shortcuts, widgets and Control Center do not offer an action that asks first: it fires only in the app.

Expand and collapse

{"expand": "<group id>"}, {"collapse": "<group id>"} and {"toggleExpand": "<group id>"} act on the app's expanded view instead of a transport (leave method out). Any control can carry one: a "More" button with "action": {"expand": "pkg"} opens group pkg from anywhere in the layout. A control inside a list row names the list's id ({"expand": "packages"}) and opens its own row. They are the same path as the group's own tap, an expand.trigger control and the hub's sheet frame (Expand). An id that matches nothing on screen does nothing.

Hub prompts

A layout's hub can ask the user to confirm something (before it installs, removes or deletes anything) with the routed prompt verb on the layout's socket. The app draws the same frame, naming the hub and its connection (Example hub over Hub · Connect+ · lights), one prompt at a time, and answers with a broadcast_request the hub receives like any action:

{ "id": "req-7", "title": "Remove the package?", "message": "You can install it again later.",
  "confirm": { "label": "Remove", "role": "destructive" }, "cancel": { "label": "Keep" },
  "timeoutS": 60, "hub": "Example hub" }

{ "msg_type": "prompt_reply", "id": "req-7", "choice": "confirm", "from": "<device>" }

choice is confirm, cancel, timeout or busy. Only the layout on screen's own connection may ask (and, when the layout names a state.authority, only a frame whose from is that authority); at most 3 wait behind the one shown and 5 are taken per 30 seconds, the rest answer busy. The full wire contract is in docs/HUB-PROMPT.md.

Generated from ControlDocs/actions.md. Something unclear or missing? Tell me.