From d34fbd48c30ba90ee8643fc8d466096e18945b24 Mon Sep 17 00:00:00 2001 From: shambergoldstein <124837286+shambergoldstein@users.noreply.github.com> Date: Thu, 19 Dec 2024 10:29:03 -0800 Subject: [PATCH 1/4] Create connections.md --- ontology/docs/connections.md | 116 +++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 ontology/docs/connections.md diff --git a/ontology/docs/connections.md b/ontology/docs/connections.md new file mode 100644 index 0000000000..6693b63753 --- /dev/null +++ b/ontology/docs/connections.md @@ -0,0 +1,116 @@ +# Connections + +Connections are a type of relationship between two entities that describe +the how the entities are associated. This may be a physical (e.g., `FEEDS`) +or logical (e.g., `HAS_PART`) association. This document details the definitions +of the various supported connections and in what scenarios each should be used. + +## Contains + +#### Definition: Source physically encapsulates at least part of Target. + +The contains connection should be used when one entity, or at least a component of it, +exists physically within another. This connection is commonly used to represent the +location of an entity within a building. For example, a building may contain a floor +which contains a room or zone, which contains a `VAV`. In this instance the connection +between the building and room should be set on the room and the connection between the +room and `VAV` should be set on the `VAV` as follows: + +``` yaml +ROOM-GUID: + code: Room 123 + connections: + BUILDING-GUID: + - CONTAINS +``` +``` yaml +VAV-GUID: + code: VAV 1-2 + connections: + ROOM-GUID: + - CONTAINS +``` + +## Controls + +#### Definition: Source determines or affects the internal state or behavior of Target. + +The controls connection should be used when one entity impacts the behavior of another. +An example of when this connection may be used would be where a lighting control +module, `LCM`, controls one or more luminaires, `LT`. In this example the connection should +be set on the `LT` entity as follows: + +``` yaml +LT-GUID: + code: LT 123 + connections: + LCM-GUID: + - CONTROLS +``` + +## Feeds + +#### Definition: Source provides some media (ex: water or air) to Target. + +The feeds connection should be used when one entity is located pysically upstream of +another in regards to its media, so that one device supplies the media to the other. +A very common use case for this connections is when an `AHU` feeds air to a `VAV`. +In this example the connection should be set on the `VAV` entity as follows: + +``` yaml +VAV-GUID: + code: VAV 1-2 + connections: + AHU-GUID: + - FEEDS +``` + +## Has Part + +#### Definition: Source has some component or part defined by Target. + +The has part connection should be used to represent which system a component belongs to. +This can be used to represent something like a pump, `PMP`, that belongs to a chilled +water system, `CHWS`. In this example the connection should be set on the `PMP` entity as follows: + +``` yaml +PMP-GUID: + code: PMP 1 + connections: + CHWS-GUID: + - HAS_PART +``` + +## Has Range + +#### Definition: Source has a coverage or detection range defined by Target. + +The has range connection should be used when the limitations of one entity are defined by another. +This could be used to describe something like an occupancy sensor, `SENSOR_ZOC`, that would have +a has range connection to a room, as the sensor can only measure the occupancy within the +boundaries of said room. In this example the connection should be set on the room entity as follows: + +``` yaml +ROOM-GUID: + code: Room 123 + connections: + SENSOR-ZOC-GUID: + - HAS_RANGE +``` + +## Measures + +#### Definition: Source quantifies attributes of the Target. + +The measures connection should be used to decribe when an entity ascertains the +quantity or value of another's attributes. One common example would be a meter that measures a +[load type](https://github.com/google/digitalbuildings/blob/master/ontology/yaml/resources/METERS/entity_types/LOADTYPES.yaml). +In these instances the connection should be set on the `LOADTYPE` entity as follows: + +``` yaml +LOADTYPE-GUID: + code: Loadtype HVAC + connections: + METER-GUID: + - MEASURES +``` From 33a46bb97c7e801c9c648e377a00e50b3d49efa7 Mon Sep 17 00:00:00 2001 From: shambergoldstein <124837286+shambergoldstein@users.noreply.github.com> Date: Wed, 5 Feb 2025 09:31:57 -0800 Subject: [PATCH 2/4] Update connections.md --- ontology/docs/connections.md | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/ontology/docs/connections.md b/ontology/docs/connections.md index 6693b63753..0e47800fb4 100644 --- a/ontology/docs/connections.md +++ b/ontology/docs/connections.md @@ -4,12 +4,14 @@ Connections are a type of relationship between two entities that describe the how the entities are associated. This may be a physical (e.g., `FEEDS`) or logical (e.g., `HAS_PART`) association. This document details the definitions of the various supported connections and in what scenarios each should be used. +When onboarding virtual devices the connections should be made on the virtual +device and not on the gateway. ## Contains #### Definition: Source physically encapsulates at least part of Target. -The contains connection should be used when one entity, or at least a component of it, +The Contains connection should be used when one entity, or at least a component of it, exists physically within another. This connection is commonly used to represent the location of an entity within a building. For example, a building may contain a floor which contains a room or zone, which contains a `VAV`. In this instance the connection @@ -31,11 +33,14 @@ VAV-GUID: - CONTAINS ``` +The Contains connection source entities must be in the `FACILITIES` namespaces. Devices +or systems that have sub-devices should use the Has Part connection instead. + ## Controls #### Definition: Source determines or affects the internal state or behavior of Target. -The controls connection should be used when one entity impacts the behavior of another. +The Controls connection should be used when one entity impacts the behavior of another. An example of when this connection may be used would be where a lighting control module, `LCM`, controls one or more luminaires, `LT`. In this example the connection should be set on the `LT` entity as follows: @@ -48,11 +53,14 @@ LT-GUID: - CONTROLS ``` +The target entity of a Controls connection must be one that performs an action. This +excludes `FACILITIES` entities. + ## Feeds #### Definition: Source provides some media (ex: water or air) to Target. -The feeds connection should be used when one entity is located pysically upstream of +The Feeds connection should be used when one entity is located pysically upstream of another in regards to its media, so that one device supplies the media to the other. A very common use case for this connections is when an `AHU` feeds air to a `VAV`. In this example the connection should be set on the `VAV` entity as follows: @@ -65,11 +73,14 @@ VAV-GUID: - FEEDS ``` +Feeds connections source entities must be devices that provide a medium. These devices +will typically be in the `HVAC` or `PLUMBING` namespaces. + ## Has Part #### Definition: Source has some component or part defined by Target. -The has part connection should be used to represent which system a component belongs to. +The Has Part connection should be used to represent which system a component belongs to. This can be used to represent something like a pump, `PMP`, that belongs to a chilled water system, `CHWS`. In this example the connection should be set on the `PMP` entity as follows: @@ -81,6 +92,10 @@ PMP-GUID: - HAS_PART ``` +The Has Part connection source entities must not be in the `FACILITIES` namespaces. `FACILITIES` +entities that have smaller `FACILITIES` entities or devices/systems within them should use the +Contains connection instead. + ## Has Range #### Definition: Source has a coverage or detection range defined by Target. @@ -98,6 +113,9 @@ ROOM-GUID: - HAS_RANGE ``` +The source entity for the Has Range connection must be a device that performs detection. +This typically includes `SENSORS`. + ## Measures #### Definition: Source quantifies attributes of the Target. @@ -114,3 +132,6 @@ LOADTYPE-GUID: METER-GUID: - MEASURES ``` + +The source entity for the Measures connection must be a device that performs quantification. +This typically includes `METERS`. From ca5d93c6ce1a98ec90c22e546d0c2c97d672d82c Mon Sep 17 00:00:00 2001 From: shambergoldstein <124837286+shambergoldstein@users.noreply.github.com> Date: Wed, 5 Feb 2025 10:26:30 -0800 Subject: [PATCH 3/4] Update connections.md --- ontology/docs/connections.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/ontology/docs/connections.md b/ontology/docs/connections.md index 0e47800fb4..652450d354 100644 --- a/ontology/docs/connections.md +++ b/ontology/docs/connections.md @@ -33,9 +33,6 @@ VAV-GUID: - CONTAINS ``` -The Contains connection source entities must be in the `FACILITIES` namespaces. Devices -or systems that have sub-devices should use the Has Part connection instead. - ## Controls #### Definition: Source determines or affects the internal state or behavior of Target. @@ -92,10 +89,6 @@ PMP-GUID: - HAS_PART ``` -The Has Part connection source entities must not be in the `FACILITIES` namespaces. `FACILITIES` -entities that have smaller `FACILITIES` entities or devices/systems within them should use the -Contains connection instead. - ## Has Range #### Definition: Source has a coverage or detection range defined by Target. From e0a8cfca1593de73609e71668a0aef70354fe124 Mon Sep 17 00:00:00 2001 From: shambergoldstein <124837286+shambergoldstein@users.noreply.github.com> Date: Wed, 12 Feb 2025 07:53:30 -0800 Subject: [PATCH 4/4] Update connections.md --- ontology/docs/connections.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ontology/docs/connections.md b/ontology/docs/connections.md index 652450d354..10df861f9b 100644 --- a/ontology/docs/connections.md +++ b/ontology/docs/connections.md @@ -71,7 +71,8 @@ VAV-GUID: ``` Feeds connections source entities must be devices that provide a medium. These devices -will typically be in the `HVAC` or `PLUMBING` namespaces. +will typically be in the `HVAC` or `PLUMBING` namespaces. The target entity can be +another device or can be a `FACILITIES` entity. ## Has Part