#282 Need better, more complete examples

Chris Tacke Thu 28 May 2015

I'm working on a .NET SDK for Haystack, and I'm struggling from a lack of understanding. I think some better examples would really help clarify things.

For example, let's use the existing documentation of the "White House" with a single AHU containing a single air temp sensor. I have it figured out how those entities work, but I'm not at all clear on the current value of that temp sensor.

If I wanted to get the current value of all points in my site - no filtering at all, what would that REST request look like?

http://{haystack root}/read

Or something else?

And what would a response look like?

An example with say 2-3 points, and/or an example with 2-3 equips with 2-3 points each would really help in my understanding.

Brian Frank Thu 28 May 2015

Regarding the read op, the URI would be whatever the end point is + /read. In SkySpark it looks like http://host/api/demo/read, in NHaystack it looks like http://host/haystack/read.

The docs do have a complete example for the read op. Did you have a specific question? I would also suggest taking a look at some of the other open source implementations (look under downloads tab) - the Java toolkit is a good reference implementation.

jeremiah johnson Tue 5 Apr 2016

The lack of examples is a real issue. I'd love to use this, but I can't because I can't figure it out AT ALL. Given a simple example or two, I can usually work out the rest, but this is not a library that is well documented.

I do not need documentation on what a Grid looks like when it's serialized to Zinc. That is of no use to me at all.

Examples I'd like to see:

  • How to connect to a server and announce yourself as some kind of device.
  • How to tell the server you're, say, a current sensor, or a temperature sensor.
  • How to send readings to the server.
  • Is connecting to a server even the proper way to go if I have a device with a sensor attached?
  • How to create a server and store data from sensors.
  • How to forward data collected to some other Haystack-enabled device/service.
  • What is the proper architecture for a client/server setup?
  • Is this protocol a client/server protocol, or something else? Server-to-Server? Peer-to-Peer? All of the above?
  • How is communication handled when I have data on one device and I need to give it to another? Do I send it, or is it requested? Is it scheduled, or on demand? How do I set up a schedule, if it's scheduled? How do I send it on demand if I'm asked? How do I ask another device for data?

The documentation is EXCELLENT if I'm someone looking to port the library over to another language. I can easily find what each object is, what it's supposed to do, and how it does it. There is ZERO (that I can find) about how to actually USE this protocol, or any of the libraries I can find via project-haystack.org. There is no practical information of any kind, that I can find.

For two days I've looked in several sprints of 15 minutes, gotten frustrated, then switched to another task for a while so I can say that I've not wasted more time, then come back later.

I need practical examples. Working code. You pick the language, I don't care what language it is. Working code for setting up a temperature sensor in code, and sending that data off to some Haystack-enabled device. Or, if that's not how it works, setting up the Haystack enabled device to ask my sensor device for its sensor data.

If anyone reading this has produced code that actually performs work, please share it.

If anyone knows where I can find working-man's sample code, in any language, for this protocol, please link it here or email me. jeremiah.j.johnson at outlook.com


Thank you.

Brian Frank Wed 6 Apr 2016

Not sure exactly what want to do. Are you trying to connect to an existing system that supports Haystack? If so what system?

The two most common ways to work with sensor data is to just perform a read on the data, and there is a concrete example for that /doc/Ops#read. The second thing you do all the time is read or write historical sampled data, and there are examples for that to /doc/Ops#hisRead.

The simplest use case would be:

  1. learn what points are available via read point
  2. then read their collected history data via hisRead

You can do much more complicated stuff like subscriptions via watches (and we are lacking examples for that).

Sounds like you want working code, of which there are many different libraries you can try out - look under Downloads tab in Source Code (there are Java, Python, Dart, C++ implementations). The Java library is a complete client and server implementation (just have to plug it into some servlet engine and bind it to real data)

jeremiah johnson Wed 6 Apr 2016

I have a WattStopper device I'm trialing. The UI appears to be "InferStack" whatever that is. It supports Haystack.

I am creating devices that will have sensors attached. Different sensors will sense current, and temperature, for now. Some may have multiple sensors of the same or different types, some may have only one of either type or another type that I've not looked into yet, such as light levels.

