Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions _toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ parts:
chapters:
- file: modeling/collections
- file: modeling/connections
- file: modeling/controllers
- file: modeling/meters
- file: modeling/point-collections
- file: modeling/terminal-units
Expand Down
4 changes: 2 additions & 2 deletions brick/aliases.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ Aliases and Equivalent Classes


```{note}
This feature is new in Brick v1.4
This feature was introduced in Brick v1.4.
```

Over its history, Brick has accumulated several duplicate class names. For example: `brick:AHU`, `brick:Air_Handler_Unit` and `brick:Air_Handling_Unit` can all be found in the Brick 1.4 release.
Brick retains all of these classes for backwards-compatibility; however, in Brick 1.4 it became necessary to denote a *preferred* class among a set of interchangeable classes.
At the same time, downstream tools and consumers should remain agnostic to whichever class was chosen by a modeler.
Brick 1.4 handles both of these features through two mechanisms: *equivalent classes* and *aliases*.
Brick handles both of these features through two mechanisms: *equivalent classes* and *aliases*.

## Aliases

Expand Down
22 changes: 22 additions & 0 deletions brick/relationships.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,18 @@ We list each of the Brick relationships related to each of the modeling perspect

`brick:hasPoint`: the *subject* has a source of telemetry identified by *object*. Generally this means that some aspect of *subject* is measured, controlled, configured or monitored, and the generated telemetry is identified by *object*. The type and definition of *object* dictates what aspect of *subject* is being represented by data.

`brick:hosts`: the *subject* (an ICT Equipment instance) hosts or exposes the *object* (a Point). Use this to describe which network device or controller physically exposes a given data point.

### Control

```{note}
`brick:controls`, `brick:isControlledBy`, `brick:hosts`, and `brick:isHostedBy` are new in Brick v1.5.
```

`brick:controls`: the *subject* (a Controller) controls the *object* (Equipment).

`brick:isControlledBy`: inverse of `brick:controls`; the *subject* (Equipment) is controlled by the *object* (a Controller).

## How and When to Use Brick Relationships

When your *subject* is a...
Expand All @@ -88,6 +100,14 @@ When your *subject* is a...
- `feeds` describes downstream equipment and locations
- AHU `feeds` VAV
- VAV `feeds` HVAC Zone
- `isControlledBy` describes the controller responsible for the equipment
- VAV `isControlledBy` VAV_Controller
- **ICT Equipment**:
- `hosts` describes points exposed by the device
- BACnet_Device `hosts` Temperature_Sensor
- **Controller**:
- `controls` describes what equipment the controller manages
- VAV_Controller `controls` VAV

### Quick Note on "Inverse" Relationships

Expand All @@ -99,6 +119,8 @@ Brick allows many relationships to be defined in two different directions throug
| `hasPart` | `isPartOf` |
| `hasLocation`| `isLocationOf` |
| `feeds` | `isFedBy` |
| `controls` | `isControlledBy` |
| `hosts` | `isHostedBy` |

In all cases where we have `subject relationship object`, an equvalent statement is `object inverse-relationship subject`.

22 changes: 21 additions & 1 deletion extra/brick-rec.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Using Brick and RealEstateCore Together
===============

```{note}
This feature is new in Brick v1.4 and relies on the integration with RealEstateCore
Brick-REC integration was introduced in Brick v1.4 and expanded in v1.5.
```

This document summarizes the changes to Brick that allow it to be used in conjunction with RealEstateCore (REC).
Expand Down Expand Up @@ -55,3 +55,23 @@ See this table:
| `brick:isPointOf` | `rec:isPointOf` |
| `brick:hasPart` | `rec:hasPart` |
| `brick:isPartOf` | `rec:isPartOf` |
| `brick:hasPart` (collection membership) | `rec:includes` |

## Collections

```{note}
This section describes changes introduced in Brick v1.5.
```

As of Brick v1.5.0, `brick:Collection` has been deprecated in favor of `rec:Collection` to remove redundancy between the two ontologies. Custom collections should now be typed as `rec:Collection` and use `rec:includes` to express membership:

