Skip to the content.

Model Instance Configuration (building configuration file)

Prerequisite Please review the Learning Modules. This readme assumes that the audience is familiar with the high level concepts which comprise the building config.

In addition to a language and primitives for configuring an abstract building model, the Digital Buildings project provides a YAML configuration syntax for mapping concrete assets to the abstract model in a lightweight way. The intent of providing this syntax is to make “manual” onboarding faster and easier (because the resulting data file is machine readable and can be machine validated) as well as provide a clean interface format for machine-assisted onboarding to use.

NB: Some of the instructions here details that are specific to Google’s implementation of this stack on its own campuses (such as references to CloudIoT registration). These should be relatively obvious to a critical reader, but if they are confusing feel free to post an issue in the project.

Key Concepts

Creation of a concrete model is primarily concerned with defining entities, their relationships to each other, and their relationships to real physical things in the world.

Conceptually, we divide entities into three categories:

The following statements apply when considering entity categories:

To completely map real data to the model we also need a few more concepts:

These should all be defined in a complete configuration.

Typical Data Elements

While there is basically infinite diversity in what can be defined for a building, some elements are more or less expected in every model:

Configuration Detail

Contents

Each configuration file should contain the contents for one building (or other logical division of your universe). The reason for this is that the definitions in the file are intentionally not keyed by a globally unique identifier. This is done for a few of reasons:

  1. The human-readable entity code is, well, more human readable.
  2. Using human-readable codes, which are typically created at design time and known a-priori, allows for incremental population of the file at different stages of the commissioning or onboarding process, rather than having to wait until all the devices are cloud-registered.
  3. There is inherent value to forcing locally unique naming of spaces and equipment (because it makes it easier to find stuff).

Config Format

The configuration format is focused around defining the entities in the model. A generic entity with all possible top level fields looks like this[^5]:

NOTE: The new Building Config format switches entities being keyed by codes to being keyed by guids and Ids are removed. To convert the old format to the new format, run your config.yaml through the guid generator.

Identifiers

New Format

f7d82b75-ea41-49e2-bb5a-53228044eb4c # Entity keyed by a GUID
  type: NAMESPACE/A_DIGITAL_BUILDINGS_ENTITY_TYPE
  code: ENTITY-CODE
  connections:
    # Listed entities are sources on connections
    ANOTHER-ENTITY-GUID: FEEDS
    A-THIRD-ENTITY-GUID: CONTAINS
  links:
    A-FOURTH-ENTITY-GUID: # Source entity keyed by a GUID
      # target_device_field: source_device_field
      supply_air_damper_position_command: supply_air_damper_command_1
      zone_air_temperature: zone_air_temperature_sensor_1
  cloud_device_id: device-id-from-cloud-iot-registry
  translation:
    zone_air_temperature_sensor:
      present_value: "points.temp_1.present_value"
      units:
        key: "points.temp_1.units"
        values:
          degrees_celsius: "degC"
    supply_air_isolation_damper_command:
      present_value: "points.damper_1.present_value"
      states:
        OPEN: "1"
        CLOSED:
        - "2"
        - "3"

Old Format

ENTITY-CODE:
  guid: f7d82b75-ea41-49e2-bb5a-53228044eb4c # guid field is generated with guid generator.
  type: NAMESPACE/A_DIGITAL_BUILDINGS_ENTITY_TYPE
  connections:
    # Listed entities are sources on connections
    ANOTHER-ENTITY: FEEDS
    A-THIRD-ENTITY: CONTAINS
  links:
    A-FOURTH-ENTITY: # Source entity code
      # target_device_field: source_device_field
      supply_air_damper_position_command: supply_air_damper_command_1
      zone_air_temperature: zone_air_temperature_sensor_1
  cloud_device_id: device-id-from-cloud-iot-registry
  translation:
    zone_air_temperature_sensor:
      present_value: "points.temp_1.present_value"
      units:
        key: "points.temp_1.units"
        values:
          degrees_celsius: "degC"
    supply_air_isolation_damper_command:
      present_value: "points.damper_1.present_value"
      states:
        OPEN: "1"
        CLOSED:
        - "2"
        - "3"

