Settings Reference

Settings are configurable parameters defined in the device definition’s settings schema. Vesbite automatically generates a tabbed settings form based on this schema. When settings are saved, they are pushed to the device over RabbitMQ using the routing key devices.{deviceId}.settings.

Settings Schema Structure

A settings schema is composed of tabs, each containing a list of fields. This structure maps directly to the tabbed form rendered in the device settings UI.

{
  "tabs": [
    {
      "label": "RF Settings",
      "elements": [
        {
          "type": "slider",
          "key": "transmitPower",
          "label": "Transmit Power (dBm)",
          "min": 10,
          "max": 30,
          "step": 0.5,
          "default": 25
        },
        {
          "type": "select",
          "key": "session",
          "label": "Session",
          "options": [
            { "value": "S0", "label": "Session 0" },
            { "value": "S1", "label": "Session 1" },
            { "value": "S2", "label": "Session 2" },
            { "value": "S3", "label": "Session 3" }
          ],
          "default": "S1"
        }
      ]
    }
  ]
}

Tab Definition

Field Types

Every field shares a common set of base properties, plus type-specific properties.

Common Field Properties

text

A single-line text input.

{
  "type": "text",
  "key": "hostname",
  "label": "Reader Hostname",
  "placeholder": "e.g., reader-01.local",
  "default": "",
  "maxLength": 253,
  "pattern": "^[a-zA-Z0-9.-]+$"
}

textarea

A multi-line text input.

{
  "type": "textarea",
  "key": "notes",
  "label": "Notes",
  "rows": 4,
  "maxLength": 1000
}

password

A masked text input for sensitive values.

{
  "type": "password",
  "key": "accessPassword",
  "label": "Access Password",
  "placeholder": "Enter password",
  "minLength": 8
}

number

A numeric input with optional constraints.

{
  "type": "number",
  "key": "reportIntervalMs",
  "label": "Report Interval (ms)",
  "default": 500,
  "min": 100,
  "max": 10000,
  "step": 100
}

slider

A range slider with a visual track.

{
  "type": "slider",
  "key": "transmitPower",
  "label": "Transmit Power (dBm)",
  "min": 10,
  "max": 30,
  "step": 0.5,
  "default": 25
}

toggle

A boolean on/off switch.

{
  "type": "toggle",
  "key": "enableFiltering",
  "label": "Enable Tag Filtering",
  "default": false
}

select

A dropdown menu with predefined options.

{
  "type": "select",
  "key": "searchMode",
  "label": "Search Mode",
  "options": [
    { "value": "dual-target", "label": "Dual Target" },
    { "value": "single-target", "label": "Single Target" },
    { "value": "single-target-reset", "label": "Single Target with Reset" }
  ],
  "default": "dual-target"
}

checkbox-group

A group of checkboxes for multi-select.

{
  "type": "checkbox-group",
  "key": "enabledAntennas",
  "label": "Enabled Antennas",
  "options": [
    { "value": "1", "label": "Antenna 1" },
    { "value": "2", "label": "Antenna 2" },
    { "value": "3", "label": "Antenna 3" },
    { "value": "4", "label": "Antenna 4" }
  ],
  "default": ["1", "2", "3", "4"],
  "minSelected": 1
}

Select Option Object

Both select and checkbox-group use the same option structure:

Validation

Settings are validated against the schema before being sent to the device:

• Type checking – Values must match the field type.
• Required fields – Fields marked required: true must have a value.
• Range constraints – Numbers must be within min/max bounds.
• Length constraints – Strings must satisfy minLength/maxLength.
• Pattern matching – Text fields with a pattern are validated against the regex.
• Selection constraints – Checkbox groups respect minSelected/maxSelected.

Invalid settings are rejected with an error message describing the violation.

Common RFID Reader Settings

RF Tab

Tag Reports Tab

Filtering Tab

GPIO Tab

Applying Settings

From the Device Page

1. Navigate to Devices and select a device.
2. Open the Settings tab.
3. Modify values across the available tabs.
4. Click Save.

Settings are pushed to the device over RabbitMQ immediately. The device applies them and sends a success/failure response.

From a Workflow

Use the Update Device Settings node. Select the target device and provide the settings as a JSON object:

{
  "transmitPower": 25,
  "session": "S2",
  "enableFiltering": true
}

You only need to include the fields you want to change. Omitted fields retain their current values.

On Device Connection

When a device connects and requests its settings (routing key devices.{deviceId}.settings.request), Vesbite responds with the stored settings from the database. This ensures devices always start with their last saved configuration.

Defaults

When a device is adopted, Vesbite reads the settings schema from the device definition, applies default values from each field, and stores them. The device receives these defaults on its next settings request.

See Also

• How to Configure Settings
• Understanding Devices
• Workflow Nodes Reference – The Update Device Settings node