gohaystack

README

gohaystack

This is a toy library to play with Project Haystack in Go. It only relies on Go's standard library.

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

What's included

This library is rather incomplete, as I am using it only for testing purpose (discovering haystack, building a sample server, and transform data from a format to another) This library has a Grid structure that can be (de)serialized to and from haystack format in JSON (no zinc yet). The Grid hold an array of Entity. An Entity has an id (format HaystackID which is a pointer to a string) a Dis field (a string used for display purpose) and a hash map of tags.

a tag is a composition of a *Label and a *Value

Please, see the API documentation for more information.

Haystack kind	JSON Serialize	JSON Deserialize	Zinc Serialize	Zinc Deserialize
Grid	x	x
List	x	x
Dict	x	x
Null	x	x
Bool	x	x
Marker	x	x
Remove	x	x
NA	x	x
Number	x	x
Ref	x	x
Str	x	x
Date	x	x
Time	x	x
DateTime	x	x
URI	x	x
Coord	x	x
Xstr

Haystack tags package

the tags subpackage contains the label and values definitions of the official haystack project tag list. This package is a commodity.

Example

Basic example

Generate a grid and add simple values:

g := NewGrid()
myTagLabel := NewLabel("mytag")
myTagSite := NewLabel("site")
myTagLabel.Display = "the display"
mySite := NewHaystackID("myreference")
entity := g.NewEntity(mySite)
myTagValue := NewStr("foo")
entity.SetTag(myTagLabel, myTagValue)
entity.SetTag(myTagSite, MarkerValue)

JSON

Generate a grid from a json payload:

g := grid.NewGrid()
dec := json.NewDecoder(os.Stdin)
err := dec.Decode(&g)
if err != nil {
    log.Fatal(err)
}

Complete example

the example/graph contains a CLI tool that reads a JSON encoded haystack grid from stdin and generates a dot compatible representation on stdout.

Caution

This is a toy project given without any warranty. I made it for my own need to discover haystack. If you want to take over the maintenance, feel free to contact me.

Documentation

Index

• Variables
• type Entity
  • func (e *Entity) GetID() *HaystackID
  • func (e *Entity) GetTags() map[*Label]*Value
  • func (e *Entity) SetTag(l *Label, v *Value)
• type Grid
  • func NewGrid() *Grid
  • func (g *Grid) GetEntities() []*Entity
  • func (g *Grid) GetEntityByID(id *HaystackID) *Entity
  • func (g *Grid) MarshalJSON() ([]byte, error)
  • func (g *Grid) NewEntity(id *HaystackID) *Entity
  • func (g *Grid) UnmarshalJSON(b []byte) error
• type HaystackID
  • func NewHaystackID(s string) *HaystackID
• type Kind
• type Label
  • func NewLabel(s string) *Label
• type Unit
  • func NewUnit(u string) Unit
• type Value
  • func NewNumber(value float32, unit Unit) *Value
  • func NewRef(r *HaystackID) *Value
  • func NewStr(s string) *Value
  • func NewURL(u *url.URL) *Value
  • func (v *Value) GetHaystackID() (*HaystackID, error)
  • func (v *Value) GetKind() Kind
  • func (v *Value) GetString() (string, error)
  • func (v *Value) MarshalJSON() ([]byte, error)
  • func (v *Value) UnmarshalJSON(b []byte) error

Examples

• Grid

Variables

var MarkerValue = &Value{
	kind: HaystackTypeMarker,
}

MarkerValue ...

Types

type Entity

type Entity struct {
	Dis string // Dis is public because it is mutable
	// contains filtered or unexported fields
}

An Entity is an abstraction for some physical object in the real world. Entity carries its tags and an ID

func (*Entity) GetID

func (e *Entity) GetID() *HaystackID

GetID of the entity

func (*Entity) GetTags

func (e *Entity) GetTags() map[*Label]*Value

GetTags from entity

func (*Entity) SetTag

func (e *Entity) SetTag(l *Label, v *Value)

SetTag for the entity. No check is done and any existing label is silently overwritten.

type Grid

type Grid struct {
	Meta map[string]string
	// contains filtered or unexported fields
}

Grid is a simple database structure, column based

Example

g := NewGrid()
myTagLabel := NewLabel("mytag")
myTagSite := NewLabel("site")
myTagLabel.Display = "the display"
mySite := NewHaystackID("myreference")
entity := g.NewEntity(mySite)
myTagValue := NewStr("foo")
entity.SetTag(myTagLabel, myTagValue)
entity.SetTag(myTagSite, MarkerValue)
// Do something with the grid ... :D
// ...
// Encode it in json
enc := json.NewEncoder(os.Stdout)
err := enc.Encode(g)
if err != nil {
	log.Fatal(err)
}

