Message List

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 (see MQTT Topics).

Downlink Envelope Format

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

The operation performed depends on the type and structure of the VALUE provided.

1. Add a New Message

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

Field Reference

Field	Type	Required	Description
`id`	`string` / `number`	Yes	Unique identifier for the message
`subj`	`string`	Yes	Subject or 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	Epoch timestamp — auto-assigned if missing
`isRead`	`boolean`	No	Read flag — auto-assigned `false` if missing

MQTT Example

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

Combining Data and Actions

Include an actions array in the same message to switch UI focus immediately (e.g. gotoWidget):

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

2. 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, and fields set to null are removed.

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

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

3. Delete a Single Message

Option A: Object with ID Only

Send an object containing only the id field:

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

Option B: Plain String ID

Send a plain string matching the message id:

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

4. Delete All Messages

Send an empty array [] to clear the entire message list feed:

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

5. TLV Encoding (BLE Transport)

When messages arrive over BLE using GATT service, they are binary encoded as TLV packets. Tag 0x05 is reserved for duress.alerts.

TLV Field Structure

Offset	Field	Description
`0x00`	`id`	Message ID (0–255)
`0x01`	`resp`	Number of responders
`0x02–0x03`	`location`	2 ASCII characters
`0x04–0x10`	`subj`	Subject name ASCII text

Binary Packet 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
```

Firmware decodes BLE TLV packets directly into JSON structures and processes them identically to Wi-Fi MQTT messages.