Actions Reference

Actions are commands sent from Vesbite to a device. Each device definition declares the actions it supports, including the parameters each action accepts and the shape of its response. Actions are delivered to devices over RabbitMQ using routing keys of the form devices.{deviceId}.actions.{actionName}.

Action Structure

Every action defined on a device has the following properties:

Property	Type	Description
`name`	string	Machine-readable identifier (e.g., `startreading`)
`displayName`	string	Human-readable label shown in the UI (e.g., “Start Reading”)
`description`	string	Explanation of what the action does
`requestSchema`	JSON	JSON Schema describing the parameters the action accepts
`responseSchema`	JSON	JSON Schema describing the data the action returns

How Actions Are Invoked

From the Device Page

Navigate to Devices and select a device.
Open the Actions tab.
Choose an action from the list.
Fill in any required parameters.
Click Execute.

From a Workflow

Add an Invoke Device Action node to your flow. Select the target device and action, then configure the parameters. Parameters support Vex expressions for dynamic values.

Via the API

Send an InvokeDeviceAction command through the API gateway. The request is routed to the Devices service, which publishes it to RabbitMQ with the routing key devices.{deviceId}.actions.{actionName}.

Request Format

When an action is invoked, Vesbite publishes the following payload to RabbitMQ:

{
  "deviceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "action": "startreading",
  "parameters": {
    "duration": 30,
    "antennas": [1, 2]
  }
}

The parameters field matches the action’s requestSchema. If the action accepts no parameters, this field is null.

Response Format

The device replies with a structured response:

{
  "success": true,
  "result": {
    "startedAt": "2026-03-20T10:30:00Z",
    "activeAntennas": [1, 2]
  },
  "error": null
}

On failure:

{
  "success": false,
  "result": null,
  "error": "Reader is already in an active reading session"
}

If the device does not respond within 30 seconds, the action times out and returns:

{
  "success": false,
  "result": {},
  "error": "Request timed out"
}

Common RFID Reader Actions

startreading

Begins an inventory session on the reader.

Parameters:

Parameter	Type	Required	Description
`duration`	number	No	Duration in seconds. Omit for continuous reading.
`antennas`	array	No	Antenna port numbers to use (e.g., `[1, 2]`). Omit for all.

Response:

Field	Type	Description
`startedAt`	string	ISO 8601 timestamp when reading began
`activeAntennas`	array	Antenna ports activated

Example:

// Request
{ "duration": 60, "antennas": [1, 2, 3, 4] }

// Response
{ "startedAt": "2026-03-20T10:30:00Z", "activeAntennas": [1, 2, 3, 4] }

stopreading

Stops an active inventory session.

Parameters: None.

Response:

Field	Type	Description
`stoppedAt`	string	ISO 8601 timestamp when reading stopped
`tagsRead`	number	Total tags read during the session

Example:

// Request
{}

// Response
{ "stoppedAt": "2026-03-20T10:31:00Z", "tagsRead": 247 }

encodetag

Writes data to an RFID tag’s EPC memory bank.

Parameters:

Parameter	Type	Required	Description
`epc`	string	Yes	Target tag’s current EPC
`newEpc`	string	Yes	New EPC value to write
`accessPassword`	string	No	Access password if the tag is locked

Response:

Field	Type	Description
`success`	boolean	Whether the write succeeded
`previousEpc`	string	The tag’s EPC before the write
`newEpc`	string	The tag’s EPC after the write

Example:

// Request
{ "epc": "E2801170000002145A8B6021", "newEpc": "E28011700000AABB11223344" }

// Response
{ "success": true, "previousEpc": "E2801170000002145A8B6021", "newEpc": "E28011700000AABB11223344" }

setgpio

Sets the state of a General Purpose Output (GPO) pin.

Parameters:

Parameter	Type	Required	Description
`pin`	number	Yes	GPO pin number
`state`	boolean	Yes	`true` for high, `false` for low

Response:

Field	Type	Description
`pin`	number	The GPO pin that was set
`state`	boolean	The new state of the pin

Example:

// Request
{ "pin": 1, "state": true }

// Response
{ "pin": 1, "state": true }

readtagmemory

Reads data from a specific memory bank on an RFID tag.

Parameters:

Parameter	Type	Required	Description
`epc`	string	Yes	Target tag’s EPC
`memoryBank`	string	Yes	Memory bank: `reserved`, `epc`, `tid`, or `user`
`wordOffset`	number	Yes	Starting word offset
`wordCount`	number	Yes	Number of 16-bit words to read
`accessPassword`	string	No	Access password if required

Response:

Field	Type	Description
`data`	string	Hex-encoded data read from the tag
`memoryBank`	string	The memory bank that was read

Example:

// Request
{ "epc": "E2801170000002145A8B6021", "memoryBank": "user", "wordOffset": 0, "wordCount": 4 }

// Response
{ "data": "48656C6C6F576F726C6421", "memoryBank": "user" }

writetagmemory

Writes data to a specific memory bank on an RFID tag.

Parameters:

Parameter	Type	Required	Description
`epc`	string	Yes	Target tag’s EPC
`memoryBank`	string	Yes	Memory bank: `reserved`, `epc`, `tid`, or `user`
`wordOffset`	number	Yes	Starting word offset
`data`	string	Yes	Hex-encoded data to write
`accessPassword`	string	No	Access password if required

Response:

Field	Type	Description
`success`	boolean	Whether the write succeeded
`wordsWritten`	number	Number of words written

Example:

// Request
{ "epc": "E2801170000002145A8B6021", "memoryBank": "user", "wordOffset": 0, "data": "48656C6C6F" }

// Response
{ "success": true, "wordsWritten": 3 }

Using Action Responses in Workflows

When you use an Invoke Device Action node in a workflow, the response data is available through expressions:

{{ output("actionActivityId").success }}
{{ output("actionActivityId").payload }}
{{ output("actionActivityId").deviceId }}

Actions Reference

Action Structure

How Actions Are Invoked

From the Device Page

From a Workflow

Via the API

Request Format

Response Format

Common RFID Reader Actions

startreading

stopreading

encodetag

setgpio

readtagmemory

writetagmemory

Using Action Responses in Workflows

See Also