The Digital Buildings platform has recently transitioned to the new format, which is identical to the above format except that entities were keyed by their codenand contained a separate id and guid field.

Entities are now keyed by a globally unique identifier and code has been moved to it’s own separate field. id fields have been totally deprecated.

The old format is still valid if the id field is removed, and can be converted to the new format using the guid generator.

NOTE: Please continue using the old format, and use the guid generator to convert a building configuration to the new format.

Spaces

In nearly every model, entities should exist for Buildings, Floors, and Rooms. The following example shows a building with one floor and one room:

# Building
UK-LON-S2:
  type: FACILITIES/BUILDING

# Floor
UK-LON-S2-1:
  type: FACILITIES/FLOOR
  connections:
    UK-LON-S2: CONTAINS

# Room
UK-LON-S2-1-1C3G:
  type: FACILITIES/ROOM
  connections:
    UK-LON-S2-1: CONTAINS

In this example, entities are identified by their globally unique identifiers. GUIDSs are widely used and highly recommended due to their exponentially low collision rate.

Types for spaces are contained in the FACILITIES namespace of the ontology.

Devices

Reporting Physical Devices

When sending data from a building via Cloud IoT, a reporting device is any device with its own entry in Cloud Device Manager (CDM)1.

For clarity the human readable ID of the device in CDM and the entity code in the config file should be the same[^6]. If the building also has a CAD drawing or BIM model, good practice is for this code to also exist in the CAD or BIM model.

Choose an entity type that has the correct fields for this type.

Define a translation as necessary…

Defining Translations

It is commonly (always?) the case that real devices have data payloads that differ from our modeled entity types. In this case, it is necessary to define a translation between the native payload and the standard form. This standardization includes the field names, field values, dimensional units and multistate definitions.

Below is a minimal example of what a translation configuration looks like in long form:

FCU-123:
  ...
  translation:
    zone_air_temperature_sensor:
      present_value: "points.temp_1.present_value"
      units:
        key: "pointset.points.temp_1.units"
        values:
          degrees_celsius: "degC"
    supply_air_isolation_damper_command:
      present_value: "points.damper_1.present_value"
      states:
        OPEN: "1"
        CLOSED:
        - "2"
        - "3"
    zone_air_temperature_setpoint: MISSING

Inside the translation block, keys correspond to standard fields in the ontology. Within each field block we provide information about the following:

Translation Shortcuts

In order to eliminate duplicate work, the format provides some shortcuts to translation definitions:

  1. Substitute the translation block with translate_like:ENTITY-CODE to use a translation that is already defined on another entity. The guid generator does this for you.
  2. For devices that comply with UDMI a short form can be used.

Virtual Devices

In many cases the logical device and the reporting device are the same thing (i.e. the device that sends data is also the entity type you want in your model). When the two are different (i.e. the logical device does not send its own data) a virtual device is required.

Virtual entities are nearly always logical entities. Because logical entities are the representations that the applications using your model will care about, virtual devices should generally map to canonical types. In an integrated design in construction stack, logical devices should be called out by code in the CAD/BIM models and the same code should be used for them in this config.

A virtual entity example:

VAV-32:
  type: NAMESPACE/DEVICE_TYPE
  links:
    ANOTHER-ENTITY: # source device
      # target_device_field: source_device_field
      supply_air_damper_position_command: supply_air_damper_command_1
      ...

The key difference between virtual and reporting entities is that all the fields of a virtual entity are derived via links. the link block lists all the source entities and fields that contribute to this entity’s data and provides a mapping to this entity’s local fields.

Device Relationships