```turtle
@prefix rec: <https://w3id.org/rec#> .
@prefix : <urn:bldg#> .

:my_collection a rec:Collection ;
rdfs:label "All of the dampers" ;
rec:includes :dmp1, :dmp2 .
```

All built-in Brick collection classes (e.g. `brick:HVAC_System`, `brick:Air_Loop`, `brick:PV_Array`) are now subclasses of `rec:Collection` rather than the deprecated `brick:Collection`.
3 changes: 2 additions & 1 deletion extra/extending.md
Original file line number Diff line number Diff line change
Expand Up @@ -229,10 +229,11 @@ In the Brick model file, `my_building_graph.ttl`, the extension classes and rela

```turtle
@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix rec: <https://w3id.org/rec#> .
@prefix ext: <https://example.com/schema/BrickExtension#> .
@prefix bldg: <urn:snow_cone_factory#> .

bldg:factory a brick:Building ;
bldg:factory a rec:Building ;
brick:buildingPrimaryFunction [ brick:value "Manufacturing/Industrial Plant" ] .

bldg:ice_machine_1 a ext:IceMachine ;
Expand Down
19 changes: 14 additions & 5 deletions modeling/collections.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Collections, Systems and Loops
A *collection* is a group of related entities, typically organized around a fixed use or function.


A collection is modeled as a Brick entity which contains other entities; the relationship between a collection and its contents is `brick:hasPart`. Collections allow a modeler to associate entities together to make them easier to find later. Systems and Loops are special kinds of Collections.
A collection is modeled as an entity which contains other entities; the relationship between a collection and its contents is `rec:includes`. Collections allow a modeler to associate entities together to make them easier to find later. Systems and Loops are special kinds of Collections.

Brick defines multiple kinds of collections and allows modelers to create their own.

Expand Down Expand Up @@ -82,16 +82,25 @@ SELECT ?content WHERE {

## Custom Collections

It is possible for a modeler to create their own ad-hoc collections, depending on how they want to organize entities in the model. The generic `brick:Collection` class is available for this purpose.
These can be created by instantiating a new entity that is of type `brick:Collection`; it is recommended to use `rdfs:label` to name the collection.
```{note}
As of Brick v1.5, custom collections use `rec:Collection` and `rec:includes`. The `brick:Collection` class is deprecated.
```

It is possible for a modeler to create their own ad-hoc collections, depending on how they want to organize entities in the model. The generic `rec:Collection` class is available for this purpose.
These can be created by instantiating a new entity that is of type `rec:Collection`; it is recommended to use `rdfs:label` to name the collection.

Using the example of the HVAC system above, one can create a collection containing just the dampers.

```turtle
@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix rec: <https://w3id.org/rec#> .
@prefix : <urn:bldg#> .

