The Multistate Output object commands a multi-state actuator
(e.g. multi-speed fan, chiller mode selector,
damper with several positions, etc. -- which may be
hardware output signals or anything similar). The present_value
is an integer in the range 1..N; the meaning of each state number
is defined locally and can be documented with state_text.
The object is fully commandable via a priority array. When
intrinsic_reporting: true is used, the COMMAND_FAILURE event algorithm plus
associated properties become active so that failure to reach the commanded state
can be alarmed.
Object Description (ASHRAE 135)
The Multi-state Output object type defines a standardized object whose properties represent the desired state of one or more physical outputs or processes within the BACnet Device in which the object resides.
Multi-state Output objects that support intrinsic reporting shall apply the COMMAND_FAILURE event algorithm.
Behaviour and Operation
Multistate Output objects command multi-position outputs.
The local logic must observe present_value (1..N) and apply it to the
target, taking state_text into account for documentation only.
The object is fully commandable: present_value is derived from the priority
array + relinquish default. Application code must use set_priority/3
to command it; direct writes to present_value are blocked.
When intrinsic reporting is enabled the COMMAND_FAILURE algorithm uses the
feedback feedback_value to detect failures to reach the commanded state.
Developer Implementation Notes (geared to device server / application authors)
The generated code handles storage + basic mechanics (validation, implicit_relationships,
readonly annotations as hints to your server, etc.). You must drive "special" live
properties and side effects yourself, analogous to maintaining present_value on
inputs via update_property/3 (never direct mutation). Read notes below + generated
tables for details.
Special / live properties and expected developer behaviour
present_value: Effective commanded discrete state. Dev must: Command only viaset_priority/3. Your driver reads effective state and maps to hardware.priority_array,relinquish_default: Dev must: Priority commanding; library derives PV.number_of_states,state_text(size must matchnumber_of_states): Human names for states 1..N. Dev must: Define states; keep text array in sync.feedback_value: Actual state from hardware. Dev must: Update from feedback sensor; used for command failure alarming.alarm_values: List of state numbers that are alarm. Dev must: For intrinsic, your event engine runs CHANGE_OF_STATE algorithm, updates event state/notifications.fault_values: States that indicate fault. Dev must: If PV in fault_values, set reliability appropriately.status_flags,out_of_service,reliability: Dev must:out_of_servicefor test direct writes. Reliability from actuator health.in_alarm/fault/out_of_servicebits ofstatus_flagsare auto-managed by the object (overriddenis local matter).
See the Your driver notes below.
Your driver: Read the effective 1..N and map it through whatever hardware abstraction you have (write a register on a VFD, set a stepper position, select a mode in a chiller controller, …).
state_text: Purely documentary. Your HMI or alarm messages can use it, but the wire protocol and your driver only ever deal with the integer.
Number of states: number_of_states tells you the valid range.
Writes of 0 or >N are rejected by update_property/3.
Multistate outputs are commonly used for "mode" or "stage" commands where the meaning of each integer is defined by the equipment manufacturer.
Intrinsic Reporting
When intrinsic_reporting: true is passed to create/4, the object uses the
COMMAND_FAILURE event algorithm.
Commandability and Priority Arrays
As an output object this always has a priority_array together with relinquish_default.
The present value is protected from direct modification and is normally only changed
through the priority array.
Examples
Creating a minimal Multistate Output:
iex> {:ok, mo} = BACnet.Protocol.ObjectTypes.MultistateOutput.create(3, "Valve", %{priority_array: %BACnet.Protocol.PriorityArray{}, relinquish_default: 1}); mo.present_value
1Using special options:
iex> {:ok, mo} = BACnet.Protocol.ObjectTypes.MultistateOutput.create(4, "Mode", %{priority_array: %BACnet.Protocol.PriorityArray{}, relinquish_default: 1}, auto_write_feedback: true, intrinsic_reporting: true); mo.object_name
"Mode"See Also
The following part has been automatically generated.
Click to expand
This module defines a BACnet object of the type `multi_state_output`. The following properties are defined: | Property | Revision | Required | Readonly | Protected | Intrinsic | |----------|----------|----------|----------|-----------|-----------| | acked_transitions | | | X | | X | | alarm_values | | | | | X | | description | | | | | | | device_type | | | | | | | event_algorithm_inhibit | | | | | X | | event_algorithm_inhibit_ref | | | | | X | | event_detection_enable | | | | | X | | event_enable | | | | | X | | event_message_texts | | | X | | X | | event_message_texts_config | | | | | X | | event_state | | X | | | | | event_timestamps | | | X | | X | | fault_values | | | | | | | feedback_value | | | | | X | | limit_enable | | | | | X | | notification_class | | | | | X | | notify_type | | | | | X | | number_of_states | | X | X | | | | object_instance | | X | X | | | | object_name | | X | X | | | | out_of_service | | X | | | | | present_value | | X | | | | | priority_array | | X | X | | | | profile_location | 19 | | | | | | profile_name | | | | | | | reliability | | | | | | | reliability_evaluation_inhibit | | | | | | | relinquish_default | | X | | | | | state_text | | | | | | | status_flags | | X | X | | | | tags | 19 | | | | | | time_delay | | | | | X | | time_delay_normal | | | | | X | The following properties have additional semantics: | Property | Has Default | Has Init | Implicit Relationships | Validators | Annotations | |----------|-------------|----------|------------------------|------------|-------------| | alarm_values | X | | | | | | event_algorithm_inhibit_ref | | | event_algorithm_inhibit | | | | fault_values | X | | reliability | | | | feedback_value | X | | | Type | | | number_of_states | X | | | Type | | | present_value | X | | | Fun/Type | | | profile_location | | | | Fun | `revision: 19` | | reliability | | | reliability_evaluation_inhibit | | | | relinquish_default | X | | | Fun/Type | | | state_text | | | | Fun | | | tags | | | | | `revision: 19` | The following table shows the default values and/or init functions: | Property | Default Value | Init Function | |----------|---------------|---------------| | alarm_values | `[]` | | | fault_values | `[]` | | | feedback_value | `1` | | | number_of_states | `1` | | | present_value | `1` | | | relinquish_default | `1` | |Summary
Types
Common object options for creation - all are optional.
Options accepted when creating or configuring a Multistate Output object.
Available property names for this object.
The structure for property errors.
Represents an Multistate Output object. All keys should be treated as read-only,
all updates should go only through update_property/3.
Functions
Adds an optional property to an object. Remote objects can not be mutated using this operation.
Creates a new object struct with the defined properties. Optional properties are not
created when not given, only required, given and dependency properties are created.
Properties with a value of nil are ignored.
Auto generated function to get the names of all properties this object supports.
Auto generated function to get the annotations for the given property name.
Auto generated function to get the list of annotations for each property.
Auto generated function to get the names of properties used for COV reporting.
Auto generated function to get the names of intrinsic properties.
Get the BACnet object identifier.
Auto generated function to get the names of optional properties.
Get the logical state of the object from the present value property.
Get the active priority value from the priority array, or nil.
Get the list of properties the object has.
Auto generated function to get a map of property name to type.
Get a property's value from an object.
Auto generated function to get the names of protected properties.
Auto generated function to get the names of readonly properties.
Auto generated function to get the names of required properties.
Checks if the given object has the given property.
Checks if the given object has Intrinsic Reporting enabled.
Checks if the given property is writable.
Removes an optional property from an object. This function is idempotent. Remote objects can not be mutated using this operation.
Sets the given priority in the priority array of an object. This function also updates the present value.
Auto generated function to check whether the object type supports intrinsic reporting.
Updates a property of an object. To update the priority array, use set_priority/3 instead.
Types
@type common_object_opts() :: {:allow_numeric_constants, boolean()} | {:allow_unknown_properties, boolean()} | {:ignore_unknown_properties, boolean()} | {:revision, BACnet.Protocol.Constants.protocol_revision()} | {:skip_property_validation_remote_object, boolean() | :value}
Common object options for creation - all are optional.
allow_numeric_constants- Constants are atoms and thus unknown constants or vendor extensions are integers and thus are rejected. Enabling this option will allow integers (non_neg_integer()) for properties with aConstants.type()spec.allow_unknown_properties- Properties that are unknown to the object implementation are usually rejected. With this option, unknown properties (numeric identifiers usually means we dont know them) are accepted and put into a separate map. This does mean we can not validate or write them. Types of the values can be anything at this point. While you can read unknown properties with atom or integer as property identifier, you can only remove numeric unknown property identifiers from an object. Property identifiers of typeatomare only accepted, if it is a remote object (object implementation is only enforced if it is a local object). Numeric property identifiers are accepted regardless of remote object or not. For remote objects, this means you have to write "raw values" (usuallyEncodingstructs).ignore_unknown_properties- Properties that are unknown to the object implementation are usually rejected. With this option, unknown properties get ignored, as if they were not specified.revision- The BACnet protocol revision to check required properties against. Optional properties are regardless of revision available. SeeBACnet.Protocol.Constants.protocol_revision/0for the available revisions.skip_property_validation_remote_object- Skips property validation for remote objects. Sometimes it is possible that the value is invalid as per BACnet specification (i.e. value 0 for a multistate object), but you still want those to be represented. Valuetrueneither type nor value are validated. Value:valuemeans the type is still validated and only the value validator is not run (if present). The property'svalidator_funwill also be skipped.
@type object_opts() :: {:auto_write_feedback, boolean()} | {:intrinsic_reporting, boolean()} | common_object_opts()
Options accepted when creating or configuring a Multistate Output object.
In addition to the common options, Multistate Output supports:
auto_write_feedback- When enabled, thefeedback_valueis automatically kept in sync withpresent_valuechanges.intrinsic_reporting- Enables COMMAND_FAILURE intrinsic reporting.
@type property_name() ::
:acked_transitions
| :alarm_values
| :description
| :device_type
| :event_algorithm_inhibit
| :event_algorithm_inhibit_ref
| :event_detection_enable
| :event_enable
| :event_message_texts
| :event_message_texts_config
| :event_state
| :event_timestamps
| :fault_values
| :feedback_value
| :limit_enable
| :notification_class
| :notify_type
| :number_of_states
| :object_instance
| :object_name
| :out_of_service
| :present_value
| :priority_array
| :profile_location
| :profile_name
| :reliability
| :reliability_evaluation_inhibit
| :relinquish_default
| :state_text
| :status_flags
| :tags
| :time_delay
| :time_delay_normal
Available property names for this object.
@type property_update_error() :: {:error, {error :: atom(), property :: BACnet.Protocol.Constants.property_identifier()}}
The structure for property errors.
@type t() :: %BACnet.Protocol.ObjectTypes.MultistateOutput{ _metadata: internal_metadata(), _unknown_properties: %{ optional(atom() | non_neg_integer()) => term() | BACnet.Protocol.ApplicationTags.Encoding.t() | [BACnet.Protocol.ApplicationTags.Encoding.t()] }, acked_transitions: BACnet.Protocol.EventTransitionBits.t() | nil, alarm_values: [non_neg_integer()] | nil, description: String.t() | nil, device_type: String.t() | nil, event_algorithm_inhibit: boolean() | nil, event_algorithm_inhibit_ref: BACnet.Protocol.ObjectPropertyRef.t() | nil, event_detection_enable: boolean() | nil, event_enable: BACnet.Protocol.EventTransitionBits.t() | nil, event_message_texts: BACnet.Protocol.EventMessageTexts.t() | nil, event_message_texts_config: BACnet.Protocol.EventMessageTexts.t() | nil, event_state: BACnet.Protocol.Constants.event_state() | (reserved_or_vendor_extension :: non_neg_integer()), event_timestamps: BACnet.Protocol.EventTimestamps.t() | nil, fault_values: [non_neg_integer()] | nil, feedback_value: pos_integer() | nil, limit_enable: BACnet.Protocol.LimitEnable.t() | nil, notification_class: non_neg_integer() | nil, notify_type: BACnet.Protocol.Constants.notify_type() | (reserved_or_vendor_extension :: non_neg_integer()) | nil, number_of_states: pos_integer(), object_instance: non_neg_integer(), object_name: String.t(), out_of_service: boolean(), present_value: pos_integer(), priority_array: BACnet.Protocol.PriorityArray.t(pos_integer()), profile_location: String.t() | nil, profile_name: String.t() | nil, reliability: BACnet.Protocol.Constants.reliability() | (reserved_or_vendor_extension :: non_neg_integer()) | nil, reliability_evaluation_inhibit: boolean() | nil, relinquish_default: pos_integer(), state_text: BACnet.Protocol.BACnetArray.t(String.t(), pos_integer()) | nil, status_flags: BACnet.Protocol.StatusFlags.t(), tags: BACnet.Protocol.BACnetArray.t(BACnet.Protocol.NameValue.t()) | nil, time_delay: non_neg_integer() | nil, time_delay_normal: non_neg_integer() | nil }
Represents an Multistate Output object. All keys should be treated as read-only,
all updates should go only through update_property/3.
Properties which are for Intrinsic Reporting are nil, if disabled. If Intrinsic Reporting is enabled on the object, then the properties can not be nil.
For commandable objects (objects with a priority array), the present value property is protected.
To get the physical state, call get_output/2 and the function gets the present value in respect
to the out of service state.
Functions
@spec add_property(t(), BACnet.Protocol.Constants.property_identifier(), term()) :: {:ok, t()} | property_update_error()
Adds an optional property to an object. Remote objects can not be mutated using this operation.
Please note that properties of services can not be dynamically added and instead
the object must be newly created using create/4.
@spec create( non_neg_integer(), String.t(), %{optional(property_name() | atom() | non_neg_integer()) => term()}, [object_opts() | internal_metadata()] ) :: {:ok, t()} | property_update_error()
Creates a new object struct with the defined properties. Optional properties are not
created when not given, only required, given and dependency properties are created.
Properties with a value of nil are ignored.
Only properties that are required for specific services (i.e. Intrinsic Reporting) are automatically created.
@spec get_all_properties() :: [BACnet.Protocol.Constants.property_identifier()]
Auto generated function to get the names of all properties this object supports.
@spec get_annotation(property_name()) :: [term()]
Auto generated function to get the annotations for the given property name.
@spec get_annotations() :: [{name :: property_name(), values :: [term()]}]
Auto generated function to get the list of annotations for each property.
@spec get_cov_properties() :: [BACnet.Protocol.Constants.property_identifier()]
Auto generated function to get the names of properties used for COV reporting.
@spec get_intrinsic_properties() :: [BACnet.Protocol.Constants.property_identifier()]
Auto generated function to get the names of intrinsic properties.
@spec get_object_identifier(t()) :: BACnet.Protocol.ObjectIdentifier.t()
Get the BACnet object identifier.
@spec get_optional_properties() :: [BACnet.Protocol.Constants.property_identifier()]
Auto generated function to get the names of optional properties.
@spec get_output(t(), pos_integer()) :: boolean()
Get the logical state of the object from the present value property.
If the object is out of service, then the decoupled_output_state is returned.
The specification specifies that when the object is out of service, then the physical output
is decoupled from the BACnet present value. The actual physical output state can then either
hold its last value, go to a safe state or behaves according to local logic (-> defined as local matter).
The default value is 1 - the safe state of physical outputs in typical environments.
@spec get_priority_value(t()) :: {priority :: 1..16, value :: pos_integer()} | nil
Get the active priority value from the priority array, or nil.
@spec get_properties(t()) :: [BACnet.Protocol.Constants.property_identifier()]
Get the list of properties the object has.
@spec get_properties_type_map() :: map()
Auto generated function to get a map of property name to type.
@spec get_property( t(), BACnet.Protocol.Constants.property_identifier() | non_neg_integer() ) :: {:ok, term()} | property_update_error()
Get a property's value from an object.
@spec get_protected_properties() :: [BACnet.Protocol.Constants.property_identifier()]
Auto generated function to get the names of protected properties.
Protected is an annotation and the object modules prevent writing to this property directly in code. The protected properties are either written on creation or updated automatically depending on other properties being written to. Some properties are only written once at creation and never updated.
@spec get_readonly_properties() :: [BACnet.Protocol.Constants.property_identifier()]
Auto generated function to get the names of readonly properties.
Readonly is only an annotation that the property should be write protected
on the BACnet side, there is no actual write protection in the object.
This is a hint to the device server. If you need actual write protection, see protected.
@spec get_required_properties() :: [BACnet.Protocol.Constants.property_identifier()]
Auto generated function to get the names of required properties.
@spec has_property?(t(), BACnet.Protocol.Constants.property_identifier()) :: boolean()
Checks if the given object has the given property.
See BACnet.Protocol.ObjectsUtility.has_property?/2 for implementation details.
Checks if the given object has Intrinsic Reporting enabled.
@spec property_writable?(t(), BACnet.Protocol.Constants.property_identifier()) :: boolean()
Checks if the given property is writable.
Check BACnet.Protocol.ObjectsUtility.property_writable?/2 for a basic run-down.
@spec remove_property( t(), BACnet.Protocol.Constants.property_identifier() | non_neg_integer() ) :: {:ok, t()} | property_update_error()
Removes an optional property from an object. This function is idempotent. Remote objects can not be mutated using this operation.
Please note that properties of services can not be dynamically removed and instead
the object must be newly created using create/4. Required properties can not be removed.
@spec set_priority(t(), 1..16, pos_integer() | nil) :: {:ok, t()} | property_update_error()
Sets the given priority in the priority array of an object. This function also updates the present value.
@spec supports_intrinsic() :: boolean()
Auto generated function to check whether the object type supports intrinsic reporting.
@spec update_property(t(), BACnet.Protocol.Constants.property_identifier(), term()) :: {:ok, t()} | property_update_error()
Updates a property of an object. To update the priority array, use set_priority/3 instead.