What AddListElement Is
AddListElement is an object-access service in BACnet, defined in Clause 15.1 of ANSI/ASHRAE 135-2024. A client uses it to add one or more elements to a property that is a BACnetLIST, or an array of BACnetLIST, without disturbing the entries already there. It is a confirmed service: the device replies with a simple acknowledgment on success, or an error identifying which element failed.
It exists because a list is not a scalar. Writing a whole list with WriteProperty replaces every entry; AddListElement appends to what is already stored, which is what you want when several clients maintain the same list.
How It Works
The client names the object, the list property, an optional array index (required only when the property is an array of BACnetLIST), and the elements to add. The datatype of each element is fixed by the object type and property being modified. The operation is all-or-nothing: if any element cannot be added, none are added and the device returns an error whose First Failed Element Number points at the first offending entry in the request. An element that already matches an existing entry is not a failure; the device may update or ignore it, and the list is unchanged for that entry.
Where You’ll See It
- Notification recipients. Adding a destination to a Notification Class object’s recipient list so a new workstation starts receiving alarms, without rewriting the recipients already configured.
- Group and reference lists. Extending a list-valued configuration property, such as a group member list, during commissioning.
- Multi-client editing. Any list that more than one tool maintains, where replacing the whole property would clobber another client’s entries.
AddListElement Error Codes
Clause 15.1 defines the error class and code a device returns for each failure, alongside a First Failed Element Number that identifies the offending entry. The general error model lives in Clause 18 of the standard.
| Situation | Error class | Error code |
|---|---|---|
| Specified object does not exist | OBJECT | UNKNOWN_OBJECT |
| Specified property does not exist | PROPERTY | UNKNOWN_PROPERTY |
| The element datatype does not match the property | PROPERTY | INVALID_DATATYPE |
| The data being written has a datatype not supported by the property | PROPERTY | DATATYPE_NOT_SUPPORTED |
| The encoding is not valid for the datatype of the property | PROPERTY | INVALID_DATA_ENCODING |
| The element value is out of range for the property | PROPERTY | VALUE_OUT_OF_RANGE |
| The specified property is currently not modifiable by the requester | PROPERTY | WRITE_ACCESS_DENIED |
| There is not enough free memory for the element | RESOURCES | NO_SPACE_TO_ADD_LIST_ELEMENT |
| The property or specified array element is not a BACnetLIST | SERVICES | PROPERTY_IS_NOT_A_LIST |
| An array index is provided but the property is not a BACnetARRAY of BACnetLIST | PROPERTY | PROPERTY_IS_NOT_AN_ARRAY |
| An array index is provided that is greater than the current length of the array | PROPERTY | INVALID_ARRAY_INDEX |
Reading these in the field:
PROPERTY_IS_NOT_A_LISTmeans the target property is not list-valued; a scalar property is changed with WriteProperty, not this service.WRITE_ACCESS_DENIEDmeans the list exists but the device does not permit this client to modify it.NO_SPACE_TO_ADD_LIST_ELEMENTmeans the list is full on that device; there is a fixed capacity, not a transient condition.- The First Failed Element Number tells you which entry in a multi-element request the device rejected; a value of zero means the request was invalid for a reason other than the elements themselves.
- No response at all is not an AddListElement error. A timeout is a transport or addressing problem, not a list problem.
Profiles That Require It
List manipulation (DM-LM-B) is not part of the required BIBB set for the common controller and workstation profiles. Among the standard device profiles the one that requires DM-LM-B is B-RTR, the Router. Recipient lists on a Notification Class object are more often edited with WriteProperty through the alarm-recipient BIBB (AE-CRL-B), which is the write path B-BC and B-AAC require. Treat AddListElement as an optional capability a device advertises in its PICS (Protocol Implementation Conformance Statement), not a baseline every device answers.
What Chipkin Provides
The CAS BACnet Stack executes AddListElement on the server side in the shipping stack; initiating it as a client is implemented in Chipkin’s BACnet test tooling rather than the shipping device stack. Talk to us about adding BACnet client or server support to your device.