@spec add_property(
  bacnet_object(),
  BACnet.Protocol.Constants.property_identifier(),
  term()
) ::
  {:ok, bacnet_object()} | {:error, term()}

Adds an optional property to an object (see bacnet_object/0).

Please note that properties of services can not be dynamically added and instead the object must be newly created.

This function calls to the object module directly, as such it enforces the bacnet_object/0 contract.

@spec cast_properties_to_object(
  BACnet.Protocol.ObjectIdentifier.t(),
  %{
    optional(
      BACnet.Protocol.Constants.property_identifier()
      | atom()
      | non_neg_integer()
    ) => term()
  },
  [cast_properties_to_object_option()]
) :: {:ok, bacnet_object()} | {:error, {atom(), term()}} | {:error, term()}

Create an object from a map of properties. This function is used for remote objects, not for local objects.

This function invokes the object module's create function.

Note: In prod environment, required modules are not explicitely loaded.

The following options are available:

• allow_unknown_properties: boolean() - Optional. Allows unknown property identifiers - which means we have no validation (defaults to false).
• ignore_unknown_properties: boolean() - Optional. Ignores properties the object module doesn't support (defaults to false).
• remote_device_id: non_neg_integer() - Optional. Adds the remote BACnet device ID to the object (ID is used for trend logging).
• revision: Constants.protocol_revision() - Optional. The BACnet protocol revision to check the properties against.
• object_opts: Keyword.t() - Optional. All other object creation options to pass to the create function.

@spec cast_property_to_value(
  BACnet.Protocol.ObjectIdentifier.t(),
  BACnet.Protocol.Constants.property_identifier(),
  BACnet.Protocol.ApplicationTags.Encoding.t()
  | [BACnet.Protocol.ApplicationTags.Encoding.t()],
  [cast_property_to_value_option()]
) :: {:ok, term()} | {:error, {atom(), term()}} | {:error, term()}

Casts a property from application tag Encoding to a more sane data type.

To cast the property to the proper data type, the correct object module needs to be known, which contains that property. The object module will tell us which data type should it be. As such, an object identifier is required.

Note: In prod environment, required modules are not explicitely loaded.

The following options are available:

• allow_partial: boolean() - Optional. Allows partial values of array or list properties (a single value).

@spec cast_read_properties_ack(
  BACnet.Protocol.ObjectIdentifier.t(),
  [
    BACnet.Protocol.Services.Ack.ReadPropertyAck.t()
    | BACnet.Protocol.Services.Ack.ReadPropertyMultipleAck.t()
  ],
  [cast_read_properties_ack_option()]
) ::
  {:ok,
   %{
     optional(
       BACnet.Protocol.Constants.property_identifier()
       | atom()
       | non_neg_integer()
     ) => term()
   }}
  | {:error, {atom(), term()}}
  | {:error, term()}

Casts the properties and its values from Read-Property-(Multiple-)Acks into a map of properties.

Note: In prod environment, required modules are not explicitely loaded.

The following options are available:

• allow_unknown_properties: boolean() | :no_unpack - Optional. Allows unknown property identifiers - which means we have no validation (defaults to false).

• ignore_array_indexes: boolean() - Optional. Ignores property array indexes as they are currently not supported (defaults to false).
• ignore_invalid_properties: boolean() - Optional. Ignores invalid properties (defaults to false).
• ignore_object_identifier_mismatch: boolean() - Optional. Ignores mismatches between object identifiers (defaults to false).
• ignore_unknown_properties: boolean() - Optional. Ignores unknown property identifiers (defaults to false).

@spec cast_value_to_property(
  BACnet.Protocol.ObjectIdentifier.t(),
  BACnet.Protocol.Constants.property_identifier(),
  term() | [term()],
  [cast_value_to_property_option()]
) ::
  {:ok,
   BACnet.Protocol.ApplicationTags.Encoding.t()
   | [BACnet.Protocol.ApplicationTags.Encoding.t()]}
  | {:error, {atom(), term()}}
  | {:error, term()}

Casts a property value to application tag Encoding.

To cast the property from the proper data type, the correct object module needs to be known, which contains that property. The object module will tell us which data type should it be. As such, an object identifier is required. No validation happens on the data.

Note: In prod environment, required modules are not explicitely loaded.

The following options are available:

• allow_nil: boolean() - Optional. Allows nil values (only useful for present value with write priority).
• allow_partial: boolean() - Optional. Allows partial values of array or list properties (a single value).

@spec delete_object_type_mapping(BACnet.Protocol.Constants.object_type()) :: :ok

Delete an object type to module relationship from the mappings.