In addition to telemetry points, many devices will have relationships to other entities. System and spatial relationships are defined with the connections block. Connection definitions work the same way for all entities, with connections always defined on the target of the connection.

Expanding the VAV definition from the previous section, and adding some lights:

VAV-32:
  type: HVAC/VAV
  connections:
    UK-LON-6PS-1: CONTAINS
    AHU-123: FEEDS

LF-123:
  type: LIGHTING/LIGHTING_FIXTURE
  connections:
    UK-LON-6PS-1-1A2: CONTAINS
    LCG-234: HAS_PART

Zones and Control Groups

In addition to spaces and devices, most buildings have other types of Logically defined areas or groups that aren’t strictly a “device”. These entities are simply virtual devices, following all the same rules, but often do not have links.

Here are some examples:

# HVAC Zone
ZONE-123:
  type: HVAC/ZONE
  connections:
    UK-LON-6PS-1: CONTAINS
    VAV-123: FEEDS

# Lighting Control Group
LCG-234:
  type: LIGHTING/SWITCH_GROUP
  connections:
    UK-LON-6PS-1: CONTAINS
    SW-456: CONTROLS

Building Configuration Modes

This document details the building configuration modes available in v1 Beta. The current version, v1 Alpha, is available with limited functionality.

  1. a configuration metadata block that informs the program how to handle the entities contained in the building configuration.

  2. Entity block(s) derived from a physical building; they model physical and virtual devices within a building. For more information please refer to the learning modules.

The configuration block, keyed by CONFIG_METADATA, currently allows for a single field operation with values of INITIALIZE or UPDATE. This is shown below for a general entity coded as E and an UPDATE configuration operation.

CONFIG_METADATA:
  operation: UPDATE

E-GUID:
  type: ...
  code: E
  etag: ...
  cloud_device_id: ...
  translation: ...
  connections: ...
  links: ...
  operation: [ ADD | DELETE | UPDATE | EXPORT ]
  <update_mask: >

  .
  .
  .

There is a specification for operation in both the configuration metadata block as well as the entity blocks contained within the building configuration file. Although they share the same attribute name, their meanings differ. The operation contained within the CONFIG_METADATA block specifies the program workflow for the building configuration file as a whole. Whereas the attribute operation of an entity details what is being done to that particular entity; with an update_mask (if applicable).

An additional attribute etag has been included in each entity. The etag is required for all entities under an UPDATE configuration and used to sync proposed changes with the current state (onboarded buildings). Under this scenario, in addition to standard offline validation checks, etags are compared between the building configuration file and backend datastore. Successfully validating the proposed update if all etags align; signaling that the update building configuration is synced to the current state. The etags are generated upon export and are not created by user; i.e. updates can only be applied to a previously exported building configuration.

In the context of a building configuration file, the program is agnostic to the location of the configuration metadata block. However, the standard practice is to place this at the very top of the building configuration.

CONFIG_METADATA:
  operation: INITIALIZE
  
E1-GUID:
  type: ...
  code: E1
  ...
  
E2-GUID:
  type: ...
  code: E2
  ...
  
E3-GUID:
  type: ...
  code: E3
  ...

INITIALIZE

Default operation for modeling a building yet to be onboarded. In this mode of operation the program will treat the entire contents of the building configuration as a new instantiation. The operation attribute for each entity contained within the building config will default to ADD; unless otherwise specified. Allowed entity operation values in this mode are of ADD or EXPORT and is enforced by the instance validator. The building config must pass all standard offline validation checks. If the CONFIG_METADATA block is missing from the building configuration the program will assume this mode of operation. An INITIALIZE configuration only allows EXPORT operations on previously onboarded entities. This is shown below with specified operations for entities E1, E2, and an export of building entity E3; note that there is no specification of operation for entity E2.

CONFIG_METADATA:
  operation: INITIALIZE
  
E1-GUID:
  type: ...
  code: E1
  operation: ADD
  ...
  
