Digital Buildings

ABEL (Automated Building Entity Loader) is a Python command-line tool designed to help systems integrators and DBO users manage Building Configuration YAML files using spreadsheets.

Building configuration files are concrete instances of the ontology that define equipment, devices, and spaces (including device types, I/O points, and relationships). Because these files can contain thousands of entities, ABEL provides a spreadsheet-based workflow to avoid manual YAML editing errors.

Key Features:

• Spreadsheet to YAML: Create or edit a Google Sheet (using the ABEL Spreadsheet Template) and export it to a building configuration file.
• Validation: Run an Instance Validator (with optional telemetry validation) during the conversion process to catch errors before onboarding.
• YAML to Spreadsheet: Convert an existing building configuration file back into a Google Sheet for easier editing.

Subfields are the basic units of meaning in the ontology, analogous to 'tags' in other systems like Brick or Haystack. They are typically defined in a global namespace and must be unique within that namespace.

Key characteristics:

• Case Insensitivity: Subfield names may be camelCased for readability but are not case sensitive.
• No Namespacing: You cannot refer to a subfield with a namespace identifier (e.g., HVAC/subfield is invalid).
• Global Preference: Most subfields should be global. Defining a subfield locally prevents any field using it from being elevated to the global namespace.

Subfields are categorized to dictate how they combine to form fields:

<table>
  <tr
   <td class="strong">Category</strong></td
   <td class="strong">Description</strong></td
   <td class="strong">Examples</strong></td
   <td class="strong">Allowed Per Field</strong></td
   <td class="strong">Required</strong></td
  </tr>
  <tr>
   <td>Aggregation Descriptor</td>
   <td>Modifies aggregations to differentiate temporal (e.g., daily max) from spatial aggregation.</td>
   <td>daily, fivesecond, fivesecondrolling</td>
   <td>1</td>
   <td>Optional (Required if Aggregation is used)</td>
  </tr>
  <tr>
   <td>Aggregation</td>
   <td>Spatial aggregation (e.g., max of 3 sensors).</td>
   <td>Average, Max, Min</td>
   <td>1</td>
   <td>Optional</td>
  </tr>
  <tr>
   <td>Descriptor</td>
   <td>General purpose modifier (e.g., Discharge, Return, Zone).</td>
   <td>Discharge, Return, Zone, Primary, Chilled etc...</td>
   <td>10</td>
   <td>Optional</td>
  </tr>
  <tr>
   <td>Component</td>
   <td>Specific subcomponent (e.g., fan of a fan-coil unit).</td>
   <td>Valve, fan, damper...</td>
   <td>10</td>
   <td>Optional</td>
  </tr>
  <tr>
   <td>Measurement Descriptor</td>
   <td>Adds context to measurement (e.g., differential vs absolute pressure).</td>
   <td>Differential, relative, static</td>
   <td>1</td>
   <td>Optional</td>
  </tr>
  <tr>
   <td>Measurement</td>
   <td>The type of measurement (e.g., temperature). Required for numeric fields (except `count`).</td>
   <td>Temperature, flowrate, flowvolume</td>
   <td>1</td>
   <td>Optional</td>
  </tr>
  <tr>
   <td>Point Type</td>
   <td>Defines directionality, reading type, and telemetric vs static nature. **Required for every field.**</td>
   <td>Sensor, Setpoint, Status, Command, Count, Accumulator</td>
   <td>1</td>
   <td>Required</td>
  </tr>
</table>

The HVAC model uses a layered approach to define equipment and systems:

1. General Types: Broad classifications used to group equipment with similar holistic functions (e.g., AHU, CH, PMP). These are applied based on the physical device, not just its telemetry.
2. Abstract Types (Analysis Types): Functional groups that define how data points relate to control strategies. They are categorized into:
   • MONITORING: Fields that monitor current state (e.g., sensors, valve positions).
   • OPERATIONAL: Holds operating conditions, always including a sensor and setpoint pair.
   • CONTROLS: Fields necessary to analyze control system performance.
3. Functional Types: Abstract groups (like functional groups) that are not applied directly to devices but are combined to create canonical types.

When modeling, if a device has incomplete telemetry (e.g., a setpoint is missing), you should still apply the correct type and mark the unavailable fields as MISSING rather than creating a new, incomplete abstract type.

Components in the ontology behave differently regarding how they handle namespaces:

Namespace-Aware Components

These components carry an explicit namespace qualifier (e.g., HVAC/zone_temperature_sensor) unless they are elevated to the global namespace.

• Fields, EntityTypes, and MultiStates are namespace-aware.
• Due to Namespace Elevation, states in field files and fields in entity type files can often be written with the namespace omitted. A namespace is only strictly required when referencing a non-elevated field located in a different namespace.

Namespace-Agnostic Components

These components do not carry namespace qualifiers and behave as follows:

• Subfields: These are not namespace-aware. They are used verbatim. If defined in a non-global namespace, they are only available within that namespace. A local subfield definition will override a global one for any fields defined in that specific namespace. It is best practice to define subfields in the global namespace.
• Units and Connections: These are always defined globally.