Msglist Protocol (Downlink)

The msglist widget stores an array of message objects. You control its contents by sending a new value for the widget in the data section of an app downlink message.

{
  "app": {
    "<dvname>": {
      "data": {
        "<widgetname>": <VALUE>
      }
    }
  }
}

The operation performed depends on the type and content of the VALUE you provide.

---

Add a new message

Send an object with an "id" that does not already exist, or omit the "id" entirely. The device automatically adds "ts" (timestamp) and "isRead": false.

Configuration variables

• VALUE (Required, object): A message object. At minimum, the "id" and "subj" fields are required; all other fields are optional.

Field	Type	Required	Description
id	string/number	yes	Unique identifier for the message
subj	string	yes	Subject / originating user name
location	string	no	Location string
resp	number	no	Number of responders
fid	string	no	Folder ID for grouping (defaults to "Urgent")
ts	number	no	Timestamp – auto‑assigned if missing
isRead	boolean	no	Read flag – auto‑assigned false if missing

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

You can also include an action in the same message — for example, gotoWidget to open the DED immediately after adding.

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

---

Update a message

Send an object with an "id" that already exists in the list. Fields present in the object are updated; new fields are added; fields set to null are removed.

Configuration variables

• VALUE (Required, object): A message object with an existing "id".

{
  "app": {
    "duress": {
      "data": {
        "alerts": { "id": "5", "resp": 2, "location": null }
      }
    }
  }
}

This example updates the responder count to 2 and removes the location field.

---

Delete a single message

Send an object that contains only an "id" field. The matching message is removed from the list.

Configuration variables

• VALUE (Required, object): An object with a single key "id" (string or number).

{
  "app": {
    "duress": {
      "data": {
        "alerts": { "id": "5" }
      }
    }
  }
}

Alternatively, send a plain string — the message whose "id" matches the string is deleted.

{
  "app": {
    "duress": {
      "data": {
        "alerts": "5"
      }
    }
  }
}

---

Delete all messages

Send an empty array to clear the entire message list.

Configuration variables

• VALUE (Required, array): []

{
  "app": {
    "duress": {
      "data": {
        "alerts": []
      }
    }
  }
}

---

TLV encoding (BLE transport)

When messages are sent over BLE using the GATT service, they are encoded as TLV packets. Tag 0x05 is reserved for updating the duress.alerts widget.

Configuration variables (TLV fields)

• T (Required, byte): 0x05 (duress alerts update).
• L (Required, byte): Total length of the Value field (1‑11 bytes).
• Value (Required, bytes): Encoded message fields.

Byte offset	Field	Description
00	id	Message ID (0‑255)
01	resp	Number of responders
02‑03	location	2 ASCII characters (mapped via dict for language lo)
04‑10	subj	Subject name as ASCII text (length determined by L minus 4)

If the update contains a new alert, the device will also open the duress DV page and the alerts DED (unless the DED is already open).

TLV examples

• Add alert: {"id":1,"subj":"Brian","resp":0,"location":"aa"}

  05 09 01 00 61 61 42 72 69 61 6e 00 00

• Update responder count: {"id":1,"resp":2}

  05 02 01 02 00 00 00 00 00 00 00 00 00

• Delete alert: {"id":1}

  05 01 01 00 00 00 00 00 00 00 00 00 00

The firmware decodes the TLV into JSON and processes it exactly as if it had arrived over WiFi.

Related

• App Downlink — how app messages are structured
• Uplink Msglist Events — isRead, button presses, delete confirmations
• App Actions — gotoWidget, delmsg and other actions