The devices available in the UI currently (the commercial products) are logging current (both on/off as well as actual current consumption in different cases), temperature, and occupancy.

I want the devices I'm creating to appear in this dashboard in the same way that those devices do. I want to see graphs, I want to have historical data, etc.

Does that help?

I've seen all the libraries; it's the binding to real data that I have absolutely no clue how to do, and no code I can find demonstrates it.

John Petze Thu 7 Apr 2016

From your last description it sounds like you want to add your devices into the commercial product (Inferstack) which is the software product embedded in the Wattstopper product. I think your questions might be more related to how to use that commercial software with your devices than about the Haystack communications protocol at a low level. Would it make sense to contact them to learn a bit about the software product?

jeremiah johnson Thu 7 Apr 2016

I'm creating devices. They are Raspberry Pi devices which I control. I am writing the software for them.

I need to speak Haystack in order for my code on my devices to talk to the commercial product.

I can read the data from sensors. My question basically boils down to this: How in the world do I get that data into the commercial device? I clearly have many choices in terms of language in terms of the API, but I have absolutely no idea how to set up the connection to the commercial device, nor how to send data to the device, or make the data available for the device to query, if it works that way.

I could have (and should have) written my own protocol in the amount of time it's taken me to post here and wait for answers. I could have had a completely secure client server application written in the week I've been staring at the Haystack documentation. It would not be as robust as this protocol but I don't need it to be. I have very specific needs.

All I need is an example of how to send data from a sensor to this commercial product with Haystack, if it works that way, or make the data available for the commercial product to query, if it works that way. I don't even know which one it is, and I can't even find an answer on that.

Everything I can find talks about setting up the software as if it's already a given. I'm writing the software. I'm setting up the communication. There is no information on how to do this.

Again, all I'm asking for is simple example code.

At this point I am wondering if I am even speaking English. I am obviously not communicating my needs appropriately because no one has yet to understand what I'm after.

Brian Frank Thu 7 Apr 2016

Based on your description of your setup, your device would a Haystack server. At the very minimum you would want to implement the following operations:

  • about
  • read (see my previous post)

Then the supervising device would be setup to connect to your device and query which points are available and "learn" them.

In an ideal situation your own device would log the data on an interval basis, and then make the logged data available via the hisRead operation. The supervising device would then be configured to periodically sync the history data. This architecture has the advantage that no data is lost during network outages.

The alternative (or something to do in conjunction with history sync) is to provide a real-time feed of your sensor data. You do this by having your server implement the following ops:

  • watchSub
  • watchPoll
  • watchUnsub

I think maybe one impression that might be confusing you is that you "push" sensor data to the supervising device. You could potentially do that with the pointWrite op, but its probably not the architecture you want here since your device "owns" the sensor points.

I am not sure what capabilities of your device are, but if you can run Java then you should be able to put together a fairly complete server using the Java toolkit by adding something like Jetty and gluing the ops to your data via the HServer class. The code is already written.

I would also recommend working your vendor. They are the ones that will explain how to setup their devices and can give you guidance on various network push/pull designs.

Kurt Kavanaugh Thu 24 Feb

I agree with Jeremiah. An API is adoptable when it has real world examples. Like reading and writing points. The basics. And how the topology fits into a standard REST entity scheme. Like....

GET http://somehost/site/999MainStreet/salesFloor/temp

Would return

{ .... example: 72 }

A value, or value history, for the space temperature of a given area

What should the JSON, and/or URL look like when you use a POST, DELETE or PUT. Or should I say what does haystack recommend.

Jay Herron Sat 26 Feb

What should the JSON, and/or URL look like when you use a POST, DELETE or PUT

Maybe I'm misunderstanding, but that sounds like the examples given here

The Haystack API doesn't have a pathing style similar to your example of GET http://somehost/site/999MainStreet/salesFloor/temp. Instead it uses filters. So instead of the url above, you might have

GET http://somehost/haystack/read?filter=point and temp and floorRef->dis=="sales" and siteRef->dis=="999MainStreet"

I don't disagree with you, though. I think there's room for improvement in the documentation, especially around easing new users into the concepts.

Login or Signup to reply.