Widget

Every interactive (buttonor editable) widget in an active DataView can have its value updated dynamically over MQTT downlink without requiring a device restart or re-allocation.

---

Downlink Envelope Protocol

All DataView runtime update payloads wrap mutations inside an app object:

{
  "app": {
    "<dvname>": {
      "data": {
        "<widgetname>": <VALUE>
      },
      "actions": [
        {
          "a": "<ACTION_SHORTNAME>",
          "p": "<PARAMETER>"
        }
      ]
    }
  }
}

JSON Structure & Field Definitions

Field / Knob	Type	Required	Description
app	object	Yes	Outer wrapper key identifying application-layer commands.
<dvname>	string	Yes	DataView ID string (e.g. "syshome", "duress"). Must match target DataView ID.
data	object	No	Map of widget names to new values. If omitted, only actions execute.
<widgetname>	string / value	No	Unique ID of target widget mapped to its new payload (string, number, boolean, object, or array).
actions	array	No	List of UI action objects executed in sequence alongside data updates.
a	string	Yes*	Action shortname code (e.g. "gotoPage", "gotoWidget", "show", "hide").
p	string	No	Parameter string passed to the action handler.

---

1. Updating Widget Values

To change a widget value, place its widget ID and new value in the data block.

Update a Single Widget

{
  "app": {
    "syshome": {
      "data": {
        "status_text": "SYSTEM OK",
      },
    },
  },
}

Update Multiple Widgets Simultaneously

{
  "app": {
    "syshome": {
      "data": {
        "status_text": "HIGH TEMP ALERT",
        "temp_value": 42.5,
        "alert_icon": "icon_warning",
      },
    },
  },
}

---

2. Combining Data & Actions

Update widget values and trigger immediate screen navigation or action execution in a single payload.

{
  "app": {
    "duress": {
      "data": {
        "alerts": [
          {
            "id": "5",
            "subj": "Dr Tata",
            "location": "A&E",
          },
        ],
      },
      "actions": [
        {
          "a": "gotoWidget",
          "p": "duress.alerts",
        },
      ],
    },
  },
}

Common Action Shortnames

Action Code (a)	Parameter (p)	Description
gotoPage	<page_id>	Switches active display to target InfoPage ID
gotoWidget	<dv>.<widget>	Opens DataView and focuses screen on target widget
show	<widget_id>	Makes target widget visible
hide	<widget_id>	Hides target widget from screen

---

3. MsgList Widget Mutations

For interactive message feeds (msglist), the data section supports message creation, field updates, deletion, and clearing:

Operation	Payload Format	Description
Add Message	Object with id & subj	Pushes new message into list feed
Update Message	Object with existing id	Modifies fields on existing message
Delete Single	Object with id only or string	Removes single message by ID
Delete All	Empty array []	Clears all messages from feed

For the complete protocol specification, field tables, and BLE TLV binary packet encoding, see MsgList Protocol Reference.