From dfc21831e8e4321f6c4f02c39a4ef12dbc42ee10 Mon Sep 17 00:00:00 2001 From: jgunstone Date: Wed, 18 Sep 2024 15:42:50 +0100 Subject: [PATCH 1/4] line break required to separate list --- BDNS_Governance_model.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/BDNS_Governance_model.md b/BDNS_Governance_model.md index a3ebe76..3797649 100644 --- a/BDNS_Governance_model.md +++ b/BDNS_Governance_model.md @@ -246,7 +246,8 @@ Any change to the register of names will follow the process for [proposing speci The ODI's contribution during Phase 1 (2019/2020) of the project was funded through the Arup-ODI Partnership agreement. -[Arup](https://www.arup.com), [Buildings IoT](https://www.buildingsiot.com/) and [FPC](https://www.fpc-global.com/) worked in 2020 and 2021 as part of agreed Statement of Works funded by Google to undertake the following: +[Arup](https://www.arup.com), [Buildings IoT](https://www.buildingsiot.com/) and [FPC](https://www.fpc-global.com/) worked in 2020 and 2021 as part of agreed Statement of Works funded by Google to undertake the following: + * Facilitate the adoption of a Google internal list of abbreviations into BDNS. * Review, updating and addition of Google project related abbreviations. From 5020472588f9a5058734c70bf4af8604a3f500f4 Mon Sep 17 00:00:00 2001 From: jgunstone Date: Wed, 18 Sep 2024 15:43:25 +0100 Subject: [PATCH 2/4] move contents of readme into index.qmd --- index.qmd | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/index.qmd b/index.qmd index 07a921e..1d6b2a1 100644 --- a/index.qmd +++ b/index.qmd @@ -2,4 +2,59 @@ title: "BDNS" --- -{{< include README.md >}} \ No newline at end of file +# Building Device and Asset Naming Standards initiative + +{{< include release.md >}} + +This repository holds resources for an initiative to improve interoperability in building management, by focusing on standardising naming of building devices and assets. + +Achieving a common standard across building devices’ naming is an important first step towards being able to efficiently collect, analyse and capture data insights from buildings, and thus optimise building performance to reduce the operational cost and environmental impact of managing buildings. + +Longer-term, this sets the groundwork for real industry collaboration - with the potential to create industry-wide benchmarking, and to facilitate trading of buildings between portfolios. + +A naming and labelling standard (complementing other industry initiatives ) will simplify and drive consistency, thus increasing value by unlocking the application of technologies such as machine learning. + +The work of this community group aligns with and complements other initiatives in the industry such as: + +* [IFC](https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/) +* [Uniclass](https://www.thenbs.com/our-tools/uniclass-2015) and [Uniclass2](http://www.cpic.org.uk/uniclass2/) +* [Omniclass](https://www.csiresources.org/standards/omniclass) +* [CIBSE Symbols](https://www.cibse.org/knowledge/digital-knowledge-tools/symbols) +* [UDMI](https://github.com/faucetsdn/udmi) +* [Web of Things](https://www.w3.org/WoT/) +* [HyperCat](https://hypercatiot.github.io/) +* [Project Haystack](https://project-haystack.org/) +* [Brick Schema](https://brickschema.org/) +* [Digital Buildings Ontology](https://github.com/google/digitalbuildings) + +In scope for this work are: +- A [specification for naming syntax](BDNS_Specification_naming_syntax.md) +- A [register of building device type abbreviations](BDNS_Abbreviations_Register.csv) + +The [register of building device type abbreviations](BDNS_Abbreviations_Register.csv) includes the following columns: + +* `asset_description` - a desription of what is named; the description typically includes a category when the level of granularity of the abbreviation is more specific +* `asset_abbreviation` - the BDNS abbreviation itself +* `can_be_connected` - a boolean value that distinguishes between assets that do not include any means of network connectivity and connectable devices +* `dbo_entity_type` - the [Digital Buildings Ontology](https://github.com/google/digitalbuildings) namespace and entity type that can be associated to the BDNS abbreviation; NOTE: while BDNS presupposes that modelers will apply abbreviations consistently based on similar domain expertise, DBO does not; instead, it provides definitions for devices which may have overlapping function or where terms are ambiguous. For example, while a BDNS user may find the distinction between AHU, ACU, and RTU to be meaningful, DBO does consider all of these as classes of AHU (and provides a definition for what an AHU is. +* `ifc_class` - the [IFC](https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/) class that can be associated to the BDNS abbreviation +* `ifc_type` - the specific [IFC](https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/) type associated to the IFC class that can be associated to the BDNS abbreviation + +The comparison columns have the purpose of providing a simple means to correlate the naming of instances with ontology objects that are present in different building services and systems related ontologies, like the [Digital Buildings Ontology](https://github.com/google/digitalbuildings) and [IFC](https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/). + + +## Use + +The device and asset names defined in this standard are meant to be used in the following applications: + +* naming of CAD object instances in drawings +* naming of object instances in BIM models +* naming of control devices in control software (for instance BACnet device names) +* naming of assets in asset management systems +* naming of devices in IoT ingestion systems +* naming of devices and assets in databases +* naming of devices and assets in MQTT topics + +## Note + +The standard is primarily focusing on naming of building control devices, but with its growing usage it also includes a number of maintainable asset names and types. From d4aa44de20ccc6a5bab4ae637fe55652ea676776 Mon Sep 17 00:00:00 2001 From: jgunstone Date: Wed, 18 Sep 2024 15:48:07 +0100 Subject: [PATCH 3/4] add note about past versions and remove version related comment from `##Note ` section (previous commit) --- index.qmd | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/index.qmd b/index.qmd index 1d6b2a1..7efc2cd 100644 --- a/index.qmd +++ b/index.qmd @@ -55,6 +55,15 @@ The device and asset names defined in this standard are meant to be used in the * naming of devices and assets in databases * naming of devices and assets in MQTT topics +## Past Versions + +- Currently we only serve the latest version of the BDNS built website and pdf documents. +- The source markdown files of previous versions can be reviewed by referring to the appropriate Github tag/release. + - e.g. [BDNS=1.2.0](https://github.com/theodi/BDNS/tree/1.2.0) = `https://github.com/theodi/BDNS/tree/1.2.0` for the source files of v1.2.0 + - e.g. [BDNS_Specification_naming_syntax=1.2.0](https://github.com/theodi/BDNS/blob/1.2.0/BDNS_Specification_naming_syntax.md) = `https://github.com/theodi/BDNS/blob/1.2.0/BDNS_Specification_naming_syntax.md` for a specific version of a document +- The `BDNS_Abbreviations_Register.csv` data file can also be retrieved directly from a previous tag/release if you are required to pin to a given version. + - e.g. [BDNS_Abbreviations_Register.csv=1.2.0](https://raw.githubusercontent.com/theodi/BDNS/1.2.0/BDNS_Abbreviations_Register.csv) = `https://raw.githubusercontent.com/theodi/BDNS/1.2.0/BDNS_Abbreviations_Register.csv` + ## Note The standard is primarily focusing on naming of building control devices, but with its growing usage it also includes a number of maintainable asset names and types. From 91c2ba606964edea9f444b57aea1a2bb99fcf06a Mon Sep 17 00:00:00 2001 From: jgunstone Date: Wed, 18 Sep 2024 15:49:45 +0100 Subject: [PATCH 4/4] add new simplified README.md that refers to the built documentation. add developer notes. --- README.md | 71 ++++++++++++++++--------------------------------------- 1 file changed, 21 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index e75f367..b54dffb 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,29 @@ -Access the [latest version of the BDNS specification](https://theodi.github.io/BDNS/) +# BDNS (Building Device Naming Specification) -# Building Device and Asset Naming Standards initiative +This repository contains the source code for the BDNS Specification. -{{< include release.md >}} +Access the [latest version of the BDNS specification](https://theodi.github.io/BDNS/). -This repository holds resources for an initiative to improve interoperability in building management, by focusing on standardising naming of building devices and assets. +Latest versions of pdf's and csv of the BDNS can be taken directly from the [BDNS specification website](https://theodi.github.io/BDNS/) +or directly via these links: -Achieving a common standard across building devices’ naming is an important first step towards being able to efficiently collect, analyse and capture data insights from buildings, and thus optimise building performance to reduce the operational cost and environmental impact of managing buildings. +- [BDNS_Governance_model](https://theodi.github.io/BDNS/BDNS_Governance_model.pdf) +- [BDNS_Scoping_guidelines_and_principles](https://theodi.github.io/BDNS/BDNS_Scoping_guidelines_and_principles.pdf) +- [BDNS_Specification_naming_syntax](https://theodi.github.io/BDNS/BDNS_Specification_naming_syntax.pdf) +- [BDNS_Abbreviations_Register](https://theodi.github.io/BDNS/BDNS_Abbreviations_Register.csv) -Longer-term, this sets the groundwork for real industry collaboration - with the potential to create industry-wide benchmarking, and to facilitate trading of buildings between portfolios. +## Development -A naming and labelling standard (complementing other industry initiatives ) will simplify and drive consistency, thus increasing value by unlocking the application of technologies such as machine learning. +This repo contains the source markdown files which build the published [BDNS specification website](https://theodi.github.io/BDNS/). +The website is built using the [Quarto](https://quarto.org/) publishing system. +To test building the documentation locally: -The work of this community group aligns with and complements other initiatives in the industry such as: +Install [mamba or micromamba](https://mamba.readthedocs.io/en/latest/index.html) then run the commands below line-by-line. -* [IFC](https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/) -* [Uniclass](https://www.thenbs.com/our-tools/uniclass-2015) and [Uniclass2](http://www.cpic.org.uk/uniclass2/) -* [Omniclass](https://www.csiresources.org/standards/omniclass) -* [CIBSE Symbols](https://www.cibse.org/knowledge/digital-knowledge-tools/symbols) -* [UDMI](https://github.com/faucetsdn/udmi) -* [Web of Things](https://www.w3.org/WoT/) -* [HyperCat](https://hypercatiot.github.io/) -* [Project Haystack](https://project-haystack.org/) -* [Brick Schema](https://brickschema.org/) -* [Digital Buildings Ontology](https://github.com/google/digitalbuildings) - -In scope for this work are: -- A [specification for naming syntax](BDNS_Specification_naming_syntax.md) -- A [register of building device type abbreviations](BDNS_Abbreviations_Register.csv) - -The [register of building device type abbreviations](BDNS_Abbreviations_Register.csv) includes the following columns: - -* `asset_description` - a desription of what is named; the description typically includes a category when the level of granularity of the abbreviation is more specific -* `asset_abbreviation` - the BDNS abbreviation itself -* `can_be_connected` - a boolean value that distinguishes between assets that do not include any means of network connectivity and connectable devices -* `dbo_entity_type` - the [Digital Buildings Ontology](https://github.com/google/digitalbuildings) namespace and entity type that can be associated to the BDNS abbreviation; NOTE: while BDNS presupposes that modelers will apply abbreviations consistently based on similar domain expertise, DBO does not; instead, it provides definitions for devices which may have overlapping function or where terms are ambiguous. For example, while a BDNS user may find the distinction between AHU, ACU, and RTU to be meaningful, DBO does consider all of these as classes of AHU (and provides a definition for what an AHU is. -* `ifc_class` - the [IFC](https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/) class that can be associated to the BDNS abbreviation -* `ifc_type` - the specific [IFC](https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/) type associated to the IFC class that can be associated to the BDNS abbreviation - -The comparison columns have the purpose of providing a simple means to correlate the naming of instances with ontology objects that are present in different building services and systems related ontologies, like the [Digital Buildings Ontology](https://github.com/google/digitalbuildings) and [IFC](https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/). - - -## Use - -The device and asset names defined in this standard are meant to be used in the following applications: - -* naming of CAD object instances in drawings -* naming of object instances in BIM models -* naming of control devices in control software (for instance BACnet device names) -* naming of assets in asset management systems -* naming of devices in IoT ingestion systems -* naming of devices and assets in databases -* naming of devices and assets in MQTT topics - -## Note - -At the moment of release 1.1.0, the standard is primarily focusing on naming of building control devices. It also includes a number of maintainable asset names. +```console +git clone https://github.com/theodi/BDNS.git +cd BDNS +mamba env create -f environment.yml +quarto install tinytex # required for generating pdf docs +quarto render . +``` \ No newline at end of file