Welcome to pyhaystack’s documentation!

pyhaystack Build status Coverage Documentation Gitter

What is this ?

Pyhaystack is a module that allow python programs to connect to a haystack server using semantic data model for buildings (project-haystack).

Browse a campus, building, floor… find VAV boxes, AHU units, etc. Then extract history data from them and get the results ready for analysis using pandas or your own database implementation.

Which clients are implemented ?

Actually, connection can be established with :

Connection to Niagara AX or Niagara 4 requires the nHaystack module by J2 Innovations to be installed and properly configured on your Jace. Refer to documentation of nHaystack for details.

How do I install pyhaystack ?

pip install pyhaystack

Or you can also git clone the develop branch and use

python setup.py install

Note

Some users reported problems when installing pyhaystack using the Python version provided by their OS (Mac OS users). We recommend to try the virtual environment approach when you are unsure about the python version our modules dependencies.

Using virtual env

You can find more information on how to use virtualenv_ but here is a short way of making it work.

sudo pip install virtualenv
mkdir your project folder
cd project
virtualenv venv
source venv/bin/activate

Note

Once you are in your virtual env DO NOT use sudo to pip install. (in fact, this is the part that made me think of permission issue as I read somewhere that we should never sudo pip install anything)

So now you are in your virtual env (it’s in parenthesis in the console) and you

pip install requests
pip install hszinc
pip install pyhaystack

(note that this time you won’t see any weird message when trying to install pandas and you need xcode to perform the install….) You are now able to

import hszinc
hszinc.MODE_ZINC
from pyhaystack.client.skyspark import SkysparkHaystackSession

What is project-haystack ?

As stated in the web site

Project Haystack is an open source initiative to streamline working with data from the Internet of Things. We standardize semantic data models and web services with the goal of making it easier to unlock value from the vast quantity of data being generated by the smart devices that permeate our homes, buildings, factories, and cities. Applications include automation, control, energy, HVAC, lighting, and other environmental systems.”

—Project-Haystack

Actual implementation

Pyhaystack is robust and will be ready for asynchronous development.

We have chosen a state machine approach with observer pattern. See the docs for more informations.

This implementation has been mostly supported by VRT and Servisys. We are hoping that more people will join us in our effort to build a well working open-source software that will open the door of building data analysis to Python users.

Dependency

Pyhaystack highly depends on hszinc which is a special parser for zinc encoded data. Zinc was created for project-haystack as a CSV replacement.

For analysis, we also suggest using Pint to deal with units. It will bring a lot of possibilities to pyhaystack (ex. unit conversion)

How to use it

Modules documentation

pyhaystack package

Subpackages

Submodules

pyhaystack.exception module

pyhaystack Custom exceptions

exception pyhaystack.exception.AuthenticationProblem

Bases: exceptions.Exception

exception pyhaystack.exception.HaystackError(message, traceback=None, *args, **kwargs)

Bases: exceptions.Exception

Exception thrown when an error grid is returned by the Haystack server. See http://project-haystack.org/doc/Rest#errorGrid

exception pyhaystack.exception.NoCookieReceived

Bases: exceptions.Exception

exception pyhaystack.exception.NoResponseFromServer

Bases: exceptions.Exception

exception pyhaystack.exception.ProblemReadingCookie

Bases: exceptions.Exception

exception pyhaystack.exception.ProblemSendingRequestToServer

Bases: exceptions.Exception

exception pyhaystack.exception.UnknownHistoryType

Bases: exceptions.Exception

pyhaystack.info module

File : pyhaystackTest.py (2.x) This module allow a connection to a haystack server Features provided allow user to fetch data from the server and eventually, to post to it.

See http://www.project-haystack.org for more details

Project Haystack is an open source initiative to streamline working with data from the Internet of Things. We standardize semantic data models and web services with the goal of making it easier to unlock value from the vast quantity of data being generated by the smart devices that permeate our homes, buildings, factories, and cities. Applications include automation, control, energy, HVAC, lighting, and other environmental systems.

Module contents

Main init file

Loading hszinc Creating “connect” shortcut for get_instance

This file will also automatically disable SubjectAltNameWarning when dealing with CA certificate. See docs for more information about that.

Indices and tables