hexabus

README

Hexabus Go

libhexabus go port

Documentation

Overview

Hexabus is the go implementation of the Hexabus packet format used by Hexabus devices. For more info see https://github.com/mysmartgrid/hexabus.

Index

• Constants
• func PacketType(packet []byte) (ptype byte, err error)
• type DateTime
  • func (d *DateTime) Decode(data interface{}) (err error)
• type EID
  • func QueryEids(address string, eid_qty uint16) ([]EID, error)
• type EpInfoPacket
  • func (p *EpInfoPacket) Decode(packet []byte) (err error)
  • func (p *EpInfoPacket) Encode() (packet []byte, err error)
• type EpQueryPacket
  • func (p *EpQueryPacket) Decode(packet []byte) (err error)
  • func (p *EpQueryPacket) Encode() []byte
  • func (p EpQueryPacket) Send(address string) ([]byte, error)
• type Error
  • func (e Error) Error() string
• type ErrorPacket
  • func (p *ErrorPacket) Decode(packet []byte) (err error)
  • func (p *ErrorPacket) Encode() []byte
• type InfoPacket
  • func (p *InfoPacket) Decode(packet []byte) (err error)
  • func (p *InfoPacket) Encode() (packet []byte, err error)
• type QueryPacket
  • func (p *QueryPacket) Decode(packet []byte) (err error)
  • func (p *QueryPacket) Encode() []byte
  • func (p QueryPacket) Send(address string) ([]byte, error)
• type Timestamp
  • func (t *Timestamp) Decode(data interface{}) (err error)
• type WritePacket
  • func (p *WritePacket) Decode(packet []byte) (err error)
  • func (p *WritePacket) Encode() (packet []byte, err error)
  • func (p WritePacket) Send(address string) error

Constants

const (
	// encoder/decoder errors
	ERR_STRBUFF   = 0xa0
	ERR_STRNOTERM = 0xa1
	ERR_BYTESIZE  = 0xa2
	ERR_HXBDTYPE  = 0xa3
	ERR_BOOLTYPE  = 0xa4
	ERR_CRCFAILED = 0xa5

	// network errors
	ERR_WRONGHEADER  = 0xb0
	ERR_UNKNOWNPTYPE = 0xb1
	ERR_ERRPACKET    = 0xb2
)

Internal error codes.

const (

	// The UDP Data of a Hexabus Packet starts with the Bytes 0x48 0x58 0x30 0x43
	// (HX0C) to identify it as a Hexabus Packet
	HEADER0, HEADER1, HEADER2, HEADER3 = 0x48, 0x58, 0x30, 0x43

	// boolean false
	FALSE = 0x00

	// boolean true
	TRUE = 0x01

	// Hexabus Error Packet
	// An error occured -- check the error code field for more information
	PTYPE_ERROR = 0x00

	// Hexabus Info Packet
	// Endpoint provides information
	PTYPE_INFO = 0x01

	// Hexabus Query Packet
	// Endpoint is requested to provide information
	PTYPE_QUERY = 0x02

	// Hexabus Write Packet
	// Endpoint is requested to set its value
	PTYPE_WRITE = 0x04

	// Hexabus EpInfo Packet
	// Endpoint metadata
	PTYPE_EPINFO = 0x09

	// Hexabus EpQuery Packet
	// Request endpoint metadata
	PTYPE_EPQUERY = 0x0a

	// Hexabus Flag "No Flag set"
	FLAG_NONE = 0x00

	// Hexabus Data Type "No data at all"
	DTYPE_UNDEFINED = 0x00

	// Data type Bool
	DTYPE_BOOL = 0x01

	// Data type uint8
	DTYPE_UINT8 = 0x02

	// Data type uint32
	DTYPE_UINT32 = 0x03

	// Data type date/time
	DTYPE_DATETIME = 0x04

	// Data type float
	DTYPE_FLOAT = 0x05

	// Data type 128String
	// char string with 128 bytes, must be 0 terminated
	DTYPE_128STRING = 0x06
	// max char length = 127 + 0 termination
	STRING_PACKET_MAX_BUFFER_LENGTH = 127

	// Data type timestamp
	// in secondes since device was booted up, 32 bit unsigned integer (4 bytes)
	DTYPE_TIMESTAMP = 0x07

	// Data type 16bytes
	// 16 bytes of raw binary data
	DTYPE_16BYTES = 0x09
	// max byte length = 16 bytes
	BYTES16_PACKET_MAX_BUFFER_LENGTH = 16

	// Data type 66bytes
	// 66 bytes of raw binary data
	DTYPE_66BYTES = 0x08
	// max byte 65 bytes DATA TYPE name is a typo since this type is
	// used by the statemachine upload only, and that is 65 bytes
	BYTES66_PACKET_MAX_BUFFER_LENGTH_ = 65

	// reserved: No error
	HXB_ERR_SUCCESS = 0x00

	// A request for an endpoint which does not exist on the device was received
	HXB_ERR_UNKNOWNEID = 0x01

	// WRITE was received for a readonly endpoint
	HXB_ERR_WRITEREADONLY = 0x02

	// A packet failed the CRC check
	// TODO How can we find out what information was lost?
	HXB_ERR_CRCFAILED = 0x03

	// A packet with a datatype that does not fit the endpoint was received
	HXB_ERR_DATATYPE = 0x04

	// A value was encountered that cannot be interpreted
	HXB_ERR_INVALID_VALUE = 0x05

	// lib hexabus version
	VERSION = "1.0.0 beta"
)

