use super::*;
use crate::event::CommandFailureDetector;
pub struct MultiStateOutputObject {
oid: ObjectIdentifier,
name: String,
description: String,
present_value: u32,
feedback_value: u32,
number_of_states: u32,
out_of_service: bool,
status_flags: StatusFlags,
priority_array: [Option<u32>; 16],
relinquish_default: u32,
reliability: u32,
reliability_before_out_of_service: Option<u32>,
reliability_inhibit: common::ReliabilityInhibitState,
reliability_evaluator: MultiStateReliabilityState,
event_detection_enable: bool,
state_text: Vec<String>,
event_detector: CommandFailureDetector,
pub(crate) event_history: EventHistory,
value_source: common::ValueSourceTracking,
}
impl MultiStateOutputObject {
pub fn new(
instance: u32,
name: impl Into<String>,
number_of_states: u32,
) -> Result<Self, Error> {
let oid = ObjectIdentifier::new(ObjectType::MULTI_STATE_OUTPUT, instance)?;
require_nonzero_states(number_of_states)?;
Ok(Self {
oid,
name: name.into(),
description: String::new(),
present_value: 1,
feedback_value: 1,
number_of_states,
out_of_service: false,
status_flags: StatusFlags::empty(),
priority_array: [None; 16],
relinquish_default: 1,
reliability: 0,
reliability_before_out_of_service: None,
reliability_inhibit: common::ReliabilityInhibitState::default(),
reliability_evaluator: MultiStateReliabilityState::default(),
event_detection_enable: false,
state_text: (1..=number_of_states)
.map(|i| format!("State {i}"))
.collect(),
event_detector: CommandFailureDetector::default(),
event_history: EventHistory::default(),
value_source: common::ValueSourceTracking::default(),
})
}
pub fn set_description(&mut self, desc: impl Into<String>) {
self.description = desc.into();
}
fn recalculate_present_value(&mut self) {
self.present_value =
common::recalculate_from_priority_array(&self.priority_array, self.relinquish_default);
let _ = self.recompute_reliability();
}
fn configuration_invalid(&self) -> bool {
let is_invalid = |value: u32| !(1..=self.number_of_states).contains(&value);
self.priority_array
.iter()
.flatten()
.copied()
.any(is_invalid)
|| is_invalid(self.relinquish_default)
|| is_invalid(self.feedback_value)
}
fn recompute_reliability(&mut self) -> ReliabilityEvaluation {
if self.out_of_service || self.reliability_inhibit.enabled() {
return ReliabilityEvaluation::Unchanged;
}
let configuration_invalid = self.configuration_invalid();
self.reliability_evaluator.evaluate(
configuration_invalid,
self.present_value,
self.number_of_states,
&mut self.reliability,
)
}
pub fn set_number_of_states(&mut self, number_of_states: u32) -> Result<(), Error> {
resize_state_text(
&mut self.number_of_states,
&mut self.state_text,
number_of_states,
)?;
let _ = self.recompute_reliability();
Ok(())
}
pub fn set_relinquish_default(&mut self, value: u32) -> Result<(), Error> {
if value < 1 || value > self.number_of_states {
return Err(common::value_out_of_range_error());
}
self.relinquish_default = value;
self.recalculate_present_value();
Ok(())
}
}
impl BACnetObject for MultiStateOutputObject {
fn object_identifier(&self) -> ObjectIdentifier {
self.oid
}
fn object_name(&self) -> &str {
&self.name
}
fn supports_cov(&self) -> bool {
true
}
crate::event::impl_builtin_intrinsic_reporting!(
event_detector,
event_history,
[present_value, feedback_value],
reliability,
event_detection_enable,
CommandFailureDetector::ALGORITHM
);
impl_intrinsic_write_rollback!(
event_detector,
event_detection_enable,
event_history,
reliability_inhibit,
reliability,
out_of_service,
reliability_before_out_of_service;
reliability_evaluator,
priority_array,
relinquish_default,
present_value
);
fn acknowledge_alarm_correlated_internal(
&mut self,
event_state: EventState,
timestamp: &BACnetTimeStamp,
) -> Result<(), Error> {
if !self.event_detection_enable {
return Err(Error::Protocol {
class: ErrorClass::OBJECT.to_raw() as u32,
code: ErrorCode::NO_ALARM_CONFIGURED.to_raw() as u32,
});
}
self.event_history.acknowledge_correlated(
&mut self.event_detector.acked_transitions,
event_state,
timestamp,
)
}
fn read_property(
&self,
property: PropertyIdentifier,
array_index: Option<u32>,
) -> Result<PropertyValue, Error> {
if property == PropertyIdentifier::STATUS_FLAGS {
return Ok(common::compute_status_flags(
self.status_flags,
self.reliability,
self.out_of_service,
self.event_detector.event_state.to_raw(),
));
}
if property == PropertyIdentifier::EVENT_DETECTION_ENABLE {
return Ok(PropertyValue::Boolean(self.event_detection_enable));
}
if let Some(value) = self.reliability_inhibit.read(property) {
return Ok(value);
}
if let Some(result) = read_common_properties!(self, property, array_index) {
return result;
}
if let Some(result) = read_generic_event_properties!(self, property) {
return result;
}
if let Some(result) = self.event_history.read(property, array_index) {
return result;
}
match property {
p if p == PropertyIdentifier::OBJECT_TYPE => Ok(PropertyValue::Enumerated(
ObjectType::MULTI_STATE_OUTPUT.to_raw(),
)),
p if p == PropertyIdentifier::PRESENT_VALUE => {
Ok(PropertyValue::Unsigned(self.present_value as u64))
}
p if p == PropertyIdentifier::FEEDBACK_VALUE => {
Ok(PropertyValue::Unsigned(self.feedback_value as u64))
}
p if p == PropertyIdentifier::NUMBER_OF_STATES => {
Ok(PropertyValue::Unsigned(self.number_of_states as u64))
}
p if p == PropertyIdentifier::VALUE_SOURCE => {
Ok(self.value_source.value_source.clone())
}
p if p == PropertyIdentifier::LAST_COMMAND_TIME => Ok(PropertyValue::Unsigned(
match self.value_source.last_command_time {
BACnetTimeStamp::SequenceNumber(n) => u64::from(n),
_ => 0,
},
)),
p if p == PropertyIdentifier::PRIORITY_ARRAY => {
common::read_priority_array!(self, array_index, |v: u32| PropertyValue::Unsigned(
v as u64
))
}
p if p == PropertyIdentifier::RELINQUISH_DEFAULT => {
Ok(PropertyValue::Unsigned(self.relinquish_default as u64))
}
p if p == PropertyIdentifier::CURRENT_COMMAND_PRIORITY => {
Ok(common::current_command_priority(&self.priority_array))
}
p if p == PropertyIdentifier::STATE_TEXT => match array_index {
None => Ok(PropertyValue::List(
self.state_text
.iter()
.map(|s| PropertyValue::CharacterString(s.clone()))
.collect(),
)),
Some(0) => Ok(PropertyValue::Unsigned(self.state_text.len() as u64)),
Some(idx) if idx >= 1 && (idx as usize) <= self.state_text.len() => Ok(
PropertyValue::CharacterString(self.state_text[(idx - 1) as usize].clone()),
),
_ => Err(common::invalid_array_index_error()),
},
_ => Err(common::unknown_property_error()),
}
}
fn write_property(
&mut self,
property: PropertyIdentifier,
array_index: Option<u32>,
value: PropertyValue,
priority: Option<u8>,
) -> Result<(), Error> {
{
let num_states = self.number_of_states;
common::write_priority_array_direct!(self, property, array_index, value, |v| {
if let PropertyValue::Unsigned(u) = v {
if u < 1 || u > num_states as u64 {
Err(common::value_out_of_range_error())
} else {
Ok(u as u32)
}
} else {
Err(common::invalid_data_type_error())
}
});
}
if property == PropertyIdentifier::PRESENT_VALUE {
let num_states = self.number_of_states;
return common::write_priority_array!(self, value, priority, |v| {
if let PropertyValue::Unsigned(u) = v {
if u < 1 || u > num_states as u64 {
Err(common::value_out_of_range_error())
} else {
Ok(u as u32)
}
} else {
Err(common::invalid_data_type_error())
}
});
}
if property == PropertyIdentifier::FEEDBACK_VALUE {
if let PropertyValue::Unsigned(u) = value {
self.feedback_value = common::u64_to_u32(u)?;
let _ = self.recompute_reliability();
return Ok(());
}
return Err(common::invalid_data_type_error());
}
if property == PropertyIdentifier::STATE_TEXT {
match array_index {
Some(idx) if idx >= 1 && (idx as usize) <= self.state_text.len() => {
if let PropertyValue::CharacterString(s) = value {
self.state_text[(idx - 1) as usize] = s;
return Ok(());
}
return Err(common::invalid_data_type_error());
}
None => return Err(common::write_access_denied_error()),
_ => return Err(common::invalid_array_index_error()),
}
}
if property == PropertyIdentifier::EVENT_DETECTION_ENABLE {
if let PropertyValue::Boolean(v) = value {
self.event_detection_enable = v;
if !v {
self.event_detector.event_state = bacnet_types::enums::EventState::NORMAL;
self.event_detector.acked_transitions = 0b111;
self.event_detector.pending = None;
self.event_detector.fault_reliability = None;
self.event_history.reset();
}
return Ok(());
}
return Err(common::invalid_data_type_error());
}
if let Some(result) = write_generic_event_properties!(self, property, value) {
return result;
}
if let Some(result) = self.reliability_inhibit.write_inhibit(
&mut self.reliability,
self.out_of_service,
property,
&value,
) {
result?;
let _ = self.recompute_reliability();
return Ok(());
}
if let Some(result) = self.reliability_inhibit.write_out_of_service(
&mut self.out_of_service,
&mut self.reliability,
&mut self.reliability_before_out_of_service,
property,
&value,
) {
result?;
let _ = self.recompute_reliability();
return Ok(());
}
if let Some(result) = common::write_object_name(&mut self.name, property, &value) {
return result;
}
if let Some(result) = common::write_description(&mut self.description, property, &value) {
return result;
}
if let Some(result) = self.reliability_inhibit.write_client_reliability(
self.out_of_service,
&mut self.reliability,
property,
&value,
) {
return result;
}
if property == PropertyIdentifier::RELINQUISH_DEFAULT {
if let PropertyValue::Unsigned(u) = value {
let v = common::u64_to_u32(u)?;
return self.set_relinquish_default(v);
}
return Err(common::invalid_data_type_error());
}
Err(common::write_access_denied_error())
}
fn property_list(&self) -> Cow<'static, [PropertyIdentifier]> {
static PROPS: &[PropertyIdentifier] = &[
PropertyIdentifier::OBJECT_IDENTIFIER,
PropertyIdentifier::OBJECT_NAME,
PropertyIdentifier::DESCRIPTION,
PropertyIdentifier::OBJECT_TYPE,
PropertyIdentifier::PRESENT_VALUE,
PropertyIdentifier::FEEDBACK_VALUE,
PropertyIdentifier::STATUS_FLAGS,
PropertyIdentifier::EVENT_STATE,
PropertyIdentifier::EVENT_DETECTION_ENABLE,
PropertyIdentifier::EVENT_ENABLE,
PropertyIdentifier::TIME_DELAY,
PropertyIdentifier::TIME_DELAY_NORMAL,
PropertyIdentifier::NOTIFY_TYPE,
PropertyIdentifier::NOTIFICATION_CLASS,
PropertyIdentifier::ACKED_TRANSITIONS,
PropertyIdentifier::EVENT_TIME_STAMPS,
PropertyIdentifier::EVENT_MESSAGE_TEXTS,
PropertyIdentifier::OUT_OF_SERVICE,
PropertyIdentifier::NUMBER_OF_STATES,
PropertyIdentifier::PRIORITY_ARRAY,
PropertyIdentifier::RELINQUISH_DEFAULT,
PropertyIdentifier::CURRENT_COMMAND_PRIORITY,
PropertyIdentifier::RELIABILITY,
PropertyIdentifier::RELIABILITY_EVALUATION_INHIBIT,
PropertyIdentifier::STATE_TEXT,
];
Cow::Borrowed(PROPS)
}
fn is_createable(&self) -> bool {
true
}
fn set_reliability_internal(&mut self, reliability: u32) -> Result<(), Error> {
if self.out_of_service || self.reliability_inhibit.enabled() {
return Err(common::write_access_denied_error());
}
if !common::is_reliability_value_valid(reliability) {
return Err(common::value_out_of_range_error());
}
self.reliability = reliability;
self.reliability_evaluator.clear_ownership();
Ok(())
}
fn evaluate_reliability_internal(&mut self) -> Result<ReliabilityEvaluation, Error> {
Ok(self.recompute_reliability())
}
fn reliability_evaluation_inhibited_internal(&self) -> bool {
self.reliability_inhibit.enabled()
}
fn is_writable_property(&self, property: PropertyIdentifier) -> bool {
common::is_multistate_commandable_writable(property)
|| property == PropertyIdentifier::RELIABILITY
|| property == PropertyIdentifier::RELIABILITY_EVALUATION_INHIBIT
|| common::is_generic_event_property_writable(property)
|| property == PropertyIdentifier::FEEDBACK_VALUE
|| property == PropertyIdentifier::EVENT_DETECTION_ENABLE
}
}
#[cfg(test)]
mod command_failure_tests {
use super::*;
use bacnet_types::enums::{EventState, EventType};
fn write_unsigned(
object: &mut MultiStateOutputObject,
property: PropertyIdentifier,
value: u64,
) {
object
.write_property(property, None, PropertyValue::Unsigned(value), None)
.unwrap();
}
fn set_detection_enabled(object: &mut MultiStateOutputObject, enabled: bool) {
object
.write_property(
PropertyIdentifier::EVENT_DETECTION_ENABLE,
None,
PropertyValue::Boolean(enabled),
None,
)
.unwrap();
}
#[test]
fn feedback_value_round_trips_and_is_advertised_writable() {
let mut mso = MultiStateOutputObject::new(1, "MSO-1", 3).unwrap();
write_unsigned(&mut mso, PropertyIdentifier::FEEDBACK_VALUE, 2);
assert_eq!(
mso.read_property(PropertyIdentifier::FEEDBACK_VALUE, None)
.unwrap(),
PropertyValue::Unsigned(2)
);
assert!(mso
.property_list()
.contains(&PropertyIdentifier::FEEDBACK_VALUE));
assert!(mso.is_writable_property(PropertyIdentifier::FEEDBACK_VALUE));
assert!(mso
.write_property(
PropertyIdentifier::FEEDBACK_VALUE,
None,
PropertyValue::Enumerated(2),
None,
)
.is_err());
}
#[test]
fn feedback_value_outside_the_state_set_is_accepted_unlike_present_value() {
let mut mso = MultiStateOutputObject::new(1, "MSO-1", 3).unwrap();
write_unsigned(&mut mso, PropertyIdentifier::FEEDBACK_VALUE, 7);
assert_eq!(
mso.read_property(PropertyIdentifier::FEEDBACK_VALUE, None)
.unwrap(),
PropertyValue::Unsigned(7)
);
assert!(mso
.write_property(
PropertyIdentifier::PRESENT_VALUE,
None,
PropertyValue::Unsigned(7),
None,
)
.is_err());
}
#[test]
fn fresh_object_reports_nothing_when_detection_is_enabled() {
let mut mso = MultiStateOutputObject::new(1, "MSO-1", 3).unwrap();
set_detection_enabled(&mut mso, true);
assert_eq!(mso.evaluate_intrinsic_reporting(), None);
assert_eq!(
mso.read_property(PropertyIdentifier::EVENT_STATE, None)
.unwrap(),
PropertyValue::Enumerated(EventState::NORMAL.to_raw())
);
}
#[test]
fn oversized_feedback_value_is_rejected_rather_than_wrapped_into_agreement() {
let mut mso = MultiStateOutputObject::new(1, "MSO-1", 3).unwrap();
set_detection_enabled(&mut mso, true);
write_unsigned(&mut mso, PropertyIdentifier::PRESENT_VALUE, 2);
assert!(mso
.write_property(
PropertyIdentifier::FEEDBACK_VALUE,
None,
PropertyValue::Unsigned(0x1_0000_0002),
None,
)
.is_err());
assert_eq!(
mso.read_property(PropertyIdentifier::FEEDBACK_VALUE, None)
.unwrap(),
PropertyValue::Unsigned(1)
);
let outcome = mso.evaluate_intrinsic_reporting().unwrap();
assert_eq!(outcome.change.to, EventState::OFFNORMAL);
assert_eq!(outcome.event_type, EventType::COMMAND_FAILURE);
}
#[test]
fn command_failure_uses_present_and_feedback() {
let mut mso = MultiStateOutputObject::new(1, "MSO-1", 3).unwrap();
set_detection_enabled(&mut mso, true);
write_unsigned(&mut mso, PropertyIdentifier::PRESENT_VALUE, 2);
let proposal = mso.evaluate_intrinsic_reporting().unwrap();
let outcome = crate::event::commit_test_proposal(&mut mso, proposal);
assert_eq!(outcome.change.to, EventState::OFFNORMAL);
assert_eq!(outcome.event_type, EventType::COMMAND_FAILURE);
write_unsigned(&mut mso, PropertyIdentifier::FEEDBACK_VALUE, 2);
let returned = mso.evaluate_intrinsic_reporting().unwrap();
assert_eq!(returned.change.from, EventState::OFFNORMAL);
assert_eq!(returned.change.to, EventState::NORMAL);
assert_eq!(returned.event_type, EventType::COMMAND_FAILURE);
}
#[test]
fn time_delay_gates_command_failure() {
let mut mso = MultiStateOutputObject::new(1, "MSO-1", 3).unwrap();
set_detection_enabled(&mut mso, true);
write_unsigned(&mut mso, PropertyIdentifier::TIME_DELAY, 2);
write_unsigned(&mut mso, PropertyIdentifier::PRESENT_VALUE, 2);
assert_eq!(mso.evaluate_intrinsic_reporting(), None);
assert_eq!(mso.tick_intrinsic_reporting(), None);
let outcome = mso.tick_intrinsic_reporting().unwrap();
assert_eq!(outcome.change.to, EventState::OFFNORMAL);
assert_eq!(outcome.event_type, EventType::COMMAND_FAILURE);
}
#[test]
fn event_enable_to_offnormal_bit_controls_distribution() {
for (encoded, expected) in [(0x80, true), (0x00, false)] {
let mut mso = MultiStateOutputObject::new(1, "MSO-1", 3).unwrap();
set_detection_enabled(&mut mso, true);
mso.write_property(
PropertyIdentifier::EVENT_ENABLE,
None,
PropertyValue::BitString {
unused_bits: 5,
data: vec![encoded],
},
None,
)
.unwrap();
write_unsigned(&mut mso, PropertyIdentifier::PRESENT_VALUE, 2);
assert_eq!(
mso.evaluate_intrinsic_reporting().unwrap().distribute,
expected
);
}
}
#[test]
fn generic_event_properties_round_trip_and_match_pics() {
let mut mso = MultiStateOutputObject::new(1, "MSO-1", 3).unwrap();
let writes = [
(
PropertyIdentifier::NOTIFY_TYPE,
PropertyValue::Enumerated(1),
),
(
PropertyIdentifier::NOTIFICATION_CLASS,
PropertyValue::Unsigned(42),
),
];
for (property, value) in writes {
mso.write_property(property, None, value.clone(), None)
.unwrap();
assert_eq!(mso.read_property(property, None).unwrap(), value);
}
assert!(mso
.write_property(
PropertyIdentifier::ACKED_TRANSITIONS,
None,
PropertyValue::BitString {
unused_bits: 5,
data: vec![0x80],
},
None,
)
.is_err());
assert!(!mso.is_writable_property(PropertyIdentifier::ACKED_TRANSITIONS));
for property in [
PropertyIdentifier::EVENT_ENABLE,
PropertyIdentifier::TIME_DELAY,
PropertyIdentifier::TIME_DELAY_NORMAL,
PropertyIdentifier::NOTIFY_TYPE,
PropertyIdentifier::NOTIFICATION_CLASS,
] {
assert!(mso.property_list().contains(&property));
assert!(mso.is_writable_property(property));
}
assert!(mso
.write_property(
PropertyIdentifier::EVENT_STATE,
None,
PropertyValue::Enumerated(EventState::NORMAL.to_raw()),
None,
)
.is_err());
assert!(!mso.is_writable_property(PropertyIdentifier::EVENT_STATE));
}
#[test]
fn detection_enable_is_a_disabled_by_default_invariant() {
let mut mso = MultiStateOutputObject::new(1, "MSO-1", 3).unwrap();
write_unsigned(&mut mso, PropertyIdentifier::PRESENT_VALUE, 2);
assert_eq!(mso.evaluate_intrinsic_reporting(), None);
assert_eq!(mso.tick_intrinsic_reporting(), None);
assert_eq!(
mso.read_property(PropertyIdentifier::EVENT_STATE, None)
.unwrap(),
PropertyValue::Enumerated(EventState::NORMAL.to_raw())
);
assert_eq!(
mso.read_property(PropertyIdentifier::STATUS_FLAGS, None)
.unwrap(),
PropertyValue::BitString {
unused_bits: 4,
data: vec![0],
}
);
set_detection_enabled(&mut mso, true);
assert_eq!(
mso.evaluate_intrinsic_reporting().unwrap().change.to,
EventState::OFFNORMAL
);
mso.event_detector.acked_transitions = 0;
set_detection_enabled(&mut mso, false);
assert_eq!(
mso.read_property(PropertyIdentifier::EVENT_STATE, None)
.unwrap(),
PropertyValue::Enumerated(EventState::NORMAL.to_raw())
);
assert_eq!(
mso.read_property(PropertyIdentifier::ACKED_TRANSITIONS, None)
.unwrap(),
PropertyValue::BitString {
unused_bits: 5,
data: vec![0xe0],
}
);
assert_eq!(mso.evaluate_intrinsic_reporting(), None);
assert_eq!(mso.tick_intrinsic_reporting(), None);
mso.reliability = 1;
assert_eq!(
mso.read_property(PropertyIdentifier::STATUS_FLAGS, None)
.unwrap(),
PropertyValue::BitString {
unused_bits: 4,
data: vec![0x40],
}
);
assert_eq!(
mso.read_property(PropertyIdentifier::EVENT_DETECTION_ENABLE, None)
.unwrap(),
PropertyValue::Boolean(false)
);
assert!(mso
.property_list()
.contains(&PropertyIdentifier::EVENT_DETECTION_ENABLE));
assert!(mso.is_writable_property(PropertyIdentifier::EVENT_DETECTION_ENABLE));
}
}
#[cfg(test)]
mod reliability_evaluator_tests {
use super::*;
use bacnet_types::enums::Reliability;
#[test]
fn configuration_error_dominates_bypassed_invalid_present_value() {
let mut mso = MultiStateOutputObject::new(1, "MSO-dominance", 2).unwrap();
mso.present_value = 3;
mso.feedback_value = 3;
mso.evaluate_reliability_internal().unwrap();
assert_eq!(
mso.reliability,
Reliability::CONFIGURATION_ERROR.to_raw(),
"invalid configuration must dominate invalid Present_Value"
);
mso.feedback_value = 1;
mso.evaluate_reliability_internal().unwrap();
assert_eq!(
mso.reliability,
Reliability::MULTI_STATE_OUT_OF_RANGE.to_raw()
);
mso.write_property(
PropertyIdentifier::PRESENT_VALUE,
None,
PropertyValue::Unsigned(1),
None,
)
.unwrap();
assert_eq!(
mso.reliability,
Reliability::NO_FAULT_DETECTED.to_raw(),
"the central priority recalculation must recover synchronously"
);
}
}