:my_collection a brick:Collection ;
:my_collection a rec:Collection ;
rdfs:label "All of the dampers" ;
brick:hasPart :dmp1, :dmp2 .
rec:includes :dmp1, :dmp2 .
```

```{note}
`brick:Collection` was deprecated in Brick v1.5.0 in favor of `rec:Collection` to remove redundancy between the two ontologies.
```
4 changes: 2 additions & 2 deletions modeling/connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ We can also augment this model with connection points which are the physical loc
@prefix : <urn:duct_example/> .

<urn:duct_example> a owl:Ontology ;
owl:imports <https://brickschema.org/schema/1.4/Brick>,
owl:imports <https://brickschema.org/schema/1.5/Brick>,
<https://brickschema.org/extension/s223extension> .

:saf1 a brick:Supply_Air_Flow_Sensor ;
Expand Down Expand Up @@ -151,7 +151,7 @@ Notice that we can attach water as well as air connection points to the VAV, and


<urn:rvav_example> a owl:Ontology ;
owl:imports <https://brickschema.org/schema/1.4/Brick>,
owl:imports <https://brickschema.org/schema/1.5/Brick>,
<https://brickschema.org/extension/s223extension> .

# define the VAV with air and water connection points
Expand Down
129 changes: 129 additions & 0 deletions modeling/controllers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
---
jupytext:
formats: md:myst
text_representation:
extension: .md
format_name: myst
kernelspec:
display_name: Python 3
language: python
name: python3
---

Controllers
===========

```{note}
`brick:Controller`, `brick:controls`/`brick:isControlledBy`, and `brick:hosts`/`brick:isHostedBy` are new in Brick v1.5.
```

A **Controller** is a piece of ICT equipment that supervises and commands one or more physical equipment instances and exposes the points used to do so.
Brick provides two relationship pairs for modeling controllers:

- `brick:controls` / `brick:isControlledBy` — links a Controller to the Equipment it supervises.
- `brick:hosts` / `brick:isHostedBy` — links a Controller (or any ICT Equipment) to the Points it exposes on the network.

These relationships are distinct from `brick:hasPoint`, which expresses that a point *describes* a piece of equipment, regardless of which device exposes it.

## Relationships

`brick:controls`: the *subject* (a `brick:Controller`) commands the *object* (a `brick:Equipment` instance).

`brick:hosts`: the *subject* (a `brick:ICT_Equipment` or `brick:Controller`) exposes the *object* (a `brick:Point`) on the network. This is the physical/logical hosting relationship — the device through which the point is accessed.

A point may be hosted by a controller (`brick:hosts`) and also described as belonging to an equipment (`brick:hasPoint` / `brick:isPointOf`). These two relationships are independent.

## Example: VAV Controller

```turtle
@prefix bldg: <http://example.com/controller#> .
@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix rec: <https://w3id.org/rec#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

bldg:Controller_1 a brick:Controller ;
rdfs:label "Main Building Controller" ;
brick:controls bldg:VAV1 ;
brick:hosts bldg:VAV1_Temperature_Sensor,
bldg:VAV1_Occupancy_Sensor .

bldg:VAV1 a brick:Variable_Air_Volume_Box ;
rdfs:label "VAV1" ;
brick:hasPoint bldg:VAV1_Temperature_Sensor,
bldg:VAV1_Occupancy_Sensor ;
brick:feeds bldg:Zone1 .

bldg:VAV1_Temperature_Sensor a brick:Temperature_Sensor .
bldg:VAV1_Occupancy_Sensor a brick:Occupancy_Sensor .

bldg:Zone1 a rec:HVACZone ;
rdfs:label "Zone 1" .
```

Here `brick:controls` captures the supervisory relationship and `brick:hosts` captures which device exposes the points on the network.
`brick:hasPoint` remains on the VAV to express that those points describe the VAV — not the controller.

## Combining Controllers with Point Collections

`brick:hosts` and `brick:Point_Collection` serve different purposes and can be used together.
Use `brick:hosts` for the physical/network hosting relationship; use a `brick:Point_Collection` to group points for display, export, or application logic.

```turtle
@prefix bldg: <urn:example/vav#> .
@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix rec: <https://w3id.org/rec#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix unit: <http://qudt.org/vocab/unit/> .

bldg:VAV_1 a brick:Variable_Air_Volume_Box ;
brick:hasPoint bldg:VAV_1_SAF_Sensor .

bldg:Ctrl_1 a brick:Controller ;
brick:controls bldg:VAV_1 ;
brick:hosts bldg:VAV_1_SAF_Sensor .

bldg:VAV_1PointCollection a brick:Point_Collection ;
rdfs:label "VAV 1 Point Collection" ;
rec:includes bldg:VAV_1_SAF_Sensor .

bldg:VAV_1_SAF_Sensor a brick:Supply_Air_Flow_Sensor ;
brick:hasUnit unit:FT3-PER-MIN ;
brick:isPointOf bldg:VAV_1 .
```

The controller hosts the sensor; the Point Collection organizes it for tools. See [Point Collections](point-collections) for more on organizing points into bundles.

## Query Patterns

Find all equipment controlled by a given controller:

```sparql
PREFIX brick: <https://brickschema.org/schema/Brick#>

