What AtomicReadFile Is
AtomicReadFile is a file-access service in BACnet, defined in Clause 14.1 of ANSI/ASHRAE 135-2024. A client uses it to perform an open-read-close operation on the contents of a file held in a device. Every file reachable this way is represented by a File object, which names the file and carries its size, type, and access method. It is a confirmed service: the device returns a block of file data and an end-of-file flag, or an error.
“Atomic” means that while one read or write is in progress on a file, no other AtomicReadFile or AtomicWriteFile operation on that same file is allowed. This keeps a file consistent while it is transferred in pieces.
How It Works
A file is modeled either as a stream of octets or as a sequence of numbered records, and the request matches the file’s access method. For stream access the client sends a start position and an octet count; for record access it sends a start record and a record count. The device returns the data it read plus an End Of File flag. Because a file rarely fits in one response, the client reads it as a series of AtomicReadFile requests, advancing the start position each time, until the device sets End Of File to TRUE. A response shorter than requested, or the End Of File flag, both signal the end of the file.
Where You’ll See It
- Backup. A backup tool driving the ReinitializeDevice backup procedure reads the device’s configuration out of its File objects with AtomicReadFile.
- Firmware and data retrieval. Pulling a firmware image, a log export, or a stored data file a device exposes as a File object.
- File browsing. A tool that lists and reads the files a device publishes reads their contents with AtomicReadFile.
AtomicReadFile Error Codes
Clause 14.1 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 |
|---|---|---|
| The File object does not exist | OBJECT | UNKNOWN_OBJECT |
| The start position or start record is out of range | SERVICES | INVALID_FILE_START_POSITION |
| Incorrect file access method | SERVICES | INVALID_FILE_ACCESS_METHOD |
| A non-File object identifier was provided | SERVICES | INCONSISTENT_OBJECT_TYPE |
Reading these in the field:
INVALID_FILE_ACCESS_METHODmeans the request used stream access on a record file or the reverse; read the File object’sFile_Access_Methodfirst and match it.INVALID_FILE_START_POSITIONmeans the start position is negative or past the end of the file; check the File object’sFile_Size.INCONSISTENT_OBJECT_TYPEmeans the identifier in the request was not a File object.- No response at all is not an AtomicReadFile error. A timeout is a transport or addressing problem, not a file problem.
- A read whose response is too large for a device without segmentation (splitting a large message across multiple packets) arrives as an abort, not an error. Request fewer octets or records per read.
Profiles That Require It
File access underpins backup and restore (DM-BR-B), which reads a device’s configuration through its File objects. Among the standard device profiles, B-BC, the Building Controller, requires DM-BR-B, as do the advanced access-control and elevator controllers. A device that supports backup therefore executes AtomicReadFile against its File objects. The minimal controller profiles (B-ASC, B-SA, B-SS) have no file-access requirement. Initiating AtomicReadFile is a backup-tool and workstation behavior.
What Chipkin Provides
The CAS BACnet Stack supports AtomicReadFile in both directions, including the stream and record access methods used by backup and restore. Talk to us about adding BACnet client or server support to your device.