Crate bacnet_objects

Expand description

§bacnet-objects

Build BACnet object state with traits::BACnetObject and database::ObjectDatabase in the Rusty BACnet workspace. The database owns registered objects and supports identifier-based lookup; object modules provide their property implementations.

The crate has no Tokio dependency. Using it alone does not start a transport, a server executor or event/COV delivery.

§Features

Profile	Features	What it has
Hosted	`std` (default)	Everything, including the file persistence backends (`FileAuditLogPersistence`, `FileLogPersistence` and the others), a writer thread per saving object, and tracing.
`no_std` with a heap	`alloc` (without `std`)	Every object type, the database and the persistence traits, for a target with a global allocator and atomic compare-and-swap (#1615). A save runs on the caller’s thread, and the application supplies the storage.

There is no build with neither feature: the database boxes every object, so a heap-free device answers from a static table instead. ARMv6-M (thumbv6m-none-eabi) lacks compare-and-swap, which alloc::sync::Arc needs, so the crate doesn’t build there. The design note has the details.

§Initialize and read an object

Place an application directory beside a checkout named rusty-bacnet, then add this dependency block to the application’s Cargo.toml. These are development-source paths, not a claim that the shown APIs are published; adjust the paths if your directories differ.

[dependencies]
bacnet-objects = { path = "../rusty-bacnet/crates/bacnet-objects" }
bacnet-types = { path = "../rusty-bacnet/crates/bacnet-types" }

Save this complete program as src/main.rs. It initializes an unattached Analog Input, transfers it to the database, then checks the stored identity, Present_Value and a missing-object lookup.

use bacnet_objects::analog::AnalogInputObject;
use bacnet_objects::database::ObjectDatabase;
use bacnet_types::enums::{EngineeringUnits, ObjectType, PropertyIdentifier};
use bacnet_types::primitives::{ObjectIdentifier, PropertyValue};

fn main() -> Result<(), bacnet_types::error::Error> {
    let object = ObjectIdentifier::new(ObjectType::ANALOG_INPUT, 7)?;
    let mut analog = AnalogInputObject::new(
        7,
        "supply-temperature",
        EngineeringUnits::DEGREES_CELSIUS,
    )?;
    analog.set_present_value(42.0);
    let mut database = ObjectDatabase::new();
    database.add(Box::new(analog))?;

    let stored = database.get(&object).expect("the object was registered");
    assert_eq!(stored.object_identifier(), object);
    assert_eq!(stored.object_name(), "supply-temperature");
    assert_eq!(
        stored.read_property(PropertyIdentifier::PRESENT_VALUE, None)?,
        PropertyValue::Real(42.0),
    );
    let absent = ObjectIdentifier::new(ObjectType::ANALOG_INPUT, 8)?;
    assert!(database.get(&absent).is_none());
    Ok(())
}

The direct setter above initializes an object before ownership transfer. AnalogInputObject::set_present_value bypasses running-server ownership, validation, intrinsic-event and COV processing. For live server updates, use BACnetServer::set_present_value_local and its documented policy instead of mutating a database object directly.

§Device identity and executor ownership

Use DeviceIdentity and device_identity::build_database_with_extra when assembling a server database. The helper installs the Device and configured Network Ports, and seeds the Device’s Object_List with the extra application objects. Adding a standalone analog object alone does not create a Device.

Objects read through a raw database return standalone state. A running BACnetServer supplies live executor-owned Device properties and lists through read_local; its shared database handle is not an equivalent live view. Never hold a database guard across network operations or shutdown. Durable objects can queue saves, so their final drop or the server’s explicit stop may wait on storage; this example uses only an in-memory Analog Input.

The example establishes local object initialization, lookup and property access. It does not establish transport operation, event delivery, physical equipment behavior, timing or standards conformance. Consult each object’s property and service documentation for its supported behavior.

§Documentation profile

This README is included as the crate landing page and the program runs as a doctest. The docs.rs profile disables defaults, explicitly selects std and targets x86_64-unknown-linux-gnu, so it shows the hosted API, the file persistence backends included; it does not render the alloc-only build, and a local render does not establish a docs.rs deployment.

Re-exports§

pub use device_identity::DeviceIdentity;

Modules§

access_control: Access Control objects (ASHRAE 135-2020 Clause 12).
accumulator: Accumulator (type 23) and Pulse Converter (type 24) objects.
analog: Analog Input (type 0), Analog Output (type 1), and Analog Value (type 2) objects.
audit: AuditLog (type 61) and AuditReporter (type 62) objects per Addendum 135-2016bj.
averaging: Averaging (type 18) object per ASHRAE 135-2020 Clause 12.5.
binary: Binary Input (type 3), Binary Output (type 4), and Binary Value (type 5) objects per ASHRAE 135-2020 Clauses 12.6, 12.7, and 12.8.
catalogue: The object catalogue: one object of each standard type this crate builds.
channel: Channel object (type 53) per ASHRAE 135-2020 Clause 12.53.
clock: Dependency-neutral clock data exposed to BACnet objects.
color: Color (type 63) and Color Temperature (type 64) objects, added by Addendum 135-2020ca (Clauses 12.X and 12.Y, Tables 12-X and 12-Y).
command: Command object (type 7) per ASHRAE 135-2020 Clause 12.10.
command_source: Explicit command origins and object-owned source tracking (Clause 19.5): per priority for a commandable Present_Value, and a single source for one with no priority array (#1552).
cov_change: The change test of COV reporting (Clause 13.1), shared by the server’s COV notifications and a Trend Log that logs by COV (#1480).
database: ObjectDatabase — stores and retrieves BACnet objects by identifier.
device: Device object (type 8) per ASHRAE 135-2020 Clause 12.11.
device_identity: Shared Device declarations and stock object construction.
durable: Saving object state off the object database lock (#1270).
elevator: Elevator Group, Escalator, and Lift objects per ASHRAE 135-2020.
event: Intrinsic reporting — OUT_OF_RANGE event state machine.
event_enrollment: EventEnrollment (type 9) object per ASHRAE 135-2020 Clause 12.12.
event_log: EventLog (type 25) object per ASHRAE 135-2020 Clause 12.27.
file: File (type 10) object per ASHRAE 135-2020 Clause 12.13.
group: Group, GlobalGroup, and StructuredView objects per ASHRAE 135-2020.
life_safety: Life Safety Point (type 21) and Life Safety Zone (type 22) objects per ASHRAE 135-2020 Clauses 12.15 and 12.16.
lighting: Lighting Output (type 54) and Binary Lighting Output (type 55) objects per ASHRAE 135-2020 Clauses 12.54 and 12.55.
load_control: Load Control object (type 28) per ASHRAE 135-2020 Clause 12.28.
log_buffer: Shared resident storage and identity projection for BACnet log objects.
log_persistence: Durable storage for the Trend Log, Trend Log Multiple and Event Log (#1541).
log_reporting: BUFFER_READY intrinsic reporting for the log objects (Clause 13.3.7).
loop_obj: Loop (type 12) object per ASHRAE 135-2020 Clause 12.17.
multistate: Multi-State Input (type 13), Multi-State Output (type 14), and Multi-State Value (type 19) objects per ASHRAE 135-2020 Clauses 12.18, 12.19, and 12.20.
network_port: Configured Network Port snapshots and selected live state (135-2020 Clause 12.56).
notification_class: NotificationClass object: priorities, acknowledgment requirements, and recipients.
notification_forwarder: Notification Forwarder object (type 51, Clause 12.51).
object_profile: The optional Tags, Profile_Location and Profile_Name rows (#1553).
present_value_access: How a Value object’s Present_Value is written.
program: Program object (type 16) per ASHRAE 135-2020 Clause 12.22.
property_metadata: Executable property metadata and compatibility projections.
schedule: Schedule (type 17) and Calendar (type 6) objects per ASHRAE 135-2020.
staging: Local-target Staging object (type 60) per ASHRAE 135-2020 Clause 12.62.
subscribed_recipients: A Notification Forwarder’s Subscribed_Recipients (Clause 12.51.9, #1049): a bounded BACnetLIST of BACnetEventNotificationSubscription whose entries lapse when their time runs out.
timer: Timer object (type 31) per ASHRAE 135-2020 Clause 12.57.
traits: BACnetObject trait — the interface all BACnet objects implement.
trend: TrendLog (type 20) and TrendLogMultiple (type 27) objects per ASHRAE 135-2020.
value_types: Extended value object types (ASHRAE 135-2020 Clause 12).