From 2227cc7153d0aa9f27eb7bc0eacf8bc295033188 Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 09:29:36 -0700 Subject: [PATCH 01/14] Update intro.md --- intro.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/intro.md b/intro.md index d97660b..953ac27 100644 --- a/intro.md +++ b/intro.md @@ -1,22 +1,23 @@ (landing-page)= # ASHRAE Standard 223 User Documentation ![Visitors](https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fdocs.open223.info%2F&countColor=%23263759) -The purpose of this site is to provide documentation for users of the *proposed* ASHRAE Standard 223, ***Designation and Classification of Semantic Tags for Building Data***. - -```{note} -This site is developed in conjunction with the ASHRAE Standard 223 project committee. However, it is not an official ASHRAE product or a part of the standard. -``` +The purpose of this site is to provide documentation for users of the *proposed* ASHRAE Standard 223 ***Semantic Data Model for Analytics and Automation Applications in Buildings***, which is currently available for public review[^1] per the schedule below. +[^1]: https://osr.ashrae.org/ ````{margin} ```{important} -The proposed standard is not yet available for public review. +This site is developed in conjunction with the ASHRAE Standard 223 project committee. However, it is not an official ASHRAE product or a part of the standard. ``` ```` -The documentation uses Diataxis[^1] as a framework for its structure, which is organized into the following sections. +Beg Date | End Date | Status +:-: | :-: | :- +2024-03-22 | 2024-05-06 | Advisory Public Review Draft + +The documentation uses Diataxis[^2] as a framework for its structure, which is organized into the following sections. -[^1]: https://diataxis.fr/ +[^2]: https://diataxis.fr/ ## Table of Contents ```{tableofcontents} From d8189177bbdc62c2bf8341f974911281e3e427db Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 09:41:57 -0700 Subject: [PATCH 02/14] Update purpose_scope.md --- explanation/purpose_scope.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/explanation/purpose_scope.md b/explanation/purpose_scope.md index c3a95a9..74c59b6 100644 --- a/explanation/purpose_scope.md +++ b/explanation/purpose_scope.md @@ -1,18 +1,17 @@ (purpose-scope)= # Purpose and Scope -The Purpose and Scope from from the current standard are provided below to introduce it to users. For more information about the standard, please see the published document [^1]. +The Purpose and Scope from from the current standard are provided below to introduce it to users. For more information about the Standard, please see the draft[^1]. -[^1]: TODO link to public review. +[^1]: https://osr.ashrae.org/ -## 1. Purpose +## 1 Purpose >The purpose of this standard is to define formal knowledge concepts and a methodology to apply them to create interoperable, machine-readable semantic frameworks for representing building automation and control data, and other building system information. -## 2. Scope +## 2 Scope >This standard provides a comprehensive way to apply semantic formalisms to represent the context of building system data and relationships between the associated building mechanical system components so that software applications can find and understand the information in an automated way. It is intended to facilitate the development and implementation of building analytics tools and enterprise knowledge applications that can implement many building system functions, including: ->1. automated fault detection and diagnostics ->2. building system commissioning ->3. digital twins ->4. real time optimization ->5. smart grid interactions - +>1. automated fault detection and diagnostics, +>2. building system commissioning, +>3. digital twins, +>4. optimization of energy use, and +>5. smart grid interactions. From d7d71f78288b8c1ba812bee88f2d123551996e37 Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:06:19 -0700 Subject: [PATCH 03/14] add definitions --- explanation/purpose_scope.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/explanation/purpose_scope.md b/explanation/purpose_scope.md index 74c59b6..e5576c1 100644 --- a/explanation/purpose_scope.md +++ b/explanation/purpose_scope.md @@ -1,7 +1,7 @@ (purpose-scope)= # Purpose and Scope -The Purpose and Scope from from the current standard are provided below to introduce it to users. For more information about the Standard, please see the draft[^1]. +The Purpose, Scope, and Definitions from the current Standard are provided below to introduce it to users. For more information about the Standard, please see the draft[^1]. [^1]: https://osr.ashrae.org/ @@ -15,3 +15,17 @@ The Purpose and Scope from from the current standard are provided below to intro >3. digital twins, >4. optimization of energy use, and >5. smart grid interactions. + +## 3 Definitions +>**Connectable**: an abstract class that represents a thing (Equipment or DomainSpace) that can be connected via ConnectionPoints and Connections. +>**Connection**: the modeling construct used to represent a physical thing (e.g., pipe, duct, or wire) that is used to convey some Medium (e.g., water, air, or electricity) between two Connectable things. +>**ConnectionPoint**: an abstract modeling construct used to represent the fact that one Connectable thing can be connected to another Connectable thing using a Connection. It is the abstract representation of the flange, wire terminal, or other physical feature where a connection is made. +>**Domain**: a categorization of building service or specialization used to characterize equipment or spaces in a building. Example domains include HVAC, lighting, and plumbing. +>**DomainSpace**: a portion or the entirety of a PhysicalSpace that is associated with a Domain, such as lighting, HVAC, or physical security. DomainSpaces can be combined to form a Zone. +>**Duct**: a subclass of Connection that represents a conduit through which air is conveyed. +>**ElectricWire**: a subclass of Connection that represents one or more electrical conductors used to convey electricity. +>**Equipment**: the modeling construct used to represent a mechanical device designed to accomplish a specific task that one might buy from a vendor. Examples include a pump, fan, heat exchanger, luminaire, temperature sensor, or flow meter. A piece of equipment can contain another piece of equipment. For example, an air handling unit can contain a cooling coil. +>**PhysicalSpace**: an architectural concept that can represent a room, a collection of rooms such as a floor, a part of a room, or any physical space that might not even be thought of as a room, such as a patio. +>**Pipe**: a subclass of Connection that represents a hollow cylinder of metal or other material used to convey a Medium. +>**System**: a task-oriented collection of interacting or interrelated Equipment defined by the modeler. Examples of possible systems are an air distribution system, or a hot water system. Systems can contain other Systems. +>**Zone**: a collection of DomainSpaces of a specific domain that are grouped together from the perspective of building services or controls. \ No newline at end of file From 5461a106c9bba9b2b2ba5d7e4985084de326de52 Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:08:02 -0700 Subject: [PATCH 04/14] heading too --- explanation/purpose_scope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/explanation/purpose_scope.md b/explanation/purpose_scope.md index e5576c1..cd69637 100644 --- a/explanation/purpose_scope.md +++ b/explanation/purpose_scope.md @@ -1,5 +1,5 @@ (purpose-scope)= -# Purpose and Scope +# Purpose, Scope, and Definitions The Purpose, Scope, and Definitions from the current Standard are provided below to introduce it to users. For more information about the Standard, please see the draft[^1]. From aed1c2a535b5484deec998148fe64be601736819 Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:08:42 -0700 Subject: [PATCH 05/14] rename --- explanation/{purpose_scope.md => purpose_scope_definitions.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename explanation/{purpose_scope.md => purpose_scope_definitions.md} (100%) diff --git a/explanation/purpose_scope.md b/explanation/purpose_scope_definitions.md similarity index 100% rename from explanation/purpose_scope.md rename to explanation/purpose_scope_definitions.md From ac7f42e56484c62332f60125844e64de6c78820e Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:12:56 -0700 Subject: [PATCH 06/14] rename definitions.md to concepts.md --- explanation/{definitions.md => concepts.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename explanation/{definitions.md => concepts.md} (100%) diff --git a/explanation/definitions.md b/explanation/concepts.md similarity index 100% rename from explanation/definitions.md rename to explanation/concepts.md From 0babb11079e0f70206dddbef2f62c67ba792ebd4 Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:13:29 -0700 Subject: [PATCH 07/14] update concepts.md --- explanation/concepts.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/explanation/concepts.md b/explanation/concepts.md index ee779b3..f9a2ddd 100644 --- a/explanation/concepts.md +++ b/explanation/concepts.md @@ -1,8 +1,8 @@ -(definitions)= -# Definitions and Concepts +(concepts)= +# Concepts -To understand the explanations in this chapter it is important to know the defintions of several concepts. More can be learned about these concepts from the resources linked in the [reference section](open223-resources). +To understand the explanations in this chapter it is important to know several concepts. More can be learned about these concepts from the resources linked in the [reference section](open223-resources). ## Graph Data Concepts @@ -15,7 +15,7 @@ Classes are organized into a hierarchy, and entities are an instance of a given Examples of relationships are *encapsulation* (one entity is contained within another), *sequence* (one entity takes effect before another in some process) and *instantiation* (one entity's type is given by another). - **Relation:** A predicate (RDF property) used to describe a given relationship. -Examples of a relation are the 223 relation `s223:contains`, which defines the relationship between two pieces of equipment in which one contains another. +Examples of a relation are the 223 relation `s223:contains`, which defines the relationship between two pieces of equipment in which one contains another. - **Graph:** An abstract organizational data structure representing a set of entities (nodes) and relationships (edges) described in triple-structure. 223 models are represented by a directed, labeled graph, and use the RDF standard. We recommend reading the [Wikipedia page on the abstract graph data structure](https://en.wikipedia.org/wiki/Graph_(abstract_data_type)) for more information. @@ -23,7 +23,7 @@ Examples of a relation are the 223 relation `s223:contains`, which defines the r ## 223 Top Level Classes -The 223 standard defines a hierarchy of classes used to define the entities within a buidling. This section provides a basic definition of the classes at the top level of the hierarchy to help users understand what the standard aims to represent, which is described in the [overview](223-overview). +The 223 standard defines a hierarchy of classes used to define the entities within a building. This section provides a basic definition of the classes at the top level of the hierarchy to help users understand what the standard aims to represent, which is described in the [overview](223-overview). - **Connection:** A modeling construct for representing a physical thing (e.g., pipe, duct, wire) that connects and conveys a medium between two Connectable things. @@ -45,7 +45,7 @@ The 223 standard defines a hierarchy of classes used to define the entities with - **Zone:** A collection of DomainSpaces grouped together based on building services or controls. - - **Properties:** Properties often represent the actuation and measurement points within a buidling. They may be associated with real-time data. They also may define the attributes of other entities (e.g. Equipment, DomainSpaces, Zones). They can be further contextualized using enumerations. + - **Properties:** Properties often represent the actuation and measurement points within a building. They may be associated with real-time data. They also may define the attributes of other entities (e.g. Equipment, DomainSpaces, Zones). They can be further contextualized using enumerations. - **Enumerations:** The standard uses enumerations to convey groups of useful values for describing attributes of Properties, Equipment, and other things in the model. For example, the enumeration `Role-Cooling` describes that the equipment in question provides cooling. From 82f1421764f8a3bb13098bfe2475ccc00db67464 Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:14:22 -0700 Subject: [PATCH 08/14] update toc --- _toc.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_toc.yml b/_toc.yml index 520aee7..1e4ebde 100644 --- a/_toc.yml +++ b/_toc.yml @@ -7,8 +7,8 @@ root: intro parts: - caption: Explanation chapters: - - file: explanation/purpose_scope.md - - file: explanation/definitions.md + - file: explanation/purpose_scope_definitions.md + - file: explanation/concepts.md - file: explanation/223_overview.md - file: explanation/graph_structure.md - caption: Tutorials From e0d7a8552b69751ce267bbd238ef011f6d616b7c Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:18:08 -0700 Subject: [PATCH 09/14] add spaces between definitions --- explanation/purpose_scope_definitions.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/explanation/purpose_scope_definitions.md b/explanation/purpose_scope_definitions.md index cd69637..0e4c53d 100644 --- a/explanation/purpose_scope_definitions.md +++ b/explanation/purpose_scope_definitions.md @@ -18,14 +18,25 @@ The Purpose, Scope, and Definitions from the current Standard are provided below ## 3 Definitions >**Connectable**: an abstract class that represents a thing (Equipment or DomainSpace) that can be connected via ConnectionPoints and Connections. +> >**Connection**: the modeling construct used to represent a physical thing (e.g., pipe, duct, or wire) that is used to convey some Medium (e.g., water, air, or electricity) between two Connectable things. +> >**ConnectionPoint**: an abstract modeling construct used to represent the fact that one Connectable thing can be connected to another Connectable thing using a Connection. It is the abstract representation of the flange, wire terminal, or other physical feature where a connection is made. +> >**Domain**: a categorization of building service or specialization used to characterize equipment or spaces in a building. Example domains include HVAC, lighting, and plumbing. +> >**DomainSpace**: a portion or the entirety of a PhysicalSpace that is associated with a Domain, such as lighting, HVAC, or physical security. DomainSpaces can be combined to form a Zone. +> >**Duct**: a subclass of Connection that represents a conduit through which air is conveyed. +> >**ElectricWire**: a subclass of Connection that represents one or more electrical conductors used to convey electricity. +> >**Equipment**: the modeling construct used to represent a mechanical device designed to accomplish a specific task that one might buy from a vendor. Examples include a pump, fan, heat exchanger, luminaire, temperature sensor, or flow meter. A piece of equipment can contain another piece of equipment. For example, an air handling unit can contain a cooling coil. +> >**PhysicalSpace**: an architectural concept that can represent a room, a collection of rooms such as a floor, a part of a room, or any physical space that might not even be thought of as a room, such as a patio. +> >**Pipe**: a subclass of Connection that represents a hollow cylinder of metal or other material used to convey a Medium. +> >**System**: a task-oriented collection of interacting or interrelated Equipment defined by the modeler. Examples of possible systems are an air distribution system, or a hot water system. Systems can contain other Systems. +> >**Zone**: a collection of DomainSpaces of a specific domain that are grouped together from the perspective of building services or controls. \ No newline at end of file From 34df3a43b21803c6719ee97f3ac61887d8582a98 Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:37:01 -0700 Subject: [PATCH 10/14] rename 223_overview.md to overview.md --- explanation/{223_overview.md => overview.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename explanation/{223_overview.md => overview.md} (100%) diff --git a/explanation/223_overview.md b/explanation/overview.md similarity index 100% rename from explanation/223_overview.md rename to explanation/overview.md From 926ee5ecfec0fa1d23a767c0417ba627139ef122 Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:38:12 -0700 Subject: [PATCH 11/14] rename graph_structure.md to structure.md --- explanation/{graph_structure.md => structure.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename explanation/{graph_structure.md => structure.md} (100%) diff --git a/explanation/graph_structure.md b/explanation/structure.md similarity index 100% rename from explanation/graph_structure.md rename to explanation/structure.md From 607aec3eb59c9127c5fba15a137c835b65064764 Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:38:28 -0700 Subject: [PATCH 12/14] update toc --- _toc.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_toc.yml b/_toc.yml index 1e4ebde..a1e6d13 100644 --- a/_toc.yml +++ b/_toc.yml @@ -9,8 +9,8 @@ parts: chapters: - file: explanation/purpose_scope_definitions.md - file: explanation/concepts.md - - file: explanation/223_overview.md - - file: explanation/graph_structure.md + - file: explanation/overview.md + - file: explanation/structure.md - caption: Tutorials chapters: - file: tutorials/model_exploration.md From acc560818710e1e16683909f7ea5c1c54543221b Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:46:59 -0700 Subject: [PATCH 13/14] update explanation files --- explanation/concepts.md | 4 ++-- explanation/overview.md | 18 +++++++++--------- explanation/structure.md | 4 ++-- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/explanation/concepts.md b/explanation/concepts.md index f9a2ddd..c6ffa75 100644 --- a/explanation/concepts.md +++ b/explanation/concepts.md @@ -2,7 +2,7 @@ (concepts)= # Concepts -To understand the explanations in this chapter it is important to know several concepts. More can be learned about these concepts from the resources linked in the [reference section](open223-resources). +To understand the explanations in this chapter it is important to know several concepts. More can be learned about these concepts from the [Open223 Resources](open223-resources). ## Graph Data Concepts @@ -23,7 +23,7 @@ Examples of a relation are the 223 relation `s223:contains`, which defines the r ## 223 Top Level Classes -The 223 standard defines a hierarchy of classes used to define the entities within a building. This section provides a basic definition of the classes at the top level of the hierarchy to help users understand what the standard aims to represent, which is described in the [overview](223-overview). +The 223 standard defines a hierarchy of classes used to define the entities within a building. This section provides a basic definition of the classes at the top level of the hierarchy to help users understand what the standard aims to represent, which is described in the [overview](overview). - **Connection:** A modeling construct for representing a physical thing (e.g., pipe, duct, wire) that connects and conveys a medium between two Connectable things. diff --git a/explanation/overview.md b/explanation/overview.md index a38df18..0c2adb6 100644 --- a/explanation/overview.md +++ b/explanation/overview.md @@ -1,9 +1,9 @@ -(223-overview)= -# 223 Overview +(overview)= +# Overview -This standard allows users to create semantic models that describe the many entities in their buildings that are relevant to advanced features and applications such as fault detection and diagnostics, demand flexibility, and real time optimization. +This standard allows users to create semantic models that describe the many entities in their buildings that are relevant to advanced features and applications such as fault detection and diagnostics, demand flexibility, and real time optimization. -There is a huge amount of information about the many entities within a building that you may want to model. This section will explain what information you should represent in a 223 model and the 223 modeling constructs you will use to do so. Descriptions assume you have some familiarity with RDF graph data and know the [definitions of key terms used in this section](definitions). +There is a huge amount of information about the many entities within a building that you may want to model. This section will explain what information you should represent in a 223 model and the 223 modeling constructs you will use to do so. Descriptions assume you have some familiarity with RDF graph data and know the [definitions of key terms used in this section](definitions). ## Type @@ -11,7 +11,7 @@ This standard provides well defined classes used to describe entities relevant t ## Topology -This standard can be used to describe the topology of the equipment and spaces in a building, but not the geometric details. Topology refers to the way entities are connected and how some media (e.g. water, air, or electricity) is conveyed between them. There are several different classes used to describe which entities participate in connections and how they connect: [Connectables](https://explore.open223.info/s223/Connectable.html), which include the entities that are capable of connecting to each other; [ConnectionPoints](https://explore.open223.info/s223/ConnectionPoint.html), which model where Connectables can be connected; and [Connections](https://explore.open223.info/s223/Connection.html), which describe physical things through which the medium is conveyed, like pipes or ducts. These [Mediums](https://explore.open223.info/s223/Substance-Medium.html) (e.g. gas, electricity, water) are defined as an [EnumerationKind](https://explore.open223.info/s223/EnumerationKind.html) in the standard. There are also multiple relations used to describe the details of these connections, and how the multiple entities involved in a connection relate to each other. Figure 1 summarizes these relations. Though there are many relations to describe different perspectives of a connection, only [`s223:cnx`](https://explore.open223.info/s223/cnx.html) needs to be manually added to the model, and the rest can be automatically added to the model through the process of [inference](model-inference). +This standard can be used to describe the topology of the equipment and spaces in a building, but not the geometric details. Topology refers to the way entities are connected and how some media (e.g. water, air, or electricity) is conveyed between them. There are several different classes used to describe which entities participate in connections and how they connect: [Connectables](https://explore.open223.info/s223/Connectable.html), which include the entities that are capable of connecting to each other; [ConnectionPoints](https://explore.open223.info/s223/ConnectionPoint.html), which model where Connectables can be connected; and [Connections](https://explore.open223.info/s223/Connection.html), which describe physical things through which the medium is conveyed, like pipes or ducts. These [Mediums](https://explore.open223.info/s223/Substance-Medium.html) (e.g. gas, electricity, water) are defined as an [EnumerationKind](https://explore.open223.info/s223/EnumerationKind.html) in the standard. There are also multiple relations used to describe the details of these connections, and how the multiple entities involved in a connection relate to each other. Figure 1 summarizes these relations. Though there are many relations to describe different perspectives of a connection, only [`s223:cnx`](https://explore.open223.info/s223/cnx.html) needs to be manually added to the model, and the rest can be automatically added to the model through the process of [inference](model-inference). ```{image} _static/images/connection-relationships.png @@ -25,14 +25,14 @@ This standard can be used to describe the topology of the equipment and spaces i ## Composition -Composition is about what entities make up what other entities. For example, a piece of mechanical equipment like a VAV may in fact be made up of other pieces of mechanical equipment, such as a damper and a reheat coil. Additionally, a zone may be made up of several different spaces that receive a similar building service, or a floor may be made up of different rooms, corridors, or offices. Several different modeling constructs use the idea of composition. These modeling constructs include include [Equipment](https://explore.open223.info/s223/Equipment.html), which may contain other equipment (e.g. VAV containing a Damper); [Zones](https://explore.open223.info/s223/Zone.html), which may have [DomainSpaces](https://explore.open223.info/s223/DomainSpace.html) that receive a similar building service; [ZoneGroups](https://explore.open223.info/s223/ZoneGroup.html), which group together similarly controlled Zones; [Systems](https://explore.open223.info/s223/System.html) that represent a collection of interrelated Equipment; or [PhysicalSpaces](https://explore.open223.info/s223/PhysicalSpace.html), which may contain other PhysicalSpaces as a floor contains multiple rooms. PhysicalSpaces may also enclose DomainSpaces, indicating that the DomainSpace is completely within the PhysicalSpace. For example, an auditorium (a PhysicalSpace) may enclose several different areas served by independently controlled lights (DomainSpaces). +Composition is about what entities make up what other entities. For example, a piece of mechanical equipment like a VAV may in fact be made up of other pieces of mechanical equipment, such as a damper and a reheat coil. Additionally, a zone may be made up of several different spaces that receive a similar building service, or a floor may be made up of different rooms, corridors, or offices. Several different modeling constructs use the idea of composition. These modeling constructs include include [Equipment](https://explore.open223.info/s223/Equipment.html), which may contain other equipment (e.g. VAV containing a Damper); [Zones](https://explore.open223.info/s223/Zone.html), which may have [DomainSpaces](https://explore.open223.info/s223/DomainSpace.html) that receive a similar building service; [ZoneGroups](https://explore.open223.info/s223/ZoneGroup.html), which group together similarly controlled Zones; [Systems](https://explore.open223.info/s223/System.html) that represent a collection of interrelated Equipment; or [PhysicalSpaces](https://explore.open223.info/s223/PhysicalSpace.html), which may contain other PhysicalSpaces as a floor contains multiple rooms. PhysicalSpaces may also enclose DomainSpaces, indicating that the DomainSpace is completely within the PhysicalSpace. For example, an auditorium (a PhysicalSpace) may enclose several different areas served by independently controlled lights (DomainSpaces). -## Telemetry +## Telemetry -A 223 model does not directly provide telemetric data about the real-time operation or past operation of the building systems. It does provide information about the meaning or context of a given data point and it can link to a source of the data values so that an analytics application can find them. If the building has a BACnet building automation and control system, the model can provide the necessary information for analytics or controls software to learn which BACnet object and property corresponds to the desired piece of information. Data points are represented using Properties. There are multiple types of [Properties](https://explore.open223.info/s223/Property.html), such as control points that can be written to ([ActuatableProperties](https://explore.open223.info/s223/ActuatableProperty.html)), sensor points that are observed ([ObservableProperties](https://explore.open223.info/s223/ObservableProperty.html)), either of which can refer to enumerated ([EnumerableProperty](https://explore.open223.info/s223/EnumerableProperty.html)) or quantified ([QuantifiableProperty](https://explore.open223.info/s223/QuantifiableProperty.html)) values. Properties may also be used for mathematical operations, including those that are common in a building such as control logic. This idea is represented using [FunctionBlocks](https://explore.open223.info/s223/FunctionBlock.html). Properties also have many different characteristics which are described by a vocabulary of [EnumerationKinds](https://explore.open223.info/s223/EnumerationKind.html). +A 223 model does not directly provide telemetric data about the real-time operation or past operation of the building systems. It does provide information about the meaning or context of a given data point and it can link to a source of the data values so that an analytics application can find them. If the building has a BACnet building automation and control system, the model can provide the necessary information for analytics or controls software to learn which BACnet object and property corresponds to the desired piece of information. Data points are represented using Properties. There are multiple types of [Properties](https://explore.open223.info/s223/Property.html), such as control points that can be written to ([ActuatableProperties](https://explore.open223.info/s223/ActuatableProperty.html)), sensor points that are observed ([ObservableProperties](https://explore.open223.info/s223/ObservableProperty.html)), either of which can refer to enumerated ([EnumerableProperty](https://explore.open223.info/s223/EnumerableProperty.html)) or quantified ([QuantifiableProperty](https://explore.open223.info/s223/QuantifiableProperty.html)) values. Properties may also be used for mathematical operations, including those that are common in a building such as control logic. This idea is represented using [FunctionBlocks](https://explore.open223.info/s223/FunctionBlock.html). Properties also have many different characteristics which are described by a vocabulary of [EnumerationKinds](https://explore.open223.info/s223/EnumerationKind.html). ## Characteristics -A model can also describe the characteristics of the entities in a building. These characteristics express details about entities that are not otherwise expressed by the type, topology, or composition of the entity. Often, these characteristics are linked to specific instances in a model. For example, a characteristic of a pump would be its rated flow. Another pump in the same 223 model may have a different rated flow, but it will use the same 223 class (i.e. [`s223:Pump`](https://explore.open223.info/s223/Pump.html)). These types of characteristics are modeled using [Properties](https://explore.open223.info/s223/Property.html). +A model can also describe the characteristics of the entities in a building. These characteristics express details about entities that are not otherwise expressed by the type, topology, or composition of the entity. Often, these characteristics are linked to specific instances in a model. For example, a characteristic of a pump would be its rated flow. Another pump in the same 223 model may have a different rated flow, but it will use the same 223 class (i.e. [`s223:Pump`](https://explore.open223.info/s223/Pump.html)). These types of characteristics are modeled using [Properties](https://explore.open223.info/s223/Property.html). Properties also have various characteristics including their units, quantity kinds, enumeration kinds, and aspects. [Units](https://www.qudt.org/doc/DOC_VOCAB-UNITS.html) describe the unit (e.g. Fahrenheit) of a [QuantifiableProperty](https://explore.open223.info/s223/QuantifiableProperty.html) and [quantity kinds](https://www.qudt.org/doc/DOC_VOCAB-QUANTITY-KINDS.html) describe the type of quantity that may be stated by means of units (e.g. temperature). These are modeled using [qudt ontologies](https://qudt.org/). [EnumerableProperties](https://explore.open223.info/s223/EnumerableProperty.html) do not have units, but they have enumerated values that can be described by [EnumerationKinds](https://explore.open223.info/s223/EnumerationKind.html). Aspects establish the context of a Property. For example, if a Property has a Temperature value of 80.6, aspects are used to state what that represents, such as a Temperature limit during working hours, etc. A Property can have any number of aspects, as needed to establish the context. Any [EnumerationKind](https://explore.open223.info/s223/EnumerationKind.html) can be used as an aspect. \ No newline at end of file diff --git a/explanation/structure.md b/explanation/structure.md index 24b2f5e..46ac3d6 100644 --- a/explanation/structure.md +++ b/explanation/structure.md @@ -1,8 +1,8 @@ -## 223 Graph Structure +## Structure Standard 223 is represented using the Resource Description Framework (RDF). RDF is a general method for representic semantic information in the form of a triple, which consists of a subject, a predicate, and an object. The subject and object define two entities, which are a instances of some class, and the predicate defines how they are related. A collection of these triples make up a graph. The 223 standard defines classes and relationships relevant to the building space that can then be used to build a multi-graph representing a specific building or group of buildings. For more information about RDF and the other semantic technologies used by the standard, please look at the [reference section](other-resources). -To create a semantic model of your building using the 223 standard, you create instances that represent the entities in your building, and define them using the classes and relationships defined or referenced by the standard. For example, you may be creating a model of a building in which the air handling unit (ahu-1) contains a fan (fan-1). Your air handling unit (ahu-1) would be modeled as an instance of the 223 class [`s223:AirHandlingUnit`](https://explore.open223.info/s223/AirHandlingUnit.html), which describes the general class of things resembling Air Handling Units. Similarly, your fan (fan-1) would be an instance of the 223 class [`s223:Fan`](https://explore.open223.info/s223/Fan.html). The idea of containment is defined using the 223 relation [`s223:contains`](https://explore.open223.info/s223/contains.html), so your air handling unit would relate to your fan using the relation `s223:contains`. The relationship between an instance and a class is defined using the RDF relation `rdf:type`, so your ahu and fan would relate to `s223:AirHandlingUnit` and `s223:Fan` using that relation. This example is shown in Figure 1. +To create a semantic model of your building using the 223 standard, you create instances that represent the entities in your building, and define them using the classes and relationships defined or referenced by the standard. For example, you may be creating a model of a building in which the air handling unit (ahu-1) contains a fan (fan-1). Your air handling unit (ahu-1) would be modeled as an instance of the 223 class [`s223:AirHandlingUnit`](https://explore.open223.info/s223/AirHandlingUnit.html), which describes the general class of things resembling Air Handling Units. Similarly, your fan (fan-1) would be an instance of the 223 class [`s223:Fan`](https://explore.open223.info/s223/Fan.html). The idea of containment is defined using the 223 relation [`s223:contains`](https://explore.open223.info/s223/contains.html), so your air handling unit would relate to your fan using the relation `s223:contains`. The relationship between an instance and a class is defined using the RDF relation `rdf:type`, so your ahu and fan would relate to `s223:AirHandlingUnit` and `s223:Fan` using that relation. This example is shown in Figure 1. ```{image} _static/images/ex-1.svg :align: center From b3a77abdc060f998caf997ba5b4ef83722e7d906 Mon Sep 17 00:00:00 2001 From: Matt Steen Date: Sat, 30 Mar 2024 10:56:30 -0700 Subject: [PATCH 14/14] alphabetize concepts --- explanation/concepts.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/explanation/concepts.md b/explanation/concepts.md index c6ffa75..6ab7671 100644 --- a/explanation/concepts.md +++ b/explanation/concepts.md @@ -21,16 +21,10 @@ Examples of a relation are the 223 relation `s223:contains`, which defines the r - **A 223 Model:** A 223 model is a digital representation of a building in RDF graph structure that uses the 223 standard. This means that elements of the building are represented using the modeling constructs defined in the standard. The standard leverages semantic web technologies, allowing easy integration with other types of models based on RDF. -## 223 Top Level Classes +## 223 Top Level Concepts The 223 standard defines a hierarchy of classes used to define the entities within a building. This section provides a basic definition of the classes at the top level of the hierarchy to help users understand what the standard aims to represent, which is described in the [overview](overview). - - **Connection:** A modeling construct for representing a physical thing (e.g., pipe, duct, wire) that connects and conveys a medium between two Connectable things. - - - **ConnectionPoint:** An abstract modeling construct representing the point where one Connectable thing connects to another. - - - **Domain:** A categorization of building service or specialization used to characterize equipment or spaces (e.g., HVAC, lighting, plumbing). - - **Connectable:** This is the top level entity that defines the classes that may be connected via ConnectionPoints and Connections. There are three major sub-classes of connectable - **DomainSpace:** A portion or entirety of a PhysicalSpace associated with a Domain. Often a DomainSpace is served by a particular piece of equipment, like a single VAV Box, and thus they can be connected to equipment. Multiple DomainSpaces controlled similarly can be grouped together, forming a Zone. @@ -39,14 +33,20 @@ The 223 standard defines a hierarchy of classes used to define the entities with - **Junction:** A Junction is a modeling construct used to represent important branching points within a Connection. - - **PhysicalSpace:** An architectural concept representing a room, floor, or any physical space in a building. These PhysicalSpaces (e.g. a floor) can contain other PhysicalSpaces (e.g. a room). - - - **System:** A task-oriented collection of interacting or interrelated Equipment defined by the modeler. + - **Connection:** A modeling construct for representing a physical thing (e.g., pipe, duct, wire) that connects and conveys a medium between two Connectable things. - - **Zone:** A collection of DomainSpaces grouped together based on building services or controls. + - **ConnectionPoint:** An abstract modeling construct representing the point where one Connectable thing connects to another. - - **Properties:** Properties often represent the actuation and measurement points within a building. They may be associated with real-time data. They also may define the attributes of other entities (e.g. Equipment, DomainSpaces, Zones). They can be further contextualized using enumerations. + - **Domain:** A categorization of building service or specialization used to characterize equipment or spaces (e.g., HVAC, lighting, plumbing). - **Enumerations:** The standard uses enumerations to convey groups of useful values for describing attributes of Properties, Equipment, and other things in the model. For example, the enumeration `Role-Cooling` describes that the equipment in question provides cooling. - - **FunctionBlock:** Is used to model transfer and/or transformation of information (e.g. control algorithms). It has relations to input properties and output properties, that represent input and output data. The actual algorithms that perform the transformations are not described in 223, and can be described using standard 231. \ No newline at end of file + - **FunctionBlock:** Is used to model transfer and/or transformation of information (e.g. control algorithms). It has relations to input properties and output properties, that represent input and output data. The actual algorithms that perform the transformations are not described in 223, and can be described using standard 231. + + - **PhysicalSpace:** An architectural concept representing a room, floor, or any physical space in a building. These PhysicalSpaces (e.g. a floor) can contain other PhysicalSpaces (e.g. a room). + +- **Properties:** Properties often represent the actuation and measurement points within a building. They may be associated with real-time data. They also may define the attributes of other entities (e.g. Equipment, DomainSpaces, Zones). They can be further contextualized using enumerations. + + - **System:** A task-oriented collection of interacting or interrelated Equipment defined by the modeler. + + - **Zone:** A collection of DomainSpaces grouped together based on building services or controls.