-
Notifications
You must be signed in to change notification settings - Fork 141
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
27229e3
commit 197a240
Showing
1 changed file
with
25 additions
and
30 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,16 +5,14 @@ Various tools have been developed to support the use of the Digital Buildings On | |
| 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. | ||
| * [Instance Validator](./validators/instance_validator/README.md) allows users to validate a concrete ontology application (i.e., a building configuration file). | ||
| * [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](./validators/instance_validator/README.md#telemetry-validation) | ||
| corresponding to entity blocks in a building configuration file. | ||
| * [Ontology Validator](./validators/ontology_validator/README.md) allows users to validate a local version of the YAML ontology upon a change or an extension. | ||
|
|
||
| ## Digital Buildings Toolkit | ||
|
|
||
| The Digital Buildings Toolkit provides a centralized | ||
| method for interfacing with all of the tools contained within the Digital | ||
| Buildings Repository. | ||
| The Digital Buildings Toolkit provides a centralized method for interfacing with all of the tools contained within the Digital Buildings Repository. | ||
|
|
||
| ### Toolkit Web Application | ||
|
|
||
|
|
@@ -25,9 +23,9 @@ Only the Instance Validator is currently supported, but other tools are planned | |
|
|
||
| To install please follow the instructions below. | ||
|
|
||
| #### First create a virtual env | ||
| #### Create a Virtual Environment | ||
|
|
||
| Create the 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 | ||
|
|
@@ -52,7 +50,7 @@ Then you can either use pip or setuptools. | |
| #### Pip | ||
| 1. Run `python3 -m pip install --upgrade pip` to ensure that your Python package management tools are up-to-date. | ||
|
|
||
| 2. Run `bash pip_install.sh` or `pip_install.bat` (windows) from the following directory digitalbuildings/tools. | ||
| 2. Run `bash pip_install.sh` or `pip_install.bat` (windows) from the following directory: digitalbuildings/tools. | ||
|
|
||
| #### Docker | ||
|
|
||
|
|
@@ -73,41 +71,38 @@ $ ./tools/docker_run.sh abel | |
|
|
||
| Run `python toolkit.py` and provide the following arguments: | ||
|
|
||
| 1. `-i/--input` The absolute filepath of a building configuration file(.yaml). | ||
| 1. `-i/--input`: The absolute filepath of a building configuration file(.yaml). | ||
|
|
||
| 2. `-m/--modified-types-filepath` **[Optional]** Validate entity types in the building configuration file against a modified ontology that is not in the main repository. Default is the [Digital Buildings Ontology](https://github.com/google/digitalbuildings/tree/master/ontology/yaml). | ||
| 2. `-m/--modified-types-filepath` **[Optional]**: Validates entity types in the building configuration file against a modified ontology (i.e., a local branch) that is not in the main repository. Default is the [Digital Buildings Ontology](https://github.com/google/digitalbuildings/tree/master/ontology/yaml). | ||
|
|
||
| 3. `-g/--generate` Generates GUIDs for entities in the building configuration file. Since the instance validator expects the [new building configuration format](https://github.com/google/digitalbuildings/blob/master/ontology/docs/building_config.md#new-format), this option also converts a building configuration from the old format to the new format. | ||
| 3. `-g/--generate` **[Optional]**: Generates GUIDs for entities in the building configuration file. Since the instance validator expects the [new building configuration format](https://github.com/google/digitalbuildings/blob/master/ontology/docs/building_config.md#new-format), this option also converts a building configuration from the old format to the new format. | ||
|
|
||
| 4. `-v/--validate` Runs instance validator to validate the building configuration file. | ||
| 4. `-v/--validate`: Runs instance validator to validate the building configuration file. | ||
|
|
||
| 5. After a building configuration's entity types are validated, validation must also be run on the telemetry payload using: | ||
| 5. After a building configuration's entity types are validated, validation must also be run on the telemetry payload using the following parameters: | ||
|
|
||
| * `-s/--subscription` The fully-qualified path to a Google Cloud Pubsub subscription, e.g. projects/google.com:your-project/subscriptions/your-subscription. | ||
| * `-s/--subscription`: The fully-qualified path to a Google Cloud Pubsub subscription, e.g. projects/google.com:your-project/subscriptions/your-subscription. | ||
|
|
||
| * `-c/--credential` An absolute or relative path to an OAuth client credential JSON file. | ||
| * `-c/--credential`: An absolute or relative path to an OAuth client credential JSON file. | ||
|
|
||
| * `-t/--timeout` **[Optional]** The 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. | ||
| * `-t/--timeout` **[Optional]**: The 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. | ||
|
|
||
| * `--udmi` **[Optional]** Validates entity metadata as [UDMI](https://github.com/faucetsdn/udmi/). Flag is set to `True` by default and include `--udmi=False` when not validating against UDMI. | ||
|
|
||
| `python instance_validator.py -i input.yaml` validates a building config against the UDMI standard. | ||
| * `--udmi` **[Optional]**: Validates entity metadata as [UDMI](https://github.com/faucetsdn/udmi/). Flag is set to `True` by default; change this parameter to `--udmi=False` when not validating against UDMI. | ||
|
|
||
| * **NOTE:** The OAuth credential and subscription are provided by the Google team. Please reach out to your IoT TPM for guidance. | ||
|
|
||
| 6. `-d/--report-directory` To write instance validation (instance_validation_report.txt) and telemetry validation (telemetry_validation_report.json) reports to the report-directory; otherwise writes instance validation to console and telemetry validation to current working directory. | ||
|
|
||
| For example: | ||
| `python toolkit.py -i //path/to/file -g -v -s subscription-name -c //path/to/oauth/cred.json -d //path/to/report-directory` | ||
| 1. Takes in a building configuration file. | ||
| 2. Generates guids for every entity instance. | ||
| 3. Re-writes building config in the new format. | ||
| 4. Validates the building configuration. | ||
| 5. Validates the telemetry payload. | ||
| 6. Writes validation results to the report directory as //path/to/report-directory/instance_validation_report.txt and //path/to/report-directory/telemetry_validation_report.json for instance validation and telemetry validation respectfully. | ||
| For example, the following input | ||
| `python toolkit.py -i //path/to/building/configuration/file.yaml -g -v -s subscription-name -c //path/to/oauth/cred.json -d //path/to/report-directory` | ||
| results in these actions: | ||
| 1. Ingests a building configuration file. | ||
| 2. Generates guids for every entity instance in the buiding configuration file. | ||
| 3. Re-writes building configuration file in the new format. | ||
| 4. Validates the building configuration file. | ||
| 5. Validates the telemetry payloads for each reporting entity in the building configuration file. | ||
| 6. Writes validation results to the report directory as `//path/to/report-directory/instance_validation_report.txt` and `//path/to/report-directory/telemetry_validation_report.json` for instance validation and telemetry validation, respectfully. | ||
|
|
||
| **NOTE:** The new building configuration format switches entities being keyed by codes | ||
| to being keyed by guids, and Ids are removed. 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). | ||
| **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). | ||
|
|
||
| Any questions or concerns can be emailed to **[email protected]** | ||
| Any questions or concerns can be emailed to **[email protected]**. | ||