Struct ColorObject 

pub struct ColorObject { /* private fields */ }

BACnet Color object (type 63).

Holds a colour as CIE 1931 xy coordinates, each 0.0 to 1.0. It isn’t commandable: Present_Value takes a write with no priority array.

Color_Command takes a BACnetColorCommand whose operation is FADE_TO_COLOR or STOP (see set_color_command) and carries it out (#1474). FADE_TO_COLOR sets Present_Value to the target at once and fades Tracking_Value to it from where it stands, over the command’s fade time or Default_Fade_Time, with In_Progress FADE_ACTIVE until it arrives. STOP ends the fade there, and Present_Value takes the colour it reached. A Present_Value write halts a fade too, then moves to the new colour as Transition says: at once for NONE, or a fade over Default_Fade_Time for FADE.

Fades run on the monotonic clock the database binds; the server’s monotonic task samples Tracking_Value for COV as it moves and ends the fade on time. With no clock bound they wait on advance_time_internal.

Cloning copies served state into an in-memory object. Tags persistence and pending saves remain solely with the original; cloning or dropping the copy never saves, corrects, settles, or waits on the original writer.

Implementations

impl ColorObject

pub fn new(instance: u32, name: impl Into<String>) -> Result<Self, Error>

Create a Color object at D65 white (x 0.3127, y 0.3290), which is also its Default_Color.

Default_Fade_Time starts at 100 ms, the shortest the addendum allows, as Lighting Output’s does, and Transition at NONE.

pub fn with_output_persistence( self, persistence: Arc<dyn ColorOutputPersistence>, ) -> Result<Self, Error>

Keep Present_Value in persistence (#1526), and take the colour it saved for this object, if any, as Present_Value. Call it right after building the object, before anything writes Present_Value.

The object then saves each new Present_Value on its own writer thread; a change doesn’t wait for its save, and a save that fails is logged and tried again (see ColorOutputPersistence). With Default_Color (0, 0), the device’s start keeps the saved colour (Clause 12.X.8).

Fails with storage’s error when what it holds can’t be loaded, and when it holds a colour temperature or a coordinate outside 0.0 to 1.0.

pub fn output_restored(&self) -> bool

Whether Present_Value came back from storage (with_output_persistence).

pub fn output_save_counters(&self) -> Option<ColorOutputSaveCounters>

The Present_Value save counters, shared with the object, or None without storage. Take them before the object joins a database.

pub fn wait_for_output_saves(&self)

Block until the Present_Value saves queued so far have run. Dropping the object waits for them too.

pub fn default_color(&self) -> BACnetXyColor

Default_Color: the colour the device’s start drives the output to, or (0, 0) to keep the colour from before the restart.

pub fn set_default_color(&mut self, color: BACnetXyColor) -> Result<(), Error>

Set Default_Color, as a WriteProperty of it would. (0, 0) is taken like any other colour and keeps the saved colour at the device’s start (Clause 12.X.8). A coordinate outside 0.0 to 1.0, or NaN, is refused with VALUE_OUT_OF_RANGE.

pub fn start_output(&mut self)

Drive the output as the device’s start does (#1526); the server calls this for every Color object in the database as it starts. An application running the object without a server, or adding it to a server already running, calls it itself.

A non-zero Default_Color becomes Present_Value at once, whatever was set before the start, with no fade, since the addendum gives the start no transition. With Default_Color (0, 0) the output keeps, in order: the colour restored from storage; else a colour set before the start; else nothing, and In_Progress reads NOT_CONTROLLED until a Present_Value or Color_Command write drives it (Clauses 12.X.4 and 12.X.8). Values set before the start are configuration, since no peer can write until then, so a first boot and later ones agree.

It is safe to call again, as an in-process restart would: the second call keeps the current colour for a zero default, since the restored one was taken by the first.

pub fn set_value_source_tracking(&mut self, enabled: bool)

Track Value_Source (Clause 19.5, #1552), provisioned before registration as the audit policy is.

On, the object serves Value_Source: the writer of the last Present_Value write, or of the last Color_Command that set Present_Value, which alone may then correct it. Such a write must name its writer (write_property_from, as the server’s network and local writes do); one without is refused with WRITE_ACCESS_DENIED. The typed setters name none, so after one Value_Source reads NONE.

pub fn with_tags_persistence( instance: u32, name: impl Into<String>, persistence: Arc<dyn TagsPersistence>, ) -> Result<Self, Error>

Build with application-owned Tags storage. Saved Tags override configured Tags only while set_profile provisions the row. Loaded data must satisfy the normal Tags rules and the opt-in 1 MiB snapshot limit.

pub fn wait_for_tag_saves(&self)

Wait for queued save attempts to finish. This is not a success receipt; writes report their own save outcomes. Unstaged local writes block.

pub fn set_profile(&mut self, profile: ObjectProfile) -> Result<(), Error>

Provision the optional Tags, Profile_Location and Profile_Name rows before registration (#1553; see ObjectProfile). Tags takes writes; the profile rows are read-only over the network. A profile that fails ObjectProfile::check is refused and changes nothing.

pub fn set_audit_policy(&mut self, policy: ObjectAuditPolicy)

Provision the optional Audit_Level and Auditable_Operations rows before registration, as an Analog or Binary Value’s are (#1525).

A field left None keeps its row out of the object; a present row is writable, and a DEFAULT level inherits the selected Audit Reporter’s. The object has no commandable property for Audit_Priority_Filter to filter, and Table 12-X doesn’t list it, so a priority filter in policy is left out. Provisioning doesn’t install or enable a Reporter.

pub fn set_present_value(&mut self, color: BACnetXyColor) -> Result<(), Error>

Set Present_Value, as a WriteProperty of the colour would.

A coordinate outside 0.0 to 1.0, or NaN, is refused with VALUE_OUT_OF_RANGE and changes nothing (Clause 12.X.4). Otherwise a fade in progress is halted, and the output moves to color as Transition says.

pub fn color_command(&self) -> BACnetColorCommand

The last command written to Color_Command, or operation NONE with no other field before any write.

pub fn set_color_command( &mut self, command: BACnetColorCommand, ) -> Result<(), Error>

Set Color_Command and carry the command out, as a WriteProperty of the encoded command would.

The command is checked against the Color object’s table of colour commands (Addendum 135-2020ca, Table 12-X2): only FADE_TO_COLOR and STOP are taken. FADE_TO_COLOR needs a target colour with both coordinates 0.0 to 1.0, and a fade time, when it carries one, of 100 to 86,400,000 ms. Fields the operation doesn’t use are kept unchecked. A refusal is VALUE_OUT_OF_RANGE and leaves the object unchanged.

Trait Implementations

impl BACnetObject for ColorObject

fn object_identifier(&self) -> ObjectIdentifier

The object’s identifier (type + instance).

fn object_name(&self) -> &str

The object’s name.

fn read_property( &self, property: PropertyIdentifier, array_index: Option<u32>, ) -> Result<PropertyValue, Error>

Read a property value.

fn write_property( &mut self, property: PropertyIdentifier, array_index: Option<u32>, value: PropertyValue, priority: Option<u8>, ) -> Result<(), Error>

Write a property value.

fn write_property_from( &mut self, property: PropertyIdentifier, array_index: Option<u32>, value: PropertyValue, priority: Option<u8>, origin: &CommandOrigin, ) -> Result<(), Error>

Write with explicit actual command provenance. Standalone callers assert the origin; server boundaries additionally validate ingress or membership. Decorators must forward this hook without discarding the origin. The default preserves custom/unaffected object behavior. First-party source-tracked commands require this hook and deny context-free writing.

fn property_metadata(&self) -> Cow<'_, [PropertyMetadata]>

Return canonical metadata for this object’s effective property rows.

fn property_list(&self) -> Cow<'static, [PropertyIdentifier]>

List all properties this object supports in the legacy projection.

fn supports_cov(&self) -> bool

Whether this object type supports COV notifications.

fn is_writable_property(&self, property: PropertyIdentifier) -> bool

Whether a property write route can accept property for this object.

fn is_array_property(&self, property: PropertyIdentifier) -> bool

Whether property accepts an array index on this object.

fn is_list_property(&self, property: PropertyIdentifier) -> bool

Whether property is a BACnetLIST on this object.

fn is_createable(&self) -> bool

Whether this object type can be created at runtime via CreateObject.

fn creation_only_properties(&self) -> &'static [PropertyIdentifier]

The properties whose whole value a CreateObject initial value may set on this object although WriteProperty can’t change it afterwards.

fn initialize_property( &mut self, _property: PropertyIdentifier, _value: PropertyValue, ) -> Result<(), Error>

Apply a CreateObject initial value to one of Self::creation_only_properties, written whole.

fn is_deleteable(&self) -> bool

Whether this object type can be deleted at runtime via DeleteObject.

fn required_properties(&self) -> Cow<'static, [PropertyIdentifier]>

List the REQUIRED properties for this object type.

fn supports_subscribe_cov_property(&self) -> bool

Whether SubscribeCOVProperty and SubscribeCOVPropertyMultiple may monitor this object’s properties.

fn supports_cov_property(&self, property: PropertyIdentifier) -> bool

Whether a readable property supports property-specific COV.

fn cov_increment(&self) -> Option<f64>

COV increment for this object (objects with a COV_Increment property).

fn cov_reported_properties(&self) -> &'static [CovReportedProperty]

Properties a whole-object (SubscribeCOV) notification reports after its leading value and Status_Flags, in report order.

fn set_overridden(&mut self, _overridden: bool)

Set the OVERRIDDEN bit in StatusFlags.

fn evaluate_intrinsic_reporting(&mut self) -> Option<TransitionOutcome>

Evaluate intrinsic reporting after a present_value change.

fn tick_intrinsic_reporting(&mut self) -> Option<TransitionOutcome>

Advance the Time_Delay countdown for a pending transition.

fn tick_schedule( &mut self, _today: SpecificDate, _time: Time, _calendar_active: &dyn Fn(ObjectIdentifier) -> bool, ) -> Option<ScheduleWrite>

Evaluate this object’s schedule at time on today (Clause 12.24.4).

fn take_owed_schedule_writes(&mut self) -> Vec<ScheduleWrite>

Take the writes this schedule owes its targets apart from its calculation, each once, in order: a NULL to every priority slot a change of List_Of_Object_Property_References or Priority_For_Writing left behind (#1088), then the Present_Value owed out of service, for a client’s write (Clause 12.24.14) or a change of those two properties.

fn complete_schedule_write( &mut self, _write: &ScheduleWrite, _outcomes: &[ScheduleTargetOutcome], ) -> bool

Report how each target took write, one of this schedule’s writes: outcomes holds one entry per member of write.references, in order.

fn retry_refusals_naming( &self, _target: ObjectIdentifier, ) -> Option<ScheduleWrite>

The retry of the current value to the references whose last write was refused and that name target, an object just added to the database (#1440), so the refusal can clear without waiting for the next pass. None when no such refusal stands, or when the pass itself would retry nothing: out of service, outside Effective_Period, or with a NULL Present_Value. Only meaningful for Schedule objects; default returns None.

fn acknowledge_alarm( &mut self, _transition_bit: EventTransitionBits, ) -> Result<(), Error>

Acknowledge an alarm transition. Sets the transition_bit flags in acked_transitions. Returns Ok(()) if the object supports event detection, Err otherwise.

fn apply_life_safety_operation( &mut self, _operation: LifeSafetyOperation, ) -> Result<LifeSafetyOperationOutcome, Error>

Apply a LifeSafetyOperation atomically to this object.

fn set_life_safety_operation_expected_internal( &mut self, _operation: LifeSafetyOperation, ) -> Result<(), Error>

Set the next LifeSafetyOperation expected by trusted local logic.

fn set_event_state_internal(&mut self, _state: EventState) -> Result<(), Error>

Apply an internally-detected Event_State transition.

fn enrollment_eval_state_internal(&self) -> Option<EventEnrollmentEvalState>

Snapshot this object’s Event Enrollment evaluation state, if it models one.

fn set_enrollment_eval_state_internal( &mut self, _state: EventEnrollmentEvalState, ) -> Result<(), Error>

Store this object’s Event Enrollment evaluation state.

fn enrollment_eval_source_internal( &self, ) -> Option<Option<EventEnrollmentMonitoredSource>>

Snapshot the monitored source that owns Event Enrollment private state.

fn set_enrollment_eval_source_internal( &mut self, _source: Option<EventEnrollmentMonitoredSource>, ) -> Result<(), Error>

Store or clear the monitored source that owns Event Enrollment state.

fn set_acked_transitions_internal( &mut self, _transition_bit: EventTransitionBits, _acknowledged: bool, ) -> Result<(), Error>

Set or clear one Acked_Transitions bit on a received event-state transition.

fn evaluate_reliability_internal( &mut self, ) -> Result<ReliabilityEvaluation, Error>

Evaluate and, when necessary, mutate this object’s Reliability.

fn set_reliability_internal( &mut self, _reliability: Reliability, ) -> Result<(), Error>

Apply an internally-derived Reliability value.

fn set_present_value_internal( &mut self, _value: PropertyValue, ) -> Result<(), Error>

Apply the logical Present_Value supplied by the local application.

fn set_present_value_from_internal( &mut self, value: PropertyValue, _origin: &CommandOrigin, ) -> Result<(), Error>

set_present_value_internal on behalf of origin, the local Device the application runs in.

fn set_tracking_value_internal( &mut self, _value: PropertyValue, ) -> Result<(), Error>

Apply the Tracking_Value the local application derived.

fn report_access_input_internal( &mut self, _input: AccessControlInput, ) -> Result<(), Error>

Apply an input the application reports for an access-control object the server holds (#1132): an Access Point’s access event, a Credential Data Input’s read or an Access Door’s hardware state, each a record whose values change together. See AccessControlInput.

fn set_controlled_variable_value_internal( &mut self, _value: PropertyValue, ) -> Result<(), Error>

Apply the Controlled_Variable_Value measured by the local application.

fn add_averaging_sample_internal( &mut self, _sample: Option<PropertyValue>, ) -> Result<(), Error>

Record one sample for an Averaging object.

fn audit_log_storage_internal(&self) -> Option<&dyn AuditLogStorage>

Borrow this object’s Audit Log query storage, if it has any.

fn audit_log_notification_sink_internal( &mut self, ) -> Option<&mut dyn AuditLogNotificationSink>

Mutably borrow this object’s Audit notification receiver capability.

fn file_storage_internal(&self) -> Option<&dyn FileStorage>

Borrow this object’s File storage, if it has any.

fn file_storage_internal_mut(&mut self) -> Option<&mut dyn FileStorage>

Mutably borrow this object’s File storage, if it has any.

fn log_record_identities_internal(&self) -> Option<Vec<LogRecordIdentity>>

Return stable identities aligned with this object’s resident log records.

fn log_buffer_internal(&self) -> Option<&dyn LogBufferRecords>

Borrow this object’s Log_Buffer records as ReadRange pages them.

fn add_trend_record(&mut self, _record: BACnetLogRecord) -> Result<(), Error>

Submit a trend record to an object’s log lifecycle.

fn add_trend_multiple_record( &mut self, _record: BACnetLogMultipleRecord, ) -> Result<(), Error>

Submit a Trend Log Multiple record, one value per monitored member, to an object’s log lifecycle.

fn add_event_log_record( &mut self, _record: BACnetEventLogRecord, ) -> Result<(), Error>

Submit an Event Log record to an object’s log lifecycle.

impl Clone for ColorObject

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.