This module provides application tags encoding and decoding as per ASHRAE 135 chapter 20.2, including constructed tags.

32bit floats (IEEE 754 single precision floating point numbers) will be truncated to the first non-repeating digit when decoding those. Due to (single) precision issues, some floats will be rounded to the nearest single precision floating point number representation, such as 0.3 -> 0.3000000004 or 6.9 -> 6.900000095367432. By default, if more than 3 consecutive numbers are the same, the float will be truncated to the first non-repeating, such as 6.914000045 -> 6.914. This behaviour can be configured at compile-time using the application environment :bacstack. Set :app_tags_truncate_float32 to false to disable this behaviour entirely. To configure the precision (or minimum number of consecutive repeating numbers), configure :app_tags_truncate_float32_precision (defaults to 4). IEEE 754 double precision floating point numbers (64bit floats) are entirely unaffected by this behaviour.

BACnet tags are encoded in an initial byte and zero or more conditional subsequent bytes. The initial byte is defined as follows:

Bit Number:
    7     6     5     4     3     2     1     0
|-----|------|-----|-----|-----|-----|-----|-----|
|       Tag Number       |Class|Length/Value/Type|
|-----|------|-----|-----|-----|-----|-----|-----|

where Tag Number = the tag number within the class

Class = the class of tag (application or context specific)

Length/Value/Type = whether the data following the tag is primitive or constructed and specifies the length or value of primitive data.

Tag numbers ranging from 0 to 14 are encoded in the initial byte. Tag numbers from 15 to 254 (255 is reserved by ASHRAE) are encoded by setting the tag number bits to 0b1111 and the tag number extension byte in the subsequent byte to the initial byte denotes the actual tag number.

The Length/Value/Type bits are used to distinguish between primitive and constructed data. The Length/Value/Type bits are defined as follows:

• if the application tag denotes a boolean, then the boolean value is encoded in the Length/Value/Type bits
• if the data is primitive and not constructed, the Length/Value/Type bits denote the length, length from 0-4 are encoded in those bits, for length from 5 to 253 the bits are set to 0b101 and the subsequent byte denotes the length from 0-253, for length from 254 to 65535 the bits are set to 0b101, the subsequent byte is set to 254 and the following two bytes denotes the length from 0-65535, for length from 65536 to 2^32-1 the bits are set to 0b101, the subsequent byte is set to 255 and the following four bytes denotes the length from 0-2^32-1
• if the data is constructed, the Length/Value/Type bits are set to 0b110 to declare an opening tag, the tags follow in complete application tags encoding, and the closing tag is encoded with the same tag number and class as the opening tag and the Length/Value/Type bits are set to 0b111 to declare a closing tag

Constructed data contains zero or more tagged elements. Each tagged element may be a constructed element iself, this does not result in ambiguous encoding.

The following table shows application tags:

For common application tags, you will receive decoding results such as:

{:enumerated, 3}
{:object_identifier, %ObjectIdentifier{
  instance: 111,
  type: :device
}}
{:unsigned_integer, 50}

Context-specific tags contain context-specific data, which are not denoted directly by an application tag. As such the data cannot be directly decoded to the correct datatype, but the application must direct the datatype to correctly decode the data. As such the following result is not uncommon:

{:tagged, {1, <<2, 15, 226, 104>>, 4}}

The :tagged atom denotes a context-specific tag encoding and contains the bytes that were given along with the tag encoding (in this case 4 bytes). However due to the context and the correct datatype being unknown, the bytes couldn't be directly decoded to a particular datatype.

Constructed data may contain primitive or context-specific tags, as such both results are to be expected:

{:constructed, {1, {:octet_string, <<11, 22>>}, 0}}
{:constructed, {3, {:tagged, {0, <<2, 12, 49, 0>>, 4}}, 0}}

Or even nested constructed data:

{:constructed, {12,
     {:constructed, {6,
       [
         tagged: {0, "U", 1},
         constructed: {2, {:real, 1.0}, 0}
       ], 0}}, 0}}

The above snippet contains a tagged and constructed element. The tagged contains a binary with length 1 and the constructed contains a real with value 1.0. In case of the constructed element, the value was decoded, as the datatype is known. In case of the tagged element, the datatype is unknown and as such knowledge of the BACnet protocol and the context the element is from needs to be known.

If that is known, the function unfold_to_type/2 can be used to produce a primitive value by specifying the correct datatype as an atom.

ApplicationTags.unfold_to_type(:unsigned_integer, {:tagged, {0, "U", 1}})

Constructed data can also be a list of values, for example when dealing with Priority Arrays:

{:constructed, {3,
  [
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil,
      null: nil
  ], 0}}