BACnet.Protocol.StatusFlags (bacstack v0.1.0-dev.1)

Copy Markdown View Source

BACnet Status Flags is a four-bit bit string (application tag 8) that provides a compact summary of an object's health and operating mode. It is the status_flags property on virtually every standard object type and appears in almost every event-related structure.

Bit ordering (MSB first, per Clause 20.2.10):

BitNameMeaning when TRUE
0IN_ALARMevent_state != NORMAL
1FAULTreliability indicates a fault
2OVERRIDDENLocal override (operator interface, physical switch, …)
3OUT_OF_SERVICEout_of_service property is TRUE

The meanings are deliberately consistent across object types so that generic workstations can interpret the flags without knowing the concrete object type.

BACnet Specification References

  • Encoding (20.2.10): Primitive bit string. First contents octet = number of unused bits (0 for a 4-bit value). Bits are placed with the first defined Boolean in bit 7 of the first subsequent octet.
  • ASN.1 (Clause 21): BACnetStatusFlags ::= BIT STRING { in-alarm (0), fault (1), overridden (2), out-of-service (3) }
  • Mandatory property: Every object type defined in Clause 12 that has an event_state or reliability property also has a status_flags property whose value is a BACnetStatusFlags.
  • Event usage: Carried inside BACnetNotificationParameters (Change-of-State, Change-of-Reliability, …) and in GetAlarmSummary / GetEventInformation ACKs.

This module stores the four Booleans in a struct for ergonomic access while the wire form is produced by the to_bitstring/1 helper used during encoding.

Examples (Doc Test)

Creating flags

iex> flags = %StatusFlags{in_alarm: false, fault: false, overridden: true, out_of_service: false}
iex> flags.overridden
true

Round-tripping through encoding

iex> flags = %StatusFlags{in_alarm: true, fault: false, overridden: false, out_of_service: false}
iex> {:ok, [encoded]} = StatusFlags.encode(flags)
iex> StatusFlags.from_bitstring(elem(encoded, 1))
%StatusFlags{in_alarm: true, fault: false, overridden: false, out_of_service: false}

See Also

Summary

Types

t()

Represents the four Boolean flags of a BACnet Status Flags bit string (see table in the module documentation for bit positions and semantics).

Functions

encode(flags, opts \\ [])

Encodes a BACnet status flags into application tags encoding.

from_bitstring(bitstring)

Creates from an application tag bitstring a status flag.

parse(tags)

Parses a BACnet status flags from application tags encoding.

to_bitstring(t)

Creates an application tag bitstring from a status flag.

valid?(t)

Validates whether the given status flags is in form valid.

Types

t()

@type t() :: %BACnet.Protocol.StatusFlags{
  fault: boolean(),
  in_alarm: boolean(),
  out_of_service: boolean(),
  overridden: boolean()
}

Represents the four Boolean flags of a BACnet Status Flags bit string (see table in the module documentation for bit positions and semantics).

Functions

encode(flags, opts \\ [])

@spec encode(t(), Keyword.t()) ::
  {:ok, BACnet.Protocol.ApplicationTags.encoding_list()} | {:error, term()}

Encodes a BACnet status flags into application tags encoding.

from_bitstring(bitstring)

@spec from_bitstring(tuple()) :: t()

Creates from an application tag bitstring a status flag.

parse(tags)

@spec parse(BACnet.Protocol.ApplicationTags.encoding_list()) ::
  {:ok, {t(), rest :: BACnet.Protocol.ApplicationTags.encoding_list()}}
  | {:error, term()}

Parses a BACnet status flags from application tags encoding.

to_bitstring(t)

@spec to_bitstring(t()) :: BACnet.Protocol.ApplicationTags.primitive_encoding()

Creates an application tag bitstring from a status flag.

valid?(t)

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

Validates whether the given status flags is in form valid.

It only validates the struct is valid as per type specification.