From b558f7cd06a5b07da1fb35af5ffe9321fe931330 Mon Sep 17 00:00:00 2001 From: Gabe Fierro Date: Thu, 30 Oct 2025 08:56:11 -0600 Subject: [PATCH 1/3] add point groups docs --- _toc.yml | 1 + modeling/point-groups.md | 85 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 modeling/point-groups.md diff --git a/_toc.yml b/_toc.yml index bdc6c3a..238b134 100644 --- a/_toc.yml +++ b/_toc.yml @@ -32,6 +32,7 @@ parts: - file: modeling/collections - file: modeling/connections - file: modeling/meters + - file: modeling/point-groups - file: modeling/terminal-units - caption: Extensions and Alignments chapters: diff --git a/modeling/point-groups.md b/modeling/point-groups.md new file mode 100644 index 0000000..abc5124 --- /dev/null +++ b/modeling/point-groups.md @@ -0,0 +1,85 @@ +Point Groups +============ + +Point Groups are Brick collections that organize sets of related points (and optionally other point groups) so they can be managed as a coherent bundle. They are intentionally lightweight: the membership of a Point Group does **not** imply any functional or causal relationship between its members. Instead, Point Groups serve UI, configuration, and lifecycle tasks such as provisioning a controller, presenting related telemetry to operators, and exchanging configuration packages between software systems. + +## Core Concepts + +- **`brick:Point_Group`** is a subclass of `brick:Collection`. Point Groups can be created whenever you need a named bundle of points. Use `rdfs:label` to provide a human-friendly title such as `"VAV1 Frost Detection Points"`. +- **Membership** is described with `rec:includes`. A Point Group may include: + - individual `brick:Point` instances + - other `brick:Point_Group` instances (nesting lets you build hierarchies such as *Zone Groups → Unit Groups → Individual Points*) +- **Controllers host groups, not raw points.** Controllers relate to Point Groups via `brick:hosts`. This reflects how most BAS controllers exchange and deploy configuration bundles. The inverse relationship is `brick:isHostedBy`. +- **Controllers and equipment.** Controllers interact with the equipment they supervise via `brick:controls` / `brick:isControlledBy`. Controllers can also indicate the zones they are configured to affect through `brick:concerns` / `brick:isConcernedBy`. + +```{important} +Avoid inferring semantics from group membership alone. For example, adding a setpoint and its min/max limits to the same Point Group does *not* mean those limits constrain that setpoint. Model explicit relationships if you need to express functional ties. +``` + +## Modeling Guidelines + +- **Scope and intent:** Use Point Groups for display, configuration exchange, and packaging telemetry. They are not a substitute for equipment, loop, or system modeling. +- **Granularity:** Prefer smaller, task-specific groups (e.g., startup points, alarm points) rather than one monolithic bundle. Nest groups when you need coarse and fine-grained organization. +- **Custom subclasses:** If your organization needs formal semantics, define project-specific subclasses of `brick:Point_Group` (`my:Startup_Point_Group`) and document their intended meaning. Brick itself does not ship a standardized taxonomy. +- **Labeling and metadata:** Provide `rdfs:label` and, when useful, add entity properties (for example a revision number or deployment status) to describe the package. + +## Example: Controller Hosting a Point Group + +```turtle +@prefix bldg: . +@prefix brick: . +@prefix rec: . +@prefix unit: . +@prefix rdfs: . + +bldg:Controller_1 a brick:Controller ; + rdfs:label "Main Building Controller" ; + brick:hosts bldg:VAV1PointGroup ; + brick:controls bldg:VAV1 ; + brick:concerns bldg:Zone1 . + +bldg:VAV1PointGroup a brick:Point_Group ; + rdfs:label "VAV1 Point Group" ; + rec:includes bldg:VAV1_Temperature_Sensor, bldg:VAV1_Occupancy_Sensor . + +bldg:VAV1_Temperature_Sensor a brick:Supply_Air_Temperature_Sensor ; + brick:hasUnit unit:DEG_C . + +bldg:VAV1_Occupancy_Sensor a brick:Occupancy_Sensor . + +bldg:VAV1 a brick:Variable_Air_Volume_Box ; + brick:feeds bldg:Zone1 . + +bldg:Zone1 a rec:HVACZone . +``` + +This pattern scales to larger controllers by nesting Point Groups—for example, `bldg:StartupPoints` and `bldg:DiagnosticsPoints` contained inside `bldg:AHU1PointGroup`, which is hosted by the controller. + +## Query Patterns + +Retrieve all points hosted by a controller (following nested groups): + +```sparql +SELECT ?point WHERE { + ?controller a/rdfs:subClassOf* brick:Controller ; + brick:hosts ?group . + ?group rec:includes+ ?point . + ?point a/rdfs:subClassOf* brick:Point . +} +``` + +Identify the Point Groups associated with a zone of interest: + +```sparql +SELECT DISTINCT ?group WHERE { + ?controller brick:concerns :Zone1 ; + brick:hosts ?group . + ?group a brick:Point_Group . +} +``` + +## Migration Notes + +- Existing models where controllers hosted individual points should introduce Point Groups and shift the `brick:hosts` relationship to target the group. Equipment such as VAV boxes can continue to reference their points through `brick:hasPoint`. +- When exporting configuration to external tools, deliver the Point Group identifiers and their member points. Consuming systems that do not yet understand Point Groups can treat them as named collections of points without additional semantics. +- Future Brick releases may add convenience shapes or inference rules (for example, deriving `brick:hosts` relationships to points). Until then, use property paths (`rec:includes+`) in queries and tooling that need to traverse Point Group hierarchies. From 12256f84bf3c1947811eaac716eaa1fcbc39f1c6 Mon Sep 17 00:00:00 2001 From: Gabe Fierro Date: Fri, 14 Nov 2025 11:16:12 -0700 Subject: [PATCH 2/3] Update Point Groups documentation for clarity Clarify the role of Point Groups in modeling and emphasize their relationship with `brick:hasPoint`. --- modeling/point-groups.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modeling/point-groups.md b/modeling/point-groups.md index abc5124..0f28af6 100644 --- a/modeling/point-groups.md +++ b/modeling/point-groups.md @@ -16,6 +16,8 @@ Point Groups are Brick collections that organize sets of related points (and opt Avoid inferring semantics from group membership alone. For example, adding a setpoint and its min/max limits to the same Point Group does *not* mean those limits constrain that setpoint. Model explicit relationships if you need to express functional ties. ``` +This is *not* a replacement for `brick:hasPoint`! You should still use `brick:hasPoint`/`brick:isPointOf` to relate points to their equipment. This modeling construct focuses on the networking/instrumentation of the system. + ## Modeling Guidelines - **Scope and intent:** Use Point Groups for display, configuration exchange, and packaging telemetry. They are not a substitute for equipment, loop, or system modeling. @@ -80,6 +82,5 @@ SELECT DISTINCT ?group WHERE { ## Migration Notes -- Existing models where controllers hosted individual points should introduce Point Groups and shift the `brick:hosts` relationship to target the group. Equipment such as VAV boxes can continue to reference their points through `brick:hasPoint`. - When exporting configuration to external tools, deliver the Point Group identifiers and their member points. Consuming systems that do not yet understand Point Groups can treat them as named collections of points without additional semantics. - Future Brick releases may add convenience shapes or inference rules (for example, deriving `brick:hosts` relationships to points). Until then, use property paths (`rec:includes+`) in queries and tooling that need to traverse Point Group hierarchies. From 1f17deb47dbeda3f0804fddf0cb79611b14896e9 Mon Sep 17 00:00:00 2001 From: Gabe Fierro Date: Thu, 11 Dec 2025 16:41:22 -0700 Subject: [PATCH 3/3] update --- modeling/point-groups.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/modeling/point-groups.md b/modeling/point-groups.md index abc5124..e79f5d7 100644 --- a/modeling/point-groups.md +++ b/modeling/point-groups.md @@ -1,16 +1,16 @@ Point Groups ============ -Point Groups are Brick collections that organize sets of related points (and optionally other point groups) so they can be managed as a coherent bundle. They are intentionally lightweight: the membership of a Point Group does **not** imply any functional or causal relationship between its members. Instead, Point Groups serve UI, configuration, and lifecycle tasks such as provisioning a controller, presenting related telemetry to operators, and exchanging configuration packages between software systems. +Point Groups are Brick collections that organize sets of related points (and optionally other point groups) so they can be managed as a coherent bundle. They are intentionally lightweight: the membership of a Point Group does **not** imply any functional or causal relationship between its members. Instead, Point Groups serve UI, configuration, and lifecycle tasks such as presenting related telemetry to operators and exchanging configuration packages between software systems. ## Core Concepts - **`brick:Point_Group`** is a subclass of `brick:Collection`. Point Groups can be created whenever you need a named bundle of points. Use `rdfs:label` to provide a human-friendly title such as `"VAV1 Frost Detection Points"`. -- **Membership** is described with `rec:includes`. A Point Group may include: +- **Membership** is described with `brick:hasPart`. A Point Group may include: - individual `brick:Point` instances - other `brick:Point_Group` instances (nesting lets you build hierarchies such as *Zone Groups → Unit Groups → Individual Points*) -- **Controllers host groups, not raw points.** Controllers relate to Point Groups via `brick:hosts`. This reflects how most BAS controllers exchange and deploy configuration bundles. The inverse relationship is `brick:isHostedBy`. -- **Controllers and equipment.** Controllers interact with the equipment they supervise via `brick:controls` / `brick:isControlledBy`. Controllers can also indicate the zones they are configured to affect through `brick:concerns` / `brick:isConcernedBy`. +- **Controllers host points directly.** Controllers relate to points with `brick:hostsPoint` (inverse: `brick:isHostedBy`). Point Groups are optional logical groupings and are *not* what controllers host. +- **Controllers and equipment.** Controllers interact with the equipment they supervise via `brick:controls` / `brick:isControlledBy` ```{important} Avoid inferring semantics from group membership alone. For example, adding a setpoint and its min/max limits to the same Point Group does *not* mean those limits constrain that setpoint. Model explicit relationships if you need to express functional ties. @@ -20,10 +20,10 @@ Avoid inferring semantics from group membership alone. For example, adding a set - **Scope and intent:** Use Point Groups for display, configuration exchange, and packaging telemetry. They are not a substitute for equipment, loop, or system modeling. - **Granularity:** Prefer smaller, task-specific groups (e.g., startup points, alarm points) rather than one monolithic bundle. Nest groups when you need coarse and fine-grained organization. -- **Custom subclasses:** If your organization needs formal semantics, define project-specific subclasses of `brick:Point_Group` (`my:Startup_Point_Group`) and document their intended meaning. Brick itself does not ship a standardized taxonomy. +- **Custom subclasses:** If your organization needs formal semantics, define project-specific subclasses of `brick:Point_Group` (e.g. `my:Startup_Point_Group`) and document their intended meaning. Brick itself does not ship a standardized taxonomy of Point Group types. - **Labeling and metadata:** Provide `rdfs:label` and, when useful, add entity properties (for example a revision number or deployment status) to describe the package. -## Example: Controller Hosting a Point Group +## Example: Controller Hosting Points (with an optional Point Group) ```turtle @prefix bldg: . @@ -34,13 +34,13 @@ Avoid inferring semantics from group membership alone. For example, adding a set bldg:Controller_1 a brick:Controller ; rdfs:label "Main Building Controller" ; - brick:hosts bldg:VAV1PointGroup ; + brick:hostsPoint bldg:VAV1_Temperature_Sensor, bldg:VAV1_Occupancy_Sensor ; brick:controls bldg:VAV1 ; brick:concerns bldg:Zone1 . bldg:VAV1PointGroup a brick:Point_Group ; rdfs:label "VAV1 Point Group" ; - rec:includes bldg:VAV1_Temperature_Sensor, bldg:VAV1_Occupancy_Sensor . + brick:hasPart bldg:VAV1_Temperature_Sensor, bldg:VAV1_Occupancy_Sensor . bldg:VAV1_Temperature_Sensor a brick:Supply_Air_Temperature_Sensor ; brick:hasUnit unit:DEG_C . @@ -53,33 +53,33 @@ bldg:VAV1 a brick:Variable_Air_Volume_Box ; bldg:Zone1 a rec:HVACZone . ``` -This pattern scales to larger controllers by nesting Point Groups—for example, `bldg:StartupPoints` and `bldg:DiagnosticsPoints` contained inside `bldg:AHU1PointGroup`, which is hosted by the controller. +This pattern scales to larger controllers by nesting Point Groups—for example, `bldg:StartupPoints` and `bldg:DiagnosticsPoints` contained inside `bldg:AHU1PointGroup`. The controller still uses `brick:hostsPoint` for the individual points; the groups remain for logical organization. ## Query Patterns -Retrieve all points hosted by a controller (following nested groups): +Retrieve all points hosted by a controller: ```sparql SELECT ?point WHERE { ?controller a/rdfs:subClassOf* brick:Controller ; - brick:hosts ?group . - ?group rec:includes+ ?point . + brick:hostsPoint ?point . ?point a/rdfs:subClassOf* brick:Point . } ``` -Identify the Point Groups associated with a zone of interest: +Identify the Point Groups associated with a zone of interest (for UI organization): ```sparql SELECT DISTINCT ?group WHERE { ?controller brick:concerns :Zone1 ; - brick:hosts ?group . - ?group a brick:Point_Group . + brick:hostsPoint ?point . + ?group brick:hasPart+ ?point ; + a brick:Point_Group . } ``` ## Migration Notes -- Existing models where controllers hosted individual points should introduce Point Groups and shift the `brick:hosts` relationship to target the group. Equipment such as VAV boxes can continue to reference their points through `brick:hasPoint`. -- When exporting configuration to external tools, deliver the Point Group identifiers and their member points. Consuming systems that do not yet understand Point Groups can treat them as named collections of points without additional semantics. -- Future Brick releases may add convenience shapes or inference rules (for example, deriving `brick:hosts` relationships to points). Until then, use property paths (`rec:includes+`) in queries and tooling that need to traverse Point Group hierarchies. +- Existing models where controllers hosted Point Groups should move the hosting relationship to points using `brick:hostsPoint`. Point Groups remain valuable for organization via `brick:hasPart`. +- When exporting configuration to external tools, deliver the hosted points directly and optionally include Point Group definitions for UI or packaging. +- Future Brick releases may add convenience shapes or inference rules to bridge hosted points and group membership; today, treat `hostsPoint` as authoritative for controller–point attachment.