diff --git a/ontology/docs/meter_loads.md b/ontology/docs/meter_loads.md new file mode 100644 index 0000000000..0e5a0533d9 --- /dev/null +++ b/ontology/docs/meter_loads.md @@ -0,0 +1,67 @@ +# Meter Load Designation + +Digital Buildings provides abstract models that can be used to represent various +types of loads within a building and can be connected to meter entities to indicate the types +of loads measured by each metering device. This document describes how these loadtypes +should be created and connected within a building configuration file. + +* For an explanation of building configuration files see + [building_config](building_config.md) + +### Create the Building Entity and Meter Device Entity + +Use the syntax described in [building_config](building_config.md) to create a +facility entity for the building and a reporting entity for the meter device. +A `CONTAINS` connection should be used to indicate that the meter exists within +the building. + +### Create an Abstract Loadtype Entity + +Create a loadtype entity to represent each of the types of loads the meters in +the building measure. The entity will consist of a single abstract loadtype +found in the file called `LOADTYPES.yaml` in the `METER` namespace. The abstract +loadtype does not implement any fields. A `CONTAINS` connection should be used +to indicate that the load exists within the building. + +### Connect the Loadtype Entity to the Meter Entity via a `MEASURES` Connection + +Add a `MEASURES` connection to the loadtype entity to indicate which meter(s) +provide data for it. A building may have multiple meters that +measure the same loadtype. + +## Example Building Layout and Config + +Example full building-loadtype-meter layout: + +![image](https://github.com/shambergoldstein/digitalbuildings/assets/124837286/427e4c03-c132-468c-94e7-20486117643a) + +Example building-loadtype-meter connection in building configuration file: +``` yaml +# The building +ccb-342: + code: BLDG-123 + type: FACILITIES/BUILDING + +# The abstract entity for MAIN load +abc-123: + code: MAIN + type: METERS/LOADTYPE_MAIN + connections: + ccb-342: CONTAINS + dde-453: MEASURES + +# The reporting entity for the meter +dde-453: + code: EM-1 + cloud_device_id: 1234 + type: METERS/EM_PWM + connections: + ccb-342: CONTAINS + translation: + power_sensor: + present_value: points.kW.present_value + units: + key: pointset.points.kW.units + values: + kilowatts: "kW" +``` diff --git a/ontology/yaml/resources/METERS/entity_types/LOADTYPES.yaml b/ontology/yaml/resources/METERS/entity_types/LOADTYPES.yaml new file mode 100644 index 0000000000..95ae72c503 --- /dev/null +++ b/ontology/yaml/resources/METERS/entity_types/LOADTYPES.yaml @@ -0,0 +1,77 @@ +# Copyright 2020 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the License); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an AS IS BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +### LOAD TYPES + +# This defines abstract load types that are measured by meters. They are not necessarily specific to any type of meter. + +LOADTYPE_MAIN: + guid: "1fa18a32-1461-45e8-ad4c-e5d030afb827" + description: "Represents the main load for a building, encompassing everything within the building." + is_abstract: true + +LOADTYPE_MECHANICAL: + guid: "dcb2fb34-c89f-4243-803c-3cda0e957c10" + description: "Represents an mechanical (HVAC) load within a building." + is_abstract: true + +LOADTYPE_PLUG: + guid: "01fa84ff-0fe0-4d75-8570-6aea5ceeb53f" + description: "Represents a plug (outlet) load within a building." + is_abstract: true + +LOADTYPE_LIGHTING: + guid: "1bf8a921-b52e-4745-acf2-ac1001f5302a" + description: "Represents a lighting fixture and infrastructure load within a building." + is_abstract: true + +LOADTYPE_CAFE: + guid: "168b157e-4de7-4c13-b466-35da0e056642" + description: "Represents a cafe and kitchen load within a building." + is_abstract: true + +LOADTYPE_SPARE: + guid: "ff156f0e-ec9c-488e-8b67-2e75e6d20f39" + description: "Represents an unassigned breaker load within a building." + is_abstract: true + +LOADTYPE_XFMR: + guid: "fa66332f-0274-4c7f-97c9-3e73c4f26c84" + description: "Represents a transformer load within a building." + is_abstract: true + +LOADTYPE_DIST: + guid: "71d483ca-233f-4b99-803b-a8c74994ef6c" + description: "Represents a general distribution load within a building. Used when multiple downstream categories are served." + is_abstract: true + +LOADTYPE_ATS: + guid: "47406858-faf0-4100-a3d2-9b40d1b01bc5" + description: "Represents an automatic transfer switch load within a building." + is_abstract: true + +LOADTYPE_PV: + guid: "e7f0dc78-9b03-4163-ab87-32281f342aeb" + description: "Represents a photovoltaic load within a building." + is_abstract: true + +LOADTYPE_EMERGENCY: + guid: "f360b259-b6cf-49ef-b828-629d596fb25c" + description: "Represents an emergency load within a building." + is_abstract: true + +LOADTYPE_MISC: + guid: "81411471-4235-4b9e-8f19-0366f94ebaee" + description: "Represents a miscellaneous load within a building." + is_abstract: true diff --git a/ontology/yaml/resources/connections/connections.yaml b/ontology/yaml/resources/connections/connections.yaml index e185e45045..0a1fb4d503 100644 --- a/ontology/yaml/resources/connections/connections.yaml +++ b/ontology/yaml/resources/connections/connections.yaml @@ -22,3 +22,5 @@ HAS_PART: description: "Source has some component or part defined by Target." HAS_RANGE: description: "Source has a coverage or detection range defined by Target." +MEASURES: + description: "Source quantifies attributes of the Target."