ABEL Spreadsheet

Overview

The ABEL Spreadsheet serves as a user-friendly interface for ABEL and allows users to create a Building Configuration file from scratch.

Note: ABEL can ingest Building Config files using the initialize operation but it does not currently support update operations

Generating GUIDs

There are two use cases for ABEL, brownfield and greenfield. Currently ABEL only supports greenfield buildings or Building Configs under the Initialize operation

Greenfield building

A greenfield building is one that has yet to be onboarded, and ABEL is used to create a Building Config from scratch to model this building. In this case GUIDs do not need to be provided except for when there are duplicate entity codes. Then and only then will the user need to provide GUIDs for the entities with duplicate codes in every one of the ABEL spreadsheet tables.

GUIDs can be generated manually by using the GUID tab in the menu bar at the top of the ABEL spreadsheet template. Note: Upon using the Generate GUIDs function, the user will have to give the guid generation script permission to edit a user’s spreadsheet.

using guid tab

Google Sheets template

The ABEL Spreadsheet Template has a strict format that must be adhered to.

Below is a definition of each table and column in the ABEL spreadsheet:

Site

The Site tab holds all information about a project site or building.

Building Code string required

A human-readable code for a building. e.g. US-SEA-BLDG1

Entity Guid string

UUID4 identifier for a building. Unless you are onboarding a Google building, this value is generated by ABEL and does not need to be provided for initial onboarding.

Etag string

Version control tag for entities in an entity type database. Used only when updating an existing building config.

Note: A Site should not be considered an entity and should not be listed in the Entities tab.

Entities

The Entities tab holds all information about reporting entities and virtual entities in a building or site. If ABEL is being used for Google then Guids are required for all entities in the FACILTITIES namespace which can be retrieved from DB API.

Entity Code string required

Human-readable code for an entity e.g. AHU-1001

Entity Guid string

UUID4 identifier for an entity. Note: If an entity belongs to the FACITITLIES namespace and ABEL is being used or Google, then this field is required or else spreadsheet validation will fail.

Etag string

Version control tag for entities in an entity type database. Used only when updating an existing building config.

Is Reporting Boolean required

TRUE if an entity is reporting data and FALSE if the entity is virtual.

Cloud Device ID string

Cloud registry device numeric identifier. The device numeric ID is automatically created by a Cloud IoT Core (or similar cloud iot service), and it is globally unique and not editable.

DBO Namespace string required

Namespace for an entity as defined in the Digital Buidings Ontology. e.g. HVAC

DBO General Type string

General Type for an entity as defined in a particular namespace in the Digital Buildings Ontology. e.g. AHU

DBO Entity Type Name string required

Entity Type Name for an Entity as defined in the Digital Buildings Ontology. e.g. VAV_SD_DSP

Operation string

An update operation for an entity which can be one of the following:

Operation specifies if and how an entity is being updated from an existing configuration.

Entity Fields

The Entity Fields tab defines fields translated by reporting entities and linked to virtual entities defined in the Entities tab.

Entity Code string required

A human-readable code for an entity of which an entity field is a data point. This code must already be defined in the Entities table. e.g. AHU-1001

Entity Guid string

UUID4 value for an entity corresponding to the entity in the Entity Code column ad is a unique identifier for an entity. This column does not need be filled in unless the corresponding entity code is not unique. This column will be used when ABEL writes to a blank spreadsheet.

Reporting Entity Code string

If a field is linked to a virtual entity and its telemetry data is reported by a reporting entity, then the Entity Code column must be the virtual entity code and the reporting entity code is the code of the entity reporting the field’s data. This may be a gateway or some other IoT connected entity. This value may be left blank unless a field is linked to a virtual entity.

Reporting Entity Guid string

UUID4 identifier for an entity corresponding to the entity in the Reporting Entity Code Column. This value may be left blank unless the reporting entity code is not unique.

Reporting Entity Field string

Name of a field as it is reported by a gateway or other reporting entity. e.g. zone_air_temperature_sensor_1 where the standard field name is zone_air_temperature_sensor. If the a field is not linked to a virtual entity then this value does not need to be filled in. Reporting entity fields may be enumerated.

DBO Standard Field Name string required

Standardized field name belonging to an entity type as defined in the Digital Buildings Ontology. e.g. zone_air_temperature_sensor

Missing boolean required

Indicates whether a field should be present in an entity’s translation to accurately model an entity type even though it may not be reported in its telemetry payload.

NOTE Raw Field Name, Raw Unit Path, DBO Standard Unit Value, and Raw Unit Value should not be provided for a missing field.

Raw Field Name string

Path to data point on a physical device’s telemetry payload. The field path is used as the present_value in an entity type’s translation to a physical device payload. e.g. points.discharge_fan_run_command.present_value.

Raw Unit Path string

Path to a data point’s units in a telemetry payload. Used as the key for units in an entity type translation. e.g. points.zone_air_cooling_temperature_setpoint.unit. Leave blank if a field is a multi-state value

DBO Standard Unit Value string

Standardized dimensional unit for a standard field as defined in Digital Buildings Ontology. e.g. degrees_celsius

NOTE If a field truly has no units, then DBO Standard Unit Value should have the value of no-units.

Raw Unit Value string

Unit value as reported by a reporting device. Used for a dimensional unit’s value mapping in an entity translation e.g. degC

NOTE If a field truly has no units, then Raw Unit Value should have the value no_units.

States

The States tab defines values for multi-state value fields defined in the Entity Fields tab.

Reporting Entity Code string required

The code or name of the entity reporting this state in its telemetry payload. This will the be the code of some reporting entity.

Entity Guid string

UUID4 identifier for an entity corresponding to the entity in the Reporting Entity Code column.

Reporting Entity Field string required

Name of the entity field which reports a multi-state value in its telemetry payload.

DBO Standard State string required

Standardized multi-state value name as defined in Digital Buildings Ontology. e.g. ON

Raw State string required

Raw multi-state value for a data point in the telemetry payload for a device. e.g. on

Connections

Connections define the device relationships that exist between two entities in a building. Connections to a building such as a building having a CONTAINS relationship to a floor do not need to be defined as they are implied. For Google buildings, relationships to a building are already accounted for and do not need to be re-defined.

Source Entity Code string required

Human-readable code for a connection source entity. e.g. AHU-1001

Source Entity Guid string

UUID4 identifier for an entity corresponding to an entity in the Entities tab for connection source. This does not need to be provided unless the source entity code is not unique.

DBO Connection Type string required

A connection type as defined in Digital Buildings Ontology connections. e.g. FEEDS

Target Entity Code string required

Human-readable code for a connection target entity. e.g. AHU-1001

Target Entity Guid string

UUID4 identifier for an entity corresponding to an entity in the Entities tab for a connection target. This does not need to be provided unless the target entity code is non-unique.