TOC

  1. Intro
  2. TagModel
  3. Structure
  4. TimeZones
  5. Units
  6. Grids
  7. Filters
  8. Zinc
  9. Json
  10. Trio
  11. Csv
  12. Rest
  13. Ops
  14. Auth
  15. VFDs
  16. Networks
  17. Energy
  18. Zones
  19. AHUs
  20. VAVs
  21. UnitaryEquips
  22. Chillers
  23. Boilers
  24. Tanks
  25. ElecPanels
  26. Lighting
  27. Builds
    1. Overview
    2. Setup
    3. Organization
    4. Design
    5. Doc Format
    6. Tag Format
  28. Bacnet
  29. ChangeLog
  30. License

Builds

Overview

The source code for documentation and this website is managed as a Mercurial repository on BitBucket. Each official Haystack version is packaged as a self contained zip file which can be downloaded from the Downloads tab. Each build file provides:

  1. source code for all documentation and tag definitions
  2. ability to run website locally
  3. build script to rebuild docs from source

Setup

Source code and build scripts are written in the Fantom programming language. You will need a Java VM installed to run the website locally or rebuild from source. Once a build is download, the easiest way to run is by calling the bin/fan launch script.

// cd to the dir where you installed the build
cd ~/haystack-2.0.9/

// to run website on your local machine
bin/fan haystackws

// run on a port other than 8080
bin/fan haystackws -port 8081

// rebuild from source
bin/fan src/build.fan

See Fantom Setup Docs for more information on setting up and trouble shooting your Fantom environment.

Organization

Builds are organized with the following directory structure:

bin/            // launch scripts
etc/            // config files, unit/tz databases
lib/            // runtime modules
  fan/          // Fantom pod files
  java/         // Java runtime for Fantom
src/            // top level dir for source code
  build.fan     // top level build script
  haystackws/   // source code for the haystackws pod
    docs/       // chapter source in fandoc format
    equips/     // equip points in plain text
    fan/        // Fantom source code for website
    locale/     // localized translations of tags
    res/        // CSS, image resource files
    tags/       // tag definitions in Trio format

The website itself and all the documentation is primarily sourced into a single pod named haystackws. The website is built upon the Fantom runtime and a web framework nicknamed sidewalk. These dependencies are included in binary form in lib/fan.

Design

The overall design of the website is as follows:

  1. Main: bootstrap code which loads library and launches web service
  2. HaystackLoader: loads source docs and tags and compiles into Lib
  3. Html: suite of renderers used by loader to generate HTML
  4. Lib: set of immutable data structures and HTML for compiled docs and tags

Doc Format

Documentation is written as plain text formatted as fandoc.

Fandoc hyperlinks are used liberally. The following link formats are supported:

Tag Format

Tag definitions are plain text formatted as Trio files. Each tag is itself defined as a set of tags:

Here is an example for maxVal:

tag: maxVal
kind: Number
alsoSee: minVal, curVal
usedWith: point
docInclude: Structure#pointMinMax
doc:
  Applied to `point` to define the maximum value to read from a sensor
  or to write from a command/setpoint. This value's unit must match
  the point's `unit` tag.