SELECT ?equipment WHERE {
?controller a/rdfs:subClassOf* brick:Controller ;
brick:controls ?equipment .
}
```

Find which controller hosts a given point:

```sparql
PREFIX brick: <https://brickschema.org/schema/Brick#>

SELECT ?controller WHERE {
?controller brick:hosts :my_point .
}
```

Find all points hosted by controllers in the model, and the equipment those points describe:

```sparql
PREFIX brick: <https://brickschema.org/schema/Brick#>

SELECT ?controller ?point ?equipment WHERE {
?controller a/rdfs:subClassOf* brick:Controller ;
brick:hosts ?point .
?point brick:isPointOf ?equipment .
}
```
4 changes: 2 additions & 2 deletions modeling/meters.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ SELECT ?meter WHERE {

## Associating Meters

Meters can be associated with the entities that they are metering through the `brick:meters` / `brick:isMeteredBy` relationships. These entities can be instances of `brick:Equipment`, `brick:Location` *or* `brick:Collection`.
Meters can be associated with the entities that they are metering through the `brick:meters` / `brick:isMeteredBy` relationships. These entities can be instances of `brick:Equipment`, `brick:Location` *or* `rec:Collection`.

Metering `brick:Equipment`: useful when the Meter is measuring the consumption/production of a single Equipment instance.

Expand All @@ -147,7 +147,7 @@ Metering `brick:Location`s: useful when the Meter is measuring the consumption/p
:camera-2 a brick:Camera .
```

Metering `brick:Collection`s: useful when the Meter is measuring the consumption/production of many entities that are not necessarily grouped by location. Recall that a `brick:Collection` is a named group of entities. This could represent the equipment in a particular air loop, in a particular chilled water system, all of the devices owned by a particular individual, or any other organization.
Metering `rec:Collection`s: useful when the Meter is measuring the consumption/production of many entities that are not necessarily grouped by location. Recall that a `rec:Collection` is a named group of entities. This could represent the equipment in a particular air loop, in a particular chilled water system, all of the devices owned by a particular individual, or any other organization.

```ttl
# pv generation systems and pv_arrays are both collections
Expand Down
29 changes: 2 additions & 27 deletions modeling/point-collections.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,34 +198,9 @@ bldg:RoomAirQualitySetpointPreComfort a brick:CO2_Setpoint ;

The top-level HVAC collection identifies the room automation application. Its point-only subcollections make it easy for tools to retrieve the points for each part of the application.

## Example: Controller-Hosted Points
## Controllers and Point Collections

Collections do not replace point hosting. A controller should still use `brick:hostsPoint` for the points it exposes, while Point Collections can organize those points for display or configuration.

```turtle
@prefix bldg: <urn:example/vav#> .
@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix rec: <https://w3id.org/rec#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix unit: <http://qudt.org/vocab/unit/> .

bldg:VAV_1 a brick:Variable_Air_Volume_Box ;
brick:hasPoint bldg:VAV_1_SAF_Sensor .

bldg:Ctrl_1 a brick:Controller ;
brick:controls bldg:VAV_1 ;
brick:hostsPoint bldg:VAV_1_SAF_Sensor .

bldg:VAV_1PointCollection a brick:Point_Collection ;
rdfs:label "VAV 1 Point Collection" ;
rec:includes bldg:VAV_1_SAF_Sensor .

bldg:VAV_1_SAF_Sensor a brick:Supply_Air_Flow_Sensor ;
brick:hasUnit unit:FT3-PER-MIN ;
brick:isPointOf bldg:VAV_1 .
```

One can nest Point Collections to model more complex setups: `brick:Controller` hosts the individual points and the collection organizes them.
Collections do not replace point hosting. A controller should still use `brick:hosts` for the points it exposes, while Point Collections can organize those points for display or configuration. See [Controllers](controllers) for a full treatment of `brick:controls` and `brick:hosts`.


## Query Patterns
Expand Down
Loading