Constants used inside Hexabus packets. They describe various packet types, data types and error responses. As well as the four header bytes, Hexabus bool type representation and paket flags.

const (
	// hexabus default port
	PORT = "61616"

	// package transmit timeout
	NET_TIMEOUT = 3
)

Defaults used by the network communication.

Functions

func PacketType

func PacketType(packet []byte) (ptype byte, err error)

Types

type DateTime

type DateTime struct {
	Hours     uint8
	Minutes   uint8
	Seconds   uint8
	Day       uint8
	Month     uint8
	Year      uint16
	DayOfWeek uint8
}

struct to hold DTYPE_DATETIME

func (*DateTime) Decode

func (d *DateTime) Decode(data interface{}) (err error)

decodes the payload from a datetime packet into a DateTime structure takes as argument a Packet.Data interface{}

type EID

type EID struct {
	Eid      uint32 // Eid
	Dtype    byte   // data type
	Desc     string // description
	Writable bool   // writeable
}

structure to hold all EID's of a hexabus device and its capabilities

func QueryEids

func QueryEids(address string, eid_qty uint16) ([]EID, error)

type EpInfoPacket

type EpInfoPacket struct {
	// 4 bytes header
	// 1 byte packet type
	Flags byte        // 1 byteflags
	Eid   uint32      // 4 bytes endpoint id
	Dtype byte        // 1 byte data type
	Data  interface{} // ... bytes payload, size depending on datatype
}

Hexabus Endpoint Info Package this is a response packet to Endpoint Query and holds the EID Dtype and a message that describes that endpoint in Data

func (*EpInfoPacket) Decode

func (p *EpInfoPacket) Decode(packet []byte) (err error)

decoder for Endpoint Info Packet

func (*EpInfoPacket) Encode

func (p *EpInfoPacket) Encode() (packet []byte, err error)

encoder for Endpoint Info Packet

type EpQueryPacket

type EpQueryPacket struct {
	// 4 bytes header
	// 1 byte packet type
	Flags byte   // flags
	Eid   uint32 // endpoint id
}

Hexabus Endpoint Query Packet used to query endpoints for a data ytpe and a short description

func (*EpQueryPacket) Decode

func (p *EpQueryPacket) Decode(packet []byte) (err error)

decoder for Endpoint Query Packet

func (*EpQueryPacket) Encode

func (p *EpQueryPacket) Encode() []byte

encoder for Endpoint Query Packet

func (EpQueryPacket) Send

func (p EpQueryPacket) Send(address string) ([]byte, error)

type Error

type Error int

Error type structure to hold err.id. err.msg and optional err.err.

func (Error) Error

func (e Error) Error() string

Error returns an error type. All Errors are passed with ID and MSG and optional an err type from other packages.

type ErrorPacket

type ErrorPacket struct {
	// 4 bytes header
	// 1 byte packet type
	Flags byte // 1 byte flags
	Error byte // 1 byte error code
}

Hexabus Error Packet if a packet os malformed or doesn't the EID is not properly used it will return a error of type ERR_UNKNOWNEID, ERR_WRITEREADONLY, ERR_CRCFAILED, ERR_DATATYPE or ERR_INVALID_VALUE

func (*ErrorPacket) Decode

func (p *ErrorPacket) Decode(packet []byte) (err error)

decoder for Error Packet

func (*ErrorPacket) Encode

func (p *ErrorPacket) Encode() []byte

encoder for Error Packet

type InfoPacket

type InfoPacket struct {
	// 4 bytes header
	// 1 byte packet type
	Flags byte        // 1 byteflags
	Eid   uint32      // 4 bytes endpoint id
	Dtype byte        // 1 byte data type
	Data  interface{} // ... bytes payload, size depending on datatype
}

Hexabus Info Packet Info Packets are send after a Query Packet or Broadcasted every n seconds

func (*InfoPacket) Decode

func (p *InfoPacket) Decode(packet []byte) (err error)

decoder for Info Packet

func (*InfoPacket) Encode

func (p *InfoPacket) Encode() (packet []byte, err error)

encoder for Info Packet

type QueryPacket

type QueryPacket struct {
	// 4 bytes header
	// 1 byte packet type
	Flags byte   // flags
	Eid   uint32 // endpoint id
}

Hexabus Query Packet used to query endpoints to return an Info Packet

func (*QueryPacket) Decode

func (p *QueryPacket) Decode(packet []byte) (err error)

decoder for Query Packet

func (*QueryPacket) Encode

func (p *QueryPacket) Encode() []byte

encoder for Query Packet

func (QueryPacket) Send

func (p QueryPacket) Send(address string) ([]byte, error)

type Timestamp

type Timestamp struct {
	TotalSeconds uint32
}

struct to hold DTYPE_TIMESTAMP

func (*Timestamp) Decode

func (t *Timestamp) Decode(data interface{}) (err error)

decodes the payload from a timestamp packet into a Timestamp structure takes as argument a Packet.Data interface{}

type WritePacket

type WritePacket struct {
	// 4 bytes header
	// 1 byte packet type
	Flags byte        // flags
	Eid   uint32      // endpoint id
	Dtype byte        // data type
	Data  interface{} // payload, size depending on datatype
}

Hexabus Write Packet used to set a writeable entpoint id to a certain value, there is no response for that o other than an Error Packet on fail

func (*WritePacket) Decode

func (p *WritePacket) Decode(packet []byte) (err error)

decoder for Write Packet

func (*WritePacket) Encode

func (p *WritePacket) Encode() (packet []byte, err error)

encoder for Write Packet

func (WritePacket) Send

func (p WritePacket) Send(address string) error