See also get_object_type_mappings/0 for more information.

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

Get the object identifier for the BACnet object. The bacnet_object contract is enforced.

@spec get_object_type(bacnet_object()) :: BACnet.Protocol.Constants.object_type()

Get the BACnet object type. The bacnet_object contract is enforced.

@spec get_object_type_mappings() :: %{
  optional(BACnet.Protocol.Constants.object_type()) => module()
}

Get the object type to module mappings.

This mapping is used for object properties casting (such as cast_property_to_value/4). This mapping is stored in :persistent_term and is automatically populated on first use with all object types from the bacstack application.

@spec get_priority_value(bacnet_object()) ::
  {priority :: 1..16, value :: term()} | nil

Get the active priority value from the priority array, or nil.

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

Get the list of properties the object has.

@spec get_property(bacnet_object(), BACnet.Protocol.Constants.property_identifier()) ::
  {:ok, term()} | {:error, term()}

Get the property of an object (see bacnet_object/0).

This function calls to the object module directly, as such it enforces the bacnet_object/0 contract.

@spec get_remote_device_id(bacnet_object()) :: {:ok, non_neg_integer()} | :error | nil

Get the remote device ID for remote objects.

For remote objects with no remote device ID attached, this function will return :error. For local objects, this function will return nil.

@spec has_priority_array?(bacnet_object()) :: boolean()

Checks whether the given object has a priority array. This function does not verify if the property is in the properties list of the object.

@spec has_property?(bacnet_object(), BACnet.Protocol.Constants.property_identifier()) ::
  boolean()

Checks if the given object has the given property.

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

Checks if the given object has Intrinsic Reporting enabled.

@spec property_writable?(
  bacnet_object(),
  BACnet.Protocol.Constants.property_identifier()
) :: boolean()

Checks if the given property is writable.

This implementation checks for arbitary properties, if the property exists and is not annotated as readonly. For commandable objects and the present value, it checks if the object is out of service. For the event algorithm inhibit property, it checks if ref is absent or uninitialized and event detection is enabled.

Object-specific behaviour are not checked and should instead be directly checked through the object module.

@spec put_many_object_type_mapping([
  {BACnet.Protocol.Constants.object_type(), module()}
]) :: :ok

Put many object type to module relationships into the mappings at once.

See also get_object_type_mappings/0 for more information.

@spec put_object_type_mapping(BACnet.Protocol.Constants.object_type(), module()) ::
  :ok

Put an object type to module relationship into the mappings.

See also get_object_type_mappings/0 for more information.

@spec remove_property(
  bacnet_object(),
  BACnet.Protocol.Constants.property_identifier()
) ::
  {:ok, bacnet_object()} | {:error, term()}

Removes an optional property from an object (see bacnet_object/0). This function is idempotent.

Please note that properties of services can not be dynamically removed and instead the object must be newly created. Required properties can not be removed.

This function calls to the object module directly, as such it enforces the bacnet_object/0 contract.

@spec set_priority(bacnet_object(), 1..16, term()) ::
  {:ok, bacnet_object()} | {:error, term()}

Sets the given priority in the priority array of an object (see bacnet_object/0). This function also updates the present value.

This function calls to the object module directly, as such it enforces the bacnet_object/0 contract, and additionally only objects with a priority array can be used.

@spec to_list(bacnet_object()) :: [
  {BACnet.Protocol.Constants.property_identifier(), term()}
]

Turns the given object's properties with their values into a keyword list. Only properties in the properties list are taken. The bacnet_object contract is enforced.

The key :object_instance will be converted into :object_identifier.

The list is sorted in ascending order by the property name.

@spec to_map(bacnet_object()) :: %{
  optional(BACnet.Protocol.Constants.property_identifier()) => term()
}

Turns the given object's properties with their values into a map. Only properties in the properties list are taken. The bacnet_object contract is enforced.

The key :object_instance will be converted into :object_identifier.

@spec truncate_float_properties(
  bacnet_object(),
  float() | non_neg_integer(),
  :round | :truncate
) :: bacnet_object()

Truncates each property, which is a float, to the given precision (float rounding).

When giving an integer as precision, this function will behave just like Float.round/2. When giving a float as precision, this function will determine the precision (i.e. 1 for 0.1, 2 for 0.01, 0 for any value >= 1.0 or 0.0). The float value itself is not relevant, only how many decimal points there are.

Depending on the selected mode, the float will be rounded or the value is truncated.

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

Updates a property of an object (see bacnet_object/0).

This function calls to the object module directly, as such it enforces the bacnet_object/0 contract.