├── .gitignore ├── LICENSE ├── etc └── build │ └── config.props ├── readme.md └── src ├── build.fan ├── docHaystack ├── build.fan └── doc │ ├── AHUs.fandoc │ ├── ATES.fandoc │ ├── Associations.fandoc │ ├── Auth.fandoc │ ├── ChangeLog.fandoc │ ├── Changes3to4.fandoc │ ├── Choices.fandoc │ ├── Csv.fandoc │ ├── DataCenters.fandoc │ ├── Defs.fandoc │ ├── Devices.fandoc │ ├── Docs.fandoc │ ├── EVSE.fandoc │ ├── ElecPanels.fandoc │ ├── Equips.fandoc │ ├── Filetypes.fandoc │ ├── Filters.fandoc │ ├── HttpApi.fandoc │ ├── Intro.fandoc │ ├── Json.fandoc │ ├── Kinds.fandoc │ ├── License.fandoc │ ├── Meters.fandoc │ ├── Motors.fandoc │ ├── Namespaces.fandoc │ ├── Normalization.fandoc │ ├── Ontology.fandoc │ ├── Ops.fandoc │ ├── Plants.fandoc │ ├── Points.fandoc │ ├── Protos.fandoc │ ├── Rdf.fandoc │ ├── Reflection.fandoc │ ├── Relationships.fandoc │ ├── Sites.fandoc │ ├── Spaces.fandoc │ ├── Subtyping.fandoc │ ├── Synthetics.fandoc │ ├── Systems.fandoc │ ├── TimeZones.fandoc │ ├── Tools.fandoc │ ├── Trio.fandoc │ ├── Units.fandoc │ ├── VAVs.fandoc │ ├── VRF.fandoc │ ├── Weather.fandoc │ ├── Zinc.fandoc │ ├── Zones.fandoc │ ├── ahu-sections.svg │ ├── chilled-water-plant.svg │ ├── evseMultiEnclosureSequentialDcfcExample.svg │ ├── evseOneEnclosureDcfcExample.svg │ ├── evseOneEnclosureOneAcEvsePortExample.svg │ └── index.fog ├── docXeto ├── build.fan └── doc │ ├── Intro.fandoc │ ├── Json.fandoc │ └── index.fog ├── ph ├── build.fan ├── lib │ ├── associations.trio │ ├── entity.trio │ ├── filetypes.trio │ ├── geo.trio │ ├── kinds.trio │ ├── lib.trio │ ├── meta.trio │ ├── misc.trio │ ├── ops.trio │ └── relationships.trio └── notes.txt ├── phIct ├── build.fan └── lib │ ├── dataCenter.trio │ ├── device.trio │ ├── equip.trio │ ├── lib.trio │ ├── misc.trio │ ├── network.trio │ └── protocol.trio ├── phIoT ├── build.fan └── lib │ ├── actuator.trio │ ├── ahu.trio │ ├── airTerminalUnit.trio │ ├── ates.trio │ ├── battery.trio │ ├── boiler.trio │ ├── cav.trio │ ├── chiller.trio │ ├── conduit.trio │ ├── coolingTower.trio │ ├── elec.trio │ ├── equip.trio │ ├── equipFunctions.trio │ ├── evse.trio │ ├── exhaustEquip.trio │ ├── flow.trio │ ├── heatExchanger.trio │ ├── lib.trio │ ├── lighting.trio │ ├── meter.trio │ ├── misc.trio │ ├── motor.trio │ ├── ops.trio │ ├── panel.trio │ ├── plant.trio │ ├── point.trio │ ├── process.trio │ ├── radiantEquip.trio │ ├── site.trio │ ├── space.trio │ ├── state.trio │ ├── substance.trio │ ├── synthetic.trio │ ├── system.trio │ ├── tank.trio │ ├── vav.trio │ ├── verticalTransport.trio │ ├── vrf.trio │ ├── weather.trio │ └── zones.trio └── phScience ├── build.fan └── lib ├── air.trio ├── lib.trio ├── misc.trio ├── phenomenon.trio ├── quantity.trio └── substance.trio /.gitignore: -------------------------------------------------------------------------------- 1 | # ignore files for fan 2 | 3 | Thumbs.db 4 | .DS_Store 5 | fan.props 6 | 7 | /lib/ 8 | -------------------------------------------------------------------------------- /etc/build/config.props: -------------------------------------------------------------------------------- 1 | // 2 | // Config: build 3 | // 4 | // History: 5 | // 18 Mar 2019 Brian Frank Creation 6 | // 7 | 8 | buildVersion=3.9.15 9 | 10 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # Project Haystack Definitions 2 | 3 | Project Haystack is an open source ontology for IoT data. 4 | This repository is used to manage the source code for the 5 | ontology's definitions. 6 | 7 | See the website for more details and how to get involved: 8 | 9 | [https://project-haystack.org/](https://project-haystack.org/) 10 | 11 | 12 | -------------------------------------------------------------------------------- /src/build.fan: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env fan 2 | // 3 | // Copyright (c) 2019, Project-Haystack 4 | // Licensed under the Academic Free License version 3.0 5 | // 6 | // History: 7 | // 16 Jan 2019 Brian Frank Creation 8 | // 9 | 10 | using build 11 | 12 | ** 13 | ** Build ph definition pods 14 | ** 15 | class Build : BuildGroup 16 | { 17 | new make() 18 | { 19 | childrenScripts = 20 | [ 21 | `ph/build.fan`, 22 | `phScience/build.fan`, 23 | `phIoT/build.fan`, 24 | `phIct/build.fan`, 25 | `docHaystack/build.fan`, 26 | //`docXeto/build.fan`, 27 | ] 28 | } 29 | 30 | @Target { help = "Delete entire lib/ directory" } 31 | Void superclean() 32 | { 33 | Delete(this, Env.cur.workDir + `lib/`).run 34 | } 35 | 36 | @Target { help = "Update trio versions from build config" } 37 | Void updateVersion() 38 | { 39 | // files to update 40 | files := File[,] 41 | childrenScripts.each |uri| 42 | { 43 | file := scriptDir.plus(uri.parent.plus(`lib/lib.trio`)) 44 | if (file.exists) files.add(file) 45 | } 46 | 47 | // update each one 48 | version := Version(config("buildVersion", "0")).toStr 49 | files.each |file| 50 | { 51 | echo("Update $file [$version]") 52 | src := file.readAllStr 53 | s := src.index("\"3.9.") 54 | e := src.index("\"", s+1) 55 | src = src[0.. `airRef` 16 | - airCooled => `airCooling` 17 | - chilledWaterCool => `chilledWaterCooling` 18 | - chilledWaterPlant => `chilled-water-plant` 19 | - chilledWaterPlantRef => `chilledWaterRef` 20 | - closedLoop => `condenserClosedLoop` 21 | - co => `co` `concentration` 22 | - co2 => `co2` `concentration` 23 | - constantVolume => `constantAirVolume` 24 | - coolOnly => `coolingOnly` 25 | - dew => `dewPoint` 26 | - dxCool => `dxCooling` 27 | - elecHeat => `elecHeating` 28 | - elecMeterLoad => `elecRef` 29 | - elecMeterRef => `elecRef` 30 | - elecPanel => `elec-panel` 31 | - elecPanelOf => `elecRef` 32 | - elecReheat => `reheat` `elecHeating` 33 | - gasHeat => `naturalGasHeating` 34 | - gasMeterLoad => `naturalGasRef` 35 | - hisInterpolate => `hisMode` 36 | - hotWaterHeat => `hotWaterHeating` 37 | - hotWaterPlant => `hot-water-plant` 38 | - hotWaterPlantRef => `hotWaterRef` 39 | - hotWaterReheat => `hotWaterHeating` 40 | - lights => `light-level` 41 | - lightLevel => `illuminance` 42 | - lightsGroup => `lighting-zone-space` or `luminaire` 43 | - mag => `magnitude` 44 | - max => `maxVal` 45 | - min => `minVal` 46 | - occupancyIndicator => `occupancy` 47 | - oil => `fuelOil` 48 | - openLoop => `condenserOpenLoop` 49 | - rooftop => `rtu` 50 | - screw => `rotaryScrew` 51 | - sitePanel => `elecRef` 52 | - steamHeat => `steamHeating` 53 | - steamMeterLoad => `steamRef` 54 | - steamPlant => `steam-plant` 55 | - steamPlantRef => `steamRef` 56 | - subPanelOf => `elecRef` 57 | - sunrise => `daytime` 58 | - uv => `unitVent` 59 | - variableVolume => `variableAirVolume` 60 | - vavMode => `hvacMode` 61 | - waterCooled => `waterCooling` 62 | - waterMeterLoad => 'xxxWaterRef' such as `chilledWaterRef` 63 | - weather => [see weather]`#weather` 64 | - weatherRef => [see weather]`#weather` 65 | - weatherPoint => [see weather]`#weather` 66 | 67 | These tags are not ported: 68 | 69 | - connection => [see networks]`#networks` 70 | - device1Ref => [see networks]`#networks` 71 | - device2Ref => [see networks]`#networks` 72 | - reheating => was only used by one VAV max flow sp 73 | 74 | Weather [#weather] 75 | ****************** 76 | In Haystack 3, weather stations were modeled via the 'weather' tag, and 77 | their points were modeled via the 'weatherPoint' tag. In Haystack 4, we 78 | use the `weather` marker on the points as the `pointSubject`. And stations 79 | are modeled via the `weatherStation` tag. Likewise, the 'weatherRef' tag 80 | is now renamed to 'weatherStationRef'. 81 | 82 | Weather points are mapped from Haystack 3 to Haystack 4 as follows: 83 | 84 | Haystack 3 Haystack 4 Notes 85 | ------------------- -------------------- ------------------------ 86 | weatherCond weatherCond same 87 | air temp air temp same 88 | wetBulb temp air wetBulb pair with air not temp 89 | apparent temp air feelsLike renamed, pair with air not temp 90 | dew temp air dewPoint pair with air not temp 91 | humidity air humidity pair with air 92 | barometric pressure atmospheric pressure renamed 93 | sunrise daytime renamed 94 | precipitation precipitation same 95 | cloudage cloudage same 96 | solar irradiance solar irradiance same 97 | wind direction wind direction same 98 | wind speed wind speed same 99 | visibility visibility same 100 | 101 | See `weatherStation` children section for full list of points. 102 | 103 | Lighting [#lighting] 104 | ******************** 105 | Most tags related to lighting have not been included pending the work 106 | under [WG 705]`https://project-haystack.org/forum/topic/705` 107 | 108 | Networks [#networks] 109 | ******************** 110 | Haystack 3 included a prototype for modeling networks, devices, and 111 | connections between them. It was never implemented by any vendors and 112 | was not complete, so it has not been ported to Haystack 4. However, some 113 | of the core concepts are found in the 'phIct' library including: 114 | - `network` 115 | - `device` 116 | - `protocol` 117 | 118 | Symbols [#symbols] 119 | ****************** 120 | Symbol is added as a new scalar type in Haystack 4. In Zinc, it is represented 121 | as '^name' and in JSON with the "y:" prefix. The format version was left 122 | as "3.0" to minimize ecosystem disruption since symbols are only used with 123 | defs and unlikely to occur in normal Haystack data. 124 | 125 | 126 | 127 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Choices.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Choices 3 | ** author: Brian Frank 4 | ** created: 17 Sep 2019 5 | ** copyright: Copyright (c) 2019, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | Choices define exclusive relationship between a set of marker tags. For 11 | example, `ductSection` is an exclusive choice - you choose one option 12 | such as `discharge` or `return`. But you cannot use `discharge` 13 | and `return` together. 14 | 15 | Many common concepts in our ontology fit this pattern: 16 | - `pointFunction` 17 | - `coolingProcess` 18 | - `heatingProcess` 19 | - `ductSection` 20 | - `pipeFluid` 21 | - `pipeSection` 22 | 23 | Definition [#definition] 24 | ************************ 25 | Choices are defined as a subtype of `choice` (which is itself a subtype 26 | of `marker`). They are registered on a given entity using `tagOn`. For 27 | example, the `pointFunction` choice identifies a point as `sensor`, `cmd`, 28 | or `sp`. The definition looks like this: 29 | 30 | def: ^pointFunction 31 | is: ^choice 32 | tagOn: ^point 33 | --- 34 | def: ^sensor 35 | is: ^pointFunction 36 | --- 37 | def: ^cmd 38 | is: ^pointFunction 39 | --- 40 | def: ^sp 41 | is: ^pointFunction 42 | 43 | In the code above, pointFunction subtypes choice. Then the exclusive 44 | set of choices are subtypes of pointFunction. This informs us that 45 | when configuring a point, you should choose exactly one marker between 46 | the three choices of sensor, cmd, and sp. 47 | 48 | Of Choices [#ofChoices] 49 | *********************** 50 | There are some situations, where we wish the choice to reuse an existing 51 | taxonomy tree where subtyping does not make sense. For example, the 52 | `pipeFluid` choice defines that we should annotate a `pipe` with the type 53 | of `fluid` it conveys. In this situation, it would be awkward to have fluid 54 | subtype pipeFluid. Instead we can define the choice to use an arbitrary 55 | set of subtypes using the `of` tag. Here is what the definition of pipeFluid 56 | looks like: 57 | 58 | def: ^pipeFluid 59 | is: ^choice 60 | of: ^fluid 61 | tagOn: [^pipe, ^valve-actuator, ^pump-motor] 62 | 63 | This definition informs us that when creating a pipe, valve, or pump that 64 | we should select exactly one subtype of `fluid` to model the working fluid. 65 | 66 | A given choice must use only one of these mechanisms. If the choice defines 67 | the 'of' tag, then the referent defines the choice options (and the choice 68 | must have no subtypes). If the 'of' tag is not defined, then it is assumed 69 | that the choice subtypes define the options. -------------------------------------------------------------------------------- /src/docHaystack/doc/Csv.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: CSV 3 | ** author: Brian Frank 4 | ** created: 16 Apr 2011 5 | ** copyright: Copyright (c) 2015, Project-Haystack 6 | ** license: Licensed under the Academic Free License version 3.0 7 | ************************************************************************** 8 | 9 | Overview [#overview] 10 | ******************** 11 | CSV stands for comma separated values. It is a plain text format 12 | commonly used for serialization of tabular data. It is specified in 13 | [RFC 4180]`http://tools.ietf.org/html/rfc4180`. CSV provides a simple 14 | way to get tabular data into other applications such as Excel. 15 | 16 | CSV is represented by the def `filetype:csv`. 17 | 18 | Grid Format [#grid] 19 | ******************* 20 | Haystack defines a standard mapping of grids into CSV, which is used 21 | by the [HTTP API]`HttpApi`. Due to its simplicity, CSV does not provide full 22 | fidelity with the Haystack grid model -- metadata and type information 23 | is discarded. 24 | 25 | The Grid to CSV mapping is as follows: 26 | - First row is the column display names (programmatic names 27 | and meta is discarded) 28 | - Subsequent rows map to rows from the Grid 29 | - Marker cells are encoded as the Unicode checkmark 30 | code point U+2713 31 | - Null cells are encoded as the empty string 32 | - Ref cells are encoded as "@id dis", for example "@3ef7 Site-1" 33 | - Bools are encoded as "true" or "false" 34 | - Strs and Uris are encoded using their unescaped value 35 | - Everything else is encoded using its `Zinc` encoding 36 | 37 | Example: 38 | 39 | // Zinc 40 | ver:"3.0" projName:"test" 41 | dis "Equip Name",equip,siteRef,installed 42 | "RTU-1",M,@153c600e-699a1886 "HQ",2005-06-01 43 | "RTU-2",M,@153c600e-699a1886 "HQ",1999-07-12 44 | 45 | // CSV 46 | Equip Name,equip,siteRef,installed 47 | RTU-1,✓,@153c600e-699a1886 HQ,2005-06-01 48 | RTU-2,✓,@153c600e-699a1886 HQ,1999-07-12 49 | 50 | -------------------------------------------------------------------------------- /src/docHaystack/doc/DataCenters.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Data Centers 3 | ** author: Brian Frank 4 | ** created: 14 Apr 2021 5 | ** copyright: Copyright (c) 2021, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | Haystack defines the fundamentals for modeling data centers via the `dataCenter` 11 | and `rack` tags. Data centers are considered a specialized type of `space`. 12 | Equipment and devices contained within the data center define their relationship 13 | to the data center via the `spaceRef` tag. 14 | 15 | Racks [#racks] 16 | ******************** 17 | Racks are modeled as specialized `equip` with the `rack` marker tag. The 18 | servers and networking gear contained by the rack declare their containment 19 | relationship via the `equipRef` tag. 20 | 21 | Examples [#examples] 22 | ******************** 23 | Here is a simple example for a data center containing one rack that contains 24 | one server: 25 | 26 | id: @dc 27 | dis: "Simple Data Center" 28 | dataCenter 29 | space 30 | siteRef: @site 31 | 32 | id: @rack1 33 | dis: "Rack-1" 34 | rack 35 | equip 36 | spaceRef: @dc 37 | siteRef: @site 38 | 39 | id: @server-1A 40 | dis: "Rack-1 Server-A" 41 | server 42 | computer 43 | device 44 | rackRef: @rack1 45 | spaceRef: @dc 46 | siteRef: @site 47 | 48 | 49 | 50 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Devices.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Devices 3 | ** author: Brian Frank 4 | ** created: 13 Apr 2021 5 | ** copyright: Copyright (c) 2021, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | We use the term *device* to describe any asset that is microprocessor based. 11 | Typically, this includes most IT and networking gear, but also includes 12 | microprocessor based controllers commonly used to perform control and monitoring 13 | of equipment. 14 | 15 | There can often be a fuzzy distinction between equipment versus devices, 16 | especially since most point data for an equipment is manifested through a 17 | controller. However when building a detailed model of a control system, 18 | use an `equip` entity to represent the physical asset and use a separate `device` 19 | entity to represent the controller. In cases where the distinction is 20 | not clear, then combine the `equip` and `device` tags into one entity. 21 | 22 | Networks [#networks] 23 | ******************** 24 | Networks are modeled with the `network` tag. Devices on a network should 25 | model their network relationship with the `networkRef` tag. 26 | 27 | Devices where the main function is networking should subtype from 28 | the `networking-device` conjuct. Haystack defines the following networking 29 | device types: 30 | 31 | - `networking-router`: device used to route data between different networks 32 | - `networking-switch`: device used to connect devices on the same network 33 | 34 | Here is a simple example of a network model that includes a switch 35 | with two controllers: 36 | 37 | id: @my-network 38 | dis: "Simple Local Network" 39 | network 40 | 41 | id: @my-switch 42 | dis: "Network Switch" 43 | networking 44 | switch 45 | device 46 | networkRef: @my-network 47 | 48 | id: @my-controller-1 49 | dis: "Controller 1" 50 | controller 51 | device 52 | networkRef: @my-network 53 | 54 | id: @my-controller-2 55 | dis: "Controller 2" 56 | controller 57 | device 58 | networkRef: @my-network 59 | 60 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Docs.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Docs 3 | ** author: Brian Frank 4 | ** copyright: Copyright (c) 2019, Project-Haystack 5 | ** license: Licensed under the Academic Free License version 3.0 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | This chapter provides guidance on how to use the reference documentation. 11 | Each section used in the documentation is described below. 12 | 13 | Index [#index] 14 | ************** 15 | The main index page is composed of the following sections: 16 | 17 | Taxonomies [#taxonomies] 18 | ======================== 19 | This section lists key terms with a link to an index of the term's 20 | subtype tree. You can add new terms into this section with the `docTaxonomy` 21 | tag. 22 | 23 | Listings [#listings] 24 | ===================== 25 | This section contains links to miscellaneous listing pages including: 26 | - 'tags': all terms composed of an atomic name 27 | - 'conjuncts': all terms composed of multiple tags 28 | - 'libs': listing of library modules 29 | - 'filetypes': listing of Haystack filetype encodings 30 | 31 | Tags [#tags-index] 32 | ================== 33 | Section within a lib index that lists the terms defined by the lib 34 | module (both atomic tags and conjuncts). 35 | 36 | Manuals [#manuals] 37 | ****************** 38 | Manuals are hand written documents that provide design details 39 | to augment the auto-generated reference documentation. Manuals 40 | are composed of chapters that correspond to individual HTML pages. 41 | 42 | A manual index is composed of two sections: 43 | - manual: summary information including name and brief overview 44 | - chapters: index of the manual's chapter pages 45 | 46 | Defs [#defs] 47 | ************ 48 | Each def has its own reference page in the documentation composed 49 | of the following sections: 50 | 51 | Def [#def] 52 | ========== 53 | The 'def' section contains summary information for the definition 54 | including its identifier formatted `doc` description. 55 | 56 | Conjunct [#conjunct] 57 | ==================== 58 | This section is used only for [conjuncts]`Defs#conjuncts`. It 59 | provides a link to the definition of each of the conjunct's parts. 60 | 61 | Meta [#meta] 62 | ============ 63 | The 'meta' section documents the [normalized]`Normalization` 64 | tags for the definition's representation as a dict. Each tag 65 | present in the definition is listed here, although some values such as 66 | the 'doc' or 'enum' may reference another section. 67 | 68 | Usage [#usage] 69 | ============== 70 | This section is used only on entity terms. It lists the required 71 | marker tags that must be applied to a dict to correctly 72 | [implement]`Reflection#implementation` the term. It takes into 73 | account conjuncts and supertypes with the `mandatory` marker. 74 | 75 | Enum [#enum] 76 | ============ 77 | If the definition has the `enum` tag, then this section provides 78 | a listing of the documented enumerations and their summary. 79 | 80 | Supertypes [#supertypes] 81 | ======================== 82 | This section lists the term's [supertypes]`Subtyping`. The supertypes 83 | are organized as an indented tree down from most general to most specific. 84 | The first item is the root type, which is typically `marker` or `val`. The 85 | last item will be the definition's declared supertype matching the `is` tag. 86 | If the term has multiple supertypes, then this tree will have multiple leaves. 87 | 88 | Subtypes [#subtypes] 89 | ==================== 90 | This section lists the term's [subtypes]`Subtyping`. The subtypes 91 | are organized in an indented tree structure. 92 | 93 | Tags [#tags] 94 | ============ 95 | This section lists the value tags associated with the entity via 96 | the `tagOn` association. This section also includes tags that are 97 | registered on the entity's supertypes. 98 | 99 | Children [#children] 100 | ==================== 101 | This section lists children [prototypes]`Protos` that are "contained" by 102 | the given entity type. 103 | 104 | Protos [#protos] 105 | **************** 106 | Prototypes are dict instances that model a predefined collection of tags. 107 | 108 | Proto [#proto] 109 | ============== 110 | The 'proto' section defines the prototypes tags. 111 | 112 | Implements [#implements] 113 | ======================== 114 | The definitions [implemented]`Reflection#implementation` by the prototype. 115 | 116 | -------------------------------------------------------------------------------- /src/docHaystack/doc/ElecPanels.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Elec Panels 3 | ** author: Brian Frank 4 | ** created: 12 Aug 2014 5 | ** copyright: Copyright (c) 2014, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | This chapter covers the modeling of electrical panels, circuits, and 11 | electricity flows. 12 | 13 | Elec Panel [#panels] 14 | *********************** 15 | Electrical panels are modeled by the `elec-panel` conjunct. 16 | 17 | A panel should define the `elecRef` to reference its upstream source. A 18 | site level panel will probably reference the main site meter. Sub-panels 19 | typically reference their parent panel via 'elecRef'. In any case, 20 | the 'elecRef' tag should always reference the most direct upstream source 21 | of electricity. 22 | 23 | Here is an example of a electrical panel directly downstream of the 24 | main site meter: 25 | 26 | id: @main-elec-panel 27 | dis: "Main Elec Panel" 28 | elec 29 | panel 30 | equip 31 | elecRef: @main-meter 32 | siteRef: @site 33 | 34 | Circuit [#circuits] 35 | ******************* 36 | The `circuit` tag models an individual electrical circuit. Circuits are used 37 | to model meta-data about the electrical circuit such as max load, phase, etc. 38 | Circuits also contain the points associated with sensors and breakers. Note 39 | these tags have not yet been formalized by Project Haystack. 40 | 41 | Circuits should reference their source panel via the `elecRef` tag. The panel 42 | is where the circuit's fuse or breaker is located. 43 | 44 | Here is a simple example for an electrical circuit in the panel from above: 45 | 46 | id: @circuit-hallway 47 | dis: "Hallway Electrical Circuit" 48 | circuit 49 | equip 50 | elecRef: @main-elec-panel 51 | siteRef: @site 52 | spaceRef: @hallway 53 | 54 | 55 | 56 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Equips.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Equips 3 | ** author: Brian Frank 4 | ** created: 13 Apr 2021 5 | ** copyright: Copyright (c) 2021, Project-Haystack 6 | ************************************************************************** 7 | 8 | Equips [#equips] 9 | **************** 10 | Equipment assets are modeled with the `equip` marker tag. Equipment is often 11 | a physical asset such as an air handler, boiler, chiller, or meter. However, 12 | equip can also be used to model a logical grouping such as an entire chilled 13 | water plant. 14 | 15 | Tags [#tags] 16 | ************ 17 | Equip entities must define a `siteRef` tag for their parent site. 18 | Additionally, use the `spaceRef` tag if the equipment is contained by a defined 19 | space. It is also typical to nest equipment using containment via the `equipRef` 20 | tag. For example, if a fan is contained by an AHU, then the fan entity should 21 | define an 'equipRef' that references the parent AHU entity. 22 | 23 | Examples [#examples] 24 | ******************** 25 | Here are examples for the proper tagging of equipment: 26 | 27 | // electric meter for a building 28 | id: @site.mainMeter 29 | dis: "Main Elec Meter" 30 | ac 31 | elec 32 | meter 33 | equip 34 | siteMeter 35 | siteRef: @site 36 | spaceRef: @site.utility-closest 37 | 38 | // chilled water plant 39 | id: @site.chillerPlant 40 | dis: "Chiller Plant" 41 | chilled 42 | water 43 | plant 44 | equip 45 | siteRef: @site 46 | 47 | // chiller contained by plant from previous example 48 | id: @site.chiller3 49 | dis: "Chiller-3" 50 | chiller 51 | equip 52 | siteRef: @site 53 | equipRef: @site.chillerPlant 54 | 55 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Filetypes.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Filetypes 3 | ** author: Brian Frank 4 | ** created: 17 Jul 2020 5 | ** copyright: Copyright (c) 2020, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ********************* 10 | Haystack defines several text formats for encoding the fixed set 11 | of standard [data types]`Kinds`. Every file type is mapped to a 12 | `filetype` definition. 13 | 14 | Zinc [#zinc] 15 | ************ 16 | Zinc is a recursive acronym for "Zinc Is Not CSV". It is the original 17 | Haystack format designed to encode CSV with strong typing. Zinc provides 18 | full fidelity to encode all Haystack kinds without loss of typing. It 19 | provides a compact and readable syntax at the expense of requiring a non-trivial 20 | custom parser. Zinc's scalar encodings are also the basis for Trio and JSON. 21 | Zinc is the default format used for the `HttpApi` (although today JSON is 22 | also equally supported and utilized). 23 | 24 | See `Zinc` chapter for further discussion and grammar. 25 | 26 | JSON [#json] 27 | ************ 28 | The JSON format specifies a standardized method for mapping the Haystack 29 | data types to JSON without loss of information. There are two methods 30 | for encoding Haystack types to JSON: 31 | - [Version 4]`Json#v4` - The default JSON encoding for Haystack 32 | - [Version 3]`Json#v3` - The Haystack 3 encoding for JSON. This encoding 33 | is supplanted by the version 4 encoding but still supported for backwards 34 | compatibility. 35 | 36 | See `Json` chapter for further details. 37 | 38 | Trio [#trio] 39 | ************ 40 | Trio is an acronym for Tag Record Input/Output. Trio is derived from 41 | [YAML]`https://en.wikipedia.org/wiki/YAML`. It uses the Zinc encodings 42 | for scalar types to provide full type fidelity. Trio is targeted for use 43 | cases when humans need to hand code Haystack data. For example its the format 44 | used for [defs]`Defs`. Most examples in the documentation are formatted 45 | in Trio. 46 | 47 | Trio is a line oriented format. Dicts are encoded with each tag on its own 48 | line. Dicts are separated by a line of "---". There is also some syntax sugar 49 | for multi-line strings and nested collection data values. 50 | 51 | Trio is not ideal for representing grids because it does not support grid 52 | meta nor column meta. As such, Trio should not typically be used to encode 53 | requests/responses in the `HttpApi`. 54 | 55 | See `Trio` chapter for further details. 56 | 57 | CSV [#csv] 58 | ********** 59 | CSV stands for Comma Separated Values. CSV files are easily imported and 60 | exported from spreadsheets and relational databases. CSV is the inspiration 61 | for Zinc. The main drawback with CSV is that there is essentially only one 62 | collection type (table/grid) and one scalar type (strings). As such CSV 63 | does not provide full fidelity with Haystack kinds. However as a widely 64 | supported open format, we specify a standard mechanism to export Haystack 65 | data to CSV. 66 | 67 | See `Csv` chapter for further details. 68 | 69 | RDF [#rdf] 70 | ********** 71 | Project Haystack specifies a standard export to RDF triples via two different 72 | formats: Turtle and JSON-LD. Both defs and instance data have a standard export 73 | mapping. 74 | 75 | See `Rdf` chapter for details. 76 | 77 | 78 | 79 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Motors.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Motors 3 | ** author: Brian Frank 4 | ** created: 12 Aug 2014 5 | ** copyright: Copyright (c) 2014, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | The `motor` tag is paired with the `equip` tag to model equipment that 11 | operates with an electric motor. Haystack defines the following 12 | standardized motor subtypes: 13 | 14 | - `fan-motor`: fans used to move air 15 | - `pump-motor`: pumps used to move fluid 16 | 17 | Often these motors are driven by a variable frequency drive, or VFD, that 18 | exposes many points. If a motor uses a VFD, then it should also be tagged 19 | with the `vfd` marker. Typically, motors such as fans and pumps are 20 | sub-components of a larger piece of equip that we nest via 21 | the `equipRef` tag. 22 | 23 | Points [#points] 24 | **************** 25 | The standardized points for motor control are: 26 | 27 | - `run` `cmd`: primary on/off command 28 | - `enable` `cmd`: secondary on/off command 29 | - `run` `sensor`: run status sensor 30 | - `enable` `sensor`: enable status sensor 31 | - `alarm` `sensor`: bolean alarm condition 32 | 33 | The primary on/off point of equipment is always modeled with the `run` tag. 34 | Paired with `cmd` it models the on/off command point; paired with `sensor` it 35 | models the run status point. Many VFDs also include a secondary `enable` point 36 | that requires both 'run' and 'enable' to be commanded to true in order for the 37 | equipment to be on. In all cases, 'true' models the *on* state, and 'false' models 38 | the *off* state. 39 | 40 | If the motor is driven by a variable frequency drive, then it should be tagged 41 | with the `vfd` marker. Points related to the drive speed control: 42 | 43 | - [vfd speed]`vfd-speed` `cmd`: speed command as percentage where 0% is off, 100% if full speed 44 | - [vfd freq]`vfd-freq` `cmd`: speed command as a frequency in Hz 45 | - [vfd speed]`vfd-speed` `sensor`: speed status as percentage where 0% is off, 100% if full speed 46 | - [vfd freq]`vfd-freq` `sensor`: speed status as frequency in Hz 47 | 48 | Many VFDs will also provide many of the same points as an electric meter. 49 | Measurements such as electric demand, consumption, voltage, and current 50 | should follow the same conventions as [elec meters]`Meters#elecMeters`. 51 | 52 | Fans [#fans] 53 | ************ 54 | Fans may optionally be defined as either an `equip` or a `point`. If the 55 | fan motor is driven by a VFD, then it is recommended to make the fan a sub-equip. 56 | However in many cases a simple fan in a terminal unit such as a `vav` 57 | is more easily modeled as just a `point`. 58 | 59 | Fan Points [#fanPoints] 60 | ======================= 61 | In simple cases where the fan is just a command and/or feedback sensor, 62 | then it is best to model it as a `point`. 63 | 64 | If annotated as an output with the `cmd` tag, then the point 65 | models the command status of the fan: 66 | - false (off) or true (on) 67 | - variable speed is 0% (off) to 100% (full speed) 68 | 69 | If annotated as an input with the `sensor` tag, then the 70 | point models a sensor used to verify the fan status: 71 | - false indicates no air flow (off) or true indicates successful 72 | airflow (fan is on) 73 | - if numeric, the point is differential pressure across the fan 74 | measured in "inH₂O" or "kPa" 75 | 76 | Fan Equips [#fanEquips] 77 | ======================= 78 | When the fan motor is a VFD, it should be modeled as an `equip` entity 79 | using the standard VFD points described above. If you wish to standardize 80 | modeling all fans as equip, then simple single speed fans should define 81 | their state via a `run` point. 82 | 83 | Example of a VFD fan on an AHU: 84 | 85 | id:@ahu ahu equip 86 | id:@ahu-fan equipRef:@ahu discharge fan vfd motor equip 87 | id:@ahu-fan-run equipRef:@ahu-fan discharge fan run cmd point 88 | id:@ahu-fan-status equipRef:@ahu-fan discharge fan run status point 89 | id:@ahu-fan-speed equipRef:@ahu-fan discharge fan drive speed cmd unit:"%" point 90 | 91 | Note that the fan is modeled as an sub-equip of the AHU via the `equipRef` 92 | tag. The VFD points are defined under the fan itself, however we must 93 | [flatten]`Protos#flattening` the 'discharge' and 'fan' tags into the points. 94 | 95 | Pumps [#pumps] 96 | ************** 97 | Pumps may optionally be defined as either an `equip` or a `point`. If 98 | the pump is a VFD, then it is recommended to make it an equip level entity. 99 | However, if the pump is modeled as a simple on/off point as a component within 100 | a large piece of equipment such as a `boiler`, then it is modeled as just a 101 | `point`. Pumps should follow the same point and equip level modeling 102 | conventions as [fans]`#fans`. 103 | 104 | 105 | 106 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Ontology.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Ontology 3 | ** author: Brian Frank 4 | ** created: 17 Jul 2020 5 | ** copyright: Copyright (c) 2020, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ********************* 10 | Project Haystack's semantic model is structured into three layers: 11 | 12 | - **Vocabulary**: giving our tag names formal definitions as terms 13 | - **Taxonomy**: organizing our terms into a subtype tree 14 | - **Ontology**: modeling more complex relationships between definitions 15 | 16 | Each standardized tag name used by Haystack data has a formal definition 17 | or [def]`Defs`. For example, the `geoCountry` tag must be a string and is 18 | always expected to be a two letter ISO 3166-1 code. [Conjuncts]`Defs#conjuncts` 19 | are terms that are defined by composing two or more marker tags. Conjuncts 20 | are like coining new compound words from existing simple words. For example, 21 | the term we use for measurement of carbon dioxide is the conjunct `co2-concentration`, 22 | which is coined from the individual tags `co2` and `concentration`. The 23 | collection of tag and conjunct definitions form what we call a [controlled 24 | vocabulary]`https://en.wikipedia.org/wiki/Controlled_vocabulary`. 25 | The vocabulary ensures that every term we use is precisely defined. 26 | 27 | All of the terms in the controlled vocabulary are further organized into 28 | a [taxonomy]`https://en.wikipedia.org/wiki/Taxonomy` tree that organizes 29 | terms from most general to most specific via the mechanism of 30 | [subtyping]`Subtyping`. Subtyping is a tool for the classification of 31 | concepts. For example, we say that `co2` is a *subtype* of `gas` 32 | because it is a specific type of gas. 33 | 34 | We classify Project Haystack as a full [ontology]`https://en.wikipedia.org/wiki/Ontology_(information_science)` 35 | because we also define many [relationships]`Associations` between our terms (beyond 36 | the taxonomy classifications). For example, we define the relationships between 37 | [substances]`substance` and the [quantities]`quantity` used to perform 38 | measurements on those substances: we define that `temp` is a `quantityOf` 39 | of physical [substances]`substance`, but that `luminous-flux` is a 40 | quantity of `light`. 41 | 42 | Instance Models [#instanceModels] 43 | **************************************** 44 | The ontology defines the *meta model* which is used to model *concepts*. We 45 | use the term *instance model* when we build a Haystack data model for 46 | specific buildings and systems. One good way to think of instances is as 47 | proper nouns with a unique names and identities. For example, the Empire 48 | State Building is an instance of a site, as opposed to the `site` tag which 49 | models the concept of all buildings. 50 | 51 | Entities [#entities] 52 | ******************** 53 | We use the term *entity* to describe a unique instance in a Haystack model. 54 | Entities model things from the real world like buildings, rooms, equipment, 55 | and sensors. An entity in Haystack is always modeled as a [dict]`Kinds#dict` 56 | (collection of tags). 57 | 58 | The `entity` taxonomy tree defines the fundamental types used to build Haystack 59 | data models. We define how to model the following fundamental entities of the 60 | built environment: 61 | 62 | - [site]`Sites`: single building with its own street address 63 | - [space]`Spaces`: location or zone within a site 64 | - [equip]`Equips`: physical or logical piece of equipment within a site 65 | - [point]`Points`: sensor, actuator or setpoint for an equip 66 | - [weatherStation]`Weather`: weather station observations 67 | - [device]`Devices`: computers, controllers, networking gear 68 | 69 | Each of these entity types is discussed in detail in the following chapters. 70 | 71 | All entities are uniquely identified via the `id` tag. The 'id' tag serves as 72 | the primary key and must be unique within the scope of the entity's dataset. 73 | We use the 'id' tag to cross-reference our relationships between entities. 74 | For example, spaces and equipment contained within a given site will model 75 | their containment relationship via the `siteRef` tag. 76 | 77 | Entities should always be given a `dis` tag that provides a human friendly 78 | name of the entity. A general rule is that display names should be relatively 79 | short (under 40 characters), but also fully descriptive of the entity. 80 | 81 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Plants.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Plants 3 | ** author: Brian Frank 4 | ** created: 22 Apr 2021 5 | ** copyright: Copyright (c) 2021, Project-Haystack 6 | ** license: Licensed under the Academic Free License version 3.0 7 | ************************************************************************** 8 | 9 | Overview [#overview] 10 | ******************** 11 | This chapter covers plants used to produce thermal energy for cooling or 12 | heating. Haystack standardizes the following types of plants: 13 | 14 | - `chilled-water-plant`: produces chilled water for cooling 15 | - `hot-water-plant`: produces hot water for heating 16 | - `steam-plant`: produces steam water 17 | 18 | Typically, these plants supply [AHUs]`AHUs` and [VAVs]`VAVs` for HVAC 19 | applications. But they can also be used for industrial processes. 20 | 21 | We typically use the term *central plant* to describe a plant that 22 | supplies a building or group of buildings. When the plant supplies 23 | a municipality, we use the term *district plant*. However, the Haystack 24 | modeling techniques described here are identical. 25 | 26 | Haystack models an entire plant as a single blackbox `equip` entity. 27 | Equipment within the plant, including heat exchangers, pumps, boilers, 28 | and chillers, are modeled as children of the plant via the `equipRef` tag. 29 | 30 | Chilled Water Plants [#chilledWaterPlants] 31 | ****************************************** 32 | Chilled water plants are modeled as a single black box using the `chilled-water-plant` 33 | conjunct along with the `equip` tag. These plants are composed of 34 | the following types of sub-equipment: 35 | - `chiller` 36 | - `coolingTower` 37 | - `heatExchanger` 38 | - `pump-motor` 39 | - `valve-actuator` 40 | 41 | This diagram shows the salient equipment and fluid flows: 42 | 43 | ![chilled water plant]`chilled-water-plant.svg` 44 | 45 | Hot Water Plants [#hotWaterPlants] 46 | ********************************** 47 | Hot water plants are modeled using the `hot-water-plant` conjunct along 48 | with the `equip` tag. These plants are composed of the following types 49 | of sub-equipment: 50 | - `hot-water-boiler` 51 | - `heatExchanger` 52 | - `pump-motor` 53 | - `valve-actuator` 54 | 55 | Steam Plants [#steamPlants] 56 | ********************************** 57 | Steam plants are modeled using the `steam-plant` conjunct along 58 | with the `equip` tag. These plants are composed of the following types 59 | of sub-equipment: 60 | - `steam-boiler` 61 | - `heatExchanger` 62 | - `pump-motor` 63 | - `valve-actuator` 64 | 65 | Loops [#loops] 66 | ************** 67 | Plants typically maintain a separation between the working fluid within 68 | the plant versus the fluid that supplies thermal energy to the building. 69 | We term the pipework within the central plant the `primaryLoop` and 70 | the pipework from the plant to the building the `secondaryLoop`. These 71 | two loops are connected through [heat exchangers]`heatExchanger`. In 72 | the case of a third loop connected to the second loop through a second 73 | set of heat exchangers we use the term `tertiaryLoop`. 74 | 75 | For example, here is how we would model a heat exchanger with a temperature 76 | sensor on the primary entering pipe and on the secondary leaving pipe: 77 | 78 | id: @hx 79 | dis: "Heat Exchanger" 80 | chilled 81 | water 82 | heatExchanger 83 | equip 84 | equipRef: @plant 85 | siteRef: @site 86 | 87 | id: @primary-temp 88 | dis: "Primary Entering Temp Sensor" 89 | chilled 90 | water 91 | primaryLoop 92 | entering 93 | temp 94 | sensor 95 | point 96 | unit: "°C" 97 | kind: "Number" 98 | equipRef: @hx 99 | siteRef: @site 100 | 101 | id: @secondary-temp 102 | dis: "Secondary Leaving Temp Sensor" 103 | chilled 104 | water 105 | secondaryLoop 106 | leaving 107 | temp 108 | sensor 109 | point 110 | unit: "°C" 111 | kind: "Number" 112 | equipRef: @hx 113 | siteRef: @site 114 | 115 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Protos.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Protos 3 | ** author: Brian Frank 4 | ** created: 17 Sep 2019 5 | ** copyright: Copyright (c) 2019, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | Prototypes, or simply *protos*, are dict templates. A proto is just a 11 | normal dict of name/value pairs along with a special tag expansion mechanism. 12 | 13 | Protos are primarily used to declare typical sub-parts of an entity 14 | via the `children` tag. For example, we use protos to answer questions such 15 | as "what points might be contained by a chiller?" Protos are generated 16 | into Project Haystack documentation. They are also used to power menu options 17 | in vendor tools. 18 | 19 | Format [#format] 20 | **************** 21 | The 'children' tag for an entity is a list of prototype dicts: 22 | 23 | def: ^pipe 24 | children: [ 25 | {valve actuator equip}, 26 | {flow sensor point}, 27 | {temp sensor point}, 28 | ] 29 | 30 | You can see these children protos in the docs for `pipe`. 31 | 32 | Flattening [#flattening] 33 | ************************ 34 | Entities with children protos can specify that specific tags are *flattened* 35 | into their children. For example, Haystack convention dictates that points 36 | within a specific pipe include tags to indicate the pipe section and 37 | the fluid being sensed: 38 | 39 | // parent pipe 40 | steam leaving pipe equip 41 | 42 | // child points 43 | steam leaving valve actuator equip 44 | steam leaving temp sensor point 45 | steam leaving flow sensor point 46 | 47 | This convention makes it easy to query points using tag combinations without 48 | regard to if or how parent pipes are modeled. 49 | 50 | We use the `childrenFlatten` tag to indicate that these tags should be 51 | flattened into their children. In our pipe example: 52 | 53 | def: ^pipe 54 | conveys: ^fluid 55 | childrenFlatten: [^fluid, ^pipeSection] 56 | children: [ 57 | {valve actuator equip}, 58 | {flow point}, 59 | {temp point}, 60 | ] 61 | 62 | Flattening occurs when we are given an instance of a parent pipe and 63 | want to generate the children protos. We walk each symbol in the 64 | childrenFlattens list and, if the parent [implements]`Reflection#reflection` 65 | the def, then it is flattened into each child proto. Lets look at some 66 | concrete examples: 67 | 68 | First, lets look at a parent pipe that implements neither a `fluid` term 69 | nor a `pipeSection` term: 70 | 71 | // parent pipe 72 | pipe equip 73 | 74 | // children protos, no tags to flatten 75 | valve actuator equip 76 | flow point 77 | temp point 78 | 79 | In the following example, the parent pipe implements the `fluid` 80 | subtype of `hot-water` 81 | 82 | // parent pipe 83 | hot water pipe equip 84 | 85 | // children protos include hot-water conjunct 86 | hot water valve actuator equip 87 | hot water flow point 88 | hot water temp point 89 | 90 | In the following example, the parent pipe implements both `fluid` via 91 | the subtype `naturalGas` and also `pipeSection` via the subtype `entering`: 92 | 93 | // parent pipe 94 | leaving naturalGas pipe equip 95 | 96 | // children protos include both leaving and naturalGas 97 | leaving naturalGas valve actuator equip 98 | leaving naturalGas flow point 99 | leaving naturalGas temp point 100 | 101 | This technique becomes a powerful tool to auto-expand tag combinations 102 | when used with equipment containing known children: 103 | 104 | def: ^chiller 105 | children: [ 106 | {chilled water leaving pipe equip}, 107 | {chilled water entering pipe equip}, 108 | {condenser water leaving pipe equip}, 109 | {condenser water entering pipe equip}, 110 | ] 111 | 112 | In the `chiller` example above, it is not necessary to enumerate every 113 | possible combination of chiller point. Rather, we declare that chillers 114 | have four specific pipes. Using indirection, we can then derive the 115 | various points by flattening the generic `pipe` definition. 116 | 117 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Reflection.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Reflection 3 | ** author: Brian Frank 4 | ** created: 25 Mar 2019 5 | ** copyright: Copyright (c) 2019, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | Defs define our meta-model and dicts define our data instances. 11 | Haystack provides a standardized processes to map between 12 | the two: 13 | - *implementation*: mapping defs to a dict using the appropriate tags 14 | - *reflection*: mapping a dict to its effective defs 15 | 16 | We say a dict *implements* a def when the it contains the appropriate 17 | tags. For example if a dict defines the `equip` tag, then the dict 18 | implements the `equip` def. If a dict contains both the `hot` and `water` 19 | tags then the dict implements `hot-water`. 20 | 21 | Reflection is the inverse process. We are given a dict and we compute 22 | the list of effective defs that the it implements. 23 | 24 | Implementation and reflection in Haystack are a flavor of 25 | [structural typing]`https://en.wikipedia.org/wiki/Structural_type_system`. 26 | Dict data never explicitly declares itself of a single class or type. 27 | Instead we use a combination of marker tags to indicate typing information. 28 | We use value tags to indicate an attribute or fact about the data. 29 | 30 | Implementation [#implementation] 31 | ******************************** 32 | The rules for a dict to implement a def are as follows: 33 | 34 | 1. Based on the def type: 35 | a. Tag def: the single tag name is applied 36 | b. Conjunct: each tag within the conjunct is applied 37 | c. Feature keys: are never implemented 38 | 39 | 2. We walk the supertype tree of the def and apply any 40 | tag that is marked as `mandatory` 41 | 42 | Lets look at some examples. 43 | 44 | If we want to apply the `point` def to a dict, then we apply rule 1a. There 45 | are no supertypes marked as 'mandatory,' so we are done. Thus, we apply 46 | only '{point}' to fully implement the `point` def. 47 | 48 | If we wish to apply the `rtu` def, then we apply rule 1a. However, when 49 | we walk the supertype tree, we see that it subtypes from two 'mandatory' 50 | defs: `ahu` and `equip`. Therefore, to implement `rtu` requires adding 51 | all three tags: '{rtu, ahu, equip}'. As a general rule, top-level entity 52 | markers such as `site`, `space`, `equip`, `point` are always required. 53 | This makes it easy to query your tag based data. 54 | 55 | If we wish to apply the `hot-water-plant` def, then we will apply rule 1b. 56 | Additionally, this def subtypes from the mandatory `equip` tag. So we need to 57 | add four tags '{hot, water, plant, equip}'. 58 | 59 | Inheritance [#inheritance] 60 | ************************** 61 | When a dict implements a def, it implicitly implements all of that def's 62 | supertypes. For example if we add the `water` tag to a dict, then we 63 | implicitly implement all of the supertypes of `water`, which include 64 | `liquid`, `fluid`, `substance`, `phenomenon`, and `marker`. We call 65 | this flattened list of supertypes the def's *inheritance*. 66 | 67 | Reflection [#reflection] 68 | ************************ 69 | Reflection is the inverse of implementation. Given a dict, we compute 70 | the defs it implements. Reflection is always done within the context 71 | of a [namespace]`Namespaces` to determine which defs are in scope. 72 | 73 | To reflect a dict to its def, we walk each tag in the dict and 74 | apply the following rules: 75 | 1. Check if the tag name maps to a tag def 76 | 2. If the tag maps to a possible conjunct, then check if 77 | the dict has all the conjunct's tags 78 | 3. Infer the [inheritance]`#inheritance` from all defs reflected 79 | from the previous steps 80 | 81 | Lets follow this process to reflect the following dict: 82 | 83 | id: @hwp, dis: "Hot Water Plant", hot, water, plant, equip 84 | 85 | Step 1 yield: `id`, `dis`, `hot`, `water`, `plant`, `equip` 86 | 87 | Step 2 yields: `hot-water`, `hot-water-plant` 88 | 89 | Step 3 yields: 90 | - from hot-water-plant/equip: `entity`, `marker` 91 | - from id/dis: `ref`, `str`, `scalar`, `val` 92 | 93 | Entity Types [#entityTypes] 94 | *************************** 95 | We use markers extensively in Haystack to indicate typing information. However, 96 | a marker tag is not a *type* per se. In a tagging system, we use tags to 97 | quickly and easily associate data to related terms. Let's examine our 98 | example from above: 99 | 100 | id: @hwp, dis: "Hot Water Plant", hot, water, plant, equip 101 | 102 | This dict implements the term `hot-water`, but we would not say that 103 | the plant "is-a" type of hot-water. Those tags only mean that this data 104 | is related to hot-water. This makes it convenient to query our data for 105 | things related to hot-water, water, or liquid. 106 | 107 | However, we would say that the dict above "is-a" type of `hot-water-plant`. We can 108 | reflect this information because `hot-water-plant` is a subtype of `entity`. 109 | The 'entity' subtype tree models primary typing information. Terms that 110 | subtype from entity must be designed to stand on their own - they cannot be used 111 | in conjuncts. 112 | 113 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Sites.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Sites 3 | ** author: Brian Frank 4 | ** created: 13 Apr 2021 5 | ** copyright: Copyright (c) 2021, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ********************* 10 | A *site* entity models a single facility using the `site` tag. A good rule of 11 | thumb is to model any building with its own street address as its own site. 12 | For example, a campus should be modeled with each building as a site, versus 13 | treating the entire campus as one site. But not all sites are buildings; a 14 | site could be a street light, cell phone tower, etc. 15 | 16 | Tags [#tags] 17 | ************ 18 | Core tags used with sites: 19 | 20 | - `geoAddr`: the geographic free-form address of the site (which might 21 | include other geolocation tags such as `geoCity` or `geoCoord`) 22 | - `tz`: the timezone where the site is located 23 | - `area`: square footage or square meters of the facility. This enables 24 | site normalization by area. 25 | - `weatherStationRef`: associate the site with a weather station to visualize 26 | weather conditions and perform weather based energy normalization 27 | - `yearBuilt`: four digit year in which the building was constructed 28 | 29 | Example [#example] 30 | ****************** 31 | Here is an example of a site entity fully tricked out with geolocation tags: 32 | 33 | id: @whitehouse 34 | dis: "White House" 35 | site 36 | area: 55000ft² 37 | tz: "New_York" 38 | weatherStationRef: @weather.washington 39 | geoAddr: "1600 Pennsylvania Avenue NW, Washington, DC" 40 | geoStreet: "1600 Pennsylvania Ave NW" 41 | geoCity: "Washington D.C." 42 | geoCountry: "US" 43 | geoPostalCode: "20500" 44 | geoCoord: C(38.898, -77.037) 45 | yearBuilt: 1792 46 | 47 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Spaces.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Spaces 3 | ** author: Brian Frank 4 | ** created: 13 Apr 2021 5 | ** copyright: Copyright (c) 2021, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | Spaces are modeled with the `space` marker tag. Spaces include the physical 11 | structure of buildings including [floors]`floor` and [rooms]`room`. Spaces 12 | also encompass logical system-oriented [zones]`zone-space` for HVAC, lighting, 13 | security, smoke/fire, etc. 14 | 15 | Tags [#tags] 16 | ************ 17 | All spaces must define a `siteRef` tag for their parent site. In 18 | addition, when spaces are wholly contained by another space, they should 19 | model that relationship via the `spaceRef` tag. 20 | 21 | Floors [#floors] 22 | **************** 23 | If a building has multiple floors, then each floor should be modeled using 24 | the `floor` and `space` marker tags. Floors are numbered using the `floorNum` 25 | tag using the European convention where the ground floor is always floor zero. 26 | Subterranean floors are numbered using negative numbers. Here are examples 27 | for the proper modeling of floors: 28 | 29 | // ground floor; typically called first floor in the US 30 | id: @site.floor1 31 | dis: "Ground Floor" 32 | ground 33 | floor 34 | space 35 | floorNum: 0 36 | siteRef: @site 37 | 38 | // basement floor 39 | id: @site.basement 40 | dis: "Basement Level 1" 41 | subterranean 42 | floor 43 | space 44 | floorNum: -1 45 | siteRef: @site 46 | 47 | // roofs are modeled as a special floor 48 | id: @site.roof 49 | dis: "Roof level of two story building" 50 | roof 51 | floor 52 | space 53 | floorNum: 2 54 | siteRef: @site 55 | 56 | Zones [#zones] 57 | ************** 58 | Zones are system oriented spaces. Currently we define the following zone 59 | types: 60 | - `hvac-zone-space`: heating/cooling/ventilation zones 61 | - `lighting-zone-space`: lighting zones 62 | 63 | Here is an example of an HVAC zone: 64 | 65 | id: @site.zone3B 66 | dis: "VAV Zone 3-B" 67 | hvac 68 | zone 69 | space 70 | siteRef: @site 71 | spaceRef: @site.floor3 72 | 73 | Zones, and their associated points, are examined in detail in the `Zones` chapter. 74 | 75 | Data Centers [#dataCenters] 76 | *************************** 77 | Data centers are also modeled as a subtype of space. 78 | See the `DataCenters` chapter for details. 79 | 80 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Subtyping.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Subtyping 3 | ** author: Brian Frank 4 | ** created: 25 Mar 2019 5 | ** copyright: Copyright (c) 2019, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ********************* 10 | Defs are organized into a tree structured taxonomy via the `is` tag. 11 | A def is a *subtype* if it defines a subset or narrowing of a broader 12 | term. For example, we say that `water` is a subtype of `liquid` because 13 | it is a specific type of liquid. The converse is that liquid is 14 | a *supertype* of water. 15 | 16 | In the context of natural language, a subtype is a [hyponym]`https://en.wiktionary.org/wiki/hyponym` 17 | and a supertype is a [hypernym]`https://en.wiktionary.org/wiki/hypernym`. 18 | If you have ever played Mad Libs, then subtyping is intuitively like 19 | filling in the blanks. For example if we say that a pipe conveys a *fluid*, 20 | then the term *fluid* encompasses specific types of fluids including water, 21 | steam, gasoline, or fuel oil. 22 | 23 | We can also evaluate subtyping in the context of set theory. If we say that 24 | `elec-meter` is a subtype of `meter`, then we are saying the set of all 25 | things that are elec meters is wholly contained by the set of all meters. 26 | 27 | Subtyping is a powerful knowledge modeling tool. However, remember that 28 | modeling the real world is a messy business. It's impossible to design 29 | a taxonomy that fits all situations. Consider the platypus and its difficulty 30 | to fit into a biological taxonomy. Haystack attempts to define a pragmatic 31 | approach between simplicity and the common use cases. But, you will likely 32 | find use cases that aren't a perfect fit for Haystack's ontology. 33 | 34 | Transitivity [#transitivity] 35 | **************************** 36 | Subtyping is defined to be a transitive relationship. If 'B' is a subtype 37 | of 'A' and 'C' is a subtype of 'B', then it is implied that 'C' is a subtype 38 | of 'A'. A concrete example: `water` is a subtype of `liquid` and `liquid` 39 | is a subtype of `fluid`, therefore `water` is inferred to be a subtype of `fluid`. 40 | 41 | Is Tag [#is] 42 | ************ 43 | Subtyping is declared via the `is` tag on a def. The value of the 'is' 44 | tag is a symbol or list of symbols. Since most defs subtype 45 | from a single def, we typically use just a symbol: 46 | 47 | def: ^water 48 | is: ^liquid 49 | 50 | In cases where multiple supertypes are required, use a list of symbols: 51 | 52 | def: ^site 53 | is: [^entity, ^geoPlace] 54 | 55 | All terms are required to have an 'is' tag with the exception of the *root 56 | terms*, which are `marker`, `val`, and `feature`. [Feature keys]`Defs#keys` 57 | have implied subtyping rules and must not declare an 'is' tag. 58 | 59 | It is invalid to create cyclic subtyping relationships. Subtyping must 60 | result in a strict tree structure. 61 | 62 | Inheritance [#inheritance] 63 | ************************** 64 | Defs are themselves specified as a set of tag name/value pairs. Subtypes 65 | automatically inherit these tags into their own definitions. We call 66 | this process *inheritance*, and it works similar to inheritance in 67 | traditional object-oriented languages. The inheritance process is 68 | discussed in detail under [normalization]`Normalization#inherit`. 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Systems.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Systems 3 | ** author: Mike Melillo 4 | ** created: 30 Jan 2023 5 | ** copyright: Copyright (c) 2023, Project-Haystack 6 | ************************************************************************** 7 | 8 | Systems [#systems] 9 | **************** 10 | Systems are modeled with the `system` marker tag. Systems the logical structure 11 | of buildings meant to group multiple `equip` that serve a similar purpose. 12 | The members of a system do not necessarily have to be in the same physical 13 | `space`. For example, a Chilled Water System may consist of equipment within 14 | the Chilled Water Plant, but also Air Handlers with Chilled Water Coils fed 15 | by that plant. Systems do not represent a physical structure unless also paired 16 | with an `equip` tag (e.g., if `system` is used in conjunction with a 'plant-equip'). 17 | 18 | Tags [#tags] 19 | ************ 20 | System entities should define a 'siteRef' tag for their parent tag. All systems 21 | subtype from `system` and are then kebab cased with other valid tags to create 22 | the conjunct (e.g., `chilled-water-system`). 23 | 24 | It is also valid for systems to define a 'systemRef' tag to describe a sub-system 25 | or primary/secondary relationship. This relationship would imply logical containment, 26 | i.e., all members of a sub-system automatically belong to the referent system as well. 27 | 28 | 29 | Examples [#examples] 30 | ******************** 31 | Here are examples of a properly tagged system and member equipment: 32 | 33 | //chilled water system for a building 34 | id: @chwSys 35 | dis: “Chilled Water System” 36 | chilled 37 | water 38 | system 39 | siteRef: @site 40 | 41 | 42 | //condenser water system for a building 43 | id: @cwSys 44 | dis: “Condenser Water System” 45 | condenser 46 | water 47 | system 48 | siteRef: @site 49 | 50 | 51 | //chilled water plant 52 | id: @chwPlant 53 | dis: “Chilled Water Plant” 54 | chilled 55 | water 56 | plant 57 | equip 58 | siteRef: @site 59 | systemRef: @chwSys 60 | 61 | 62 | //condenser water plant 63 | id: @cwPlant 64 | dis: “Condenser Water Plant” 65 | condenser 66 | water 67 | plant 68 | equip 69 | siteRef: @site 70 | systemRef: @cwSys 71 | 72 | 73 | //water cooled chiller, co-membership in both systems 74 | id: @chiller 75 | dis: “Chiller ##” 76 | chiller 77 | equip 78 | siteRef: @site 79 | systemRef: [@chwSys, @cwSys] 80 | equipRef: @chwPlant 81 | chilledWaterRef: @chwPlant 82 | condenserWaterRef: @cwPlant 83 | 84 | 85 | //heat exchanger, co-membership in both systems 86 | id: @hx 87 | dis: “Heat Exchanger ##” 88 | heatExchanger 89 | equip 90 | siteRef: @site 91 | systemRef: [@chwSys, @cwSys] 92 | equipRef: @chwPlant 93 | chilledWaterRef: @chwPlant 94 | condenserWaterRef: @cwPlant 95 | 96 | 97 | //chilled water pump 98 | id: @chwp 99 | dis: “Chilled Water Pump ##" 100 | chilled 101 | water 102 | pump 103 | motor 104 | equip 105 | siteRef: @site 106 | systemRef: [@chwSys, @cwSys] 107 | equipRef: @chwPlant 108 | chilledWaterRef: @chwPlant 109 | condenserWaterRef: @cwPlant 110 | 111 | 112 | //condenser water pump 113 | id: @chwp 114 | dis: “Chilled Water Pump ##" 115 | chilled 116 | water 117 | pump 118 | motor 119 | equip 120 | siteRef: @site 121 | systemRef: [@chwSys, @cwSys] 122 | equipRef: @chwPlant 123 | chilledWaterRef: @chwPlant 124 | condenserWaterRef: @cwPlant 125 | 126 | -------------------------------------------------------------------------------- /src/docHaystack/doc/TimeZones.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: TimeZones 3 | ** author: Brian Frank 4 | ** created: 22 Feb 2011 5 | ** copyright: Copyright (c) 2015, Project-Haystack 6 | ** license: Licensed under the Academic Free License version 3.0 7 | ************************************************************************** 8 | 9 | Overview [#overview] 10 | ******************** 11 | Time-series data is the foundation for sensor and operational data. 12 | This makes it critical to define a proper, unambiguous representation 13 | of time and timezones. Timezones are identified using the `tz` tag with a city 14 | name from the [zoneinfo database]`http://en.wikipedia.org/wiki/Tz_database` (discussed 15 | below). 16 | 17 | Concepts [#concepts] 18 | ******************** 19 | In Haystack, we use the term timezone to encapsulate two concepts: offset 20 | from UTC and daylight saving time rules. For example, US Eastern Standard 21 | Time is -5hrs from UTC. But between 2am on the second Sunday of March and 2am 22 | on the first Sunday in November is daylight savings time (DST) and is -4hrs 23 | from UTC. 24 | 25 | Because timezones are such a critical aspect of time-series data, Haystack 26 | requires a comprehensive model and database of timezones. Timezones are quite 27 | problematic for computers because they are a political abstraction versus a 28 | scientific abstraction. This means that a given region might change its timezone 29 | rules (either UTC offset of DST rules) over time. For example, in 2007 the US 30 | changed the dates for when DST starts and ends. This means that computing a date 31 | in 2000 uses different rules than 2010 (we call these historical timezones). 32 | 33 | Zoneinfo [#zoneinfo] 34 | ******************** 35 | Luckily, there is a database that keeps track of these rules across regions 36 | and time. Haystack uses the zoneinfo database, which is also used by Unix and 37 | many programming languages. The zoneinfo database uses a convention of naming 38 | timezones as "Continent/City". For example, US Eastern time is canonically 39 | identified as "America/New_York". Since there are no duplicate city names 40 | between continents, the city name also works as a canonical identifier. 41 | 42 | All timezones in Haystack are represented using the city name of an entry 43 | in the zoneinfo database. 44 | 45 | Common TimeZones [#common] 46 | ************************** 47 | Here are some common timezones used in the United States: 48 | - 'New_York': US Eastern Time 49 | - 'Chicago': US Central Time 50 | - 'Denver': US Mountain Time 51 | - 'Los_Angeles': US Pacific Time 52 | - 'Phoenix': Arizona Time (Mountain Time with no DST) 53 | 54 | The list above is by no means comprehensive. You can download the full list 55 | of timezones from [project-haystack.org]`https://project-haystack.org/download#tz` 56 | or visit the [zoneinfo website]`https://www.iana.org/time-zones`. -------------------------------------------------------------------------------- /src/docHaystack/doc/Tools.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Tools 3 | ** author: Brian Frank 4 | ** created: 10 Sep 2021 5 | ** copyright: Copyright (c) 2021, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | This chapter provides guidance to for open source tools available for 11 | to work with Project Haystack data. 12 | 13 | Build from Source [#build] 14 | ************************** 15 | To compile the ontology from source into HTML, Json, Turtle, etc follow 16 | these steps: 17 | 18 | 1. Checkout source from [GitHub]`#github` 19 | 20 | 2. Install [Haxall]`#haxall` 21 | 22 | 3. Run the [defc]`#defc` command line tool to compile the defs 23 | 24 | GitHub [#github] 25 | **************** 26 | All Haystack source material is managed on [GitHub]`https://github.com/Project-Haystack/haystack-defs`. 27 | 28 | If you have [git]`https://git-scm.com/` installed on your machine, you 29 | can clone the Haystack repo to your local machine with this command: 30 | 31 | git clone https://github.com/Project-Haystack/haystack-defs.git 32 | 33 | This will create a 'haystack-defs/' directory under your current working 34 | directory. 35 | 36 | Haxall [#haxall] 37 | **************** 38 | [Haxall]`https://haxall.io` is an open source framework which includes the 39 | reference implementation used to generate the documentation and downloads 40 | found on `https://project-haystack.org/`. It provides several features for 41 | working with Project-Haystack data: 42 | - 'defc' command line tool to compile the ontology from source 43 | - 'hx convert' command line to convert between the different 44 | [file types]`Filetypes` 45 | - Haxall daemon which provides a full runtime to load and explore 46 | haystack data using a functional scripting langauge 47 | 48 | Haxall requires a Java VM to run. So you will need Java installed on your 49 | machine as a prerequisite. To install Haxall download the latest release 50 | from [GitHub]`https://github.com/haxall/haxall/releases`. Releases are 51 | packaged as a zip file you can unzip to your machine. Once installed 52 | you can test using the "bin/hx" Bash script or "bin/hx.bat" Window's batch file 53 | as follows: 54 | 55 | > bin/hx version 56 | 57 | Defc [#defc] 58 | ************ 59 | The 'defc' command line tool is used to compile the ontology from source. 60 | It compiles the source [Trio]`Trio` files one or more of the following 61 | output files: 62 | - html: generate the HTML documentation as found on the website 63 | - csv: output defs as a [CSV]`Csv` file 64 | - zinc: output defs as a [Zinc]`Zinc` file 65 | - trio: output ontology as a [Trio]`Trio` file 66 | - json: output ontology as a [Json]`Json` file 67 | - turtle: output ontology as a [RDF Turtle]`Rdf` file 68 | 69 | To use defc, first install [haxall]`#haxall` and verify its installed as follows 70 | 71 | bin/defc -version 72 | 73 | Run this command to print out command line syntax and examples: 74 | 75 | bin/defc -? 76 | 77 | If you have cloned the haystack git repo, then you can compile it as follows 78 | 79 | // compile ontology to HTML docs 80 | bin/defc haystack-defs/src 81 | 82 | // compile ontology to JSON 83 | bin/defc -output json haystack-defs/src 84 | 85 | // compile ontology to Turtle 86 | bin/defc -output turtle haystack-defs/src 87 | 88 | // compile ontology to JSON and Turtle 89 | bin/defc -output json,turtle haystack-defs/src 90 | 91 | Note that if running defc straight from a source directory, it will not 92 | compile docHaystack to HTML. Compiling the full set of HTML documentation 93 | requires first compiling each library and docHaystack to a pod zip file. 94 | You can do that by ensuring that your haystack-defs directory is under your 95 | Haxall installation: 96 | 97 | // cd to your haxall install directory 98 | cd haxall-3.1.6 99 | 100 | // clone haystack-defs under haxall 101 | git clone https://github.com/Project-Haystack/haystack-defs.git 102 | 103 | // build the defs as pod zip files 104 | bin/fan haystack-defs/src/build.fan 105 | 106 | // run defc with defaults and it will automatically use haystack def pod files 107 | bin/defc -output html 108 | 109 | 110 | 111 | 112 | 113 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Trio.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Trio 3 | ** author: Brian Frank 4 | ** created: 13 Jul 2016 5 | ** copyright: Copyright (c) 2015, Project-Haystack 6 | ** license: Licensed under the Academic Free License version 3.0 7 | ************************************************************************** 8 | 9 | Overview [#overview] 10 | ******************** 11 | Trio stands for "Text Record Input/Output". Trio is a simple plain text 12 | format used for hand authoring Haystack data. It is derived as a semi-subset 13 | of [YAML]`https://en.wikipedia.org/wiki/YAML`. It is the primary format 14 | for authoring the tag definitions on the Project Haystack site itself. 15 | 16 | Trio is represented by the def `filetype:trio`. 17 | 18 | Format [#format] 19 | **************** 20 | Trio uses a simple plain text format designed for easy editing by hand: 21 | 22 | - entities are separated by lines beginning with "-", the lines 23 | can have as many dashes as you want followed by a newline (a 24 | line with just dashes) 25 | 26 | - each entity is defined by one or more tags 27 | 28 | - one line is used per tag formatted as "name:val" 29 | 30 | - if no value is specified, the value is assumed to be Marker 31 | 32 | - the value is encoded using the same grammar as Zinc 33 | 34 | - string values may be left unquoted if they begin with a non-ASCII 35 | Unicode character or contain only the "safe" chars: 'A-Z', 'a-z', 36 | or underbar 37 | 38 | - booleans may be encoded as true/false or Zinc T/F; however 39 | if using nested lists/dicts then you must the Zinc T/F syntax 40 | 41 | - if a newline follows the colon, then the value is an indented 42 | multi-line string terminated by the first non-indented line 43 | 44 | - nested data may be encoded with Zinc or Trio as a multi-line 45 | string prefixed with the string value "Zinc:" or "Trio:" on 46 | the tag line 47 | 48 | - nested lists may be encoded in Zinc as a multi-line string 49 | prefixed with "[" on the tag line; the multi-line string should 50 | be parsed as follows: 1) skip lines starting with "//", 2) strip 51 | newlines, and 3) parse a zinc '' production 52 | 53 | - can use '//' as line comment 54 | 55 | Here is a simple example: 56 | 57 | dis: "Site 1" 58 | site 59 | area: 3702ft² 60 | geoAddr: "100 Main St, Richmond, VA" 61 | geoCoord: C(37.5458,-77.4491) 62 | strTag: OK if unquoted if only safe chars 63 | summary: 64 | This is a string value that spans multiple 65 | lines with two or more space characters 66 | --- 67 | name: "Site 2" 68 | site 69 | summary: 70 | Entities are separated by one more dashes 71 | 72 | Here are examples with nested data values: 73 | 74 | // Zinc 75 | ver:"3.0" 76 | type,val 77 | "list",[1,2,3] 78 | "dict",{dis:"Dict!" foo} 79 | "grid",<< 80 | ver:"2.0" 81 | a,b 82 | 1,2 83 | 3,4 84 | >> 85 | "scalar","simple string" 86 | 87 | // Trio 88 | type:list 89 | val:[1,2,3] 90 | --- 91 | type:dict 92 | val:{ dis:"Dict!" foo} 93 | --- 94 | type:grid 95 | val:Zinc: 96 | ver:"3.0" 97 | b,a 98 | 20,10 99 | 100 | // nested list 101 | def: ^myEquip 102 | children: [ 103 | {fan, motor, equip}, 104 | {damper, actuator, equip}, 105 | ] 106 | 107 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Units.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Units 3 | ** author: Brian Frank 4 | ** created: 26 Feb 2011 5 | ** copyright: Copyright (c) 2015, Project-Haystack 6 | ** license: Licensed under the Academic Free License version 3.0 7 | ************************************************************************** 8 | 9 | Overview [#overview] 10 | ******************** 11 | All number tag values can be annotated with an optional unit. In addition, 12 | it is required to annotate each numeric `point` with the `unit` tag. In 13 | both cases, the unit must be an identifier defined by the standard unit 14 | database. 15 | 16 | Unit System [#unitSystem] 17 | ************************* 18 | As a general principle, all the data associated with a given site should 19 | exclusively use either the SI metric system or the US customary system. 20 | Mixing unit systems within one site will cause serious headaches. 21 | 22 | Database [#database] 23 | ******************** 24 | The unit database used by Project Haystack is managed by the 25 | [Fantom]`http://fantom.org/` open source community as part of the 26 | [sys::Unit]`http://fantom.org/doc/sys/Unit.html` API. 27 | This database was originally based on the [oBIX]`http://en.wikipedia.org/wiki/OBIX` 28 | specification, but has since been expanded to allow multiple aliases to be 29 | used for each unit. 30 | 31 | Each unit of measurement has a full name and zero or more symbols that are 32 | used as aliases for that unit. For example "square_meter" is the full name 33 | and the symbol alias is "m²". Some units might have multiple symbols. For 34 | example, "hour" has the symbols "hr" and "h". Some units like "day" have no 35 | symbols. 36 | 37 | All unit identifiers are limited to the following characters: 38 | - any Unicode char over 128 39 | - ASCII letters 'a' - 'z' and 'A' - 'Z' 40 | - underbar '_' 41 | - division sign '/' 42 | - percent sign '%' 43 | - dollar sign '$' 44 | 45 | By convention, the symbol is the preferred notation. If there are multiple 46 | symbols, then the last symbol defined by the database is the preferred 47 | one. 48 | 49 | Common Units [#common] 50 | ********************** 51 | Below are some commonly used units. You can download the full unit database 52 | from [project-haystack.org]`https://project-haystack.org/download#units` website. 53 | 54 | --- Misc --- 55 | percent, % 56 | 57 | --- Area --- 58 | square_meter, m² 59 | square_foot, ft² 60 | 61 | -- Currency --- 62 | australian_dollar, AUD 63 | british_pound, GBP, £ 64 | canadian_dollar, CAD 65 | chinese_yuan, CNY, 元 66 | euro, EUR, € 67 | us_dollar, USD, $ 68 | 69 | --- Energy --- 70 | kilowatt_hour, kWh 71 | 72 | --- Power --- 73 | kilowatt, kW 74 | 75 | --- Pressure --- 76 | kilopascal, kPa 77 | pounds_per_square_inch, psi 78 | inches_of_water, inH₂O 79 | inches_of_mercury, inHg 80 | 81 | --- Temperature --- 82 | fahrenheit, °F 83 | celsius, °C 84 | 85 | --- Temperature Differential --- 86 | fahrenheit_degrees, Δ°F 87 | celsius_degrees, Δ°C 88 | 89 | --- Time --- 90 | millisecond, ms 91 | second, sec 92 | minute, min 93 | hour, hr, h 94 | day 95 | week, wk 96 | julian_month, mo 97 | year, yr 98 | 99 | --- Volumetric Flow --- 100 | liters_per_second, L/s 101 | cubic_feet_per_minute, cfm 102 | 103 | -------------------------------------------------------------------------------- /src/docHaystack/doc/VAVs.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: VAVs 3 | ** author: Brian Frank 4 | ** created: 26 Feb 2011 5 | ** copyright: Copyright (c) 2011, Project-Haystack 6 | ** license: Licensed under the Academic Free License version 3.0 7 | ************************************************************************** 8 | 9 | Overview [#overview] 10 | ******************** 11 | The `vav` tag is used to model variable air volume terminal units. VAVs 12 | are supplied conditioned air from an [AHU]`AHUs` and use a damper to 13 | modulate the air flow to the zone. Typically VAVs are supplied cool 14 | air at a temperature of around 55°F (13°C). Some VAVs support *reheat* 15 | that allow them to heat this cool air to a warmer temperature. 16 | 17 | A VAV without reheat must be defined with the `coolingOnly` tag. Otherwise, it 18 | must define one of the [heating process]`#heatingProcess` tags. Some reheat 19 | VAVs contain a fan, in which case they should also define the `fanPowered` tag. 20 | 21 | VAVs should define the `airRef` tag to reference their supply AHU. When 22 | there are multiple supply AHUs, then the 'airRef' tag should be a list 23 | of all the upstream AHUs. 24 | 25 | Choices [#tags] 26 | *************** 27 | AHUs define a suite of [choices]`Choices` that should be made on 28 | a per instance basis. 29 | 30 | Heating Process [#heatingProcess] 31 | ================================= 32 | If the VAV provides reheat, then it should add one of the following 33 | `heatingProcess` choices: 34 | - `elecHeating` 35 | - `hotWaterHeating` 36 | - `steamHeating` 37 | 38 | Or if the VAV does not support reheat, then add the `coolingOnly` tag. 39 | 40 | When applicable the heating choice marker should also be paired with 41 | the appropriate flow ref tag. For example, if a VAV uses hot water 42 | for reheat, then it should also define the `hotWaterRef` tag to refer 43 | to its hot water plant. 44 | 45 | Modulation [#vavModulation] 46 | =========================== 47 | One of the following `vavModulation` 48 | markers should be defined: 49 | - `pressureDependent` 50 | - `pressureIndependent` 51 | 52 | vavAirCircuitType [#vavAirCircuit] 53 | =========================== 54 | If the VAV is fan powered, then one of the following `vavAirCircuit` 55 | markers should be defined: 56 | - [parallel]`vav-parallel` 57 | - [series]`vav-series` 58 | 59 | Ductwork [#ductwork] 60 | ==================== 61 | One of the following `ductConfig` markers should be 62 | defined: 63 | - `singleDuct` 64 | - `dualDuct` 65 | 66 | Sections [#sections] 67 | ******************** 68 | We associate points with sections of a VAV using these tags: 69 | - `inlet`: air entering the unit from the AHU 70 | - `discharge`: air exiting the unit to be supplied to the zones 71 | - `zone`: conditioned space associated with the unit 72 | 73 | Since most points are not clearly associated with the inlet or discharge 74 | ducts, we typically omit a section tag for most points. However, any 75 | points that would conflict with the zone points must be 76 | qualified with either 'inlet' or 'discharge'. 77 | 78 | Examples [#examples] 79 | ******************** 80 | The following are examples of fully tagged VAVs: 81 | 82 | // Cooling only VAV 83 | id: @vav 84 | dis: "VAV-Example" 85 | vav 86 | equip 87 | coolingOnly 88 | pressureDependent 89 | singleDuct 90 | airRef: @ahu 91 | siteRef: @site 92 | 93 | // Fan powered VAV with hot water reheat 94 | id: @vav 95 | vav 96 | equip 97 | fanPowered 98 | hotWaterHeating 99 | pressureDependent 100 | singleDuct 101 | hotWaterRef: @hot-water-plant 102 | airRef: @ahu 103 | siteRef: @site 104 | 105 | -------------------------------------------------------------------------------- /src/docHaystack/doc/VRF.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: VRF 3 | ** author: WG 916 4 | ** created: 21 Nov 2022 5 | ** copyright: Copyright (c) 2022, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ********************* 10 | A Variable refrigerant flow, or VRF system, is an HVAC system where 11 | refrigerant is the only coolant material. VRF uses refrigerant as the 12 | cooling and heating catalyst. This refrigerant is conditioned by one or 13 | more outdoor units and is circulated within the building to indoor units. 14 | 15 | Types of VRF systems [#types] 16 | ***************************** 17 | There are three basic types of VRF systems: 18 | 19 | - `vrf-coolingOnly-system`: Cooling only VRF systems can only cool; 20 | heating is not available 21 | 22 | - `vrf-heatPump-system`: Heat pump VRF system can reverse the direction of 23 | the refrigerant flow to provide heating or cooling to the indoor space. 24 | All indoor units connected to a heat pump system can use individual control 25 | and set points, but they operate in the same mode of either heating or cooling 26 | at any given time. 27 | 28 | - `vrf-heatRecovery-system`: Heat recovery units are heat pump systems that 29 | can provide simultaneous heating and cooling. All indoor units connected 30 | to a heat recovery system not only can use individual control and set 31 | points, but they can also individually operate in heating or cooling mode 32 | at any given time. 33 | 34 | VRF Equipment [#equip] 35 | ********************** 36 | VRF system consists of the following equipment: 37 | 38 | - [Outdoor Units]`#outdoorUnits`: Outdoor unit has one or more compressors. 39 | As each indoor unit sends a demand to the outdoor unit, outdoor unit 40 | delivers the amount of refrigerant needed to meet the individual requirements 41 | of each indoor unit. 42 | 43 | - [Refrigerant Plant]`#refrigPlant`: Multiple outdoor units can be connected, 44 | and the refrigerant plant covers all the connected outdoor units. 45 | 46 | - [Branch Selectors]`#branchSelector` : Branch selectors are used for heat 47 | recovery VRF system as control devices directing the liquid refrigerant or 48 | gas refrigerant to zones requiring cooling or heating 49 | 50 | - [Indoor Units]`#indoorUnits`: Indoor units operate to satisfy a heating or 51 | cooling load in a zone based on a zone thermostat temperature set point 52 | 53 | Outdoor Units [#outdoorUnits] 54 | ***************************** 55 | Outdoor units are modeled with the `vrf-outdoorUnit` tags. They can be water or 56 | air cooled. An outdoor unit contains a compressor, circuit board and a heat 57 | exchange coil. In case of air cooled units they also have a propeller fan. 58 | These units are typically situated outside the condtitioned space, and pump 59 | refrigerant to and from its companion indoor units. 60 | 61 | Indoor Units [#indoorUnits] 62 | *************************** 63 | Indoor units are modeled with the `vrf-indoorUnit` tags. Indoor units are 64 | located inside the conditioned space and provide conditioned air to the spacs. 65 | This unit generallycontains a heat exchange coil, filters, remote signal 66 | receiver, and fan. 67 | 68 | Branch Selector [#branchSelector] 69 | ********************************* 70 | Branch selectors are modeled with the `branchSelector` tag. Branch selectors 71 | are used for heat recovery VRF system as control devices directing the liquid 72 | refrigerant or gas refrigerant to zones requiring cooling or heating. 73 | 74 | Refrigerant Plant [#refrigPlant] 75 | ******************************** 76 | Refrigerant plants are modeled with the `vrf-refrig-plant` tags. They 77 | model a group of outdoor units as a single black box. If one VRF system 78 | has multiple outdoor units, refrigerant plants work as heat-source side 79 | for the entire VRF systems, combining multiple outdoor units. These plants 80 | are composed of outdoor units as sub-equipment. 81 | 82 | -------------------------------------------------------------------------------- /src/docHaystack/doc/Weather.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Weather 3 | ** author: Brian Frank 4 | ** created: 13 Apr 2021 5 | ** copyright: Copyright (c) 2021, Project-Haystack 6 | ************************************************************************** 7 | 8 | Overview [#overview] 9 | ******************** 10 | Haystack standardizes the modeling of weather stations and their 11 | associated observations. The stations themselves are modeled using 12 | the `weatherStation` marker tag. The observations are modeled as 13 | normalized [points]`Points` along with the `weather` marker tag. 14 | 15 | Stations [#stations] 16 | ******************** 17 | Weather stations model a geographic location where observations are 18 | taken. Stations might be an official government location; for example in 19 | the US the NOAA provides an extensive database of station locations and their 20 | associated data. Many online weather services are virtual and approximate 21 | data using several physical stations. Or, it is possible to model site 22 | local weather sensors using the Haystack weather model. 23 | 24 | All weather stations must define the `weatherStation` marker tag along 25 | with the appropriate `geoPlace` tags. The `tz` tag must also be defined. 26 | 27 | Here is an example of a weather station entity: 28 | 29 | id: @richmond 30 | dis: "Weather for Richmond VA" 31 | weatherStation 32 | geoCoord: C(37.542979,-77.469092) 33 | geoCity: "Richmond" 34 | geoCountry: "US" 35 | geoState: "VA" 36 | tz: "New_York" 37 | 38 | When a weather station is available for a site, the site should define 39 | the `weatherStationRef` tag to model the relationship. 40 | 41 | Points [#points] 42 | **************** 43 | All weather observation points must define the following tags: 44 | - `weather`: marker to indicate entity is a weather point 45 | - `weatherStationRef`: parent weather station associated with the point 46 | - `sensor`: all observation points are considered sensor points 47 | 48 | Additionally the standard point tags must be defined including `point`, 49 | `kind`, `unit`, and `enum`. 50 | 51 | The following are the standardized weather points that may be defined 52 | for a given station: 53 | 54 | - [air temp]`air-temp`: dry bulb temperature in °C or °F 55 | - `air` `wetBulb`: web bulb temperature in °C or °F 56 | - `air` `feelsLike`: apparent temperature in °C or °F 57 | - `air` `dewPoint`: dew point temperature in °C or °F 58 | - `air` `humidity`: relative humidity in %RH 59 | - `air` `enthalpy`: total heat content in kJ/kg or BTU/lb 60 | - [atmospheric pressure]`atmospheric-pressure`: barometric pressure in 61 | millibar or inHg 62 | - `cloudage`: cloudiness as percentage 63 | - `daytime`: boolean point that is true between sunrise and sunset 64 | - `precipitation`: fallen atmospheric water vapor in mm or in 65 | - [solar irradiance]`solar-irradiance`: energy received from sun in W/m² 66 | - `weatherCond`: enumeration for clear, cloudy, rain, snow, etc 67 | - [wind speed]`wind-speed`: wind speed in km/h or mph 68 | - [wind direction]`wind-direction`: direction that wind originates in degrees 69 | - `visibility`: distance at which light can be discerned in km or mile 70 | 71 | Example of a weather observation point: 72 | 73 | // air temperature with a current value 74 | id: @richmond.temp 75 | dis: "Temperature for Richmond VA" 76 | weather 77 | air 78 | temp 79 | sensor 80 | point 81 | unit: "°F" 82 | kind: "Number" 83 | tz: "New_York" 84 | weatherStationRef: @richmond 85 | cur 86 | curVal: 56°F 87 | curStatus: "ok" 88 | 89 | -------------------------------------------------------------------------------- /src/docHaystack/doc/index.fog: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Index 3 | ** author: Brian Frank 4 | ** created: 22 Mar 2019 5 | ** copyright: Copyright (c) 2019, Project-Haystack 6 | ************************************************************************** 7 | 8 | [ 9 | [`Intro`, "Introduction to Project Haystack"], 10 | 11 | "Data Model", 12 | [`Kinds`, "Data types"], 13 | [`TimeZones`, "Respresentation of timezones"], 14 | [`Units`, "Respresentation of units of measurement"], 15 | [`Filters`, "Predicates for querying Haystack data"], 16 | 17 | "Ontology", 18 | [`Ontology`, "Overview of ontology"], 19 | [`Sites`, "Sites entities"], 20 | [`Systems`, "Systems entities"], 21 | [`Synthetics`, "Synthetic data"], 22 | [`Spaces`, "Space entities including floors, rooms, and zones"], 23 | [`Equips`, "Equipment entities"], 24 | [`Points`, "Point entities - sensors, actuators, and setpoints"], 25 | [`Weather`, "Weather station entities"], 26 | [`Devices`, "Device entities including controllers and networks"], 27 | 28 | "Verticals", 29 | [`Meters`, "Modeling meters"], 30 | [`AHUs`, "Modeling air handling units"], 31 | [`VAVs`, "Modeling variable air volume terminal units"], 32 | [`Zones`, "Modeling zone occupancy, hvac, air quality, lighting"], 33 | [`Plants`, "Modeling central plants"], 34 | [`Motors`, "Modeling fans, pumps, and other motors"], 35 | [`ElecPanels`, "Modeling electrical panels, circuits, and breakers"], 36 | [`EVSE`, "Modeling of Electric Vehicle Supply Equipment (EVSE)"], 37 | [`VRF`, "Modeling variable refrigerant flow systems"], 38 | [`ATES`, "Modeling aquifer thermal energy storage"], 39 | [`DataCenters`, "Modeling data center spaces"], 40 | 41 | "Defs", 42 | [`Defs`, "Definition meta-model"], 43 | [`Namespaces`, "Symbolic namespaces"], 44 | [`Subtyping`, "Definition subtyping"], 45 | [`Reflection`, "Mapping between dicts and defs"], 46 | [`Normalization`, "Normalized dict representation of defs"], 47 | [`Associations`, "Ontological relationships"], 48 | [`Choices`, "Exclusive marker choices"], 49 | [`Relationships`, "Modeling relationships"], 50 | [`Protos`, "Dict prototypes"], 51 | 52 | "Filetype Formats", 53 | [`Filetypes`, "Data encoding formats"], 54 | [`Zinc`, "Zinc plain text format"], 55 | [`Json`, "JSON format"], 56 | [`Trio`, "Tag record I/O format"], 57 | [`Csv`, "Comma separated valus format"], 58 | [`Rdf`, "Resource Description Framework export"], 59 | 60 | "HTTP API", 61 | [`HttpApi`, "Haystack HTTP API"], 62 | [`Ops`, "HTTP API operations"], 63 | [`Auth`, "HTTP API authentication"], 64 | 65 | "Appendix", 66 | [`Tools`, "Tools to work with Haystack data"], 67 | [`Docs`, "Guidance on reference documentation"], 68 | [`ChangeLog`, "Version history"], 69 | [`Changes3to4`, "Notes for upgrading from version 3 to 4"], 70 | [`License`, "Academic Free License 3.0"], 71 | ] 72 | -------------------------------------------------------------------------------- /src/docXeto/build.fan: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env fan 2 | // 3 | // Copyright (c) 2024, Project-Haystack 4 | // Licensed under the Academic Free License version 3.0 5 | // 6 | // History: 7 | // 12 Apr 2024 Brian Frank Creation 8 | // 9 | 10 | using build 11 | 12 | ** 13 | ** Build: docXeto 14 | ** 15 | class Build : BuildPod 16 | { 17 | new make() 18 | { 19 | podName = "docXeto" 20 | summary = "Xeto documentation" 21 | meta = ["org.name": "Project Haystack", 22 | "org.uri": "https://project-haystack.org/", 23 | "proj.name": "Project Haystack Defs", 24 | "license.name": "Academic Free License 3.0", 25 | "vcs.name": "Git", 26 | "vcs.uri": "https://github.com/Project-Haystack/haystack-defs"] 27 | depends = Str[,] 28 | resDirs = [`doc/`] 29 | } 30 | } 31 | 32 | -------------------------------------------------------------------------------- /src/docXeto/doc/Intro.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Introduction 3 | ** author: Brian Frank 4 | ** created: 12 Apr 2024 5 | ** copyright: Copyright (c) 2024, Project-Haystack 6 | ** license: Licensed under the Academic Free License version 3.0 7 | ************************************************************************** 8 | 9 | Overview [#overview] 10 | ******************** 11 | Xeto stands for "eXtensible Explicitly Typed Objects". It is a textual 12 | language used to define data types and typed data. 13 | 14 | -------------------------------------------------------------------------------- /src/docXeto/doc/Json.fandoc: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Json 3 | ** author: Brian Frank 4 | ** created: 12 Apr 2024 5 | ** copyright: Copyright (c) 2024, Project-Haystack 6 | ** license: Licensed under the Academic Free License version 3.0 7 | ************************************************************************** 8 | 9 | Overview [#overview] 10 | ******************** 11 | JSON is widely used as a simple textual data interchange format. Xeto 12 | specs and instance data maybe represented in JSON multiple ways. Plus 13 | Xeto may be used to validate JSON data. There are two primary JSON 14 | representations of Xeto: 15 | 16 | - **typed**: each Xeto object is represented as a JSON object with 17 | an explicit spec property. This format is more verbose but extremely 18 | precise for each object's type and provides full fidelity with the 19 | Xeto format itself. 20 | 21 | - **untyped**: each Xeto object is mapped to its closest native JSON 22 | value type. This format is closer to common usage of JSON. It is 23 | a much simpler, clean representation but with a loss of fidelity since 24 | we must infer the types. 25 | 26 | Instances [#instances] 27 | ********************** 28 | First let's look at the JSON representation of instance data with an example: 29 | 30 | // Xeto 31 | @rogueOne: { 32 | movie 33 | name: "Rogue One" 34 | release: Date "2016-12-10" 35 | runTime: Number "134min" 36 | characters: List { "Jyn Erso", "Cassian Andor" } 37 | } 38 | 39 | // Untyped JSON 40 | { 41 | "id": "test::rogueOne", 42 | "movie": "marker" 43 | "name": "Rogue One", 44 | "release": "2016-12-12", 45 | "runTime": "134min", 46 | "characters": ["Jyn Erso", "Cassian Andor"] 47 | } 48 | 49 | // Typed JSON 50 | { 51 | "spec": "sys::Dict", "val": { 52 | "id: { "spec":"sys::Ref", "val":"test::rogueOne" }, 53 | "movie": { "spec":"sys::Marker", "val":"marker" }, 54 | "name": { "spec":"sys::Str", "val":"Rogue One" }, 55 | "release": { "spec":"sys::Date", "val":"2016-12-12" }, 56 | "runTime": { "spec":"sys::Duration", "val":"134min" }, 57 | "characters": { 58 | "spec":sys::List" 59 | "of: { "spec":"sys::Ref", "val":"sys::Str" } 60 | "val": [ 61 | { "spec":"sys::Str", "val": "Jyn Erso" }, 62 | { "spec":"sys::Str", "val": "Cassian Andor" }, 63 | ] 64 | } 65 | } 66 | } 67 | 68 | The untyped JSON omits the type to create a "clean" JSON representation 69 | where scalars map to JSON strings, dicts map to JSON objects, and lists map 70 | to JSON arrays. The typed JSON is more verbose, but each Xeto value 71 | explicitly declares its type via the 'spec' field. 72 | 73 | Untyped JSON Mapping [#untypedJson] 74 | *********************************** 75 | The following rules are used to map Xeto values to untyped JSON values: 76 | 77 | Xeto JSON Notes 78 | --------- -------- ----------------------------- 79 | sys::None null 80 | sys::Bool Boolean 81 | sys::Number Number Only if no unit is specified 82 | sys::Scalar String Any scalar not listed above using string encoding 83 | sys::List Array 84 | sys::Dict Object 85 | 86 | Typed JSON Mapping [#typedJson] 87 | ******************************* 88 | In this representation every Xeto value is represented by a JSON object with 89 | the following properties: 90 | - 'spec': String with the value's qualified type name 91 | - 'val': JSON untyped mapping using same rules specified above 92 | - 'of': used for additional parameterized typing metadata 93 | 94 | -------------------------------------------------------------------------------- /src/docXeto/doc/index.fog: -------------------------------------------------------------------------------- 1 | ************************************************************************** 2 | ** title: Index 3 | ** author: Brian Frank 4 | ** created: 12 Apr 2024 5 | ** copyright: Copyright (c) 2024, Project-Haystack 6 | ************************************************************************** 7 | 8 | [ 9 | [`Intro`, "Introduction to Xeto"], 10 | [`Json`, "JSON representations"], 11 | ] 12 | 13 | -------------------------------------------------------------------------------- /src/ph/build.fan: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env fan 2 | // 3 | // Copyright (c) 2017, Project-Haystack 4 | // Licensed under the Academic Free License version 3.0 5 | // 6 | // History: 7 | // 22 Nov 2017 Brian Frank Creation 8 | // 9 | 10 | using build 11 | 12 | ** 13 | ** Build: ph 14 | ** 15 | class Build : BuildPod 16 | { 17 | new make() 18 | { 19 | podName = "ph" 20 | summary = "Project Haystack core definitions" 21 | meta = ["org.name": "Project Haystack", 22 | "org.uri": "https://project-haystack.org/", 23 | "proj.name": "Project Haystack Defs", 24 | "license.name": "Academic Free License 3.0", 25 | "vcs.name": "Git", 26 | "vcs.uri": "https://github.com/Project-Haystack/haystack-defs", 27 | ] 28 | resDirs = [`lib/`] 29 | index = [ "ph.lib": "ph"] 30 | } 31 | } -------------------------------------------------------------------------------- /src/ph/lib/associations.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 24 Apr 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^association 11 | is: ^list 12 | of: ^symbol 13 | docTaxonomy 14 | doc: 15 | Associations model ontological relationships between definitions. 16 | See [Associations]`docHaystack::Associations` chapter. 17 | -------------------------------------------------------------------------- 18 | def: ^reciprocalOf 19 | is: ^symbol 20 | doc: 21 | Specifies the inverse of an association or relationships. 22 | See [Associations]`docHaystack::Associations#reciprocalOf` and 23 | [Relationships]`docHaystack::Relationships#reciprocalOf` chapter. 24 | -------------------------------------------------------------------------- 25 | def: ^is 26 | is: ^association 27 | tagOn: ^def 28 | doc: 29 | Defines one or more supertypes of a subtyping relationship. 30 | See [Subtyping]`docHaystack::Subtyping` chapter. 31 | -------------------------------------------------------------------------- 32 | 33 | ////////////////////////////////////////////////////////////////////////// 34 | // Tags/TagOn 35 | ////////////////////////////////////////////////////////////////////////// 36 | 37 | -------------------------------------------------------------------------- 38 | def: ^tagOn 39 | is: ^association 40 | notInherited 41 | tagOn: ^def 42 | accumulate 43 | reciprocalOf: ^tags 44 | doc: "This tag is used on the given entity" 45 | -------------------------------------------------------------------------- 46 | def: ^tags 47 | is: ^association 48 | reciprocalOf: ^tagOn 49 | computedFromReciprocal 50 | docAssociations 51 | doc: "Tags used with this entity" 52 | -------------------------------------------------------------------------- 53 | 54 | -------------------------------------------------------------------------------- /src/ph/lib/entity.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 6 Jan 2019 Brian Frank New design 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^entity 12 | is: ^marker 13 | doc: 14 | Top-level dicts with a unique identifier. 15 | See `docHaystack::Ontology#entities` chapter. 16 | -------------------------------------------------------------------------- 17 | def: ^id 18 | is: ^ref 19 | tagOn: ^entity 20 | doc: 21 | Defines the unique identifier of an entity in system using a `ref` value 22 | type. The scope of an entity is undefined, but must be unique with a 23 | given system or project. This identifier may be used by other entities 24 | for cross-referencing. See `docHaystack::Ontology#entities` chapter. 25 | -------------------------------------------------------------------------- 26 | def: ^dis 27 | is: ^str 28 | tagOn: ^entity 29 | doc: 30 | Display name for an entity. 31 | See `docHaystack::Ontology#entities` chapter. 32 | -------------------------------------------------------------------------- 33 | 34 | -------------------------------------------------------------------------------- /src/ph/lib/filetypes.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 25 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | ////////////////////////////////////////////////////////////////////////// 10 | // Feature 11 | ////////////////////////////////////////////////////////////////////////// 12 | 13 | -------------------------------------------------------------------------- 14 | def: ^filetype 15 | is: ^feature 16 | doc: "File format type definition" 17 | -------------------------------------------------------------------------- 18 | def: ^mime 19 | is: ^str 20 | tagOn: ^filetype 21 | doc: "Mime type formatted as type/subtype" 22 | -------------------------------------------------------------------------- 23 | def: ^fileExt 24 | is: ^str 25 | tagOn: ^filetype 26 | doc: "Filename extension such as \"csv\"" 27 | -------------------------------------------------------------------------- 28 | 29 | ////////////////////////////////////////////////////////////////////////// 30 | // Types 31 | ////////////////////////////////////////////////////////////////////////// 32 | 33 | -------------------------------------------------------------------------- 34 | def: ^filetype:csv 35 | dis: "CSV" 36 | mime: "text/csv" 37 | fileExt: "csv" 38 | wikipedia: `https://wikipedia.org/wiki/Comma-separated_values` 39 | doc: "Comma Separated Values - see `docHaystack::Csv`" 40 | -------------------------------------------------------------------------- 41 | def: ^filetype:json 42 | dis: "JSON" 43 | mime: "application/json" 44 | fileExt: "json" 45 | wikipedia: `https://wikipedia.org/wiki/JSON` 46 | doc: "Haystack JavaScript Object Notation format - see `docHaystack::Json`" 47 | -------------------------------------------------------------------------- 48 | def: ^filetype:jsonld 49 | dis: "JSON-LD" 50 | mime: "application/ld+json" 51 | fileExt: "jsonld" 52 | wikipedia: `https://wikipedia.org/wiki/JSON-LD` 53 | doc: "JavaScript Object Notation for Linked Data - see `docHaystack::Rdf`" 54 | -------------------------------------------------------------------------- 55 | def: ^filetype:trio 56 | dis: "Trio" 57 | mime: "text/trio" 58 | fileExt: "trio" 59 | doc: "Haystack Tag Record Input Output - see `docHaystack::Trio`" 60 | -------------------------------------------------------------------------- 61 | def: ^filetype:turtle 62 | dis: "Turtle" 63 | mime: "text/turtle" 64 | fileExt: "ttl" 65 | wikipedia: `https://wikipedia.org/wiki/Turtle_(syntax)` 66 | doc: "RDF Turtle - see `docHaystack::Rdf`" 67 | -------------------------------------------------------------------------- 68 | def: ^filetype:zinc 69 | dis: "Zinc" 70 | mime: "text/zinc" 71 | fileExt: "zinc" 72 | doc: "Haystack typed CSV format - see `docHaystack::Zinc`" 73 | -------------------------------------------------------------------------- -------------------------------------------------------------------------------- /src/ph/lib/lib.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 3 Aug 2018 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^lib:ph 11 | doc: "Project Haystack core definitions" 12 | version: "3.9.15" 13 | baseUri: `https://project-haystack.org/def/ph/` 14 | ------------------------------------------------------------------------ -------------------------------------------------------------------------------- /src/ph/lib/misc.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 6 Jan 2019 Brian Frank New design 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^deprecated 12 | is: ^marker 13 | doc: "Obsoleted" 14 | -------------------------------------------------------------------------- 15 | def: ^filterStr 16 | is: ^str 17 | doc: "Haystack filter string. See `docHaystack::Filters`" 18 | -------------------------------------------------------------------------- 19 | def: ^kind 20 | is: ^str 21 | doc: 22 | Kind name used to identity a value data type 23 | enum: 24 | - Marker: is-a label 25 | - Bool: true or false 26 | - NA: not available 27 | - Number: floating point with optional unit 28 | - Str: Unicode string 29 | - Uri: Universal resource identifier 30 | - Ref: reference to an entity 31 | - Date: an ISO 8601 date as year, month, day: 2011-06-07 32 | - Time: an ISO 8601 time as hour, minute, seconds: 09:51:27.354 33 | - DateTime: an ISO 8601 timestamp followed by timezone name 34 | - Coord: geographic coordinate in latitude/longitude formatted as C(lat,lng) 35 | - XStr: extended string with type name 36 | - List: ordered sequence 37 | - Dict: key/value map 38 | - Grid: two dimensional tabular data collection 39 | -------------------------------------------------------------------------- 40 | def: ^max 41 | is: ^marker 42 | doc: "Maximum" 43 | -------------------------------------------------------------------------- 44 | def: ^min 45 | is: ^marker 46 | doc: "Minimum" 47 | -------------------------------------------------------------------------- 48 | def: ^nodoc 49 | is: ^marker 50 | doc: "Undocumented and not officially supported" 51 | -------------------------------------------------------------------------- 52 | def: ^nosrc 53 | is: ^marker 54 | doc: "Do not include source code in documentation" 55 | -------------------------------------------------------------------------- 56 | def: ^tz 57 | is: ^str 58 | doc: "Timezone identifier from standard [timezone database]`docHaystack::TimeZones`" 59 | -------------------------------------------------------------------------- 60 | def: ^unit 61 | is: ^str 62 | doc: "Unit identifier from standard unit database" 63 | -------------------------------------------------------------------------- 64 | 65 | 66 | -------------------------------------------------------------------------------- /src/ph/lib/ops.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2021, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 31 Mon 2021 Brian Frank Creation 7 | // 8 | 9 | ////////////////////////////////////////////////////////////////////////// 10 | // Feature 11 | ////////////////////////////////////////////////////////////////////////// 12 | 13 | -------------------------------------------------------------------------- 14 | def: ^op 15 | is: ^feature 16 | doc: 17 | Operation for HTTP API. 18 | See `docHaystack::Ops` chapter. 19 | -------------------------------------------------------------------------- 20 | def: ^noSideEffects 21 | is: ^marker 22 | wikipedia: `https://en.wikipedia.org/wiki/Side_effect_(computer_science)` 23 | doc: 24 | Marks a function or operation as having no side effects. The function 25 | may or may not be *pure* in that calling it multiple times with the 26 | same arguments always evaluates to the same result. 27 | -------------------------------------------------------------------------- 28 | 29 | ////////////////////////////////////////////////////////////////////////// 30 | // Ops 31 | ////////////////////////////////////////////////////////////////////////// 32 | 33 | -------------------------------------------------------------------------- 34 | def: ^op:about 35 | noSideEffects 36 | doc: 37 | Query basic information about the server. 38 | See `docHaystack::Ops#about` chapter. 39 | -------------------------------------------------------------------------- 40 | def: ^op:close 41 | doc: 42 | Close the current session and cancel the auth bearer token. 43 | See `docHaystack::Ops#close` chapter. 44 | -------------------------------------------------------------------------- 45 | def: ^op:defs 46 | noSideEffects 47 | doc: 48 | Query the definitions in the current namespace. 49 | See `docHaystack::Ops#defs` chapter. 50 | -------------------------------------------------------------------------- 51 | def: ^op:filetypes 52 | noSideEffects 53 | doc: 54 | Query the filetype defs in the current namespace. 55 | See `docHaystack::Ops#filetypes` chapter. 56 | -------------------------------------------------------------------------- 57 | def: ^op:libs 58 | noSideEffects 59 | doc: 60 | Query the lib defs in the current namespace. 61 | See `docHaystack::Ops#libs` chapter. 62 | -------------------------------------------------------------------------- 63 | def: ^op:read 64 | noSideEffects 65 | doc: 66 | Query the a set of entity records by id or by filter. 67 | See `docHaystack::Ops#read` chapter. 68 | -------------------------------------------------------------------------- 69 | def: ^op:ops 70 | noSideEffects 71 | doc: 72 | Query the op defs in the current namespace. 73 | See `docHaystack::Ops#ops` chapter. 74 | -------------------------------------------------------------------------- 75 | def: ^op:nav 76 | noSideEffects 77 | doc: 78 | Query the navigation tree for discovery. 79 | See `docHaystack::Ops#nav` chapter. 80 | -------------------------------------------------------------------------- 81 | def: ^op:watchPoll 82 | doc: 83 | Poll a watch subscription. 84 | See `docHaystack::Ops#watchPoll` chapter. 85 | -------------------------------------------------------------------------- 86 | def: ^op:watchSub 87 | doc: 88 | Subscribe to entity data. 89 | See `docHaystack::Ops#watchSub` chapter. 90 | -------------------------------------------------------------------------- 91 | def: ^op:watchUnsub 92 | doc: 93 | Unsubscribe to entity data. 94 | See `docHaystack::Ops#watchUnsub` chapter. 95 | -------------------------------------------------------------------------- 96 | 97 | 98 | -------------------------------------------------------------------------------- /src/ph/lib/relationships.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 26 Mar 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^relationship 11 | is: ^symbol 12 | docTaxonomy 13 | doc: 14 | Ref tags used to model entity-to-entity relationships. 15 | See [Relationships]`docHaystack::Relationships` chapter. 16 | -------------------------------------------------------------------------- 17 | def: ^transitive 18 | is: ^marker 19 | doc: 20 | This marker is applied to a `relationship` to indicate it is transitive. 21 | Transitivity requires that if the relationship applies to A,B and B,C 22 | then it also applies to A,C. 23 | -------------------------------------------------------------------------- 24 | 25 | ////////////////////////////////////////////////////////////////////////// 26 | // Contains/ContainedBy 27 | ////////////////////////////////////////////////////////////////////////// 28 | 29 | -------------------------------------------------------------------------- 30 | def: ^containedBy 31 | is: ^relationship 32 | reciprocalOf: ^contains 33 | transitive 34 | doc: "The entity is logically contained by the referent." 35 | -------------------------------------------------------------------------- 36 | def: ^contains 37 | is: ^relationship 38 | reciprocalOf: ^containedBy 39 | computedFromReciprocal 40 | transitive 41 | doc: "Entities logically contained by this entity" 42 | -------------------------------------------------------------------------- 43 | 44 | ////////////////////////////////////////////////////////////////////////// 45 | // Input/Output 46 | ////////////////////////////////////////////////////////////////////////// 47 | 48 | -------------------------------------------------------------------------- 49 | def: ^inputs 50 | is: ^relationship 51 | reciprocalOf: ^outputs 52 | transitive 53 | doc: 54 | The entity inputs a substance from the referent. 55 | The value of this tag is what is received. 56 | -------------------------------------------------------------------------- 57 | def: ^outputs 58 | is: ^relationship 59 | reciprocalOf: ^inputs 60 | transitive 61 | doc: 62 | The entity outputs a substance to the referent. 63 | The value of this tag is what is supplied. 64 | -------------------------------------------------------------------------- 65 | 66 | // Markers for input/output entities 67 | 68 | -------------------------------------------------------------------------- 69 | def: ^input 70 | is: ^marker 71 | doc: "Entity inputs a substance which flows from another entity" 72 | -------------------------------------------------------------------------- 73 | def: ^output 74 | is: ^marker 75 | doc: "Entity outputs a substance with flows to other entities" 76 | -------------------------------------------------------------------------- 77 | 78 | -------------------------------------------------------------------------------- /src/ph/notes.txt: -------------------------------------------------------------------------------- 1 | 2 | Notes for re-modeling the ontology using the new def tree design 3 | 4 | - space model (space, building, floor, room, zone-space) 5 | - new airQuality quantities pm25, pm10, tvoc 6 | - elec-ac, elec-dc subtypes 7 | - phenomenon taxonomy 8 | - quantity taxonomy 9 | - process taxonomy 10 | - wikipedia hyperlinks in defs where applicable 11 | - temp versioning scheme 3.9.YYYYMMDD 12 | - filetype defs 13 | 14 | // tag renames 15 | - weatherStation -> weather 16 | - weather -> weatherPoint 17 | - daytime -> sunrise 18 | - magnitude -> mag (used with current and volt) 19 | - uv -> unitVent 20 | - hisMode -> hisInterpolate 21 | 22 | 23 | 24 | 25 | -------------------------------------------------------------------------------- /src/phIct/build.fan: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env fan 2 | // 3 | // Copyright (c) 2019, Project-Haystack 4 | // Licensed under the Academic Free License version 3.0 5 | // 6 | // History: 7 | // 20 May 2019 Brian Frank Creation 8 | // 9 | 10 | using build 11 | 12 | ** 13 | ** Build: phIct 14 | ** 15 | class Build : BuildPod 16 | { 17 | new make() 18 | { 19 | podName = "phIct" 20 | summary = "Project Haystack information and communication technology definitions" 21 | meta = ["org.name": "Project Haystack", 22 | "org.uri": "https://project-haystack.org/", 23 | "proj.name": "Project Haystack Defs", 24 | "license.name": "Academic Free License 3.0", 25 | "vcs.name": "Git", 26 | "vcs.uri": "https://github.com/Project-Haystack/haystack-defs", 27 | ] 28 | resDirs = [`lib/`] 29 | index = [ "ph.lib": "phIct"] 30 | } 31 | } -------------------------------------------------------------------------------- /src/phIct/lib/dataCenter.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 24 Sep 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^dataCenter 11 | is: ^space 12 | doc: 13 | Space used to house computer and networking gear. 14 | See `docHaystack::DataCenters` chapter. 15 | wikipedia: `https://en.wikipedia.org/wiki/Data_center` 16 | children: [ 17 | {rack equip}, 18 | {crac fcu equip}, 19 | ] 20 | -------------------------------------------------------------------------- 21 | def: ^rack 22 | is: ^equip 23 | wikipedia: `https://en.wikipedia.org/wiki/19-inch_rack` 24 | doc: 25 | Enclosure or chassis used to mount computer and networking gear. 26 | Devices are mounted to rails of a standard width, typically 19 or 23 27 | inches. Height is measured in *rack units* where one 1U is 1.75 inches. 28 | A full rack has a height of 42U. 29 | See `docHaystack::DataCenters#racks` chapter. 30 | children: [ 31 | {server device}, 32 | {networking device}, 33 | ] 34 | -------------------------------------------------------------------------- 35 | def: ^ups 36 | is: ^equip 37 | wikipedia: `https://en.wikipedia.org/wiki/Uninterruptible_power_supply` 38 | doc: "Uninterruptible power supply" 39 | -------------------------------------------------------------------------- 40 | 41 | 42 | -------------------------------------------------------------------------------- /src/phIct/lib/device.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 20 May 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^device 11 | is: ^entity 12 | mandatory 13 | docTaxonomy 14 | doc: 15 | Microprocessor based hardware device. This is the general term for 16 | all computers, mobile phones, controllers, and I/O modules. 17 | See `docHaystack::Devices#networks` chapter. 18 | -------------------------------------------------------------------------- 19 | def: ^deviceRef 20 | is: ^ref 21 | of: ^device 22 | doc: "Device which controls a monitors this entity" 23 | -------------------------------------------------------------------------- 24 | 25 | ////////////////////////////////////////////////////////////////////////// 26 | // General Purpose 27 | ////////////////////////////////////////////////////////////////////////// 28 | 29 | -------------------------------------------------------------------------- 30 | def: ^phone 31 | is: ^device 32 | wikipedia: `https://en.wikipedia.org/wiki/Telephone` 33 | doc: "Telephone used for voice telecommunication." 34 | -------------------------------------------------------------------------- 35 | def: ^mobile-phone 36 | is: ^phone 37 | wikipedia: `https://en.wikipedia.org/wiki/Mobile_phone` 38 | doc: "Cellular phone providing telecommunication over radio links." 39 | -------------------------------------------------------------------------- 40 | def: ^tablet 41 | is: ^device 42 | wikipedia: `https://en.wikipedia.org/wiki/Tablet_computer` 43 | doc: "Mobile device with touch screen for user input." 44 | -------------------------------------------------------------------------- 45 | def: ^computer 46 | is: ^device 47 | wikipedia: `https://en.wikipedia.org/wiki/Computer` 48 | doc: "General purpose computer." 49 | -------------------------------------------------------------------------- 50 | def: ^server-computer 51 | is: ^computer 52 | wikipedia: `https://en.wikipedia.org/wiki/Server_(computing)` 53 | doc: "General purpose computer used as a server. Typically servers are rack mounted." 54 | -------------------------------------------------------------------------- 55 | def: ^laptop 56 | is: ^computer 57 | wikipedia: `https://en.wikipedia.org/wiki/Laptop` 58 | doc: "Portable laptop computer." 59 | -------------------------------------------------------------------------- 60 | 61 | ////////////////////////////////////////////////////////////////////////// 62 | // Networking 63 | ////////////////////////////////////////////////////////////////////////// 64 | 65 | -------------------------------------------------------------------------- 66 | def: ^networking-device 67 | is: ^device 68 | wikipedia: `https://en.wikipedia.org/wiki/Networking_hardware` 69 | doc: "Microprocessor device used to establish networks." 70 | -------------------------------------------------------------------------- 71 | def: ^networking-router 72 | is: ^networking-device 73 | wikipedia: `https://en.wikipedia.org/wiki/Router_(computing)` 74 | doc: "Networking device used to route data between different networks." 75 | -------------------------------------------------------------------------- 76 | def: ^networking-switch 77 | is: ^networking-device 78 | wikipedia: `https://en.wikipedia.org/wiki/Network_switch` 79 | doc: "Networking device used to connect devices on the same network." 80 | -------------------------------------------------------------------------- 81 | 82 | ////////////////////////////////////////////////////////////////////////// 83 | // Controllers 84 | ////////////////////////////////////////////////////////////////////////// 85 | 86 | -------------------------------------------------------------------------- 87 | def: ^controller 88 | is: ^device 89 | doc: 90 | Microprocessor based device used in a control system. Controllers 91 | interact with the physical world through direct I/O to sensors and 92 | actuators or via network [protocols]`protocol`. 93 | -------------------------------------------------------------------------- 94 | defx: ^equipRef 95 | tagOn: ^controller 96 | -------------------------------------------------------------------------- 97 | 98 | -------------------------------------------------------------------------------- /src/phIct/lib/equip.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 24 Sep 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^controls-panel 11 | is: ^panel 12 | doc: "Panel housing controllers and networking gear" 13 | children: [ 14 | {controller device}, 15 | {networking device}, 16 | ] 17 | -------------------------------------------------------------------------- 18 | 19 | 20 | -------------------------------------------------------------------------------- /src/phIct/lib/lib.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 20 May 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^lib:phIct 11 | version: "3.9.15" 12 | baseUri: `https://project-haystack.org/def/phIct/` 13 | depends: [^lib:ph, ^lib:phIoT] 14 | wikipedia: `https://en.wikipedia.org/wiki/Information_and_communications_technology` 15 | doc: 16 | Project Haystack definitions for Information and Communications Technology. 17 | This includes microprocessor based hardware, software, and networking 18 | technologies. 19 | ------------------------------------------------------------------------ -------------------------------------------------------------------------------- /src/phIct/lib/misc.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 24 Sep 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^mobile 11 | is: ^marker 12 | doc: "Relating to mobile phones, hand-held computers, and similar technology" 13 | -------------------------------------------------------------------------- 14 | def: ^networking 15 | is: ^marker 16 | doc: "Related to data communication networks" 17 | -------------------------------------------------------------------------- 18 | def: ^router 19 | is: ^marker 20 | doc: "Device used to route data packets" 21 | -------------------------------------------------------------------------- 22 | def: ^server 23 | is: ^marker 24 | wikipedia: `https://en.wikipedia.org/wiki/Server_(computing)` 25 | doc: "Hardware or software which provides services for other programs or devices." 26 | -------------------------------------------------------------------------- 27 | 28 | 29 | -------------------------------------------------------------------------------- /src/phIct/lib/network.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 20 May 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^network 11 | is: ^entity 12 | doc: 13 | Logical communications network between two or more devices. 14 | See `docHaystack::Devices#networks` chapter. 15 | -------------------------------------------------------------------------- 16 | def: ^networkRef 17 | is: ^ref 18 | of: ^network 19 | doc: 20 | Associates a device which communicates on specific a network. 21 | -------------------------------------------------------------------------- 22 | 23 | -------------------------------------------------------------------------------- /src/phIct/lib/protocol.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 20 May 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^protocol 11 | is: ^marker 12 | wikipedia: `https://en.wikipedia.org/wiki/Communication_protocol` 13 | docTaxonomy 14 | doc: "Communication protocol used for devices on a network." 15 | -------------------------------------------------------------------------- 16 | 17 | ////////////////////////////////////////////////////////////////////////// 18 | // Subtypes 19 | ////////////////////////////////////////////////////////////////////////// 20 | 21 | -------------------------------------------------------------------------- 22 | def: ^bacnet 23 | is: ^protocol 24 | wikipedia: `https://en.wikipedia.org/wiki/BACnet` 25 | doc: "ASHRAE building automation and control protocol" 26 | -------------------------------------------------------------------------- 27 | def: ^bluetooth 28 | is: ^protocol 29 | wikipedia: `https://en.wikipedia.org/wiki/Bluetooth` 30 | doc: "Short range wireless communication protocol" 31 | -------------------------------------------------------------------------- 32 | def: ^coap 33 | is: ^protocol 34 | wikipedia: `https://en.wikipedia.org/wiki/Constrained_Application_Protocol` 35 | doc: "Constrained Application Protocol" 36 | -------------------------------------------------------------------------- 37 | def: ^dali 38 | is: ^protocol 39 | wikipedia: `https://en.wikipedia.org/wiki/Digital_Addressable_Lighting_Interface` 40 | doc: "Digital Addressable Lighting Interface protocol for lighting" 41 | -------------------------------------------------------------------------- 42 | def: ^ftp 43 | is: ^protocol 44 | wikipedia: `https://en.wikipedia.org/wiki/File_Transfer_Protocol` 45 | doc: "File Transfer Protocol" 46 | -------------------------------------------------------------------------- 47 | def: ^haystack 48 | is: ^protocol 49 | doc: "Haystack HTTP protocol for exchanging tagged data" 50 | -------------------------------------------------------------------------- 51 | def: ^http 52 | is: ^protocol 53 | wikipedia: `https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol` 54 | doc: "Hypertext Transfer Protocol which is foundation of the web" 55 | -------------------------------------------------------------------------- 56 | def: ^imap 57 | is: ^protocol 58 | wikipedia: `https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol` 59 | doc: "Internet Message Access Protocol for retrieving email" 60 | -------------------------------------------------------------------------- 61 | def: ^knx 62 | is: ^protocol 63 | wikipedia: `https://en.wikipedia.org/wiki/KNX_(standard)` 64 | doc: "KNX protocol commonly used for lighting systems" 65 | -------------------------------------------------------------------------- 66 | def: ^modbus 67 | is: ^protocol 68 | wikipedia: `https://en.wikipedia.org/wiki/Modbus` 69 | doc: "Register based communication protocol used with industrial devices." 70 | -------------------------------------------------------------------------- 71 | def: ^mqtt 72 | is: ^protocol 73 | wikipedia: `https://en.wikipedia.org/wiki/MQTT` 74 | doc: "Message Queuing Telemetry Transport publish/subscribe protocol" 75 | -------------------------------------------------------------------------- 76 | def: ^obix 77 | is: ^protocol 78 | wikipedia: `https://en.wikipedia.org/wiki/OBIX` 79 | doc: "XML based Open Building Information eXchange protocol." 80 | -------------------------------------------------------------------------- 81 | def: ^pop3 82 | is: ^protocol 83 | wikipedia: `https://en.wikipedia.org/wiki/Post_Office_Protocol` 84 | doc: "Post Office Protocol version 3 for retrieving email" 85 | -------------------------------------------------------------------------- 86 | def: ^sox 87 | is: ^protocol 88 | doc: "Sedona Framework UDP based communication protocol" 89 | -------------------------------------------------------------------------- 90 | def: ^snmp 91 | is: ^protocol 92 | wikipedia: `https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol` 93 | doc: "Simple Network Management Protocol for managing IP devices" 94 | -------------------------------------------------------------------------- 95 | def: ^smtp 96 | is: ^protocol 97 | wikipedia: `https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol` 98 | doc: "Simple Mail Transfer Protocol for sending email" 99 | -------------------------------------------------------------------------- 100 | def: ^zigbee 101 | is: ^protocol 102 | wikipedia: `https://en.wikipedia.org/wiki/Zigbee` 103 | doc: "Low power wireless communication protocol for home automation" 104 | -------------------------------------------------------------------------- 105 | def: ^zwave 106 | is: ^protocol 107 | wikipedia: `https://en.wikipedia.org/wiki/Z-Wave` 108 | doc: "Low power wireless communication protocol for home automation" 109 | -------------------------------------------------------------------------- 110 | 111 | -------------------------------------------------------------------------------- /src/phIoT/build.fan: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env fan 2 | // 3 | // Copyright (c) 2017, Project-Haystack 4 | // Licensed under the Academic Free License version 3.0 5 | // 6 | // History: 7 | // 22 Nov 2017 Brian Frank Creation 8 | // 9 | 10 | using build 11 | 12 | ** 13 | ** Build: phIoT 14 | ** 15 | class Build : BuildPod 16 | { 17 | new make() 18 | { 19 | podName = "phIoT" 20 | summary = "Project Haystack definitions for Internet of Things" 21 | meta = ["org.name": "Project Haystack", 22 | "org.uri": "https://project-haystack.org/", 23 | "proj.name": "Project Haystack Defs", 24 | "license.name": "Academic Free License 3.0", 25 | "vcs.name": "Git", 26 | "vcs.uri": "https://github.com/Project-Haystack/haystack-defs", 27 | ] 28 | resDirs = [`lib/`] 29 | index = [ "ph.lib": "phIoT"] 30 | 31 | } 32 | } -------------------------------------------------------------------------------- /src/phIoT/lib/actuator.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 3 May 2019 Brian Frank New design 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^actuator 12 | is: [^equip, ^elec-input] 13 | wikipedia: `https://en.wikipedia.org/wiki/Actuator` 14 | doc: 15 | Equipment to move or control a mechanism. Actuators may be manually 16 | operated or automated via a control system to convert an energy source 17 | into mechanical energy. Typically the energy source is electricity, 18 | hydraulics, or pneumatics. 19 | -------------------------------------------------------------------------- 20 | 21 | ////////////////////////////////////////////////////////////////////////// 22 | // Damper 23 | ////////////////////////////////////////////////////////////////////////// 24 | 25 | -------------------------------------------------------------------------- 26 | def: ^damper 27 | is: ^marker 28 | wikipedia: `https://en.wikipedia.org/wiki/Damper_(flow)` 29 | doc: "Damper equipment or control point." 30 | -------------------------------------------------------------------------- 31 | def: ^damper-actuator 32 | is: ^actuator 33 | childrenFlatten: [^ductSection] 34 | wikipedia: `https://en.wikipedia.org/wiki/Damper_(flow)` 35 | doc: "Actuator to regulate the flow of air." 36 | children: [ 37 | 38 | // Damper position command to regulate air flow and pressure. Fully open is 39 | // represented as true or 100%; fully closed is represented as false or 0%. 40 | {damper cmd point}, 41 | 42 | // Damper feedback sensor.eedback sensor. A voltage sensor which provides 43 | // exact position is measured as 100% fully open or 0% fully closed. End 44 | // point switches indicate true for open and false for closed. 45 | {damper sensor point}, 46 | ] 47 | -------------------------------------------------------------------------- 48 | 49 | ////////////////////////////////////////////////////////////////////////// 50 | // Valve 51 | ////////////////////////////////////////////////////////////////////////// 52 | 53 | -------------------------------------------------------------------------- 54 | def: ^valve 55 | is: ^marker 56 | wikipedia: `https://en.wikipedia.org/wiki/Valve` 57 | doc: "Valve equipment or control point" 58 | -------------------------------------------------------------------------- 59 | def: ^valve-actuator 60 | is: ^actuator 61 | childrenFlatten: [^fluid, ^pipeSection] 62 | wikipedia: `https://en.wikipedia.org/wiki/Valve` 63 | doc: "Actuator to regulate the flow of fluid." 64 | children: [ 65 | 66 | // Valve position command to regulate flow and pressure. Fully open is 67 | // represented as true or 100%; fully closed is represented as false or 0%. 68 | {valve cmd point}, 69 | 70 | // Valve feedback sensor. Position is measured as 100% fully open or 0% 71 | // fully closed. Digital feedback uses true for open and false for closed. 72 | {valve sensor point}, 73 | ] 74 | -------------------------------------------------------------------------- 75 | 76 | -------------------------------------------------------------------------------- /src/phIoT/lib/airTerminalUnit.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 25 Apr 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^airTerminalUnit 11 | is: [^equip, ^air-input, ^air-output, ^elec-input] 12 | doc: 13 | Equipment in air distribution systems which terminate at the space. 14 | Terminal units receive air from `airHandlingEquip` which have the 15 | primarily responsibility to condition air. Terminal units are primarily 16 | responsible for delivery of air to the space and tempering the temperature. 17 | children: [ 18 | {thermostat equip}, 19 | {discharge duct equip}, 20 | {inlet duct equip}, 21 | {thermostat equip}, 22 | ] 23 | -------------------------------------------------------------------------- 24 | 25 | -------------------------------------------------------------------------------- /src/phIoT/lib/ates.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2021, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 24 Feb 2021 Jaap Balvers Creation, based on work of the Project Haystack WG ATES systems 7 | // 03 Mar 2021 Jaap Balvers Added children to equips 8 | // 12 Mar 2021 Jaap Balvers, Coen Hoogervorst Added children 9 | // 30 Mar 2021 Jaap Balvers Added atesDesign and atesDesignType 10 | // 11 | 12 | ////////////////////////////////////////////////////////////////////////// 13 | // Equips 14 | ////////////////////////////////////////////////////////////////////////// 15 | 16 | -------------------------------------------------------------------------- 17 | def: ^ates 18 | is: ^equip 19 | wikipedia: `https://en.wikipedia.org/wiki/Aquifer_thermal_energy_storage` 20 | doc: 21 | Aquifer Thermal Energy Storage system. 22 | See `docHaystack::ATES` chapter. 23 | children: [ 24 | {warm well equip}, 25 | {cool well equip}, 26 | {infiltration well equip}, 27 | {extraction well equip}, 28 | {flowInverter equip}, 29 | {warm water flow thermal meter equip}, 30 | {cool water flow thermal meter equip}, 31 | {heatExchanger equip}, 32 | {ground water flow sensor point}, 33 | {ground water volume sensor point}, 34 | {ground water pressure sensor point}, 35 | {purge water flow sensor point}, 36 | {purge water volume sensor point}, 37 | ] 38 | -------------------------------------------------------------------------- 39 | def: ^well 40 | is: ^equip 41 | doc: 42 | A well is a source of groundwater and potentially thermal energy. When 43 | used within an [ATES]`docHaystack::ATES` system, the well facilitates thermal 44 | energy exchange with the ground warm and cool water sources. In this case, a 45 | well can be either a closed system that transports water through pipes in the 46 | ground, or an open system that pumps up and returns ground water. 47 | children: [ 48 | {water temp sensor point}, 49 | {water flow sensor point}, 50 | {water volume sensor point}, 51 | {water pressure sensor point}, 52 | {water level sensor point}, 53 | {water pump motor equip}, 54 | ] 55 | -------------------------------------------------------------------------- 56 | def: ^flowInverter 57 | is: ^equip 58 | doc: "System to change direction of substance flow " 59 | -------------------------------------------------------------------------- 60 | 61 | ////////////////////////////////////////////////////////////////////////// 62 | // ATES Design 63 | ////////////////////////////////////////////////////////////////////////// 64 | 65 | -------------------------------------------------------------------------- 66 | def: ^atesDesign 67 | is: ^choice 68 | tagOn: ^ates 69 | doc: "Design type of the ATES underground system." 70 | -------------------------------------------------------------------------- 71 | def: ^atesMono 72 | is: ^atesDesign 73 | doc: 74 | The ATES has only one physical well. This well is deep enough 75 | to penetrate two layers of groundwater. 76 | -------------------------------------------------------------------------- 77 | def: ^atesDoublet 78 | is: ^atesDesign 79 | doc: 80 | The ATES has one or more pairs of a separate warm and cool well. 81 | -------------------------------------------------------------------------- 82 | def: ^atesDoubletPaired 83 | is: ^atesDesign 84 | doc: 85 | The ATES is as a doublet, but with specific warm and cool wells linked together. 86 | These linked wells do not exchange water with other wells. 87 | -------------------------------------------------------------------------- 88 | def: ^atesUnidirectional 89 | is: ^atesDesign 90 | doc: 91 | Similar to a doublet, but water always flows in the same direction from 92 | the extraction to the infiltration well. 93 | -------------------------------------------------------------------------- 94 | def: ^atesClosedLoop 95 | is: ^atesDesign 96 | doc: 97 | The ATES uses closed piping to transport a water/glycol mixture 98 | through the ground. The system works like a heat exchanger; there 99 | is no ground water transported. 100 | -------------------------------------------------------------------------- 101 | 102 | 103 | -------------------------------------------------------------------------------- /src/phIoT/lib/battery.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 21 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^battery 11 | is: [^equip, ^elec-output] 12 | wikipedia: `https://en.wikipedia.org/wiki/Electric_battery` 13 | doc: "Equipment used to store electric energy" 14 | -------------------------------------------------------------------------- 15 | 16 | -------------------------------------------------------------------------------- /src/phIoT/lib/boiler.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 21 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^boiler 11 | is: [^equip, ^elec-input] 12 | wikipedia: `https://en.wikipedia.org/wiki/Boiler` 13 | doc: "Equipment to generate hot water or steam for heating" 14 | children: [ 15 | // Boolean alarm condition. True indicates an alarm condition. 16 | {alarm sensor point}, 17 | ] 18 | -------------------------------------------------------------------------- 19 | def: ^hot-water-boiler 20 | is: [^boiler, ^hot-water-output] 21 | doc: "Boiler which outputs hot water" 22 | children: [ 23 | {hot water leaving pipe equip}, 24 | {hot water entering pipe equip}, 25 | {makeup water entering pipe equip}, 26 | {circ pipe equip}, 27 | {outside duct equip}, 28 | {flue duct equip}, 29 | ] 30 | -------------------------------------------------------------------------- 31 | def: ^steam-boiler 32 | is: [^boiler, ^steam-output] 33 | doc: "Boiler which outputs steam" 34 | children: [ 35 | {steam leaving pipe equip}, 36 | {condensate entering pipe equip}, 37 | {makeup water entering pipe equip}, 38 | {circ pipe equip}, 39 | {outside duct equip}, 40 | {flue duct equip}, 41 | ] 42 | -------------------------------------------------------------------------- 43 | 44 | -------------------------------------------------------------------------------- /src/phIoT/lib/cav.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 25 Apr 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^cav 11 | is: ^airTerminalUnit 12 | wikipedia: `https://en.wikipedia.org/wiki/Constant_air_volume` 13 | doc: 14 | Constant air volume terminal unit. CAV systems use a constant 15 | air flow rate with a variable air temperature. 16 | -------------------------------------------------------------------------- 17 | 18 | -------------------------------------------------------------------------------- /src/phIoT/lib/chiller.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 21 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^chiller 11 | is: [^equip, ^elec-input] 12 | wikipedia: `https://en.wikipedia.org/wiki/Chiller` 13 | doc: 14 | Equipment to remove heat from a liquid. Chillers typically use a vapor 15 | compression or an absorption refrigeration cycle. 16 | children: [ 17 | // Primary on/off command (on is true, off is false) 18 | {run cmd point}, 19 | 20 | // Secondary on/off command (enabled is true, disabled is false) 21 | {enable cmd point}, 22 | 23 | // Run status sensor. True indicates on and false off. 24 | {run sensor point}, 25 | 26 | // Enable status sensor. True indicates enabled and false disabled. 27 | {enable sensor point}, 28 | 29 | // Load limit command as percentage from 0% to 100% 30 | {load cmd point}, 31 | 32 | // Load factor status as percentage from 0% to 100% 33 | {load sensor point}, 34 | 35 | // Measured efficiency sensor measured in "COP" or "kW/ton" 36 | {efficiency sensor point}, 37 | 38 | // Boolean alarm condition. True indicates an alarm condition. 39 | {alarm sensor point}, 40 | 41 | {chilled water leaving pipe equip}, 42 | {chilled water entering pipe equip}, 43 | {chilled water delta temp sensor point}, 44 | {chilled water delta flow sensor point}, 45 | {chilled water valve isolation cmd point}, 46 | 47 | {condenser water leaving pipe equip}, 48 | {condenser water entering pipe equip}, 49 | {condenser water valve isolation cmd point}, 50 | 51 | {condenser run cmd point}, 52 | {condenser run sensor point}, 53 | {condenser refrig temp sensor point}, 54 | {condenser refrig pressure sensor point}, 55 | {evaporator refrig temp sensor point}, 56 | {evaporator refrig pressure sensor point}, 57 | ] 58 | -------------------------------------------------------------------------- 59 | 60 | ////////////////////////////////////////////////////////////////////////// 61 | // Tags 62 | ////////////////////////////////////////////////////////////////////////// 63 | 64 | -------------------------------------------------------------------------- 65 | def: ^coolingCapacity 66 | is: ^number 67 | tagOn: ^chiller 68 | doc: "Measurement of a chiller ability to remove heat measured" 69 | prefUnit: ["tonref", "BTU/h", "kW"] 70 | -------------------------------------------------------------------------- 71 | 72 | ////////////////////////////////////////////////////////////////////////// 73 | // chillerMechanism 74 | ////////////////////////////////////////////////////////////////////////// 75 | 76 | -------------------------------------------------------------------------- 77 | def: ^chillerMechanism 78 | is: ^choice 79 | tagOn: ^chiller 80 | doc: "Primary mechanism of chiller" 81 | -------------------------------------------------------------------------- 82 | def: ^chiller-absorption 83 | is: [^absorption, ^chillerMechanism] 84 | -------------------------------------------------------------------------- 85 | def: ^chiller-reciprocal 86 | is: [^reciprocal, ^chillerMechanism] 87 | -------------------------------------------------------------------------- 88 | def: ^chiller-rotaryScrew 89 | is: [^rotaryScrew, ^chillerMechanism] 90 | -------------------------------------------------------------------------- 91 | def: ^chiller-centrifugal 92 | is: [^centrifugal, ^chillerMechanism] 93 | -------------------------------------------------------------------------- 94 | 95 | ////////////////////////////////////////////////////////////////////////// 96 | // Chiller Misc 97 | ////////////////////////////////////////////////////////////////////////// 98 | 99 | -------------------------------------------------------------------------- 100 | def: ^efficiency 101 | is: ^marker 102 | doc: 103 | Efficiency point of a chiller measured in "COP" or "kW/ton". 104 | -------------------------------------------------------------------------- 105 | def: ^load 106 | is: ^marker 107 | doc: 108 | Chiller point to command or measure the chiller's load as a percentage 109 | from "0%" to "100%". When paired with cmd this models the chiller's 110 | load limit. When paired with sensor this models the chiller's current 111 | load factor. 112 | -------------------------------------------------------------------------- 113 | 114 | 115 | -------------------------------------------------------------------------------- /src/phIoT/lib/coolingTower.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 21 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^coolingTower 11 | is: [^equip, ^elec-input] 12 | wikipedia: `https://en.wikipedia.org/wiki/Cooling_tower` 13 | doc: "Equipment to transfer waste heat into the atmosphere" 14 | children: [ 15 | {condenser water entering pipe equip}, 16 | {condenser water leaving pipe equip}, 17 | {fan motor equip}, 18 | ] 19 | -------------------------------------------------------------------------- 20 | 21 | ////////////////////////////////////////////////////////////////////////// 22 | // Condenser Loop Type 23 | ////////////////////////////////////////////////////////////////////////// 24 | 25 | -------------------------------------------------------------------------- 26 | def: ^condenserLoop 27 | is: ^choice 28 | tagOn: ^chilled-water-plant 29 | doc: "Open or closed loop for condenser working fluid" 30 | -------------------------------------------------------------------------- 31 | def: ^condenserOpenLoop 32 | is: ^condenserLoop 33 | doc: "Uses working fluid itself for evaporation into the atmosphere" 34 | -------------------------------------------------------------------------- 35 | def: ^condenserClosedLoop 36 | is: ^condenserLoop 37 | doc: "Working fluid is kept separate from fluid used for heat transfer into the atmosphere" 38 | -------------------------------------------------------------------------- 39 | 40 | -------------------------------------------------------------------------------- /src/phIoT/lib/equip.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 6 Jan 2019 Brian Frank New design 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^equip 12 | is: ^entity 13 | docTaxonomy 14 | mandatory 15 | doc: 16 | Equipment asset. 17 | See `docHaystack::Equips` chapter. 18 | children: [ 19 | {equip}, 20 | {point}, 21 | ] 22 | -------------------------------------------------------------------------- 23 | 24 | ////////////////////////////////////////////////////////////////////////// 25 | // Relationships 26 | ////////////////////////////////////////////////////////////////////////// 27 | 28 | -------------------------------------------------------------------------- 29 | def: ^equipRef 30 | is: ^ref 31 | of: ^equip 32 | containedBy: ^equip 33 | tagOn: [^equip, ^point] 34 | doc: "Reference to equip which contains this entity" 35 | -------------------------------------------------------------------------- 36 | 37 | 38 | -------------------------------------------------------------------------------- /src/phIoT/lib/exhaustEquip.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 26 Apr 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^fumeHood 11 | is: [^equip, ^elec-input] 12 | wikipedia: `https://en.wikipedia.org/wiki/Fume_hood` 13 | doc: "Ventilation equipment to limit exposure to hazardous fumes." 14 | children: [ 15 | {alarm sensor point}, 16 | {air flow sensor point}, 17 | {air flow sp point}, 18 | {air velocity sensor point}, 19 | {air velocity sp point}, 20 | ] 21 | -------------------------------------------------------------------------- 22 | 23 | -------------------------------------------------------------------------------- /src/phIoT/lib/heatExchanger.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 21 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^heatExchanger 11 | is: ^equip 12 | wikipedia: `https://en.wikipedia.org/wiki/Heat_exchanger` 13 | doc: "Equipment to transfer heat between two working fluids." 14 | -------------------------------------------------------------------------- 15 | def: ^coil 16 | is: ^heatExchanger 17 | wikipedia: `https://en.wikipedia.org/wiki/Heat_exchanger#HVAC_air_coils` 18 | doc: 19 | Heat exchanger used to heat or cool air. Coils are sub-components 20 | of HVAC equipment such as `airHandlingEquip`. 21 | -------------------------------------------------------------------------- 22 | 23 | ////////////////////////////////////////////////////////////////////////// 24 | // Cooling Coils 25 | ////////////////////////////////////////////////////////////////////////// 26 | 27 | -------------------------------------------------------------------------- 28 | def: ^coolingCoil 29 | is: ^coil 30 | childrenFlatten: [^ductDeck, ^ductSection] 31 | doc: "Coil used to cool air." 32 | children: [ 33 | {stage:1 cool run cmd point}, 34 | {chilled water cool valve cmd point}, 35 | ] 36 | -------------------------------------------------------------------------- 37 | 38 | ////////////////////////////////////////////////////////////////////////// 39 | // Heating Coils 40 | ////////////////////////////////////////////////////////////////////////// 41 | 42 | -------------------------------------------------------------------------- 43 | def: ^heatingCoil 44 | is: ^coil 45 | childrenFlatten: [^ductDeck, ^ductSection] 46 | doc: "Coil used to heat air." 47 | children: [ 48 | {stage:1 heat run cmd point}, 49 | {hot water heat valve cmd point}, 50 | {steam heat valve cmd point}, 51 | ] 52 | -------------------------------------------------------------------------- 53 | 54 | 55 | 56 | -------------------------------------------------------------------------------- /src/phIoT/lib/lib.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 9 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^lib:phIoT 11 | version: "3.9.15" 12 | baseUri: `https://project-haystack.org/def/phIoT/` 13 | wikipedia: `https://en.wikipedia.org/wiki/Internet_of_things` 14 | depends: [^lib:ph, ^lib:phScience] 15 | doc: "Project Haystack definitions for Internet of Things" 16 | ------------------------------------------------------------------------ -------------------------------------------------------------------------------- /src/phIoT/lib/lighting.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 26 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^luminaire 11 | is: [^equip, ^lightingZonePoints, ^elec-input] 12 | wikipedia: `https://en.wikipedia.org/wiki/Light_fixture` 13 | doc: "Light fixture using electricity to provide illumination" 14 | -------------------------------------------------------------------------- 15 | 16 | -------------------------------------------------------------------------------- /src/phIoT/lib/meter.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 9 Jan 2019 Brian Frank New design 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^meter 12 | is: ^equip 13 | doc: 14 | Equipment to meter a substance or phenomenon. 15 | See `docHaystack::Meters` chapter. 16 | -------------------------------------------------------------------------- 17 | def: ^elec-meter 18 | is: [^meter, ^elec-input, ^elec-output] 19 | doc: "Electricity meter" 20 | -------------------------------------------------------------------------- 21 | def: ^ac-elec-meter 22 | is: ^elec-meter 23 | doc: 24 | AC Electricity meter. 25 | See `docHaystack::Meters` chapter. 26 | children: [ 27 | // energy 28 | {total net ac elec active energy sensor point}, 29 | {total import ac elec active energy sensor point}, 30 | {total export ac elec active energy sensor point}, 31 | {phase:"A" net ac elec active energy sensor point}, 32 | 33 | // demand 34 | {total ac elec demand sensor point}, 35 | 36 | // power 37 | {total active ac elec power sensor point}, 38 | {total reactive ac elec power sensor point}, 39 | {total apparent ac elec power sensor point}, 40 | {phase:"A" active ac elec power sensor point}, 41 | {phase:"A" reactive ac elec power sensor point}, 42 | {phase:"A" apparent ac elec power sensor point}, 43 | 44 | // current 45 | {avg ac elec current magnitude sensor point}, 46 | {avg ac elec current angle sensor point}, 47 | {avg ac elec current imbalance sensor point}, 48 | {avg ac elec current thd sensor point}, 49 | {phase:"A" ac elec current magnitude sensor point}, 50 | {phase:"A" ac elec current angle sensor point}, 51 | {phase:"A" ac elec current imbalance sensor point}, 52 | {phase:"A" ac elec current thd sensor point}, 53 | 54 | // volt 55 | {avg ac elec volt magnitude sensor point}, 56 | {avg ac elec volt angle sensor point}, 57 | {avg ac elec volt imbalance sensor point}, 58 | {avg ac elec volt thd sensor point}, 59 | {phase:"A" ac elec volt magnitude sensor point}, 60 | {phase:"A" ac elec volt angle sensor point}, 61 | {phase:"A" ac elec volt imbalance sensor point}, 62 | {phase:"A" ac elec volt thd sensor point}, 63 | 64 | // power factor 65 | {avg ac elec pf sensor point}, 66 | {phase:"A" ac elec pf sensor point}, 67 | ] 68 | -------------------------------------------------------------------------- 69 | def: ^dc-elec-meter 70 | is: ^elec-meter 71 | doc: 72 | DC Electricity meter. 73 | See `docHaystack::Meters` chapter. 74 | -------------------------------------------------------------------------- 75 | def: ^flow-meter 76 | is: ^meter 77 | doc: 78 | Meter to measure flow rate and total volume of fluid. 79 | See `docHaystack::Meters` chapter. 80 | -------------------------------------------------------------------------- 81 | 82 | ////////////////////////////////////////////////////////////////////////// 83 | // MeterScope 84 | ////////////////////////////////////////////////////////////////////////// 85 | 86 | -------------------------------------------------------------------------- 87 | def: ^meterScope 88 | is: ^choice 89 | tagOn: ^meter 90 | doc: "Classifies a meter as a main site meter or submeter" 91 | -------------------------------------------------------------------------- 92 | def: ^siteMeter 93 | is: ^meterScope 94 | doc: "Main meter for the associated site" 95 | -------------------------------------------------------------------------- 96 | def: ^submeter 97 | is: ^meterScope 98 | doc: "Submeters measure usage of a sub-system or equipment within a site" 99 | -------------------------------------------------------------------------- 100 | ////////////////////////////////////////////////////////////////////////// 101 | // Relationships 102 | ////////////////////////////////////////////////////////////////////////// 103 | 104 | -------------------------------------------------------------------------- 105 | def: ^submeterOf 106 | is: ^ref 107 | of: ^meter 108 | tagOn: ^meter 109 | doc: "Reference to parent meter which is immediately upstream of this meter" 110 | -------------------------------------------------------------------------- 111 | 112 | -------------------------------------------------------------------------------- /src/phIoT/lib/motor.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 24 Apr 2019 Brian Frank New design 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^motor 12 | is: [^equip, ^elec-input] 13 | wikipedia: `https://en.wikipedia.org/wiki/Electric_motor` 14 | doc: 15 | Equipment that converts electrical energy into mechanical energy. 16 | See `docHaystack::Motors` chapter. 17 | children: [ 18 | // Primary on/off command (on is true, off is false) 19 | {run cmd point}, 20 | 21 | // Secondary on/off command (enabled is true, disabled is false) 22 | {enable cmd point}, 23 | 24 | // Run status sensor. True indicates on and false off. 25 | {run sensor point}, 26 | 27 | // Enable status sensor. True indicates enabled and false disabled. 28 | {enable sensor point}, 29 | 30 | // Boolean alarm condition. True indicates an alarm condition. 31 | {alarm sensor point}, 32 | 33 | // Speed command as percentage where 0% is off, 100% if full speed 34 | {vfd speed cmd point}, 35 | 36 | // Speed command as a frequency in Hz 37 | {vfd freq cmd point}, 38 | 39 | // Speed status as percentage where 0% is off, 100% if full speed 40 | {vfd speed sensor point}, 41 | 42 | // Speed status as frequency in Hz 43 | {vfd freq sensor point}, 44 | ] 45 | -------------------------------------------------------------------------- 46 | 47 | ////////////////////////////////////////////////////////////////////////// 48 | // VFD 49 | ////////////////////////////////////////////////////////////////////////// 50 | 51 | -------------------------------------------------------------------------- 52 | def: ^vfd 53 | is: ^marker 54 | tagOn: [^motor] 55 | wikipedia: `https://en.wikipedia.org/wiki/Variable-frequency_drive` 56 | doc: 57 | Variable-frequency drive. 58 | See `docHaystack::Motors` chapter. 59 | -------------------------------------------------------------------------- 60 | def: ^vfd-speed 61 | is: ^quantity 62 | prefUnit: ["%"] 63 | doc: 64 | VFD speed measured in "%"; 0% is off and 100% is the fastest speed. 65 | -------------------------------------------------------------------------- 66 | def: ^vfd-freq 67 | is: ^quantity 68 | prefUnit: ["Hz"] 69 | doc: 70 | VFD frequency measured in "Hz". 71 | -------------------------------------------------------------------------- 72 | 73 | 74 | ////////////////////////////////////////////////////////////////////////// 75 | // Fan 76 | ////////////////////////////////////////////////////////////////////////// 77 | 78 | -------------------------------------------------------------------------- 79 | def: ^fan 80 | is: ^marker 81 | wikipedia: `https://en.wikipedia.org/wiki/Fan_(machine)` 82 | doc: Fan equipment or control point 83 | -------------------------------------------------------------------------- 84 | def: ^fan-motor 85 | is: ^motor 86 | wikipedia: `https://en.wikipedia.org/wiki/Fan_(machine)` 87 | childrenFlatten: [^ductSection, ^fan] 88 | doc: 89 | Motor used with a fan to create air flow. 90 | See `docHaystack::Motors` chapter. 91 | -------------------------------------------------------------------------- 92 | 93 | ////////////////////////////////////////////////////////////////////////// 94 | // Pump 95 | ////////////////////////////////////////////////////////////////////////// 96 | 97 | -------------------------------------------------------------------------- 98 | def: ^pump 99 | is: ^marker 100 | wikipedia: `https://en.wikipedia.org/wiki/Pump` 101 | doc: "Pump equipment or control point" 102 | -------------------------------------------------------------------------- 103 | def: ^pump-motor 104 | is: ^motor 105 | wikipedia: `https://en.wikipedia.org/wiki/Pump` 106 | childrenFlatten: [^fluid, ^pipeSection, ^pump] 107 | doc: 108 | Motor used with a pump to move fluid. 109 | See `docHaystack::Motors` chapter. 110 | -------------------------------------------------------------------------- 111 | 112 | -------------------------------------------------------------------------------- /src/phIoT/lib/ops.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2021, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 1 Jun 2021 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^op:hisRead 11 | noSideEffects 12 | doc: 13 | Read historized time series data from a `his-point`. 14 | See `docHaystack::Ops#hisRead` chapter. 15 | -------------------------------------------------------------------------- 16 | def: ^op:hisWrite 17 | doc: 18 | Write historized time series data from a `his-point`. 19 | See `docHaystack::Ops#hisWrite` chapter. 20 | -------------------------------------------------------------------------- 21 | def: ^op:pointWrite 22 | doc: 23 | Read or command a `writable-point`. 24 | See `docHaystack::Ops#pointWrite` chapter. 25 | -------------------------------------------------------------------------- 26 | def: ^op:invokeAction 27 | doc: 28 | Invoke a user action on a target entity. 29 | See `docHaystack::Ops#invokeAction` chapter. 30 | -------------------------------------------------------------------------- 31 | 32 | -------------------------------------------------------------------------------- /src/phIoT/lib/panel.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 24 Sep 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^panel 11 | is: ^equip 12 | doc: 13 | Enclosure for electrical and control equipment. Panels may be 14 | used to isolate electrical connections and provide environmental 15 | protection. 16 | -------------------------------------------------------------------------- 17 | def: ^elec-panel 18 | is: [^panel, ^elec-input, ^elec-output] 19 | wikipedia: `https://en.wikipedia.org/wiki/Distribution_board` 20 | doc: 21 | Physical housing for electrical circuits, fuses, and breakers. 22 | See `docHaystack::ElecPanels#panels` chapter. 23 | -------------------------------------------------------------------------- 24 | def: ^circuit 25 | is: [^equip, ^elec-input, ^elec-output] 26 | wikipedia: `https://en.wikipedia.org/wiki/Electrical_network` 27 | doc: 28 | Electrical circuit and its associated components such as breakers. 29 | See `docHaystack::ElecPanels#circuits` chapter. 30 | -------------------------------------------------------------------------- 31 | 32 | -------------------------------------------------------------------------------- /src/phIoT/lib/plant.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 21 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^plant 11 | is: ^equip 12 | doc: 13 | Central plant used to generate a substance for a process. 14 | See `docHaystack::Plants`. 15 | children: [ 16 | // Overall plant enable command 17 | {enable cmd point} 18 | ] 19 | -------------------------------------------------------------------------- 20 | def: ^chilled-water-plant 21 | is: [^plant, ^chilled-water-output] 22 | doc: 23 | Plant used to generate chilled water for cooling. 24 | See `docHaystack::Plants`. 25 | children: [ 26 | {chiller equip}, 27 | {coolingTower equip}, 28 | 29 | {chilled water bypass pipe equip}, 30 | {chilled water entering pipe equip}, 31 | {chilled water leaving pipe equip}, 32 | {chilled water header pipe equip}, 33 | {chilled water heatExchanger equip}, 34 | {chilled water delta flow point}, 35 | {chilled water delta pressure point}, 36 | {chilled water delta temp point}, 37 | {chilled water mixing valve cmd point}, 38 | 39 | {condenser water bypass pipe equip}, 40 | {condenser water delta flow sensor point}, 41 | {condenser water delta pressure sensor point}, 42 | {condenser water delta temp sensor point}, 43 | ] 44 | -------------------------------------------------------------------------- 45 | def: ^hot-water-plant 46 | is: [^plant, ^hot-water-output] 47 | doc: 48 | Plant used to generate hot water for heating. 49 | See `docHaystack::Plants`. 50 | children: [ 51 | {hot water boiler equip}, 52 | 53 | {hot water bypass pipe equip}, 54 | {hot water entering pipe equip}, 55 | {hot water leaving pipe equip}, 56 | {hot water header pipe equip}, 57 | {hot water heatExchanger equip}, 58 | {hot water delta pressure sensor point}, 59 | {hot water delta flow sensor point}, 60 | {hot water delta temp sensor point}, 61 | {hot water mixing valve cmd point}, 62 | 63 | {makeup water entering pipe equip}, 64 | {outside duct equip}, 65 | {flue duct equip}, 66 | ] 67 | -------------------------------------------------------------------------- 68 | def: ^steam-plant 69 | is: [^plant, ^steam-output] 70 | doc: 71 | Plant used to generate steam for heating. 72 | See `docHaystack::Plants`. 73 | children: [ 74 | {steam boiler equip}, 75 | 76 | {steam leaving pipe equip}, 77 | {condensate entering pipe equip}, 78 | {steam bypass pipe equip}, 79 | {steam header pipe equip}, 80 | {steam heatExchanger equip}, 81 | {steam delta pressure sensor point}, 82 | {steam delta flow sensor point}, 83 | {steam delta temp sensor point}, 84 | {steam mixing valve cmd point}, 85 | 86 | {makeup water entering pipe equip}, 87 | {outside duct equip}, 88 | {flue duct equip}, 89 | ] 90 | -------------------------------------------------------------------------- 91 | 92 | -------------------------------------------------------------------------------- /src/phIoT/lib/process.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 21 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^process 11 | is: ^marker 12 | docTaxonomy 13 | doc: "Industrial or HVAC process" 14 | -------------------------------------------------------------------------- 15 | 16 | ////////////////////////////////////////////////////////////////////////// 17 | // Heating 18 | ////////////////////////////////////////////////////////////////////////// 19 | 20 | -------------------------------------------------------------------------- 21 | def: ^heating 22 | is: ^marker 23 | doc: "Heating mode or process" 24 | -------------------------------------------------------------------------- 25 | def: ^heatingProcess 26 | is: ^choice 27 | tagOn: [^airHandlingEquip, ^boiler, ^chilledBeam, ^heatingCoil, ^radiator, ^radiantFloor, ^vav] 28 | doc: "Processed used to heat a substance" 29 | -------------------------------------------------------------------------- 30 | def: ^biomassHeating 31 | is: ^heatingProcess 32 | doc: "Heating by the combustion of biomass" 33 | -------------------------------------------------------------------------- 34 | def: ^coalHeating 35 | is: ^heatingProcess 36 | doc: "Heating by the combustion of coal" 37 | -------------------------------------------------------------------------- 38 | def: ^dxHeating 39 | is: ^heatingProcess 40 | doc: 41 | Heating using direct expansion of a refrigerant vapor. 42 | Also see `dxCooling` and `heatPump`. 43 | -------------------------------------------------------------------------- 44 | def: ^hotWaterHeating 45 | is: [^heatingProcess, ^hot-water-input] 46 | doc: "Heating using energy of hot water" 47 | -------------------------------------------------------------------------- 48 | def: ^propaneHeating 49 | is: ^heatingProcess 50 | doc: "Heating by the combustion of propane" 51 | -------------------------------------------------------------------------- 52 | def: ^steamHeating 53 | is: [^heatingProcess, ^steam-input] 54 | doc: "Heating using energy of steam" 55 | -------------------------------------------------------------------------- 56 | def: ^naturalGasHeating 57 | is: [^heatingProcess, ^naturalGas-input] 58 | doc: "Heating by the combustion of natural gas" 59 | -------------------------------------------------------------------------- 60 | def: ^fuelOilHeating 61 | is: [^heatingProcess, ^fuelOil-input] 62 | doc: "Heating by the combustion of fuel oil" 63 | -------------------------------------------------------------------------- 64 | def: ^elecHeating 65 | is: [^heatingProcess, ^elec-input] 66 | wikipedia: `https://en.wikipedia.org/wiki/Electric_heating` 67 | doc: "Heating by the conversion of electrical energy" 68 | -------------------------------------------------------------------------- 69 | 70 | ////////////////////////////////////////////////////////////////////////// 71 | // Cooling 72 | ////////////////////////////////////////////////////////////////////////// 73 | 74 | -------------------------------------------------------------------------- 75 | def: ^cooling 76 | is: ^marker 77 | doc: "Cooling mode or process" 78 | -------------------------------------------------------------------------- 79 | def: ^coolingProcess 80 | is: ^choice 81 | tagOn: [^airHandlingEquip, ^chilledBeam, ^coolingCoil] 82 | doc: "Processed used to cool a substance" 83 | -------------------------------------------------------------------------- 84 | def: ^airCooling 85 | is: [^coolingProcess, ^air-input] 86 | wikipedia: `https://en.wikipedia.org/wiki/Air_cooling` 87 | doc: "Cooling by dissipating heat into the surrounding air" 88 | -------------------------------------------------------------------------- 89 | def: ^condenserCooling 90 | is: ^coolingProcess 91 | doc: "Removal of heat through the process of water condensation" 92 | -------------------------------------------------------------------------- 93 | def: ^dxCooling 94 | is: ^coolingProcess 95 | doc: 96 | Cooling using direct expansion of a refrigerant vapor. 97 | Also see `dxHeating` and `heatPump`. 98 | -------------------------------------------------------------------------- 99 | def: ^chilledWaterCooling 100 | is: [^coolingProcess, ^chilled-water-input] 101 | doc: "Cooling using transfer of heat to chilled water" 102 | -------------------------------------------------------------------------- 103 | def: ^waterCooling 104 | is: [^coolingProcess] 105 | wikipedia: `https://en.wikipedia.org/wiki/Water_cooling` 106 | doc: "Cooling using transfer of heat to water which is not explicitly chilled" 107 | -------------------------------------------------------------------------- 108 | 109 | -------------------------------------------------------------------------------- /src/phIoT/lib/radiantEquip.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 26 Apr 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^radiantEquip 11 | is: ^equip 12 | doc: "HVAC equipment that conditions a space without forced air." 13 | -------------------------------------------------------------------------- 14 | def: ^radiator 15 | is: ^radiantEquip 16 | wikipedia: `https://en.wikipedia.org/wiki/Radiator_(heating)` 17 | doc: 18 | Heats a space using exposed pipes or coils. Hot water and steam 19 | radiators are often cast iron and installed directly in the space 20 | or along the baseboard. Electric radiators are typically installed 21 | on the baseboard. 22 | -------------------------------------------------------------------------- 23 | def: ^radiantFloor 24 | is: ^radiantEquip 25 | wikipedia: `https://en.wikipedia.org/wiki/Underfloor_heating` 26 | doc: "Heats a space using pipes or cables embedded beneath floor." 27 | -------------------------------------------------------------------------- 28 | def: ^chilledBeam 29 | is: ^radiantEquip 30 | wikipedia: `https://en.wikipedia.org/wiki/Chilled_beam` 31 | doc: "Conditions a space using a heat exchanger integrated into the ceiling" 32 | -------------------------------------------------------------------------- 33 | 34 | -------------------------------------------------------------------------------- /src/phIoT/lib/site.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 6 Jan 2019 Brian Frank New design 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^site 12 | is: [^entity, ^geoPlace] 13 | docTaxonomy 14 | mandatory 15 | doc: 16 | Site is a geographic location of the built environment. 17 | Typically site maps to one building with its own unique 18 | street address. See `docHaystack::Sites` chapter. 19 | children: [ 20 | {space}, 21 | {equip}, 22 | ] 23 | -------------------------------------------------------------------------- 24 | 25 | ////////////////////////////////////////////////////////////////////////// 26 | // Tags 27 | ////////////////////////////////////////////////////////////////////////// 28 | 29 | -------------------------------------------------------------------------- 30 | defx: ^tz 31 | tagOn: ^site 32 | -------------------------------------------------------------------------- 33 | def: ^yearBuilt 34 | is: ^int 35 | tagOn: ^site 36 | doc: "Original year of construction as four digit year such as 1980" 37 | -------------------------------------------------------------------------- 38 | def: ^primaryFunction 39 | is: ^str 40 | tagOn: ^site 41 | doc: "Primary function of building as US Energy Star key" 42 | enum: 43 | Adult Education 44 | Ambulatory Surgical Center 45 | Aquarium 46 | Automobile Dealership 47 | Bank Branch 48 | Bar/Nightclub 49 | Barracks 50 | Bowling Alley 51 | Casino 52 | College/University 53 | Convenience Store with Gas Station 54 | Convenience Store without Gas Station 55 | Convention Center 56 | Courthouse 57 | Data Center 58 | Distribution Center 59 | Drinking Water Treatment & Distribution 60 | Enclosed Mall 61 | Energy/Power Station 62 | Fast Food Restaurant 63 | Financial Office 64 | Fire Station 65 | Fitness Center/Health Club/Gym 66 | Food Sales 67 | Food Service 68 | Hospital (General Medical & Surgical) 69 | Hotel 70 | Ice/Curling Rink 71 | Indoor Arena 72 | K-12 School 73 | Laboratory 74 | Library 75 | Lifestyle Center 76 | Mailing Center/Post Office 77 | Manufacturing/Industrial Plant 78 | Medical Office 79 | Mixed Use Property 80 | Movie Theater 81 | Multifamily Housing 82 | Museum 83 | Non-Refrigerated Warehouse 84 | Office 85 | Other - Education 86 | Other - Entertainment/Public Assembly 87 | Other - Lodging/Residential 88 | Other - Mall 89 | Other - Public Services 90 | Other - Recreation 91 | Other - Restaurant/Bar 92 | Other - Services 93 | Other - Stadium 94 | Other - Technology/Science 95 | Other - Utility 96 | Other 97 | Other/Specialty Hospital 98 | Outpatient Rehabilitation/Physical Therapy 99 | Parking 100 | Performing Arts 101 | Personal Services (Health/Beauty, Dry Cleaning, etc) 102 | Police Station 103 | Pre-school/Daycare 104 | Prison/Incarceration 105 | Race Track 106 | Refrigerated Warehouse 107 | Repair Services (Vehicle, Shoe, Locksmith, etc) 108 | Residence Hall/Dormitory 109 | Restaurant 110 | Retail Store 111 | Roller Rink 112 | Self-Storage Facility 113 | Senior Care Community 114 | Single Family Home 115 | Social/Meeting Hall 116 | Stadium (Closed) 117 | Stadium (Open) 118 | Strip Mall 119 | Supermarket/Grocery Store 120 | Swimming Pool 121 | Transportation Terminal/Station 122 | Urgent Care/Clinic/Other Outpatient 123 | Veterinary Office 124 | Vocational School 125 | Wastewater Treatment Plant 126 | Wholesale Club/Supercenter 127 | Worship Facility 128 | Zoo 129 | -------------------------------------------------------------------------- 130 | 131 | ////////////////////////////////////////////////////////////////////////// 132 | // Refs 133 | ////////////////////////////////////////////////////////////////////////// 134 | 135 | -------------------------------------------------------------------------- 136 | def: ^siteRef 137 | is: ^ref 138 | of: ^site 139 | containedBy: ^site 140 | tagOn: [^system, ^space, ^equip, ^point] 141 | doc: "Reference to site which contains the entity" 142 | -------------------------------------------------------------------------- 143 | 144 | -------------------------------------------------------------------------------- /src/phIoT/lib/space.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 6 Jan 2019 Brian Frank New design 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^space 12 | is: ^entity 13 | docTaxonomy 14 | mandatory 15 | doc: 16 | Space is a three-dimensional volume in the built environment. 17 | See `docHaystack::Spaces` chapter. 18 | children: [ 19 | {space}, 20 | {equip}, 21 | {point}, 22 | ] 23 | -------------------------------------------------------------------------- 24 | def: ^area 25 | is: ^number 26 | prefUnit: ["ft²", "m²"] 27 | tagOn: [^site, ^space] 28 | doc: "Area of a shape or floor space" 29 | -------------------------------------------------------------------------- 30 | 31 | ////////////////////////////////////////////////////////////////////////// 32 | // Floors 33 | ////////////////////////////////////////////////////////////////////////// 34 | 35 | -------------------------------------------------------------------------- 36 | def: ^floor 37 | is: ^space 38 | wikipedia: `https://en.wikipedia.org/wiki/Storey` 39 | doc: 40 | Storey of a building. See `docHaystack::Spaces#floors` chapter. 41 | -------------------------------------------------------------------------- 42 | def: ^ground-floor 43 | is: ^floor 44 | doc: 45 | Floor at ground level. In North America this is typically called 46 | the first floor, but in Europe its often labeled as floor zero. 47 | If `floorNum` is defined, then it must be set to zero. 48 | -------------------------------------------------------------------------- 49 | def: ^subterranean-floor 50 | is: ^floor 51 | doc: 52 | Floor below ground level. Subterranean floors are also known as 53 | basements, lower levels, or cellars. 54 | -------------------------------------------------------------------------- 55 | def: ^roof-floor 56 | is: ^floor 57 | doc: 58 | The roof floor is the topmost level of a building. It is often 59 | where HVAC equipment is located such as rooftop AHUs. 60 | -------------------------------------------------------------------------- 61 | 62 | ////////////////////////////////////////////////////////////////////////// 63 | // Floor Tags 64 | ////////////////////////////////////////////////////////////////////////// 65 | 66 | -------------------------------------------------------------------------- 67 | def: ^floorNum 68 | is: ^int 69 | tagOn: ^floor 70 | doc: 71 | Unitless integer indicating the floor's distance from ground level. The 72 | ground floor is always defined as zero. Additional floors above ground are 73 | numbered 1, 2, 3, etc. Subterranean floors are numbered -1, -2, -3, etc. 74 | This convention is consistent with how most European buildings number 75 | floors. In North America its common to label the ground floor 76 | as the first floor; however Haystack requires the ground level to be 77 | assigned a floorNum of 0. 78 | -------------------------------------------------------------------------- 79 | 80 | ////////////////////////////////////////////////////////////////////////// 81 | // Rooms 82 | ////////////////////////////////////////////////////////////////////////// 83 | 84 | -------------------------------------------------------------------------- 85 | def: ^room 86 | is: ^space 87 | wikipedia: `https://en.wikipedia.org/wiki/Room` 88 | doc: "Enclosed room of a building" 89 | -------------------------------------------------------------------------- 90 | 91 | 92 | ////////////////////////////////////////////////////////////////////////// 93 | // Refs 94 | ////////////////////////////////////////////////////////////////////////// 95 | 96 | -------------------------------------------------------------------------- 97 | def: ^spaceRef 98 | is: ^ref 99 | of: ^space 100 | containedBy: ^space 101 | tagOn: [^space, ^equip, ^point] 102 | doc: "Reference to space which contains this entity" 103 | -------------------------------------------------------------------------- 104 | 105 | 106 | 107 | -------------------------------------------------------------------------------- /src/phIoT/lib/state.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 3 May 2019 Brian Frank Creation 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | 12 | -------------------------------------------------------------------------------- /src/phIoT/lib/substance.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 6 Jan 2019 Brian Frank New design 8 | // 9 | 10 | 11 | ////////////////////////////////////////////////////////////////////////// 12 | // IoT Substances 13 | ////////////////////////////////////////////////////////////////////////// 14 | 15 | -------------------------------------------------------------------------- 16 | def: ^biomass 17 | is: ^substance 18 | wikipedia: `https://en.wikipedia.org/wiki/Biomass` 19 | doc: "Plant or animal material used as fuel to produce electricity or heat" 20 | -------------------------------------------------------------------------- 21 | def: ^coal 22 | is: ^solid 23 | wikipedia: `https://en.wikipedia.org/wiki/Coal` 24 | doc: "Combustible sedimentary rock" 25 | -------------------------------------------------------------------------- 26 | def: ^condensate 27 | is: ^liquid 28 | doc: "Liquid phase produced by the condensation of steam or other gas" 29 | -------------------------------------------------------------------------- 30 | def: ^diesel 31 | is: ^liquid 32 | wikipedia: `https://en.wikipedia.org/wiki/Diesel_fuel` 33 | doc: "Liquid fuel specifically designed for use in diesel engines" 34 | -------------------------------------------------------------------------- 35 | def: ^fuelOil 36 | is: ^liquid 37 | wikipedia: `https://en.wikipedia.org/wiki/Fuel_oil` 38 | doc: "Petroleum based oil burned for energy" 39 | -------------------------------------------------------------------------- 40 | def: ^naturalGas 41 | is: ^gas 42 | wikipedia: `https://en.wikipedia.org/wiki/Natural_gas` 43 | doc: 44 | Fossil fuel energy source consisting largely of methane and other hydrocarbons. 45 | 46 | The energy content of natural gas varies by region within a range determined 47 | on impurities in the gas. You can find a table of these conversions 48 | [here]`https://en.wikipedia.org/wiki/Heat_of_combustion#Higher_heating_values_of_natural_gases_from_various_sources` 49 | ----------------------------------------------------------------------------- 50 | def: ^propane 51 | is: ^gas 52 | wikipedia: `https://en.wikipedia.org/wiki/Propane` 53 | doc: "By-product of natural gas processing and petroleum refining (C₃H₈)" 54 | ----------------------------------------------------------------------------- 55 | def: ^refrig 56 | is: ^fluid 57 | wikipedia: `https://en.wikipedia.org/wiki/Refrigerant` 58 | doc: 59 | Fluid used in refrigeration and heat exchange. Refrigerants typically 60 | alternate between liquid and gas state. 61 | -------------------------------------------------------------------------- 62 | def: ^gasoline 63 | is: ^liquid 64 | wikipedia: `https://en.wikipedia.org/wiki/Gasoline` 65 | doc: "Petroleum derived liquid used as a fuel source" 66 | -------------------------------------------------------------------------- 67 | 68 | ////////////////////////////////////////////////////////////////////////// 69 | // Water Subtypes 70 | ////////////////////////////////////////////////////////////////////////// 71 | 72 | -------------------------------------------------------------------------- 73 | def: ^blowdown-water 74 | is: ^water 75 | doc: "Water expelled from a system to remove mineral build up" 76 | -------------------------------------------------------------------------- 77 | def: ^domestic-water 78 | is: ^water 79 | doc: "Tap water for drinking, washing, cooking, and flushing of toilets" 80 | -------------------------------------------------------------------------- 81 | def: ^chilled-water 82 | is: ^water 83 | doc: "Water cooled for use in HVAC and industrial processes" 84 | wikipedia: `https://en.wikipedia.org/wiki/Chilled_water` 85 | -------------------------------------------------------------------------- 86 | def: ^cold-water 87 | is: ^water 88 | doc: "Water supplied to cold taps" 89 | -------------------------------------------------------------------------- 90 | def: ^condenser-water 91 | is: ^water 92 | doc: "Water used used to remove heat through condensation" 93 | -------------------------------------------------------------------------- 94 | def: ^cool-water 95 | is: ^water 96 | doc: "Relatively cool water without active chilling" 97 | -------------------------------------------------------------------------- 98 | def: ^ground-water 99 | is: ^water 100 | doc: "Water present under the ground or from a well" 101 | wikipedia: `https://en.wikipedia.org/wiki/Groundwater` 102 | -------------------------------------------------------------------------- 103 | def: ^hot-water 104 | is: ^water 105 | doc: "Hot water used for HVAC heating or supplied to hot taps" 106 | -------------------------------------------------------------------------- 107 | def: ^makeup-water 108 | is: ^water 109 | doc: "Water used used to makeup water loss through leaks, evaporation, or blowdown" 110 | -------------------------------------------------------------------------- 111 | def: ^purge-water 112 | is: ^water 113 | doc: "Water expelled from a system to remove contaminants." 114 | -------------------------------------------------------------------------- 115 | def: ^warm-water 116 | is: ^water 117 | doc: "Relatively warm water without active heating" 118 | -------------------------------------------------------------------------- 119 | 120 | -------------------------------------------------------------------------------- /src/phIoT/lib/system.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2022, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 21 Nov 2022 Brian Frank Creation 7 | // 30 Jan 2023 Mike Melillo Haystack Labs WG Revisions 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^system 12 | is: ^entity 13 | docTaxonomy 14 | mandatory 15 | doc: 16 | Grouping of related equipment dedicated to a single application. 17 | See `docHaystack::Systems` chapter. 18 | children: [ 19 | {equip}, 20 | {point}, 21 | ] 22 | -------------------------------------------------------------------------- 23 | def: ^air-system 24 | is: ^system 25 | doc: 26 | System for moving air to maintain indoor thermal comfort and/or air quality. 27 | -------------------------------------------------------------------------- 28 | def: ^air-conditioning-system 29 | is: ^air-system 30 | doc: 31 | System for air treatment to control its temperature, humidity, cleanliness, 32 | and distribution to meet the requirements of a conditioned space. 33 | -------------------------------------------------------------------------- 34 | def: ^air-exhaust-system 35 | is: ^air-system 36 | doc: 37 | System consisting of one or more fans that remove air from the building. 38 | Exhaust systems allow outdoor air to enter by ventilation inlets or normal 39 | leakage paths sthrough the building envelope. 40 | -------------------------------------------------------------------------- 41 | def: ^air-ventilation-system 42 | is: ^air-system 43 | doc: 44 | System that supplies or removes air by natural or mechanical means to or 45 | from any space in order to provide outdoor air to the space. Such air may or 46 | may not have been conditioned. 47 | -------------------------------------------------------------------------- 48 | def: ^elec-system 49 | is: ^system 50 | doc: 51 | System that generates, converts, distributes, and/or stores electricity. 52 | -------------------------------------------------------------------------- 53 | def: ^lighting-system 54 | is: ^elec-system 55 | doc: 56 | System designed to provide lighting. 57 | -------------------------------------------------------------------------- 58 | def: ^refrig-system 59 | is: ^system 60 | doc: 61 | Refrigerant distribution to fulfill all or parts of a refrigeration cycle. 62 | -------------------------------------------------------------------------- 63 | def: ^water-system 64 | is: ^system 65 | doc: 66 | System that supplies or collects potable or non-potable water in any state. 67 | -------------------------------------------------------------------------- 68 | def: ^chilled-water-system 69 | is: ^water-system 70 | doc: 71 | System that circulates water in its liquid state below ambient temperature 72 | for cooling a space or process. 73 | -------------------------------------------------------------------------- 74 | def: ^condenser-water-system 75 | is: ^water-system 76 | doc: 77 | System that circulates water in its liquid state for rejecting heat 78 | from a space or process. 79 | -------------------------------------------------------------------------- 80 | def: ^hot-water-system 81 | is: ^water-system 82 | doc: 83 | System that circulates water in its liquid state for heating 84 | a space or process. 85 | -------------------------------------------------------------------------- 86 | def: ^steam-system 87 | is: ^water-system 88 | doc: 89 | System that circulates water in its vapor state for heating 90 | a space or process. 91 | -------------------------------------------------------------------------- 92 | def: ^domestic-water-system 93 | is: ^water-system 94 | doc: 95 | System that circulates potable water in its liquid state for purposes 96 | other than space conditioning and process requirements. 97 | -------------------------------------------------------------------------- 98 | def: ^domestic-cold-water-system 99 | is: ^domestic-water-system 100 | doc: 101 | System that circulates potable cold water in its liquid state for purposes 102 | other than space cooling and process requirements. 103 | -------------------------------------------------------------------------- 104 | def: ^domestic-hot-water-system 105 | is: ^domestic-water-system 106 | doc: 107 | System that circulates potable hot water in its liquid state for purposes 108 | other than space heating and process requirements. 109 | -------------------------------------------------------------------------- 110 | 111 | ////////////////////////////////////////////////////////////////////////// 112 | // Refs 113 | ////////////////////////////////////////////////////////////////////////// 114 | 115 | ------------------------------------------------------------------------- 116 | def: ^systemRef 117 | is: [^ref] 118 | of: ^system 119 | tagOn: [^equip, ^point, ^system] 120 | doc: "Reference to system" 121 | -------------------------------------------------------------------------- -------------------------------------------------------------------------------- /src/phIoT/lib/tank.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 21 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^tank 11 | is: ^equip 12 | wikipedia: `https://en.wikipedia.org/wiki/Storage_tank` 13 | childrenFlatten: [^substance] 14 | doc: "Tank used to store a substance for temporary holding" 15 | children: [ 16 | {level sensor point}, 17 | {temp sensor point}, 18 | {pressure sensor point}, 19 | ] 20 | -------------------------------------------------------------------------- 21 | def: ^tankSubstance 22 | is: ^choice 23 | of: ^substance 24 | tagOn: ^tank 25 | doc: "Substance stored by a tank" 26 | -------------------------------------------------------------------------- 27 | 28 | -------------------------------------------------------------------------------- /src/phIoT/lib/vav.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 9 Jan 2019 Brian Frank New design 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^vav 12 | is: ^airTerminalUnit 13 | wikipedia: `https://en.wikipedia.org/wiki/Variable_air_volume` 14 | doc: 15 | Variable air volume terminal unit. VAV systems use a constant air 16 | temperature with a variable air flow rate. See `docHaystack::VAVs` chapter. 17 | children: [ 18 | {reheat cmd point}, 19 | {hvacMode sp point}, 20 | {ductArea sp point}, 21 | {perimeterHeat cmd point}, 22 | ] 23 | -------------------------------------------------------------------------- 24 | 25 | ////////////////////////////////////////////////////////////////////////// 26 | // VAV Modulation 27 | ////////////////////////////////////////////////////////////////////////// 28 | 29 | -------------------------------------------------------------------------- 30 | def: ^vavModulation 31 | is: ^choice 32 | tagOn: ^vav 33 | doc: "How does VAV modulate the temp based on duct pressure" 34 | -------------------------------------------------------------------------- 35 | def: ^pressureDependent 36 | is: ^vavModulation 37 | doc: 38 | VAV damper modulates to control space temp; dependent on duct pressure 39 | being maintained 40 | -------------------------------------------------------------------------- 41 | def: ^pressureIndependent 42 | is: ^vavModulation 43 | doc: 44 | VAV damper or a control valve that modulates to maintain desired flow 45 | setpoint; independent of the duct pressure 46 | -------------------------------------------------------------------------- 47 | 48 | ////////////////////////////////////////////////////////////////////////// 49 | // VAV Air Circuit 50 | ////////////////////////////////////////////////////////////////////////// 51 | 52 | -------------------------------------------------------------------------- 53 | def: ^vavAirCircuit 54 | is: ^choice 55 | tagOn: ^vav 56 | doc: "How does the VAV pull in air" 57 | -------------------------------------------------------------------------- 58 | def: ^vav-series 59 | is: ^vavAirCircuit 60 | doc: "VAV pulls air from the primary air flow" 61 | -------------------------------------------------------------------------- 62 | def: ^vav-parallel 63 | is: ^vavAirCircuit 64 | doc: "VAV pulls air from outside the primary air flow" 65 | -------------------------------------------------------------------------- 66 | 67 | ////////////////////////////////////////////////////////////////////////// 68 | // VAV Misc 69 | ////////////////////////////////////////////////////////////////////////// 70 | 71 | -------------------------------------------------------------------------- 72 | def: ^ductArea 73 | is: ^marker 74 | doc: "Config point on a `vav` for duct area measured in ft² or m²" 75 | -------------------------------------------------------------------------- 76 | def: ^hvacMode 77 | is: ^marker 78 | doc: "Operational mode for HVAC equipment" 79 | enum: 80 | - cooling: 81 | - heating: 82 | - reheat: 83 | - warmup: morning warmup where AHU is supplying warm air 84 | - purge: night purge when AHU is supplying 100% fresh air 85 | - pressurize: 86 | - depressurize: 87 | - manual: 88 | -------------------------------------------------------------------------- 89 | def: ^perimeterHeat 90 | is: ^marker 91 | doc: "Auxiliary heating points associated with a `vav`" 92 | -------------------------------------------------------------------------- 93 | 94 | 95 | -------------------------------------------------------------------------------- /src/phIoT/lib/verticalTransport.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2019, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 26 Jan 2019 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^verticalTransport 11 | is: ^equip 12 | doc: "Equipment to move humans and materials" 13 | -------------------------------------------------------------------------- 14 | def: ^elevator 15 | is: [^verticalTransport, ^elec-input] 16 | wikipedia:`https://en.wikipedia.org/wiki/Elevator` 17 | doc: "Enclosure used to move people between floors." 18 | -------------------------------------------------------------------------- 19 | def: ^escalator 20 | is: [^verticalTransport, ^elec-input] 21 | wikipedia:`https://en.wikipedia.org/wiki/Escalator` 22 | doc: "Moving staircase used to move people between floors." 23 | -------------------------------------------------------------------------- 24 | def: ^movingWalkway 25 | is: [^verticalTransport, ^elec-input] 26 | wikipedia:`https://en.wikipedia.org/wiki/Moving_walkway` 27 | doc: "Conveyor to move people across a horizontal or inclined plane." 28 | -------------------------------------------------------------------------- 29 | 30 | -------------------------------------------------------------------------------- /src/phIoT/lib/weather.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2011, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Feb 2011 Brian Frank Creation 7 | // 24 Jan 2019 Brian Frank New design 8 | // 9 | 10 | -------------------------------------------------------------------------- 11 | def: ^weatherStation 12 | is: [^entity, ^geoPlace] 13 | mandatory 14 | doc: 15 | Logical weather station and its measurement points. 16 | See `docHaystack::Weather#stations` chapter. 17 | wikipedia: `https://en.wikipedia.org/wiki/Weather_station` 18 | children: [ 19 | {weather air temp sensor point}, 20 | {weather air wetBulb sensor point}, 21 | {weather air feelsLike sensor point}, 22 | {weather air dewPoint sensor point}, 23 | {weather air humidity sensor point}, 24 | {weather air enthalpy sensor point}, 25 | {weather atmospheric pressure sensor point}, 26 | {weather cloudage sensor point}, 27 | {weather daytime sensor point}, 28 | {weather precipitation sensor point}, 29 | {weather solar irradiance sensor point}, 30 | {weather weatherCond sensor point}, 31 | {weather wind speed sensor point}, 32 | {weather wind direction sensor point}, 33 | {weather visibility sensor point}, 34 | ] 35 | -------------------------------------------------------------------------- 36 | defx: ^tz 37 | tagOn: ^weatherStation 38 | -------------------------------------------------------------------------- 39 | 40 | ////////////////////////////////////////////////////////////////////////// 41 | // Misc 42 | ////////////////////////////////////////////////////////////////////////// 43 | 44 | -------------------------------------------------------------------------- 45 | def: ^weather-point 46 | is: ^point 47 | doc: 48 | Weather station observation point. 49 | See `docHaystack::Weather#points` chapter. 50 | -------------------------------------------------------------------------- 51 | def: ^weatherStationRef 52 | is: ^ref 53 | of: ^weatherStation 54 | tagOn: [^site, ^weather-point] 55 | doc: "Reference to weather station for to use this entity" 56 | -------------------------------------------------------------------------- 57 | 58 | -------------------------------------------------------------------------------- /src/phIoT/lib/zones.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2020, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 22 Mar 2020 Brian Frank Creation COVID-19! 7 | // 8 | 9 | ////////////////////////////////////////////////////////////////////////// 10 | // Zone Types 11 | ////////////////////////////////////////////////////////////////////////// 12 | 13 | -------------------------------------------------------------------------- 14 | def: ^zone-space 15 | is: ^space 16 | doc: 17 | Space associated with a specific system. 18 | See `docHaystack::Spaces#zones` and `docHaystack::Zones` chapters. 19 | children: [ 20 | {occupied sensor point}, 21 | {occupied sp point}, 22 | {occupancy sensor point}, 23 | ] 24 | -------------------------------------------------------------------------- 25 | def: ^hvac-zone-space 26 | is: [^zone-space, ^hvacZonePoints, ^airQualityZonePoints, ^air-input] 27 | doc: 28 | Zone related to conditioning of a space's air temperature and quality. 29 | See `docHaystack::Spaces#zones` and `docHaystack::Zones#hvac` chapters. 30 | -------------------------------------------------------------------------- 31 | def: ^lighting-zone-space 32 | is: [^zone-space, ^lightingZonePoints] 33 | doc: 34 | Zone related to lighting system. 35 | See `docHaystack::Spaces#zones` and `docHaystack::Zones#lighting` chapters. 36 | -------------------------------------------------------------------------- 37 | 38 | ////////////////////////////////////////////////////////////////////////// 39 | // HVAC Zone Points 40 | ////////////////////////////////////////////////////////////////////////// 41 | 42 | -------------------------------------------------------------------------- 43 | def: ^hvacZonePoints 44 | is: ^pointGroup 45 | doc: 46 | Entity with logical grouping of zone HVAC air points. 47 | See `docHaystack::Zones#hvac` chapter. 48 | children: [ 49 | {zone air hvacMode sp point}, 50 | {zone air temp sensor point}, 51 | {zone air temp effective sp point}, 52 | {zone air temp effective cooling sp point}, 53 | {zone air temp effective heating sp point}, 54 | {zone air temp occ cooling sp point}, 55 | {zone air temp occ heating sp point}, 56 | {zone air temp unocc cooling sp point}, 57 | {zone air temp unocc heating sp point}, 58 | {zone air temp standby cooling sp point}, 59 | {zone air temp standby heating sp point}, 60 | {zone air pressure sensor point}, 61 | {zone air pressure sp point}, 62 | {zone air humidity sensor point}, 63 | {zone air humidity sp point}, 64 | {zone air dewPoint sensor point}, 65 | {zone air dewPoint sp point}, 66 | {zone air enthalpy sensor point}, 67 | {zone air enthalpy sp point}, 68 | ] 69 | -------------------------------------------------------------------------- 70 | def: ^thermostat 71 | is: [^equip, ^hvacZonePoints] 72 | wikipedia: `https://en.wikipedia.org/wiki/Thermostat` 73 | doc: 74 | Senses and controls temperature of space in HVAC system. Thermostats 75 | may provide an interface for setpoint control. 76 | -------------------------------------------------------------------------- 77 | 78 | ////////////////////////////////////////////////////////////////////////// 79 | // Air Quality 80 | ////////////////////////////////////////////////////////////////////////// 81 | 82 | -------------------------------------------------------------------------- 83 | def: ^airQualityZonePoints 84 | is: ^pointGroup 85 | doc: 86 | Entity with logical grouping of zone air quality points. 87 | See `docHaystack::Zones#airQuality` chapter. 88 | children: [ 89 | {zone air ch2o concentration sensor point}, 90 | {zone air co concentration sensor point}, 91 | {zone air co2 concentration sensor point}, 92 | {zone air co2 concentration sp point}, 93 | {zone air nh3 concentration sensor point}, 94 | {zone air no2 concentration sensor point}, 95 | {zone air o3 concentration sensor point}, 96 | {zone air pm01 concentration sensor point}, 97 | {zone air pm10 concentration sensor point}, 98 | {zone air pm25 concentration sensor point}, 99 | {zone air tvoc concentration sensor point}, 100 | ] 101 | -------------------------------------------------------------------------- 102 | 103 | ////////////////////////////////////////////////////////////////////////// 104 | // Lighting Zone Points 105 | ////////////////////////////////////////////////////////////////////////// 106 | 107 | -------------------------------------------------------------------------- 108 | def: ^lightingZonePoints 109 | is: ^pointGroup 110 | doc: 111 | Entity with logical grouping of lighting points. 112 | See `docHaystack::Zones#lighting` chapter. 113 | children: [ 114 | {light level sensor point}, 115 | {light level sp point}, 116 | {light illuminance sensor point}, 117 | {light luminous flux sensor point}, 118 | ] 119 | -------------------------------------------------------------------------- 120 | 121 | 122 | -------------------------------------------------------------------------------- /src/phScience/build.fan: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env fan 2 | // 3 | // Copyright (c) 2018, Project-Haystack 4 | // Licensed under the Academic Free License version 3.0 5 | // 6 | // History: 7 | // 25 Dec 2018 Brian Frank Creation 8 | // 9 | 10 | using build 11 | 12 | ** 13 | ** Build: phScience 14 | ** 15 | class Build : BuildPod 16 | { 17 | new make() 18 | { 19 | podName = "phScience" 20 | summary = "Project Haystack scientific definitions" 21 | meta = ["org.name": "Project Haystack", 22 | "org.uri": "https://project-haystack.org/", 23 | "proj.name": "Project Haystack Defs", 24 | "license.name": "Academic Free License 3.0", 25 | "vcs.name": "Git", 26 | "vcs.uri": "https://github.com/Project-Haystack/haystack-defs", 27 | ] 28 | resDirs = [`lib/`] 29 | index = [ "ph.lib": "phScience"] 30 | } 31 | } -------------------------------------------------------------------------------- /src/phScience/lib/lib.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2018, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 25 Dec 2018 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^lib:phScience 11 | doc: "Project Haystack scientific definitions" 12 | version: "3.9.15" 13 | baseUri: `https://project-haystack.org/def/phScience/` 14 | depends: [^lib:ph] 15 | ------------------------------------------------------------------------ -------------------------------------------------------------------------------- /src/phScience/lib/misc.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2018, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 25 Dec 2018 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^angle 11 | is: ^marker 12 | doc: "Measurement of the relative difference in direction between two vectors or phasors" 13 | -------------------------------------------------------------------------- 14 | def: ^avg 15 | is: ^marker 16 | doc: "Average; central or typical value; median" 17 | -------------------------------------------------------------------------- 18 | def: ^apparent 19 | is: ^marker 20 | doc: "Perceived quantity" 21 | -------------------------------------------------------------------------- 22 | def: ^atmospheric 23 | is: ^marker 24 | doc: "Related to the atmosphere of the earth" 25 | -------------------------------------------------------------------------- 26 | def:^co2e 27 | is: ^marker 28 | wikipedia: `https://en.wikipedia.org/wiki/Global_warming_potential` 29 | doc: "Carbon dioxide equivalent" 30 | -------------------------------------------------------------------------- 31 | def: ^current 32 | is: ^marker 33 | doc: "Movement of fluid or electricity" 34 | -------------------------------------------------------------------------- 35 | def: ^flux 36 | is: ^marker 37 | doc: "Measurement through a given surface" 38 | -------------------------------------------------------------------------- 39 | def: ^intensity 40 | is: ^marker 41 | doc: "Measure of an electromagnetic field" 42 | -------------------------------------------------------------------------- 43 | def: ^luminous 44 | is: ^marker 45 | doc: "Relating to light as perceived by the eye" 46 | -------------------------------------------------------------------------- 47 | def: ^magnitude 48 | is: ^marker 49 | doc: "Size or extent" 50 | -------------------------------------------------------------------------- 51 | def: ^quality 52 | is: ^marker 53 | doc: "Quantity measured against standard metric" 54 | -------------------------------------------------------------------------- 55 | def: ^total 56 | is: ^marker 57 | doc: "Complete or absolute" 58 | -------------------------------------------------------------------------- 59 | def: ^velocity 60 | is: ^marker 61 | doc: "Speed in a given direction" 62 | -------------------------------------------------------------------------- 63 | def: ^volt 64 | is: ^marker 65 | doc: "Electrical potential difference or electromotive force." 66 | -------------------------------------------------------------------------- 67 | 68 | -------------------------------------------------------------------------------- /src/phScience/lib/phenomenon.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2018, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 23 Dec 2018 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^phenomenon 11 | is: ^marker 12 | docTaxonomy 13 | doc: "Aspect of scientific interest with measurable quantities" 14 | -------------------------------------------------------------------------- 15 | def: ^elec 16 | is: ^phenomenon 17 | wikipedia: `https://en.wikipedia.org/wiki/Electricity` 18 | doc: 19 | Associated with electricity or with electrical force, power, or energy. 20 | This is often opposed to `mech` mechanical energy. 21 | -------------------------------------------------------------------------- 22 | def: ^light 23 | is: ^phenomenon 24 | wikipedia: `https://en.wikipedia.org/wiki/Light` 25 | doc: "Electromagnetic radiation in the visible spectrum" 26 | -------------------------------------------------------------------------- 27 | def: ^solar 28 | is: ^phenomenon 29 | doc: "Relating to energy from the sun" 30 | -------------------------------------------------------------------------- 31 | def: ^wind 32 | is: ^phenomenon 33 | wikipedia: `https://en.wikipedia.org/wiki/Wind` 34 | doc: "Flow of air on surface of the Earth" 35 | -------------------------------------------------------------------------- 36 | def: ^weather 37 | is: ^phenomenon 38 | wikipedia: `https://en.wikipedia.org/wiki/Weather` 39 | doc: 40 | Associated with atmospheric air or phenomenon. 41 | See `docHaystack::Weather` chapter. 42 | -------------------------------------------------------------------------- 43 | 44 | -------------------------------------------------------------------------------- /src/phScience/lib/substance.trio: -------------------------------------------------------------------------------- 1 | // 2 | // Copyright (c) 2018, Project-Haystack 3 | // Licensed under the Academic Free License version 3.0 4 | // 5 | // History: 6 | // 23 Dec 2018 Brian Frank Creation 7 | // 8 | 9 | -------------------------------------------------------------------------- 10 | def: ^substance 11 | is: ^phenomenon 12 | wikipedia: `https://en.wikipedia.org/wiki/Matter` 13 | doc: "Matter in one the three states solid, liquid, or gas" 14 | -------------------------------------------------------------------------- 15 | def: ^solid 16 | is: ^substance 17 | wikipedia: `https://en.wikipedia.org/wiki/Solid` 18 | doc: "Substance with definite shape and volume" 19 | -------------------------------------------------------------------------- 20 | def: ^fluid 21 | is: ^substance 22 | wikipedia: `https://en.wikipedia.org/wiki/Fluid` 23 | doc: "Liquid or gas" 24 | -------------------------------------------------------------------------- 25 | def: ^liquid 26 | is: ^fluid 27 | wikipedia: `https://en.wikipedia.org/wiki/Liquid` 28 | doc: "Substance with definite volume but takes the shape of its container" 29 | -------------------------------------------------------------------------- 30 | def: ^gas 31 | is: ^fluid 32 | wikipedia: `https://en.wikipedia.org/wiki/Gas` 33 | doc: "Substance with neither definite volume nor shape" 34 | -------------------------------------------------------------------------- 35 | def: ^ice 36 | is: ^solid 37 | wikipedia: `https://en.wikipedia.org/wiki/Ice` 38 | doc: "Water in its solid form" 39 | -------------------------------------------------------------------------- 40 | def: ^water 41 | is: ^liquid 42 | wikipedia: `https://en.wikipedia.org/wiki/Water` 43 | doc: "Water in its liquid form" 44 | -------------------------------------------------------------------------- 45 | def: ^steam 46 | is: ^gas 47 | wikipedia: `https://en.wikipedia.org/wiki/Steam` 48 | doc: "Water in its gas form" 49 | -------------------------------------------------------------------------- 50 | 51 | --------------------------------------------------------------------------------