What AtomicWriteFile Is
AtomicWriteFile is a file-access service in BACnet, defined in Clause 14.2 of ANSI/ASHRAE 135-2024. A client uses it to perform an open-write-close operation, writing data into a file held in a device. Every file reachable this way is represented by a File object. It is a confirmed service: the device acknowledges the position where the data was written, or returns 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. It is the counterpart to AtomicReadFile.
How It Works
Like reading, writing matches the file’s access method. For stream access the client sends a start position and the octet data; for record access it sends a start record, a record count, and the record data. A start position of -1 means append to the end of the file. If the start position is past the current end, the file is extended to reach it. A file too large to send in one request is written as a series of AtomicWriteFile requests, each advancing the position, with the device confirming where each block landed.
Where You’ll See It
- Restore. A backup tool driving the ReinitializeDevice restore procedure writes a saved configuration back into the device’s File objects with AtomicWriteFile.
- Firmware update. Pushing a firmware image into a device that exposes it as a writable File object.
- Data loading. Writing a configuration or data file a device accepts through a File object during commissioning.
AtomicWriteFile Error Codes
Clause 14.2 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 |
| Write to a read-only file | SERVICES | FILE_ACCESS_DENIED |
| A syntax error is encountered after the file was partially modified | SERVICES | INVALID_TAG |
| The File object is full | OBJECT | FILE_FULL |
| A non-File object identifier was provided | SERVICES | INCONSISTENT_OBJECT_TYPE |
Reading these in the field:
FILE_ACCESS_DENIEDmeans the File object is read-only; the device publishes it for reading but does not accept writes.FILE_FULLmeans the file cannot grow further on that device, a fixed-capacity limit.INVALID_FILE_ACCESS_METHODmeans the request used the wrong access method; match the File object’sFile_Access_Method.INVALID_TAGafter a partial write means the message was malformed midway through; because the file may already be partially modified, verify and rewrite from a known position.- No response at all is not an AtomicWriteFile error. A timeout is a transport or addressing problem, not a file problem.
Profiles That Require It
File access underpins backup and restore (DM-BR-B), whose restore side writes a device’s configuration back 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 restore therefore executes AtomicWriteFile against its File objects. The minimal controller profiles (B-ASC, B-SA, B-SS) have no file-access requirement. Initiating AtomicWriteFile is a backup-tool and workstation behavior.
What Chipkin Provides
The CAS BACnet Stack supports AtomicWriteFile in both directions, including the stream and record access methods and the append form used by restore. Talk to us about adding BACnet client or server support to your device.