func NewGrid

func NewGrid() *Grid

NewGrid creates an empty grid

func (*Grid) GetEntities

func (g *Grid) GetEntities() []*Entity

GetEntities from the grid

func (*Grid) GetEntityByID

func (g *Grid) GetEntityByID(id *HaystackID) *Entity

GetEntityByID returns the entity identified by id, or nil if nothing is found if a grid has two elements with the same ID (there is no fence to protect from that), only the first one is returned

func (*Grid) MarshalJSON

func (g *Grid) MarshalJSON() ([]byte, error)

MarshalJSON in haystack compatible format

func (*Grid) NewEntity

func (g *Grid) NewEntity(id *HaystackID) *Entity

NewEntity identified by id. it returns an error if the ID is already taken. It is the responsibility of the caller to ensure that the ID does not exists yet in the grid.

func (*Grid) UnmarshalJSON

func (g *Grid) UnmarshalJSON(b []byte) error

UnmarshalJSON turns a JSON encoded grid into a Grid object

type HaystackID

type HaystackID string

HaystackID is a Unique identifier for an entity. see https://www.project-haystack.org/doc/TagModel#Id

func NewHaystackID

func NewHaystackID(s string) *HaystackID

NewHaystackID from string s

type Kind

type Kind int

Kind is a supported type for a haystack value

const (
	// HaystackTypeUndefined ...
	HaystackTypeUndefined Kind = iota
	// HaystackTypeGrid is a Grid object
	HaystackTypeGrid
	// HaystackTypeList Array
	HaystackTypeList
	// HaystackTypeDict Object
	HaystackTypeDict
	// HaystackTypeNull null
	HaystackTypeNull
	// HaystackTypeBool Boolean
	HaystackTypeBool
	// HaystackTypeMarker "m:"
	HaystackTypeMarker
	// HaystackTypeRemove "-:"
	HaystackTypeRemove
	// HaystackTypeNA "z:"
	HaystackTypeNA
	// HaystackTypeNumber "n:<float> [unit]" "n:45.5" "n:73.2 °F" "n:-INF"
	HaystackTypeNumber
	// HaystackTypeRef "r:<id> [dis]"  "r:abc-123" "r:abc-123 RTU #3"
	HaystackTypeRef
	// HaystackTypeStr "hello" "s:hello"
	HaystackTypeStr
	// HaystackTypeDate "d:2014-01-03"
	HaystackTypeDate
	// HaystackTypeTime "h:23:59:00"
	HaystackTypeTime
	// HaystackTypeDateTime "t:2015-06-08T15:47:41-04:00 New_York"
	HaystackTypeDateTime
	// HaystackTypeURI "u:http://project-haystack.org/"
	HaystackTypeURI
	// HaystackTypeCoord "c:<lat>,<lng>" "c:37.545,-77.449"
	HaystackTypeCoord
	//HaystackTypeXStr "x:Type:value"
	HaystackTypeXStr
	// HaystackLastType ...
	HaystackLastType
)

type Label

type Label struct {
	Value   string
	Display string
}

Label of a tag. Label is a string and for efficiency we are using pointer to Label in the entities

func NewLabel

func NewLabel(s string) *Label

NewLabel from string s

type Unit

type Unit *string

Unit represents a unit is a number

func NewUnit

func NewUnit(u string) Unit

NewUnit returns a new unit

type Value

type Value struct {
	// contains filtered or unexported fields
}

Value is an haystack value

func NewNumber

func NewNumber(value float32, unit Unit) *Value

NewNumber ...

func NewRef

func NewRef(r *HaystackID) *Value

NewRef new reference

func NewStr

func NewStr(s string) *Value

NewStr new string value

func NewURL

func NewURL(u *url.URL) *Value

NewURL ...

func (*Value) GetHaystackID

func (v *Value) GetHaystackID() (*HaystackID, error)

GetHaystackID Returns the underlying value of the reference

func (*Value) GetKind

func (v *Value) GetKind() Kind

GetKind of the underlying value

func (*Value) GetString

func (v *Value) GetString() (string, error)

GetString value; returns an error if the underlying type is not an haystack string

func (*Value) MarshalJSON

func (v *Value) MarshalJSON() ([]byte, error)

MarshalJSON encode the value in format compatible with haystack's JSON: https://www.project-haystack.org/doc/Json

func (*Value) UnmarshalJSON

func (v *Value) UnmarshalJSON(b []byte) error

UnmarshalJSON extract a value from b