BACnet ReadRange Service

What ReadRange Is

ReadRange is an object-access service in BACnet, defined in Clause 15.8 of ANSI/ASHRAE 135-2024. A client uses it to read a bounded range of items from a property that is a list, rather than fetching the whole property in one response. It works on any BACnetLIST property, or on an array of BACnetLIST. It is a confirmed service: the device returns the requested items plus flags describing where in the list they sit, or an error.

This is how trend-log records are read. A Trend Log can hold thousands of entries in its Log_Buffer, far more than fit in a single response, so a viewer reads them a page at a time with ReadRange instead of with ReadProperty.

How It Works

The client names the object, the property (for example Log_Buffer), and a range that selects which items to return. The device answers with an item count, the item data, and a set of result flags (FIRST_ITEM, LAST_ITEM, MORE_ITEMS) that tell the client whether it has reached the start or end of the list and whether more items matched than fit in the response. The range takes one of three forms. By Position selects items by their ordinal place in the list. By Sequence Number selects by the sequence number an item was assigned when it was added, which is stable even as the list changes. By Time selects the first item newer (or older) than a reference timestamp. Each form carries a signed count: a positive count reads forward from the reference, a negative count reads backward.

The paging trap is that a busy log keeps growing and wrapping while it is being read. Positional indices shift as new records arrive and old ones roll off the buffer, so a client that pages purely By Position can skip or repeat records. The spec’s own guidance is to locate the start of the wanted set By Time, then read the rest By Sequence Number, because sequence numbers do not move when the buffer wraps. MORE_ITEMS set to TRUE means the device had more matching items than fit in one APDU (Application Protocol Data Unit, the largest message a device accepts in one exchange); the client issues another ReadRange to continue.

Where You’ll See It

• Trend viewing. When a tool like the CAS BACnet Explorer or a head end (the central BMS server) uploads a trend log for charting, that upload is a sequence of ReadRange requests walking the Log_Buffer.
• Event and audit logs. The same paging model reads an Event Log or an Audit Log, both of which are list-valued and can be long.
• Long list properties. Any BACnetLIST that will not fit in one response is read in pages with ReadRange rather than pulled whole.

ReadRange Error Codes

Clause 15.8 defines the error class and code a device returns for each failure. The general error model lives in Clause 18 of the standard.

Situation	Error class	Error code
Specified property does not exist	PROPERTY	UNKNOWN_PROPERTY
The specified property is currently not readable by the requester	PROPERTY	READ_ACCESS_DENIED
Property is not a BACnetLIST or BACnetARRAY of 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
The list items do not have a sequence number but a request By Sequence Number was received	PROPERTY	LIST_ITEM_NOT_NUMBERED
The list items are not timestamped but a request By Time was received	PROPERTY	LIST_ITEM_NOT_TIMESTAMPED

Reading these in the field:

• PROPERTY_IS_NOT_A_LIST means ReadRange was pointed at a scalar property; read that one with ReadProperty instead.
• LIST_ITEM_NOT_NUMBERED and LIST_ITEM_NOT_TIMESTAMPED mean the range form does not match the list. Not every list carries sequence numbers or timestamps; a Log_Buffer does, a plain recipient list does not.
• An empty result is not an error. A request that matches no items returns a success with an item count of zero.
• No response at all is not a ReadRange error. A timeout means the request never reached the device or the reply never came back, a transport or addressing problem.
• A response too large for a device without segmentation (splitting a large message across multiple packets) arrives as an abort, not an error. Read fewer items per page.

Profiles That Require It

Answering ReadRange (DS-RR-B) is required by the trend-viewing capability (T-VMT-I-B) that a device hosting Trend Log objects must provide. Among the standard device profiles that is B-BC, the Building Controller, which is required to host trend logs and serve their records. The minimal controller profiles (B-ASC, B-SA, B-SS) have no trending requirement and do not require ReadRange. Initiating ReadRange is an operator-workstation and trend-tool behavior.

What Chipkin Provides

The CAS BACnet Stack supports ReadRange in both directions, including the By Position, By Sequence Number, and By Time forms for paging trend and log buffers. Talk to us about adding BACnet client or server support to your device.

Related Pages

• Why “It Works on My Bench” Is Not BTL Conformance
• BACnet
• BACnet Services
• BACnet ReadProperty Service
• BACnet Trend Log Object
• BACnet B-BC Building Controller Profile
• BACnet Total_Record_Count vs Record_Count: the counter semantics behind the sequence number you page against
• BACnet TrendLog vs TrendLogMultiple: why a wide record changes what you can page in one response
• BACnet BUFFER_READY: the notification that tells you when to run a ReadRange, and why it goes missing