File

A File object exposes a file that other devices can read, and sometimes write. It is how a device shares configuration backups, firmware images, logs or other data over BACnet. The File object describes the file; the AtomicReadFile and AtomicWriteFile services move the data.

Typical uses

• Offer a configuration backup for download
• Accept a firmware image from an engineering tool
• Share a log file with a maintenance laptop
• Hold a certificate or key file for a secure connection

Key properties

Property	What it holds
File_Access_Method	Stream access reads and writes a run of bytes. Record access reads and writes whole numbered records. Fixed when the object is created.
File_Size	The size of the file in bytes. A client can write it on a writable stream file.
File_Type	A text label that describes the kind of file.
Modification_Date	When the file last changed.
Read_Only	True if clients cannot write the file.
Record_Count	The number of records. Present only on record-access files.

How it behaves

A File object is not commandable and has no alarm algorithm. Clients read and write its contents with the file services, not with ReadProperty. Archive tells a client whether the file changed since it was last backed up.

With the CAS BACnet Stack

Enable it with the STACK_OPTION_OBJECT_TYPE_FILE build option. Create it with BACnetStack_AddFileObject, which sets File_Access_Method and Read_Only and enables Record_Count for record files. That function also needs STACK_OPTION_ATOMIC_FILE_IO, which STACK_OPTION_DM_BR_BACKUP_AND_RESTORE or STACK_OPTION_NM_SCCM_A (with the BACnet/SC data link) turns on. Do not use BACnetStack_AddObject alone, because every file read and write then aborts. Serve Object_Name and File_Type with the callback you register with BACnetStack_RegisterCallbackGetPropertyCharacterString, File_Size with the BACnetStack_RegisterCallbackGetPropertyUnsignedInteger callback, and Archive with the BACnetStack_RegisterCallbackGetPropertyBool callback and the BACnetStack_RegisterCallbackSetPropertyBool callback. Move the data with BACnetStack_RegisterCallbackReadFile and BACnetStack_RegisterCallbackWriteFile for stream files, and BACnetStack_RegisterCallbackReadFileRecord and BACnetStack_RegisterCallbackWriteFileRecord for record files. A record file answers at most 128 records and 2048 octets of record data per request. That limit is a declared deviation from the standard, so declare it in the PICS of your product.

Related object types

Device, Network Port, Trend Log

Properties

The properties ASHRAE 135-2024 clause 12.13 defines for this object type.

How to read the table:

• Conformance is what the standard asks of every object of this type: R is required, W is required and writable by a client, O is optional. A digit after the letter marks a condition in the standard that decides when the property is present or writable, such as support for intrinsic reporting.
• Present by default: yes means the stack presents the property as soon as you add the object; no means it is optional and you turn it on with BACnetStack_SetPropertyEnabled. This is the stack’s starting setup, so it can differ from the conformance code.
• Writable is whether a client can write the property by default. Change it with BACnetStack_SetPropertyWritable.
• not in profile means the stack does not offer this property for this object type.
• Value when your callback does not answer: “Held by the stack” means the stack stores and serves the value itself and does not ask your callbacks. Otherwise it is the value the stack answers when your callback declines or is not registered.

Property	Datatype	Conformance	Present by default	Writable	Value when your callback does not answer
Object_Identifier	BACnetObjectIdentifier	R	yes	no	Held by the stack.
Object_Name	CharacterString	R	yes	no	"Object <type>,<instance>", such as "Object 0,1" for Analog Input 1.
Object_Type	BACnetObjectType	R	yes	no	Held by the stack.
Description	CharacterString	O	no	no	""
File_Type	CharacterString	R	yes	no	No default: value-not-initialized until a callback or a client write supplies one.
File_Size	Unsigned	R1	yes	no	No default: value-not-initialized until a callback or a client write supplies one.
Modification_Date	BACnetDateTime	R	yes	no	No default: value-not-initialized until a callback or a client write supplies one.
Archive	Boolean	W	yes	yes	No default: value-not-initialized until a callback or a client write supplies one.
Read_Only	Boolean	R	yes	no	Held by the stack; a Get callback that answers wins.
File_Access_Method	BACnetFileAccessMethod	R	yes	no	Held by the stack.
Record_Count	Unsigned	O2	no	no	0
Property_List	BACnetARRAY[N] of BACnetPropertyIdentifier	R	yes	no	Held by the stack.
Audit_Level	BACnetAuditLevel	O3	not in profile	not in profile	No default: the read fails.
Auditable_Operations	BACnetAuditOperationFlags	O3	not in profile	not in profile	No default: the read fails.
Tags	BACnetARRAY[N] of BACnetNameValue	O	no	no	No default: the read fails.
Profile_Location	CharacterString	O	no	no	""
Profile_Name	CharacterString	O	no	no	""