BACnet.Protocol.ObjectTypes.Program (bacstack v0.1.0-dev.1)

The Program object gives BACnet clients a standardised window into a vendor-specific control program, script, or state machine running inside the device. It exposes the current program_state (idle, running, halted, etc.), a program_change command property that can be used to start, stop, restart, or unload the program, plus optional reason_for_halt, program_location, and instance_of (for identifying which program (image) is loaded).

The object deliberately leaves the actual program logic and any additional parameters as vendor-specific. It is the standard way to monitor and control embedded control logic, custom sequences, or downloadable applications from a BACnet workstation.

Object Description (ASHRAE 135)

The Program object type defines a standardized object whose properties represent the externally visible characteristics of an application program.
Program objects that support intrinsic reporting shall apply the NONE event algorithm.

Behaviour and Operation

Program objects give network visibility and limited control over a vendor-specific control program, script, state machine or downloadable application running inside the device.

The local program runtime is responsible for updating program_state, reason_for_halt, program_location, etc. as the program executes. Clients can write to program_change to request start, stop, restart, unload, etc. The object implementation (or device server) translates the program_change request into the appropriate action on the underlying program.

program_change is the control surface. Reliability can reflect problems with the program image or runtime.

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, via update_property/3 (never direct mutation). Read notes below + generated tables for details.

Special / live properties and expected developer behaviour

program_state: idle, running, halted, loading, etc. Dev must: Your actual runtime (script, PLC, state machine) must keep this updated as it executes.
program_change: The control surface (ready, load, run, halt, restart, unload...). Dev must: On write/change, interpret and perform the action on your runtime. Then update program_state and set program_change to ready to reflect result.
reason_for_halt, description_of_halt: Details on why halted. Dev must: Your runtime sets these when entering halted state.
program_location, instance_of: Identification of what is loaded. Dev must: Set when loading.
out_of_service, status_flags, reliability: Dev must: Reliability for image corrupt, interpreter crash, missing resources. Your runtime updates these. in_alarm/fault/out_of_service bits of status_flags are auto-managed by the object. The status_flags property is automatically updated depending on the program_state (idle means not in service, TRUE).

See the detailed "Your runtime owns the real program" and "program_change is the control surface" below.

The Program object is a window into something that is deliberately vendor-specific. The BACnet-visible surface is small; everything interesting lives in the "black box" that the Program object points at.

Your runtime owns the real program: The object only stores the standardised view (program_state, program_change, reason_for_halt, program_location, instance_of, description_of_halt, …). Your script / state machine / PLC logic / … is responsible for keeping those fields up to date as it runs.

program_change is the control surface: When a client (or your own code) writes a program_request (ready, load, run, halt, restart, unload, …) into program_change, you must interpret it and actually do the work:

load a new image (perhaps from a File object)
start / stop / single-step the interpreter or task
unload / free resources After the action you write the resulting state back into program_state and update program_change to ready.

program_state is what the world sees: idle, loading, running, waiting, halted, etc. Your runtime must keep it current; clients poll it or subscribe to COVs on it to know what the "app" is doing.

Reliability: Use it for "the program image is corrupt", "the interpreter crashed", "a required external resource (another object, a file, a network connection) is missing", etc. reason_for_halt gives a more detailed code when the program is in the halted state.

Reinitialise / power up: On device restart you set the Program object back to a known state based on your program's state.

Examples

Creating a Program object:

iex> {:ok, p} = BACnet.Protocol.ObjectTypes.Program.create(1400, "MyApp", %{program_state: :idle}); p.object_name
"MyApp"

Summary

Types

common_object_opts()

Common object options for creation - all are optional.

object_opts()

Options accepted when creating or configuring a Program object.

property_name()

Available property names for this object.

property_update_error()

The structure for property errors.

t()

Represents a Program object. All keys should be treated as read-only, all updates should go only through update_property/3.

Functions

add_property(object, property, value)

Adds an optional property to an object. Remote objects can not be mutated using this operation.

create(instance_number, object_name, properties \\ %{}, opts \\ [])

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.

get_all_properties()

Auto generated function to get the names of all properties this object supports.

get_annotation(name)

Auto generated function to get the annotations for the given property name.

get_annotations()

Auto generated function to get the list of annotations for each property.

get_cov_properties()

Auto generated function to get the names of properties used for COV reporting.

get_intrinsic_properties()

Auto generated function to get the names of intrinsic properties.

get_object_identifier(object)

Get the BACnet object identifier.

get_optional_properties()

Auto generated function to get the names of optional properties.

get_properties(object)

Get the list of properties the object has.

get_properties_type_map()

Auto generated function to get a map of property name to type.

get_property(object, property)

Get a property's value from an object.

get_protected_properties()

Auto generated function to get the names of protected properties.

get_readonly_properties()

Auto generated function to get the names of readonly properties.

get_required_properties()

Auto generated function to get the names of required properties.

has_property?(object, property)

Checks if the given object has the given property.

intrinsic_reporting?(object)

Checks if the given object has Intrinsic Reporting enabled.

property_writable?(object, property)

Checks if the given property is writable.

remove_property(object, property)

Removes an optional property from an object. This function is idempotent. Remote objects can not be mutated using this operation.

supports_intrinsic()

Auto generated function to check whether the object type supports intrinsic reporting.

update_property(object, property, value)

Updates a property of an object.

Types

common_object_opts()

@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 a Constants.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 type atom are 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" (usually Encoding structs).
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. See BACnet.Protocol.Constants.protocol_revision/0 for 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. Value true neither type nor value are validated. Value :value means the type is still validated and only the value validator is not run (if present). The property's validator_fun will also be skipped.

