Reference · built on requestConnectorIndustrial & building protocols

Project Haystack

Sites, equipment, points, and histories from any building system that speaks the Haystack HTTP API and tagging model.

Request accessPricing ↗

About

Project Haystack is an open source suite for modeling building and IoT data, licensed under the Academic Free License 3.0. Its ontology tags entities as site, space, equip, point, and device, linked by siteRef, equipRef, and spaceRef. A point is a sensor, cmd, or sp of kind Number, Bool, or Str, and carries cur, his, and writable markers for live value, history, and priority array. Data travels as grids in Zinc, JSON, Trio, CSV, or RDF.

Through Fibric, a connector calls a Haystack server's HTTP ops: read, nav, watchSub, hisRead. An operator watches points and histories and proposes a pointWrite or an invokeAction for your approval.

This is a reference listing. It documents what Fibric would read from Project Haystack and what it could propose, based on the vendor's published interfaces. Fibric builds it under a managed deployment when you request it; selecting it here installs nothing.

Inputs

  • Entities by filter or by id through the read op, for example every point whose equipRef names one air handler
  • Current values and status of points: curVal, curStatus, and curErr
  • Histories through hisRead with ranges such as today, yesterday, a date, or a dateTime span, in single or batch form
  • Changes to watched entities through watchSub, watchPoll, and watchUnsub with a leased watchId
  • The priority array of a writable point, read with pointWrite by id: level, levelDis, val, and who
  • Server identity and time zone from the about op, and the project tree from nav

Proposed actions

  • Target capability: propose a pointWrite with id, level 1 to 17, val, who, and an optional duration, on a point tagged writable
  • Target capability: propose an invokeAction on a record, naming the action and its arguments
  • Target capability: propose a hisWrite that posts ts and val rows to a historized point you own

Proposed actions are target capabilities. Every action runs propose-first and needs a validated deployment and the appropriate permissions.

What you can build

  • Setpoints that no longer match the schedule

    Points tagged sp under each zone are read each cycle and compared with their schedule. The operator proposes a pointWrite at level 8 for a drifted zone and puts the priority array state in the receipt.

    With Setpoint Drift

  • Check the economizer before summer

    Outside air, mixed air, and damper cmd histories from hisRead show whether an air handler economizes when conditions allow. The operator flags units that never open the damper.

    With Economizer Check

  • Sensors that read flat

    A sensor whose curStatus is down or fault, or whose history stops changing, is listed with its equip and site. The operator proposes a work order for each.

    With Sensor Health

  • Compare buildings on the same tags

    Because every site models meters and points with the same tags, the operator can total energy per site from hisRead and rank sites by the floor area you provide.

    With Site Benchmark

Requirements

  • A server that implements the Haystack HTTP API, with a base URI such as /haystack/ and the ops you need listed by its ops op
  • A user account for the connector; SCRAM is mandatory on compliant servers, and PLAINTEXT is allowed only over TLS
  • Points tagged writable for any write proposal, since pointWrite targets points with that tag
  • Consistent tagging, so filters on equipRef and siteRef resolve to the equipment you mean
Authentication
The Haystack authentication flow: a HELLO handshake, then SCRAM with SHA-256 or SHA-512, which every compliant server must support, yielding an authToken sent as Authorization: BEARER on each request.

Limits

  • Haystack defines the model and the API; how much of a building is exposed depends on the server product and its tagging
  • The response of invokeAction is undefined by the specification, so the connector records the call rather than a result
  • Request errors return HTTP 200 with an err grid; only transport failures use 4xx and 5xx codes
  • A watch lapses at the end of its lease unless polled, so a paused connector must subscribe again

Access and pricing

Reference listing. Fibric builds the connector under a managed deployment when you request it. Your quote covers the build, capabilities, usage, and support.

Request Project Haystack ↗

Questions and answers

What does a Haystack request look like?
A client sends one grid to http://server/haystack/{op} and receives one grid. Ops marked noSideEffects, such as read and hisRead, accept GET with query parameters; others use POST. The default encoding is text/zinc, with application/json, text/trio, text/csv, and text/turtle also standardized.
How does the connector write a point?
With the pointWrite op. The request names the point id, a level from 1 to 17, the val, an optional who, and an optional duration. Level 1 is emergency override, level 8 is manual override, and level 17 is the relinquish default.
Who maintains Project Haystack?
Project Haystack publishes its documentation, tag definitions, and file formats on project-haystack.org under the Academic Free License 3.0. The current documentation describes Haystack 4, whose defs mechanism lets the ontology be extended.
Ask about Project Haystack

Ask about the capabilities and requirements in this listing.

For project-specific requirements, contact Fibric.

This connector listing is developed, published, and supported by Fibric. It describes integration with Project Haystack through published interfaces. Third-party names and logos identify the systems an integration connects to; they are the property of their respective owners, who are not affiliated with Fibric and do not sponsor or endorse this listing. Trademark policy