diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 0000000..8ce62c8 --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,41 @@ +name: Build docs + +on: + push: + tags: + - '*' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: GitHub Tag Name example + run: | + echo "Status: *release* $GITHUB_REF_NAME" > release.md + + - name: Setup Mambaforge + uses: conda-incubator/setup-miniconda@v2 + with: + miniforge-variant: Mambaforge + miniforge-version: latest + activate-environment: bdns + use-mamba: true + + - name: Create environment + run: mamba env update -n bdns -f environment.yml + + - name: Install tinytex + shell: bash -l {0} + run: quarto install tinytex + + - name: Build docs + shell: bash -l {0} + run: quarto render . + + - name: Push docs to gh-pages + uses: JamesIves/github-pages-deploy-action@v4 + with: + branch: gh-pages + folder: _site diff --git a/.gitignore b/.gitignore index aafda3a..264fb52 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ .vscode .idea + +/.quarto/ +/_site/* \ No newline at end of file diff --git a/BDNS_Abbreviations_Register.csv b/BDNS_Abbreviations_Register.csv index 7b8337a..0c1b4de 100644 --- a/BDNS_Abbreviations_Register.csv +++ b/BDNS_Abbreviations_Register.csv @@ -2,10 +2,10 @@ asset_description,asset_abbreviation,dbo_entity_type,ifc_class,ifc_type,can_be_c access control - RFID controller,RFIDC,,IfcController,NOTDEFINED,1 access control - RFID reader,RFIDR,,IfcCommunicationsAppliance,SCANNER,1 access control - access control system,ACS,,IfcDistributionSystem,SECURITY,1 +access control - audio intercom,AIC,,IfcSwitchingDevice,NOTDEFINED,1 access control - biometric reader,BIOR,,IfcCommunicationsAppliance,SCANNER,1 access control - request to exit,RTE,,IfcSwitchingDevice,CONTACTOR,1 access control - video intercom,VIC,,IfcSwitchingDevice,NOTDEFINED,1 -access control - audio intercom,AIC,,IfcSwitchingDevice,NOTDEFINED,1 actuator,ACT,,IfcActuator,NOTDEFINED,1 actuator - frost protection switch,FPSW,,IfcActuator,ELECTRICACTUATOR,1 actuator - motorized window operator,WDO,,IfcActuator,ELECTRICACTUATOR,1 @@ -65,6 +65,7 @@ av equipment - wireless sender,WSEND,,IfcAudioVisualAppliance,NOTDEFINED,1 battery,BATT,ELECTRICAL/BATT,IfcElectricFlowStorageDevice,BATTERY,0 battery - battery trip unit,BTR,ELECTRICAL/BATT,IfcProtectiveDevice,NOTDEFINED,0 battery - electric heater battery,EHB,ELECTRICAL/BATT,IfcElectricFlowStorageDevice,BATTERY,0 +battery - lithium ion cell,BATTLI,,IfcElectricFlowStorageDevice,NOTDEFINED,1 beverage machine - airpot,BVAP,,IfcElectricAppliance,NOTDEFINED,0 beverage machine - chai machine,BVC,,IfcElectricAppliance,NOTDEFINED,0 beverage machine - coffee grinder,BVCFMG,,IfcElectricAppliance,NOTDEFINED,0 @@ -451,7 +452,6 @@ lightning protection - earthing bar,EBA,,IfcDistributionElement,NOTDEFINED,0 lightning protection - earthing clamp,ECL,,IfcFastener,NOTDEFINED,0 lightning protection - earthing rod,ERO,,IfcDistributionElement,NOTDEFINED,0 lightning protection - earthing tape,ETA,,IfcDistributionElement,NOTDEFINED,0 -battery - lithium ion cell,BATTLI,,IfcElectricFlowStorageDevice,NOTDEFINED,1 location services - beacon,LBCN,,IfcCommunicationsAppliance,NOTDEFINED,1 meter,MTR,METERS/MTR,IfcFlowMeter,NOTDEFINED,1 meter - electric branch meter,EBM,METERS/MTR,IfcFlowMeter,NOTDEFINED,1 diff --git a/BDNS_Abbreviations_Register.qmd b/BDNS_Abbreviations_Register.qmd new file mode 100644 index 0000000..7e4dd5a --- /dev/null +++ b/BDNS_Abbreviations_Register.qmd @@ -0,0 +1,35 @@ +--- +execute: + echo: false +tbl-cap-location: bottom +format: + html: + page-layout: full +toc: false +jupyter: + jupytext: + text_representation: + extension: .qmd + format_name: quarto + format_version: '1.0' + jupytext_version: 1.16.1 + kernelspec: + display_name: Python 3 (ipykernel) + language: python + name: python3 +--- + +# Building Device and Asset Naming Standards initiative + +{{< include release.md >}} + +# Abbreviations Register + +```{python} +import pandas as pd +from itables import init_notebook_mode, show + +init_notebook_mode(all_interactive=True) +df = pd.read_csv("BDNS_Abbreviations_Register.csv") +show(df, buttons=["pageLength", "csvHtml5"], lengthMenu=[20, 50, 100, 500], style="table-layout:auto;width:100%;float:left") +``` diff --git a/BDNS_Governance_model.md b/BDNS_Governance_model.md index d46605a..a3ebe76 100644 --- a/BDNS_Governance_model.md +++ b/BDNS_Governance_model.md @@ -1,9 +1,13 @@ - +--- +format: + html: default + pdf: default +--- # Building Device and Asset Naming Standards initiative -Status: *release 1.1.0* +{{< include release.md >}} -## Governance model +# Governance model ## Background diff --git a/BDNS_Scoping_guidelines_and_principles.md b/BDNS_Scoping_guidelines_and_principles.md index 33647b5..6eb55a3 100644 --- a/BDNS_Scoping_guidelines_and_principles.md +++ b/BDNS_Scoping_guidelines_and_principles.md @@ -1,10 +1,16 @@ +--- +format: + html: default + pdf: default +--- # Building Device and Asset Naming Standards initiative -Status: *release 1.1.0* -## Scoping guidelines and principles +{{< include release.md >}} -# Context and background +# Scoping guidelines and principles + +## Context and background Building data is currently structured in many different ways, with no single standard. Although several attempts have been made to introduce a universal standard, these have not been universally adopted, and have often found to be insufficiently detailed to allow automated acquisition and surfacing of data from device (both input and outputs), into a structured database for use in end user and building operator applications. @@ -12,7 +18,7 @@ The lack of standardised naming and labelling for building devices from design t 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. -# Purpose +## Purpose This project intends to provide an **industry wide naming convention framework** for Information Technology (IT), Mechanical, Electrical and Public Health (MEP), and other Operational Technology (OT) devices and assets within buildings. @@ -35,7 +41,7 @@ There is a number of initiatives around naming and tagging already in the indust The intent is not to replace these standards or create an overarching umbrella standard on top of existing initiatives, but to create a convention that is complementary and can address the correct naming of control system devices and associated maintainable assets (within the framework) from the early design stages through to operation, while ensuring relevance and suitability to all design and operational building stakeholders. -# Scope +## Scope The scope of this project is very focused: to provide an open naming convention and associated specifications for the naming of building control devices and associated items (within the defined framework) within buildings. @@ -58,7 +64,7 @@ The naming standard is applicable to fixed equipment only. Mobile equipment such Components that are part of a device, such as fan coil unit valves and controllers are not considered to be standalone devices, and therefore do not need individual names. Their data points can however be described and named using complementary standards such as [Project Haystack](https://project-haystack.org/), [Brick Schema](https://brickschema.org/) and the [Digital Buildings Ontology](https://github.com/google/digitalbuildings). -# Deliverables +## Deliverables The following documents have been developed as part of the scope: @@ -66,7 +72,7 @@ The following documents have been developed as part of the scope: * A [register of building device and asset type abbreviations](BDNS_Abbreviations_Register.csv) * A [governance model](BDNS_Governance_model.md) for the initiative -# Principles +## Principles The guiding principles for the standard are the following: @@ -80,7 +86,7 @@ Our recommendation is to store data in shared repositories and not standalone sy * Consistency of device identity across phases * Transfer of design parameters from design model to operational models -# Process +## Process The proposed governance principles and change process are documented in the [Building Device and Asset Naming Standard Proposed Governance](https://docs.google.com/document/d/141jJWvlckhQtMX-F310I1KpWGwD7rvurKyeMpwVq_-g/edit#) document. The document includes information on the open licensing of the work being driven by this initiative, communication mechanisms and a process for consensus building. @@ -89,7 +95,7 @@ In practice, the proposed change process will rely on the GitHub platform: * Changes to the syntax can be proposed by submitting an [issue](https://github.com/theodi/BDNS/issues) on the Github platform. Issues will be discussed and resolved on GitHub, and may be discussed additionally through the other communication mechanisms of the group, including mailing-list and semi-regular teleconferences. * Additions to the register can be proposed by submitting a [pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/about-pull-requests) (PR) to the [Github repository](https://github.com/theodi/BDNS). Alternative submission mechanisms (e.g. through a mail address) may be made available if the Github PR mechanisms are deemed too technical. -# Future work +## Future work The intention is for this work to develop further to cover standardisation of naming for maintainable assets, but to exclude the naming of **metadata** and **data points**, which are meant to be named with a complementary standard, as discussed above. diff --git a/BDNS_Specification_naming_syntax.md b/BDNS_Specification_naming_syntax.md index 61b9f39..2cbb926 100644 --- a/BDNS_Specification_naming_syntax.md +++ b/BDNS_Specification_naming_syntax.md @@ -1,6 +1,11 @@ +--- +format: + html: default + pdf: default +--- # Building Device and Asset Naming Standards initiative -Status: *release 1.1.0* +{{< include release.md >}} # Specification for naming syntax diff --git a/BDNS_Specification_naming_syntax.pdf b/BDNS_Specification_naming_syntax.pdf deleted file mode 100644 index 5047f45..0000000 Binary files a/BDNS_Specification_naming_syntax.pdf and /dev/null differ diff --git a/README.md b/README.md index dbc4db2..abcb3bd 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Building Device and Asset Naming Standards initiative -Status: *release 1.1.0* +{{< 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. diff --git a/_quarto.yml b/_quarto.yml new file mode 100644 index 0000000..cd58ac5 --- /dev/null +++ b/_quarto.yml @@ -0,0 +1,24 @@ +project: + type: website + +website: + navbar: + left: + - href: index.qmd + - href: BDNS_Governance_model.md + text: Governance + - href: BDNS_Scoping_guidelines_and_principles.md + text: Scope + - href: BDNS_Specification_naming_syntax.md + text: Naming Specification Syntax + - href: BDNS_Abbreviations_Register.qmd + text: Abbreviations Register + +format: + html: + theme: cosmo + css: styles.css + toc: true + + + diff --git a/environment.yml b/environment.yml new file mode 100644 index 0000000..b207a0d --- /dev/null +++ b/environment.yml @@ -0,0 +1,16 @@ +name: bdns +# channels priority +# see https://bioconda.github.io/ +# conda-forge has highest prioriy +# --------------------------------- +# requirements for building docs +channels: + - defaults + - conda-forge +dependencies: + - python>=3.8 + - jupyter + - quarto + - itables + - pyfiglet + - pandas diff --git a/index.qmd b/index.qmd new file mode 100644 index 0000000..07a921e --- /dev/null +++ b/index.qmd @@ -0,0 +1,5 @@ +--- +title: "BDNS" +--- + +{{< include README.md >}} \ No newline at end of file diff --git a/release.md b/release.md new file mode 100644 index 0000000..3a088fc --- /dev/null +++ b/release.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/styles.css b/styles.css new file mode 100644 index 0000000..2ddf50c --- /dev/null +++ b/styles.css @@ -0,0 +1 @@ +/* css styles */