What RemoveListElement Is
RemoveListElement is an object-access service in BACnet, defined in Clause 15.2 of ANSI/ASHRAE 135-2024. A client uses it to remove one or more elements from a property that is a BACnetLIST, or an array of BACnetLIST, leaving the rest of the list intact. It is a confirmed service: the device replies with a simple acknowledgment on success, or an error identifying which element failed.
It is the counterpart to AddListElement. Together they let a client edit a list one entry at a time instead of rewriting the whole property with WriteProperty, which is what preserves entries other clients rely on.
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 remove. The device compares each supplied element against the entries in the list and removes the matches. The operation is all-or-nothing: if any element is not present or cannot be removed, none are removed and the device returns an error whose First Failed Element Number points at the first offending entry in the request.
Where You’ll See It
- Notification recipients. Removing a decommissioned workstation from a Notification Class object’s recipient list so it stops receiving alarms, without touching the other recipients.
- Group and reference lists. Pruning a stale member from a list-valued configuration property during a site change.
- Multi-client editing. Any list that more than one tool maintains, where rewriting the whole property would remove another client’s entries.
RemoveListElement Error Codes
Clause 15.2 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 specified property is currently not modifiable by the requestor | PROPERTY | WRITE_ACCESS_DENIED |
| A list element to be removed is not present | SERVICES | LIST_ELEMENT_NOT_FOUND |
| 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 or is zero | PROPERTY | INVALID_ARRAY_INDEX |
Reading these in the field:
LIST_ELEMENT_NOT_FOUNDmeans the element you asked to remove is not in the list; because the operation is all-or-nothing, one missing entry cancels the whole request and nothing is removed.WRITE_ACCESS_DENIEDmeans the list exists but the device does not permit this client to modify it.- Matching is on the complete element unless the property says otherwise, so a partial or slightly different element will not match an existing entry.
- No response at all is not a RemoveListElement 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). Treat RemoveListElement 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 RemoveListElement 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.