object_opts()

@type object_opts() :: common_object_opts()

Options accepted when creating or configuring a Program object.

property_name()

@type property_name() ::
  :acked_transitions
  | :description
  | :description_of_halt
  | :event_algorithm_inhibit
  | :event_algorithm_inhibit_ref
  | :event_detection_enable
  | :event_enable
  | :event_message_texts
  | :event_message_texts_config
  | :event_timestamps
  | :instance_of
  | :limit_enable
  | :notification_class
  | :notify_type
  | :object_instance
  | :object_name
  | :out_of_service
  | :profile_location
  | :profile_name
  | :program_change
  | :program_state
  | :reason_for_halt
  | :reliability
  | :reliability_evaluation_inhibit
  | :status_flags
  | :tags
  | :time_delay
  | :time_delay_normal

Available property names for this object.

property_update_error()

@type property_update_error() ::
  {:error,
   {error :: atom(),
    property :: BACnet.Protocol.Constants.property_identifier()}}

The structure for property errors.

t()

@type t() :: %BACnet.Protocol.ObjectTypes.Program{
  _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,
  description: String.t() | nil,
  description_of_halt: 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_timestamps: BACnet.Protocol.EventTimestamps.t() | nil,
  instance_of: String.t() | 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,
  object_instance: non_neg_integer(),
  object_name: String.t(),
  out_of_service: boolean(),
  profile_location: String.t() | nil,
  profile_name: String.t() | nil,
  program_change:
    BACnet.Protocol.Constants.program_request()
    | (reserved_or_vendor_extension :: non_neg_integer()),
  program_state:
    BACnet.Protocol.Constants.program_state()
    | (reserved_or_vendor_extension :: non_neg_integer()),
  reason_for_halt:
    BACnet.Protocol.Constants.program_error()
    | (reserved_or_vendor_extension :: non_neg_integer())
    | nil,
  reliability:
    BACnet.Protocol.Constants.reliability()
    | (reserved_or_vendor_extension :: non_neg_integer())
    | nil,
  reliability_evaluation_inhibit: boolean() | 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 a Program object. All keys should be treated as read-only, all updates should go only through update_property/3.

Functions

add_property(object, property, value)

@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.

create(instance_number, object_name, properties \\ %{}, opts \\ [])

@spec create(
  non_neg_integer(),
  String.t(),
  %{optional(property_name() | atom() | non_neg_integer()) => term()},
  [object_opts() | internal_metadata()]
) :: {:ok, t()} | property_update_error()

Only properties that are required for specific services (i.e. Intrinsic Reporting) are automatically created.

get_all_properties()

@spec get_all_properties() :: [BACnet.Protocol.Constants.property_identifier()]

Auto generated function to get the names of all properties this object supports.

get_annotation(name)

@spec get_annotation(property_name()) :: [term()]

Auto generated function to get the annotations for the given property name.

get_annotations()

@spec get_annotations() :: [{name :: property_name(), values :: [term()]}]

Auto generated function to get the list of annotations for each property.

get_cov_properties()

@spec get_cov_properties() :: [BACnet.Protocol.Constants.property_identifier()]

Auto generated function to get the names of properties used for COV reporting.

get_intrinsic_properties()

@spec get_intrinsic_properties() :: [BACnet.Protocol.Constants.property_identifier()]

Auto generated function to get the names of intrinsic properties.

get_object_identifier(object)

@spec get_object_identifier(t()) :: BACnet.Protocol.ObjectIdentifier.t()

Get the BACnet object identifier.

get_optional_properties()

@spec get_optional_properties() :: [BACnet.Protocol.Constants.property_identifier()]

Auto generated function to get the names of optional properties.

get_properties(object)

@spec get_properties(t()) :: [BACnet.Protocol.Constants.property_identifier()]

Get the list of properties the object has.

get_properties_type_map()

@spec get_properties_type_map() :: map()

Auto generated function to get a map of property name to type.

get_property(object, property)

@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.

get_protected_properties()

@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.

get_readonly_properties()

@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.

get_required_properties()

@spec get_required_properties() :: [BACnet.Protocol.Constants.property_identifier()]

Auto generated function to get the names of required properties.

has_property?(object, property)

@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.

intrinsic_reporting?(object)

@spec intrinsic_reporting?(t()) :: boolean()

Checks if the given object has Intrinsic Reporting enabled.

property_writable?(object, property)

@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.

remove_property(object, property)

@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.

supports_intrinsic()

@spec supports_intrinsic() :: boolean()

Auto generated function to check whether the object type supports intrinsic reporting.

update_property(object, property, value)

@spec update_property(t(), BACnet.Protocol.Constants.property_identifier(), term()) ::
  {:ok, t()} | property_update_error()

Updates a property of an object.

BACnet.Protocol.ObjectTypes.Program (bacstack v0.1.0-dev.1)

Object Description (ASHRAE 135)

Behaviour and Operation

Developer Implementation Notes (geared to device server / application authors)

Examples

See Also

Summary

Types

Functions

Types

common_object_opts()

object_opts()

property_name()

property_update_error()

t()

Functions

add_property(object, property, value)

create(instance_number, object_name, properties \\ %{}, opts \\ [])

get_all_properties()

get_annotation(name)

get_annotations()

get_cov_properties()

get_intrinsic_properties()

get_object_identifier(object)

get_optional_properties()

get_properties(object)

get_properties_type_map()

get_property(object, property)

get_protected_properties()

get_readonly_properties()

get_required_properties()

has_property?(object, property)

intrinsic_reporting?(object)

property_writable?(object, property)

remove_property(object, property)

supports_intrinsic()

update_property(object, property, value)