E2-GUID: # no operation specified, ADD assumed
  type: ...
  code: E2
  connections:
    E3-GUID: CONNECTS_TO  # reference connection to an onboarded building
  ...
  
E3-GUID: # export an onboarded building as its referenced by E2
  type: FACILITIES/BUILDING
  code: E3
  operation: EXPORT
  ...

UPDATE

In this mode the configuration will be considered as a scoped view of an already instantiated building; allowing users to perform operations of ADD, DELETE, UPDATE, and EXPORT on entities. This follows the copy-and-replace strategy:

Under the UPDATE configuration:

This mode, with an entity operation of UPDATE, introduces another attribute to the entity blocks keyed by update_mask. This is shown in the example for an entity coded as E4, showing all possible entity attributes, where update_mask is given with fields of translation and cloud_device_id.

CONFIG_METADATA:
  operation: UPDATE

E4-GUID:
  type: ...
  code: E4
  etag: ...
  cloud_device_id: ...
  translation: ...
  connections: ...
  links: ...
  operation: UPDATE # This can be omitted when update_mask is specified
  update_mask:
    - translation
    - cloud_device_id

There are various types of updates that can be performed. All of this updates are performed according to the fields provided in the update_mask. They are grouped in the following categories:

  1. type
  2. code
  3. translation
  4. connections
  5. links

    Type update

    This update typically occurs alongside an update to the translation or links . If the update to another type contains the same fields, as the previous type, this can be done independently. The entity type can be changed to any valid identifier but cannot be cleared. This is shown in the description for Code update.

Code update

This update may be completed independently; however, it typically follows a type update. In the following example: the code is updated from FAN-123 to PMP-123 which follows a change of type from HVAC/FAN_SS to HVAC/PMP_SS. Since the two types share the same fields there is no need to make updates to the translations.

Translation update

In general, a type update requires an update of the translation. These updates are completed on the standard field by the following: replacement and mapping, addition, or removal. For example an entity coded as ENTITY-CODE with the required fields field_a, field_b, and field_c:

ENTITY-GUID:
  type: SOME_TYPE_NAMESPACE/SOME_TYPE_A
  code: ENTITY-CODE
  etag: ...
  cloud_device_id: NEW-CLOUD-DEVICE-ID
  translation:
    field_a: 
      present_value: points.analog-value_1.present_value
      units: 
    field_b: 
      present_value: points.analog-value_2.present_value
      units: 
    field_c: 
      present_value: points.analog-value_3.present_value
      units: 

To change the type from SOME_TYPE_A to SOME_TYPE_B in the same namespace requiring fields: field_b, field_c, and field_d. This can be done as follows:

ENTITY-GUID:
  type: SOME_TYPE_NAMESPACE/SOME_TYPE_B
  code: ...
  etag: ...
  cloud_device_id: ...
  translation:
    field_b: 
      present_value: points.analog-value_2.present_value
      units: 
    field_c: 
      present_value: points.analog-value_3.present_value
      units: 
    field_d: 
      present_value: points.analog-value_4.present_value
      units: 
  update_mask:
    - type
    - translation

Note: a type update typically requires a code update. This has been omitted from the example for brevity. Any field that is omitted is deleted, not present in the instantiated entity is added, or present is ignored.

Connections update

The entity’s connections can be updated to reflect a new connection type, source, or can be cleared. An update to both the source entity and connection type together is allowed. For example: an entity coded as LF-123 with a connection to source entity coded as LCG-123:

LF-123-GUID
  type: LIGHTING/LIGHTING_FIXTURE
  code: LF-123
  etag: ...
  cloud_device_id: ...
  connections:
    LCG-123-GUID: HAS_PART

The connection type can be updated from HAS_PART to CONNECTS_TO as:

