diff --git a/ontology/yaml/resources/HVAC/entity_types/ABSTRACT.yaml b/ontology/yaml/resources/HVAC/entity_types/ABSTRACT.yaml index 1b74a5732..798abf42a 100644 --- a/ontology/yaml/resources/HVAC/entity_types/ABSTRACT.yaml +++ b/ontology/yaml/resources/HVAC/entity_types/ABSTRACT.yaml @@ -3674,6 +3674,8 @@ MXVPM: guid: "4bb25777-d661-4fd3-9f8f-a84b349ada87" description: "Mixing valve percent monitoring." is_abstract: true + opt_uses: + - mixing_valve_percentage_sensor uses: - mixing_valve_percentage_command implements: @@ -7026,6 +7028,43 @@ VSMC: - high_speed_status - schedule_run_command +CO2DSPMADC: + guid: "316d6473-f187-45ce-9b0e-35b8149e83ce" + description: "Dual setpoint CO2 control with mixed air damper (for recirculated air in AHU)." + is_abstract: true + uses: + - mixed_air_damper_open_command + - mixed_air_damper_closed_command + - low_limit_return_air_co2_concentration_setpoint + - high_limit_return_air_co2_concentration_setpoint + - return_air_co2_concentration_sensor + implements: + - CONTROL + +HTWHLZTC: + guid: "0d063fbc-57cc-4678-9516-d9372e9ccf15" + description: "Heat wheel which controls zone temperature using speed control." + is_abstract: true + implements: + - CONTROL + opt_uses: + - exhaust_air_temperature_sensor + - heat_wheel_speed_percentage_sensor + - return_air_temperature_sensor + - supply_air_temperature_sensor + - failed_exhaust_air_temperature_alarm + - high_return_air_temperature_alarm + - high_supply_air_temperature_alarm + - low_return_air_temperature_alarm + - low_supply_air_temperature_alarm + uses: + - heat_wheel_run_command + - heat_wheel_run_status + - heat_wheel_speed_percentage_command + - outside_air_temperature_sensor + - zone_air_temperature_sensor + - zone_air_temperature_setpoint + SDM2X: guid: "b56e4a52-c988-448a-847d-25710ae4aaef" description: "Supply air damper monitoring, dual status fields." @@ -7277,6 +7316,9 @@ CPC2X: - circulation_pump_run_status_1 - circulation_pump_run_command_2 - circulation_pump_run_status_2 + opt_uses: + - failed_circulation_pump_alarm_1 + - failed_circulation_pump_alarm_2 SDHC: guid: "de065843-b1a9-4d2e-b751-31d7af8e8991" @@ -7306,3 +7348,38 @@ FPHC: uses: - heating_water_valve_percentage_command - chilled_water_valve_percentage_command + +SSTC: + guid: "3aefe568-b8eb-485e-a3d9-38ac3bb9906d" + description: "Supply steam valve monitoring to control water temperature on supply side for steam exchanger." + is_abstract: true + opt_uses: + - supply_steam_valve_percentage_sensor + uses: + - supply_steam_valve_percentage_command + - heating_supply_water_temperature_sensor + - heating_supply_water_temperature_setpoint + +COC2XDSP: + guid: "fa7cba8d-be4d-4968-a5bf-f55429006b77" + description: "Dual setpoint CO concentration control with 2 sensors." + is_abstract: true + uses: + - high_limit_zone_air_co_concentration_setpoint + - low_limit_zone_air_co_concentration_setpoint + - zone_air_co_concentration_sensor_1 + - zone_air_co_concentration_sensor_2 + implements: + - CONTROL + +NO2C2XDSP: + guid: "7a76fa65-88d2-4cea-8297-3bdb4ca507e4" + description: "Dual setpoint NO2 concentration control with 2 sensors." + is_abstract: true + uses: + - high_limit_zone_air_no2_concentration_setpoint + - low_limit_zone_air_no2_concentration_setpoint + - zone_air_no2_concentration_sensor_1 + - zone_air_no2_concentration_sensor_2 + implements: + - CONTROL diff --git a/ontology/yaml/resources/HVAC/entity_types/AHU.yaml b/ontology/yaml/resources/HVAC/entity_types/AHU.yaml index dbf2bbc9a..ed8d195d3 100644 --- a/ontology/yaml/resources/HVAC/entity_types/AHU.yaml +++ b/ontology/yaml/resources/HVAC/entity_types/AHU.yaml @@ -918,6 +918,26 @@ AHU_DFSS_CHWDT_DTM_RTC_RWISOVPC_OAFC_FDPSM2X: - OAFC - FDPSM2X +AHU_SFSS_SFVSC_EFSS_EFVSC_HTWHLZTC_HWZTC_CHWZTC_SSPC_RSPC_CO2DSPMADC_MTM_ECONZ_FDPM3X: + guid: "d1f96a1d-3c49-49c9-8ff7-aa60f1f7e10b" + description: "AHU that serves multiple dampers all feeding a single zone." + is_canonical: true + implements: + - AHU + - SFSS + - SFVSC + - EFSS + - EFVSC + - HTWHLZTC + - HWZTC + - CHWZTC + - SSPC + - RSPC + - CO2DSPMADC + - MTM + - ECONZ + - FDPM3X + ### Multi-zone Units ### AHU_DXSC_ECON_EFSS_SFSS: diff --git a/ontology/yaml/resources/HVAC/entity_types/FAN.yaml b/ontology/yaml/resources/HVAC/entity_types/FAN.yaml index 8f4316da1..ccfe31404 100644 --- a/ontology/yaml/resources/HVAC/entity_types/FAN.yaml +++ b/ontology/yaml/resources/HVAC/entity_types/FAN.yaml @@ -562,6 +562,16 @@ FAN_SS_FDPM_VSC_SRC: - VSC - SRC +FAN_HLC_COC2XDSP_NO2C2XDSP: + guid: "69a67398-f2d7-4fc7-b60a-945be99012b2" + description: "Two-speed fan (low/high) with CO concentration dual setpoint control and NO2 concentration dual setpoint control with 2 sensors." + is_canonical: true + implements: + - FAN + - HLC + - COC2XDSP + - NO2C2XDSP + ################################### ### Existing Non-standard Types ### ################################### diff --git a/ontology/yaml/resources/HVAC/entity_types/FCU.yaml b/ontology/yaml/resources/HVAC/entity_types/FCU.yaml index e8f82056f..7166de284 100644 --- a/ontology/yaml/resources/HVAC/entity_types/FCU.yaml +++ b/ontology/yaml/resources/HVAC/entity_types/FCU.yaml @@ -1255,6 +1255,15 @@ FCU_DFSS_DFVSC_FDPM_CHWDC_SRC_DFRMM: - SRC - DFRMM +FCU_DFSS_CHWRC: + guid: "854f3eff-07db-4324-a4b3-84e19f6a8639" + description: "CRAC unit with discharge fan and return temperature control." + is_canonical: true + implements: + - FCU + - DFSS + - CHWRC + FCU_DXZTC_DFSS: guid: "5688519e-f88e-4620-8bd5-89d91467028d" description: "FCU with SS, discharge temp sensors, zone control and sensor, filter change" @@ -1338,6 +1347,17 @@ FCU_DFSS_CHWDC_CSP_RTM_DXZC: - filter_alarm - run_mode +FCU_SS_HTRC_DTM_ZTM: + guid: "3d9b6b87-0770-4ae6-9bfc-8f729341ccac" + description: "FCU with return temperature control, discharge temperature monitoring, zone temperature monitorning and start/stop control." + is_canonical: true + implements: + - FCU + - SS + - HTRC + - DTM + - ZTM + ################################### ### Existing Non-standard Types ### ################################### @@ -1790,6 +1810,15 @@ FCU_DSP_DFVSC_DTM_RTM: - DTM - RTM +FCU_DFSS_DFSMC_HWRC: + guid: "1388eea8-a039-4b33-8613-24ae9de719dd" + description: "Warm air curtain with return air temperature control." + implements: + - FCU + - DFSS + - DFSMC + - HWRC + FCU_DFVSC_RTM_CO2M_HWZTC_CHWZTC: guid: "6f6fd049-576c-4f0a-894d-a6433575b8dd" description: "Fan coil unit with zone temperature control, heating water and chilled water valve monitoring." diff --git a/ontology/yaml/resources/HVAC/entity_types/HX.yaml b/ontology/yaml/resources/HVAC/entity_types/HX.yaml index ca3b78de9..644df2519 100644 --- a/ontology/yaml/resources/HVAC/entity_types/HX.yaml +++ b/ontology/yaml/resources/HVAC/entity_types/HX.yaml @@ -187,3 +187,12 @@ HX_CWDT_HSWTC_HWDPC_HWBYPVPM: - HSWTC - HWDPC - HWBYPVPM + +HX_SSTC_SSSPC: + guid: "02c3c81d-241c-4868-b260-9c580c29379b" + description: "Steam exchanger with heating water temperature control and steam static pressure control on supply side." + is_canonical: true + implements: + - HX + - SSTC + - SSSPC diff --git a/ontology/yaml/resources/HVAC/entity_types/MAU.yaml b/ontology/yaml/resources/HVAC/entity_types/MAU.yaml index 1073cc816..096811813 100644 --- a/ontology/yaml/resources/HVAC/entity_types/MAU.yaml +++ b/ontology/yaml/resources/HVAC/entity_types/MAU.yaml @@ -16,6 +16,20 @@ ### Canonical Types ### ######################## +MAU_HWSC_SFM_SFVSC_FDPM_FDPSM_SDM_SSPC: + guid: "5d055bc2-ea29-4d1e-beb9-e082f7bea4c7" + description: "Make-up air unit with heating control" + is_canonical: true + implements: + - MAU + - HWSC + - SFM + - SFVSC + - FDPM + - FDPSM + - SDM + - SSPC + MAU_SFSS_STM: guid: "9532ed28-f40c-472b-90aa-4a679911ef17" description: "Simple make-up air unit." diff --git a/ontology/yaml/resources/fields/telemetry_fields.yaml b/ontology/yaml/resources/fields/telemetry_fields.yaml index c9b6f864c..1040c578a 100644 --- a/ontology/yaml/resources/fields/telemetry_fields.yaml +++ b/ontology/yaml/resources/fields/telemetry_fields.yaml @@ -148,6 +148,10 @@ literals: - HIGH - OFF - VFD + - TWENTY_PERCENT + - FORTY_PERCENT + - SIXTY_PERCENT + - EIGHTY_PERCENT - discharge_fan_speed_percentage_command: fixed_min: 0.0 fixed_max: 100.0 @@ -3212,6 +3216,18 @@ literals: - low_discharge_air_static_pressure_alarm: - ACTIVE - INACTIVE +- mixed_air_damper_open_command: + - ON + - OFF +- mixed_air_damper_closed_command: + - ON + - OFF +- low_limit_return_air_co2_concentration_setpoint: + flexible_min: 0.00005 + flexible_max: 0.005 +- high_limit_return_air_co2_concentration_setpoint: + flexible_min: 0.00005 + flexible_max: 0.005 - average_zone_air_co2_concentration_setpoint: flexible_min: 0.00005 flexible_max: 0.005 @@ -3229,4 +3245,16 @@ literals: flexible_max: 80 - tamper_alarm: - ACTIVE - - INACTIVE \ No newline at end of file + - INACTIVE +- supply_steam_valve_percentage_command: + fixed_min: 0.0 + fixed_max: 100.0 +- supply_steam_valve_percentage_sensor: + fixed_min: 0.0 + fixed_max: 100.0 +- high_limit_zone_air_no2_concentration_setpoint: + fixed_min: 0.0 + flexible_max: 0.0005 +- low_limit_zone_air_no2_concentration_setpoint: + fixed_min: 0.0 + flexible_max: 0.0005 diff --git a/ontology/yaml/resources/states/states.yaml b/ontology/yaml/resources/states/states.yaml index 0460e6929..24e4556a1 100644 --- a/ontology/yaml/resources/states/states.yaml +++ b/ontology/yaml/resources/states/states.yaml @@ -27,6 +27,10 @@ VFD: Discrete speed (frequency) control BYPASS: Bypassing an element or entity. DEHUMIDIFY: Modes of operation in DX unit where the unit acts as a dehumidifier by removing moisture from air FAN_ONLY: Modes of operation in DX unit where only fan runs and heating/cooling is disabled +TWENTY_PERCENT: Speed of 20 percent of the maximum +FORTY_PERCENT: Speed of 40 percent of the maximum +SIXTY_PERCENT: Speed of 60 percent of the maximum +EIGHTY_PERCENT: Speed of 80 percent of the maximum # Moved from HVAC namespace because all fields are currently global in DL. COMMISSIONING: The fan speed and valve positions are set to preconfigured parameters. diff --git a/tools/README.md b/tools/README.md index f111333e2..1ee7d5075 100644 --- a/tools/README.md +++ b/tools/README.md @@ -3,8 +3,8 @@ Various tools have been developed to support the use of the Digital Buildings Ontology and Building Configuration files. The tools and their functions are summarized below: - * [ABEL](./abel/README.md) generates from/to Google spreadsheet/[Building Configuration](../ontology/docs/building_config.md). - * [Explorer](./explorer/README.md) allows users to explorer the ontology types and their associated fields. + * [ABEL](./abel/README.md) generates from a Google Sheets spreadsheet to a [Building Configuration YAML file](../ontology/docs/building_config.md) (and vice versa). + * [Explorer](./explorer/README.md) allows users to explore the ontology types and their associated fields. * [Instance Validator](./validators/instance_validator/README.md) allows users to validate a concrete instance of the ontology (i.e., a building configuration file). * A sub-function of the Instance Validator is to also validate telemetry messages for each reporting entity in the building configuration file using [Telemetry Validator](./validators/instance_validator/README.md#telemetry-validation). * [Ontology Validator](./validators/ontology_validator/README.md) allows users to validate a local version of the YAML ontology upon a change or an extension. @@ -12,7 +12,7 @@ The tools and their functions are summarized below: ## Digital Buildings Toolkit The Digital Buildings Toolkit provides a centralized method for interfacing with the following Digital Buildings tools: - * Instance Validator (with optional Telemetry Validator) + * Instance Validator (with optional telemetry validation) * GUID generator There are currently two methods for interacting with the Toolkit: the Toolkit Web Application (currently in alpha) and the Toolkit Command Line Interface (CLI). @@ -29,7 +29,7 @@ To install please follow the instructions below. #### Create a Virtual Environment -First, create a virtual environment with `venv` followed by the environment name (in this example: `tooling`) in the digitalbuildings repository. +First, create a virtual environment with `venv` followed by the environment name (in this example: `tooling`) in the `digitalbuildings` repository. ``` python -m venv tooling @@ -47,6 +47,7 @@ Windows ``` tooling\Scripts\activate ``` + #### Install Packages Next, you can either use pip or setup (to be deprecated) to install the necessary packages and dependencies. diff --git a/tools/abel/README.md b/tools/abel/README.md index 2d3937e90..bfbf46bf6 100644 --- a/tools/abel/README.md +++ b/tools/abel/README.md @@ -1,25 +1,37 @@ # ABEL -### Automated Building Entity Loader -Allows system integrators to easily and efficiently create and -modify [Building Configuration files](../../ontology/docs/building_config.md). +ABEL is an acronym that stands for **A**utomated **B**uilding **E**ntity **L**oader. It is a tool that assists systems integrators (and other DBO users) in efficiently creating and +modifying [Building Configuration YAML files](../../ontology/docs/building_config.md). -## Setup and installation +ABEL has the following key features: +* Convert a Google Sheet (in the ABEL Spreadsheet Template) to a building configuration YAML file + * Run Instance Validator (with optional telemetry validation) on the building configuration file +* Convert a building configuration YAML file to a Google Sheet -The setup process is broken into two parts: +## Table of Contents -1. Setup a virtual environment using [virtualenv](https://virtualenv.pypa.io/en/latest/) and install all of the -proper dependencies -2. Obtain credentials for [Google Sheets API](https://developers.google.com/sheets/api/reference/rest) for use with -ABEL +* [Setup and Installation](#setup-and-installation) +* [Using ABEL](#using-abel) + * [Update Workflow](#update-workflow) + * [Initialization Workflow](#initialization-workflow) + * [Split Workflow](#split-workflow) + +## Setup and Installation -Total setup process should only take about 15 minutes. +Before starting the setup and installation process, please ensure that the dependencies are met: -Before starting the setup and installation process, please ensure that the -dependencies are met: 1. You are running **Python 3.9** or higher + 2. you have installed the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) +The total setup process should only take about 15 minutes. The process is broken into two parts: + +1. Setup a virtual environment using [virtualenv](https://virtualenv.pypa.io/en/latest/) and install all of the +proper dependencies + +2. Obtain credentials for [Google Sheets API](https://developers.google.com/sheets/api/reference/rest) for use with +ABEL + ### Set up a tooling environment If environment is already set up then the following steps can be ignored. @@ -44,32 +56,33 @@ If environment is already set up then the following steps can be ignored. 4. Activate your virtual environment -* MacOs/Linux: - - ``` - source tooling/bin/activate - ``` - -* Windows: - - ``` - tooling\Scripts\activate - ``` + * MacOs/Linux: + + ``` + source tooling/bin/activate + ``` + + * Windows: + + ``` + tooling\Scripts\activate + ``` 5. Depending on your operating system, run either of the global setup scripts to configure dependencies -* Linux/MacOs: - ``` - ./pip_install.sh - ``` - -* Windows: + * Linux/MacOs: - ``` - pip_install.bat - ``` + ``` + ./pip_install.sh + ``` + + * Windows: + + ``` + pip_install.bat + ``` -5. Navigate to the [ABEL directory](./) +6. Navigate to the [ABEL directory](./) ``` cd abel @@ -77,108 +90,102 @@ cd abel ### Obtain a GCP OAuth client credential -1. Contact your IoT Technical Program Manager and ask for an oauth client `credential.json` file for authenticating against Google Sheets API. +1. Contact your IoT Technical Program Manager and ask for an OAuth client `credential.json` file for authenticating against Google Sheets API. 2. Use the `credential.json` file for ABEL's `--credential` command line argument. ## Using ABEL -ABEL has a few pieces of core functionality, they are: -1. Modify a spreadsheet or a building config for an existing building to produce an [UPDATE building config](../../ontology/docs/building_config.md#update) - * [Update Workflow](#update-workflow) +ABEL has a few pieces of core functionality, they are as follows: +1. Modify a spreadsheet or a building configuration for an existing building to produce an [UPDATE building config](../../ontology/docs/building_config.md#update) + * [Update Workflow](#update-workflow) + 2. Create a [Building Config](../../ontology/docs/building_config.md) from an [ABEL spreadsheet](../../tools/abel/validators/README.md) for a new building - * [Initialization workflow](#initialization-workflow) + * [Initialization Workflow](#initialization-workflow) + 3. Split a building configuration file on a namespace - * [Split Workflow](#split-functionality) + * [Split Workflow](#split-workflow) -### Command-line arguments for ABEL: -`-c` or `--credential` **required** absolute or relative path to a gcp OAuth client -credential file. An OAuth client credential is required for authentication -against Google Sheets service. +### Command-line arguments for ABEL +1. `-c` or `--credential` **Required**: The absolute or relative path to a GCP OAuth client credential file. An OAuth client credential is required for authentication against Google Sheets service. -`-s` or `--spreadsheet_id` id for a google sheets spreadsheet - * [ABEL Spreadsheet Template](https://docs.google.com/spreadsheets/d/1b6IRimNS1dAtPjkNN-fk4TirnLzOiDyyUmOKP_MhMM0/copy#gid=980240783) - * A Google Sheets ID is found embedded into the spreadsheet's url. Required when ABEL is creating a building config from a Google spreadsheet. - e.g. `https://docs/google/com/spreadsheets/d//edit#gid=123467` +2. `-s` or `--spreadsheet_id`: The ID associated with a Google Sheets spreadsheet + * [ABEL Spreadsheet Template](https://docs.google.com/spreadsheets/d/1b6IRimNS1dAtPjkNN-fk4TirnLzOiDyyUmOKP_MhMM0/copy#gid=980240783) + * A Google Sheets ID is found embedded into the spreadsheet's URL (e.g., `https://docs/google/com/spreadsheets/d//edit#gid=123467`). Required when ABEL is creating a building configuration from a Google spreadsheet. -`-b` or `--building_config` absolute o relative path to a local building configuration -file. Only required for the `Building Config -> Spreadsheet` workflow. - * [Building Configuration Docs](../../ontology/docs/building_config.md) +3. `-b` or `--building_config`: The absolute or relative path to a local building configuration file. Only required for the `Building Configuration -> Spreadsheet` workflow. + * [Building Configuration Docs](../../ontology/docs/building_config.md) -`-p` or `--subscription` fully-qualified path to a Google Cloud Pubsub subscription, e.g. `projects/google.com:your-project/subscriptions/your-subscription`. This parameter is only required for telemetry validation. +4. `-p` or `--subscription` **[Optional]**: A fully-qualified path to a Google Cloud Pubsub subscription, e.g., `projects/google.com:your-project/subscriptions/your-subscription`. This parameter is only required for telemetry validation. -`-o` or `--timeout` timeout duration in seconds for the telemetry validation test. The default value is 600 seconds, or 10 minutes. If this time limit is exceeded before the validator receives a test pubsub message for each of the entities configured in the given instance config file, the test will fail with an error and report the entities that were not heard from. +5. `-o` or `--timeout` **[Optional]**: Custom timeout duration in seconds for the telemetry validation test. The default value is 600 seconds, or 10 minutes. If this time limit is exceeded before the validator receives a test pubsub message for each of the entities configured in the given building configuration file, the test will fail with an error and report the entities that were not heard from. -`-m` or `--modified-types-filepath` fully-qualified path to a modified ontology -that is not in the [DigitalBuildings repository](../..). The [Ontology -Validator](../validators/ontology_validator) will surface validation results -from the modified ontology, and Building Configuration files will be validated -against the modified ontology. +6. `-m` or `--modified-types-filepath` **[Optional]**: A fully-qualified path to a modified ontology that is not in the [DigitalBuildings repository](../..). The [Ontology Validator](../validators/ontology_validator) will surface validation results from the modified ontology, and building configuration files will be validated against the modified ontology. -`-d` or `--output-dir` fully qualified or relative file path to a directory which ABEL can write files to. ABEL must have write access to this directory or else an error will be raised. +7. `-d` or `--output-dir`: An absolute or relative file path to a directory which ABEL can write files to. ABEL must have write access to this directory or else an error will be raised. ### The ABEL Spreadsheet -The ABEL spreadsheet serves as a user-friendly interface for ABEL and is what -allows a user to make changes to machine-readable documents like [Building -Config](../../ontology/docs/building_config.md). +The ABEL spreadsheet serves as a user-friendly interface for ABEL and is what allows a user to make changes to machine-readable documents like [Building Config](../../ontology/docs/building_config.md). -Please see the [ABEL spreadsheet docs](../../tools/abel/validators/README.md) for detailed instructions on how to create your own spreadsheet. +Please see the [ABEL Spreadsheet docs](../../tools/abel/validators/README.md) for detailed instructions on how to create your own spreadsheet. ### Update Workflow -If you would like to create a building config to update an already onboarded building, then there are two options: +If you would like to create a building configuration to update an already onboarded building, there are two options: -Generate an ABEL spreadsheet from an exported building config. +Generate an ABEL spreadsheet from an exported building configuration. 1. In `digitalbuildings/tools/abel` run ABEL with the command: + ``` python3 abel.py -c /path/to/credential.json -b absolute/path/to/building/config ``` -To generate a building config from an already updated spreadsheet. +To generate a building config from an already-updated spreadsheet. 1. In `digitalbuildings/tools/abel` run ABEL with the command: + ``` python3 abel.py -s -c -d ``` - 2. If your spreadsheet does not pass the validation criteria found in the - [spreadsheet docs](../../tools/abel/validators/README.md) then ABEL will fast - fail and a validation - report will be created in your current directory with the name, - `spreadsheet_validation_.log` - 3. The resulting Building Config and instance validation report will be written - to the current directory with names: - * `bc_export_.yaml` - * `instance_validation_.log` - -### Initialization workflow + + 3. If your spreadsheet does not pass the validation criteria found in the + [spreadsheet docs](../../tools/abel/validators/README.md) then ABEL will fast-fail and a validation report will be created in the current directory with the name `spreadsheet_validation_.log` + + 4. The resulting building configuration file and instance validation report will be written to the current directory with the following names: + * `bc_export_.yaml` + * `instance_validation_.log` + +### Initialization Workflow If you would like create a building configuration file under the initialization operation -The process for using an ABEL spreadsheet to generate a new Building Config is as +The process for using an ABEL spreadsheet to generate a new building configuration is as follows: 1. Create a spreadsheet for ABEL from [ABEL Spreadsheet template](https://docs.google.com/spreadsheets/d/1nlFVwVvmumBSIAAAv7xq1-xuqGy0k1ONyrG2rMqrgdE/copy#gid=980240783) + 2. Populate your spreadsheet. A well-defined guide on how to populate your spreadsheet can be found in the [spreadsheet docs](../../tools/abel/validators/README.md) + 3. In `digitalbuildings/tools/abel` run ABEL with the command: ``` python3 abel.py -s -c -d ``` + 4. Choose option 2: Create a spreadsheet for a new building -5. If your spreadsheet does not pass the validation criteria found in the - [spreadsheet docs](../../tools/abel/validators/README.md) then ABEL will fast - fail and a validation report will be created in the directory specified with the `-d` arguments with the name, - `spreadsheet_validation_.log` -6. The resulting Building Config and instance validation report will be written - to the same directory with names: + +5. If your spreadsheet does not pass the validation criteria found in the [spreadsheet docs](../../tools/abel/validators/README.md) then ABEL will fast-fail and a validation report will be created in the directory specified with the `-d` arguments with the name `spreadsheet_validation_.log` + +6. The resulting building configuration file and instance validation report will be written to the same directory with the following names: * `bc_export_.yaml` * `instance_validation_.log` -### Split Functionality -To split a building config file on a certain namespace: +### Split Workflow +To split a building configuration file on a specific DBO namespace: -1. Run abel with a json credential and a building config: +1. Run abel with a json credential and a building configuration: ``` python3 abel.py -c -b ``` 2. Select option 3: `Split a building config` -3. ABEL will generate a new building config split on the desired namespace - along with any dependencies. Provide the `-d` argument if you would like ABEL to write to a specific directory. + +4. ABEL will generate a new building configuration split on the desired namespace along with any dependencies (e.g., a building configuration containing only entities in the DBO `METERS` namespace). + * Provide the `-d` argument if you would like ABEL to write to a specific directory. diff --git a/tools/validators/instance_validator/README.md b/tools/validators/instance_validator/README.md index 279ecbc45..46b366aca 100644 --- a/tools/validators/instance_validator/README.md +++ b/tools/validators/instance_validator/README.md @@ -1,8 +1,14 @@ # Instance Validator -The Instance Validator allows validation of concrete DBO instances (i.e., building configuration files) to ensure they conform to the given ontology model, are formatted correctly, and contain all required fields. There is also optional functionality to validate telemetry messages for all reporting entities in the building configuration using Telemetry Validator. +The Instance Validator allows validation of concrete DBO instances (i.e., building configuration files) to ensure they conform to the given ontology model, are formatted correctly, and contain all required components. There is also optional functionality to validate telemetry messages for all reporting entities in the building configuration using temeletry validation (requires a valid Pub/Sub subscription and OAuth credential). **The recommended workflow is to first use the Instance Validator without telemetry validation. Once your building configuration file produces a clean Instance Validation report, then use Instance Validator with telemetry validation enabled.** -## Install +## Table of Contents +* [Installation](#installation) +* [Instance Validator Workflow](#instance-validator-workflow) + * [Telemetry Validation](#telemetry-validation) +* [Warnings and Errors](#warnings-and-errors) + +## Installation Installing and using the Instance Validator requires Python 3.9, and the specific Python command to run may vary depending on your operating system and the presence of Python 2. Use the appropriate command listed below when the instructions call for `python3`: @@ -14,7 +20,7 @@ You can run the command with just the version flag (e.g. `python --version`) to ### Create a Virtual Environment -First, create a virtual environment with `venv` followed by the environment name (in this example: `tooling`) in the digitalbuildings repository. +First, create a virtual environment with `venv` followed by the environment name (in this example: `tooling`) in the `digitalbuildings` repository. ``` python -m venv tooling @@ -32,10 +38,10 @@ Windows ``` tooling\Scripts\activate ``` -## Install Packages +### Install Packages Next, you can either use pip or setuptools (to be deprecated) to install the necessary packages and dependencies. -### Install Pip +#### Install Pip 1. Run the following command to ensure that your Python package management tools are up-to-date. ``` @@ -44,7 +50,7 @@ python3 -m pip install --upgrade pip 2. Run `bash pip_install.sh` (MacOS / Linux) or `pip_install.bat` (Windows) from the following directory: `digitalbuildings/tools`. -### Setuptools (to be deprecated) +#### Setuptools (to be deprecated) 1. Run `python3 -m pip install --upgrade pip setuptools` to ensure that your Python package management tools are up-to-date. 2. Run `python3 setup.py install` from the following directory: digitalbuildings/tools/validators/ontology_validator. @@ -90,40 +96,40 @@ results in these actions: **NOTE:** The new building configuration format requires that entities are keyed by Version 4 UUIDs (referred to as guids) instead of the code. To convert from old format to the new format, run your building configuration file(.yaml) through the [guid generator](https://github.com/google/digitalbuildings/tree/master/tools/guid_generator). -### Warnings and Errors +## Warnings and Errors The Instance Validator has two types of outputs: **Warnings** and **Errors**. In short, errors are exposed when a Building Config is not readable by the instance validator while warnings are exposed when a Building Config is readable but its contents may not be valid. -#### Errors +### Errors Errors cause the validator to exit prematurely with some kind of exception. For example, An error could be caused by an entity block not containing a `GUID`. This would raise an exception in the validation logic and cause the validator to exit prematurely because the instance validator expects every entity block in a Building Config to have an associated `GUID`. The [GUID generator](https://github.com/google/digitalbuildings/tree/master/tools/guid_generator) must be used to generate GUIDs for a Building Configuration file. Other entity block elements are `type` and `code`. - The following entity block would throw an error because it does not contain a type nor a code. - - 8318f346-10b4-44f0-ac0b-bf7659510bfa: - translation: - zone_air_temperature_sensor: - present_value: "temp_1" - units: - key: "units" - values: - degrees_celsius: "degC" - degrees_fahrenheit: "degF" - -#### Warnings +The following entity block would throw an error because it does not contain a type or a code. +```yaml + 8318f346-10b4-44f0-ac0b-bf7659510bfa: + translation: + zone_air_temperature_sensor: + present_value: "temp_1" + units: + key: "units" + values: + degrees_celsius: "degC" + degrees_fahrenheit: "degF" +``` +### Warnings Warnings, on the other hand, expose inconsistencies in the content of an entity block but do not cause the validator to fail since the core elements of what make an entity block readable are still present. For example, if the fields defined in `translation` or `links` do not align with the fields for the entity's type as defined in [Digital Buildings Ontology](https://github.com/google/digitalbuildings/tree/master/ontology/yaml), then the validator will warn the user it is not a valid entity. - The following entity block would only expose a warning because these are not the fields for VAV_SD_DSP as defined in DBO: - - 4931e096-dea5-4b81-86ad-234c6d07b978: - code: VAV-2 - connections: - c773b86d-b0c0-46fc-bd3f-d726fadd5f1e: - - FEEDS - links: - 547a33c5-0ce4-4dfb-9924-5169a3475c89: - supply_air_flowrate_sensor: supply_air_flowrate_sensor_2 - 2b152e08-3440-4358-9067-3f2acc58c982: - zone_air_temperature_sensor: zone_air_temperature_sensor - zone_air_temperature_setpoint: zone_air_temperature_setpoint - type: HVAC/VAV_SD_CSP - +The following entity block would only expose a warning because these are not the correct fields for VAV_SD_DSP as defined in DBO. +```yaml + 4931e096-dea5-4b81-86ad-234c6d07b978: + code: VAV-2 + connections: + c773b86d-b0c0-46fc-bd3f-d726fadd5f1e: + - FEEDS + links: + 547a33c5-0ce4-4dfb-9924-5169a3475c89: + supply_air_flowrate_sensor: supply_air_flowrate_sensor_2 + 2b152e08-3440-4358-9067-3f2acc58c982: + zone_air_temperature_sensor: zone_air_temperature_sensor + zone_air_temperature_setpoint: zone_air_temperature_setpoint + type: HVAC/VAV_SD_CSP +``` diff --git a/tools/validators/ontology_validator/README.md b/tools/validators/ontology_validator/README.md index df2e6a353..765d0dfbe 100644 --- a/tools/validators/ontology_validator/README.md +++ b/tools/validators/ontology_validator/README.md @@ -2,10 +2,14 @@ The Ontology Validator allows users validate a local set of ontology YAML files (i.e., new ontology extensions or modifications) to ensure all extensions/modifications conform to DBO guidelines. Ontology Validator is also run on all pull requests that are opened within the DBO repository. -## Install requirements +## Table of Contents +* [Installation](#installation) +* [Ontology Validator Workflow](#ontology-validator-workflow) + +## Installation ### Create a Virtual Environment -First, create a virtual environment with `venv` followed by the environment name (in this example: `tooling`) in the digitalbuildings repository. +First, create a virtual environment with `venv` followed by the environment name (in this example: `tooling`) in the `digitalbuildings` repository. ``` python -m venv tooling