diff --git a/_config.yml b/_config.yml index f394b7f..52e162a 100644 --- a/_config.yml +++ b/_config.yml @@ -1,7 +1,7 @@ # https://jupyterbook.org/en/stable/customize/config.html # Book settings -title: ASHRAE 223P User Documentation +title: ASHRAE Standard 223P User Documentation author: "" copyright: "" logo: "" diff --git a/_toc.yml b/_toc.yml index e2f05b5..fdcd198 100644 --- a/_toc.yml +++ b/_toc.yml @@ -5,6 +5,9 @@ format: jb-book root: intro parts: +- caption: Explanation + chapters: + - file: explanation/223p.md - caption: Tutorials chapters: - file: tutorials/223-explore.md @@ -16,16 +19,13 @@ parts: - file: guides/how-to-model.md - file: guides/how-to-telemetry.md - file: guides/how-to-extend.md -- caption: Explanation - chapters: - - file: explanation/223p.md - - file: explanation/supporting-tech.md - caption: Reference chapters: - file: reference/supporting-links.md - file: reference/tools.md - file: reference/open-223.md - file: reference/example-models.md + - file: reference/supporting-tech.md - caption: Example Models chapters: - file: examples/lbnl-example.md diff --git a/explanation/223p.md b/explanation/223p.md index e783595..4796b7f 100644 --- a/explanation/223p.md +++ b/explanation/223p.md @@ -1,16 +1,16 @@ -# Introduction to ASHRAE 223P +# ASHRAE Standard 223P Standard 223P provides a comprehensive approach to applying semantic formalisms for representing building automation system data and relationships between associated entities such as equipment, physical spaces, and zones. The primary purpose is to enable software applications to automate the discovery and understanding of information related to building systems. This facilitates the development of advanced tools and applications for building analytics and supports the creation of digital twins and optimization of energy usage within building systems. Specific functionalities include automated fault detection, diagnostics, building system commissioning, and interactions with smart grids. -The standard provides a machine-readable representation of building systems, their associated spaces, and key measurement/control points that can be used to construct semantic models for individual buildings or entire capmuses. It rigorously defines the concepts of the standard using validation and inference rules, helping to ensure that models are created correctly and will be interoperable. This is accomplished using various semantic web technologies, further described in the [following section](supporting-tech). The notions of entities, classes, relationships, and graphs are required to understand the standard, and are defined below. +The standard provides a machine-readable representation of building systems, their associated spaces, and key measurement/control points that can be used to construct semantic models for individual buildings or entire capmuses. It rigorously defines the concepts of the standard using validation and inference rules, helping to ensure that models are created correctly and will be interoperable. This is accomplished using various semantic web technologies, further described in the [reference section](../reference/supporting-tech.md). The notions of entities, classes, relationships, and graphs are required to understand the standard, and are defined below. Definitions - - **Entity:** An entity is an abstraction of any physical, logical or virtual item; the actual "things" in a building. Examples are mechanical equipment such as air handling units, luminaires, spatial elements like rooms, or the area of these rooms served by certain mechanical equipment. Virtual and logical entities may represent the various data points in a BAS system, such as sensing and actuation points, as well as basic representations of controls. + - **Entity:** An entity is an abstraction of any physical, logical or virtual item; the actual "things" in a building. Examples are mechanical equipment such as air handling units, luminaires, spatial elements like rooms, or the area of these rooms served by certain mechanical equipment. Virtual and logical entities may represent the various data points in a BAS system, such as sensing and actuation points, as well as basic representations of controls. - - **Class:** A named category with intensional meaning (a definition) used for grouping entities. -Classes are organized into a hierarchy, and entities are an instance of a given class. Classes are defined using SHACL shapes ensuring that they are instantiated correctly. + - **Class:** A named category with intensional meaning (a definition) used for grouping entities. +Classes are organized into a hierarchy, and entities are an instance of a given class. Classes are defined using SHACL shapes ensuring that they are instantiated correctly. - **Relationship:** Defines the nature of a link between two related entities. 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 entity). @@ -18,11 +18,11 @@ Examples of relationships are *encapsulation* (one entity is contained within an - **Graph:** An abstract organizational data structure representing a set of entities (nodes) and relationships (edges) described in triple-structure. 223P models are represented by a directed, labeled graph. We recommend reading the [Wikipedia page on the abstract graph data structure](https://en.wikipedia.org/wiki/Graph_(abstract_data_type)). - - **A 223P model:** A 223P model is a digital representation of a building that utilizes the 223P standard. This means that elements of a particular buidling are represented using instances of the classes defined by the 223P standard and use relationships as defined by the rules present in the standard. 223P leverages the semantic web technologies, allowing easy integration with other types of models that utilize RDF. + - **A 223P model:** A 223P model is a digital representation of a building that utilizes the 223P standard. This means that elements of a particular buidling are represented using instances of the classes defined by the 223P standard and use relationships as defined by the rules present in the standard. 223P leverages the semantic web technologies, allowing easy integration with other types of models that utilize RDF. ## 223P Top Level Classes -The 223P standard defines several high level concepts, represented as classes, that are subclassed and composed to create 223P models. All entities in a 223P model are an instance of these classes or one of their subclasses. More detail about each of these concepts and their classes can be found on [Open 223 Explorer](https://explore.open223.info/). A [tutorial](223-explore) is provided to help users explore that website if they are unfamiliar with semantic ontologies. Additionally, a [modeling guidance section](how-to-model) provides detailed description of how these concepts can be applied, and [example models](example-models) are avaialable to see how these concepts are used. +The 223P standard defines several high level concepts, represented as classes, that are subclassed and composed to create 223P models. All entities in a 223P model are an instance of these classes or one of their subclasses. More detail about each of these concepts and their classes can be found on [Open 223 Explorer](https://explore.open223.info/). A [tutorial](223-explore) is provided to help users explore that website if they are unfamiliar with semantic ontologies. Additionally, a [modeling guidance section](how-to-model) provides detailed description of how these concepts can be applied, and [example models](example-models) are avaialable to see how these concepts are used. - **Connectable:** An abstract class representing a thing that can be connected via ConnectionPoints and Connections. @@ -36,7 +36,7 @@ The 223P standard defines several high level concepts, represented as classes, t - **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. - - **Equipment:** A modeling construct used to represent a mechanical device designed to accomplish a specific task (e.g. pump, fan, heat exchanger, luminaire, temperature sensor, flow meter). Equipment may contain and connect to other equipment, allowing detailed modeling of mechanical systems. Certain pieces of equipment (i.e. Sensors, Actuators, Controllers) may have unique relationships to properties to define how they act on the properties of other entities. + - **Equipment:** A modeling construct used to represent a mechanical device designed to accomplish a specific task (e.g. pump, fan, heat exchanger, luminaire, temperature sensor, flow meter). Equipment may contain and connect to other equipment, allowing detailed modeling of mechanical systems. Certain pieces of equipment (i.e. Sensors, Actuators, Controllers) may have unique relationships to properties to define how they act on the properties of other entities. - **Junction:** A Junction is a modeling construct used to represent important branching points within a Connection. @@ -48,6 +48,6 @@ The 223P standard defines several high level concepts, represented as classes, t - **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. - - **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. + - **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 223P, and can be described using standard 231P. + - **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 223P, and can be described using standard 231P. diff --git a/intro.md b/intro.md index 647fd0b..9e9daf2 100644 --- a/intro.md +++ b/intro.md @@ -1,4 +1,4 @@ -# ASHRAE 223P User Documentation [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://open223.github.io/docs.open223.info/) +# ASHRAE Standard 223P User Documentation [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://open223.github.io/docs.open223.info/) 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***. diff --git a/explanation/supporting-tech.md b/reference/supporting-tech.md similarity index 100% rename from explanation/supporting-tech.md rename to reference/supporting-tech.md