LF-123-GUID
  type: LIGHTING/LIGHTING_FIXTURE
  code: LF-123
  etag: ...
  cloud_device_id: ...
  connections:
    LCG-123-GUID: CONNECTS_TO
  update_mask:
    - connections

The connection source can be updated from LCG-123-GUID to LCG-234-GUID as:

LF-123-GUID
  type: LIGHTING/LIGHTING_FIXTURE
  code: LF-123
  etag: ...
  cloud_device_id: ...
  connections:
    LCG-234-GUID: HAS_PART
  update_mask:
    - connections

Or all connection can be cleared by specifying connections in the update_mask and no specification for connections:

LF-123-GUID
  type: LIGHTING/LIGHTING_FIXTURE
  code: LF-123
  etag: ...
  cloud_device_id: ...
  update_mask:
    - connections

The links exist on virtual entities and are tied to physical entities and more precisely to the standard fields of a given translation Virtual Devices. Therefore, when an entity type is updated with a change applied at the translation level, the links must be updated. The links update follows the same concept as the translation depicted earlier. For example: a virtual entity coded as VIRTUAL-ENTITY-123 of TYPE-C is linked to another coded as ENTITY-123 with type TYPE-A and fields: field_a, field_b, field_c.

ENTITY-A-123-GUID:
  type: SOME_TYPE_NAMESPACE/TYPE-A
  code: ENTITY-A-123
  etag: ...
  cloud_device_id: ...
  translation:
    field_a: 
      present_value: points.analog-value_1.present_value
      units: ...
    field_b: 
      present_value: points.analog-value_2.present_value
      units: ...
    field_c: 
      present_value: points.analog-value_3.present_value
      units: ...   

VIRTUAL-ENTITY-C-123-GUID:
  type: SOME_TYPE_NAMESPACE/TYPE-C
  code: VIRTUAL-ENTITY-C-123
  etag: ...
  cloud_device_id: ...
  links:
  entity-123:
    field_a: field_a_1
    field_b: field_b_1
    field_c: field_c_1

It is required to change the type of ENTITY-123 from TYPE-A to TYPE-B with fields: field_b, field_c, and field_d; necessitating an update also to its code and links. In addition VIRTUAL-ENTITY-123, which depends on ENTITY-123, must be updated. This can be achieved by the following:

ENTITY-A-123-GUID:
  type: SOME_TYPE_NAMESPACE/TYPE-B
  code: ENTITY-B-123
  etag: ...
  cloud_device_id: ...
  translation:
    field_b: 
      present_value: points.analog-value_1.present_value
      units: ...
    field_c: 
      present_value: points.analog-value_2.present_value
      units: ...
    field_d: 
      present_value: points.analog-value_3.present_value
      units: ...
  update_mask:
    - type
    - code
    - translation

VIRTUAL-ENTITY-C-123-GUID:
  type: SOME_TYPE_NAMESPACE/TYPE-D
  code: VIRTUAL-ENTITY-D-123
  links:
    ENTITY-A-123-GUID:
      field_b: field_b_1
      field_c: field_c_1
      field_d: field_d_1
  update_mask:
    - type
    - links

Validation

The building config can be machine validated for consistency and adherence to the rules defined in the data model. This tool is available here.

Notes

  1. Practically speaking, the entry typically corresponds to the controller, which may or may not map to exactly one complete piece of equipment. \ [^2]: It is anticipated that non 1:1 mapping will only apply to HVAC equipment. \ [^3]: A fully compliant UDMI payload uses standard names for units, formatted with points in the payload using the fully qualified path points.<name>.present_value and units in metadata with the path ` pointset.points..units`. A UDMI compliant field will use the exact text (case insensitive) for multi-states, and all states defined for the field will be used. \ [^5]: A user would almost never define all the sections in a single entity, but all are shown below for illustration purposes. \ [^6]: An unstated assumption here is that the CDM registry scope and the scope of the config file are the same. This guarantees that a unique ID can be found in the CDM registry for each entity.