loxone

README

Loxone Websocket Golang

• Loxone DNS
• Download Socket
• Version Check

Documentation

Index

• Constants
• type Body
• type Category
• type Config
  • func (cfg *Config) CatName(key interface{}) string
  • func (cfg *Config) GetControl(uuid string) *Control
  • func (cfg *Config) RoomName(key interface{}) string
• type Control
  • func (cntl *Control) StatisticalNames() []string
• type ControlDetails
• type ControlStatistic
• type ControlStatisticItem
• type HashAlg
  • func (ha HashAlg) Valid() bool
• type Loxone
  • func New(opts ...WebsocketOption) (Loxone, error)
• type LoxoneDownloadSocket
• type Room
• type SimpleValue
• type WebsocketOption
  • func WithAutoReconnect(autoReconnect bool) WebsocketOption
  • func WithCloudDNS(miniserverMac string) WebsocketOption
  • func WithConnectionTimeout(connectionTimeout time.Duration) WebsocketOption
  • func WithHost(host string) WebsocketOption
  • func WithJWTToken(tokenString string) WebsocketOption
  • func WithKeepAliveInterval(keepAliveInterval time.Duration) WebsocketOption
  • func WithPort(port uint16) WebsocketOption
  • func WithReconnectTimeout(timeout time.Duration) WebsocketOption
  • func WithRegisterEvents() WebsocketOption
  • func WithURL(urlString string) WebsocketOption
  • func WithUsernameAndPassword(username string, password string) WebsocketOption
  • func WithoutSSLVerification() WebsocketOption

Examples

• New
• New (CloudDNS)
• New (Complex)

Constants

const (
	MiniserverEpochOffset = 1230768000
)

Types

type Body

type Body struct {
	// Control name of the control invoked
	Control string
	// Code status
	Code int32
}

Body response form command sent by ws

type Category

type Category struct {
	Name string
	UUID string
	Type string
}

Category represent a category

type Config

type Config struct {
	// LastModified
	LastModified string
	// MsInfo
	MsInfo map[string]interface{}
	// GlobalStates states about the sun, the day, etc
	GlobalStates map[string]string
	// OperatingModes of the loxone server
	OperatingModes map[string]interface{}
	// Rooms of the loxone server
	Rooms map[string]*Room
	// Cats Categories of the loxone server
	Cats map[string]*Category
	// Controls all the control of the loxone server
	Controls map[string]*Control
}

Config represent the LoxAPP3.json config file

func (*Config) CatName

func (cfg *Config) CatName(key interface{}) string

func (*Config) GetControl

func (cfg *Config) GetControl(uuid string) *Control

GetControl returns the control with the given uuid

func (*Config) RoomName

func (cfg *Config) RoomName(key interface{}) string

type Control

type Control struct {
	Name        string
	Type        string
	UUIDAction  string
	IsFavorite  bool `json:"isFavorite"`
	Room        string
	Cat         string
	States      map[string]interface{} // Can be an array or a string
	Details     ControlDetails
	Statistic   ControlStatistic
	SubControls map[string]*Control
}

Control represent a control

func (*Control) StatisticalNames

func (cntl *Control) StatisticalNames() []string

StatisticalNames returns a list of names for the given control and the statistical data the control writes. first we will loop over the outputs values within the statistics of the control, trying to find a state with a matching uuid. If no entry was found, we will use the name of the statistic entry in the output array.

type ControlDetails

type ControlDetails struct {
	Format string
}

ControlDetails details of a control

type ControlStatistic

type ControlStatistic struct {
	Frequency int                    `json:"frequency"`
	Outputs   []ControlStatisticItem `json:"outputs"`
}

type ControlStatisticItem

type ControlStatisticItem struct {
	ID       int    `json:"id"`
	Name     string `json:"name"`
	Format   string `json:"format"`
	UUID     string `json:"uuid"`
	VisuType int    `json:"visuType"`
}

type HashAlg

type HashAlg string

HashAlg defines the algorithm used to hash some user information during token generation

const (
	SHA1   HashAlg = "SHA1"
	SHA256 HashAlg = "SHA256"
)

func (HashAlg) Valid

func (ha HashAlg) Valid() bool

Valid checks for valid & supported hash algorithms. The value for the algorithm is returned by the miniserver within the process of getting an auth-token and will be used for hashing {password}:{userSalt} and {user}:{pwHash} within createToken() / hashUser()

type Loxone

type Loxone interface {
	GetEvents() <-chan events.Event
	Done() <-chan bool
	AddHook(uuid string, callback func(events.Event))
	SendCommand(command string, class interface{}) (*Body, error)
	SendEncryptedCommand(command string, class interface{}) (*Body, error)
	GetDownloadSocket() (LoxoneDownloadSocket, error)
	Close()
	RegisterEvents() error
	PumpEvents(stop <-chan bool)
	GetConfig() (*Config, error)
	IsConnected() bool
	SetConnectedHandler(func(bool))
}

func New

func New(opts ...WebsocketOption) (Loxone, error)

New creates a websocket and connects to the Miniserver

Example

// create a new connection to 1.2.3.4 using the default port 80 with the username 'admin' and password 'admin'
// auto reconnect will be enabled with a timeout of 30 seconds
lox, err := New(WithHost("1.2.3.4"), WithUsernameAndPassword("admin", "admin"))
if err != nil {
	panic(err)
}

// register for events so we get sent updates for values
err = lox.RegisterEvents()
if err != nil {
	panic(err)
}

// loop the events channel
for event := range lox.GetEvents() {
	log.Infof("%s: %.2f", event.UUID, event.Value)
}

Example (CloudDNS)

// gets the connection details from Loxone Cloud DNS for the specified Miniserver MAC and connects with the
// username 'admin' and password 'admin' auto reconnect will be enabled with a timeout of 30 seconds
lox, err := New(WithCloudDNS("504f94a00000"), WithUsernameAndPassword("admin", "admin"))
if err != nil {
	panic(err)
}

// register for events so we get sent updates for values
err = lox.RegisterEvents()
if err != nil {
	panic(err)
}

// loop the events channel
for event := range lox.GetEvents() {
	log.Infof("%s: %.2f", event.UUID, event.Value)
}

Example (Complex)

// create a new connection to 1.2.3.4 using a custom port 7777 with the username 'admin' and password 'admin',
// automatically register for events when connected and adjust the reconnect timeout to 15 seconds.
lox, err := New(WithHost("1.2.3.4"), WithPort(7777), WithUsernameAndPassword("admin", "admin"), WithRegisterEvents(), WithReconnectTimeout(15*time.Second))
if err != nil {
	panic(err)
}

// loop the events channel
for event := range lox.GetEvents() {
	log.Infof("%s: %.2f", event.UUID, event.Value)
}

type LoxoneDownloadSocket

type LoxoneDownloadSocket interface {
	Close()
	Done() <-chan bool
	IsConnected() bool
	SetConnectedHandler(func(bool))
	GetFile(filename string) ([]byte, error)
}

type Room

type Room struct {
	Name string
	UUID string
	Type int32
}

Room represent a room

type SimpleValue

type SimpleValue struct {
	// The value answered
	Value string
}

SimpleValue represent a simple Loxone Response Value

type WebsocketOption

type WebsocketOption func(*websocketImpl) error

WebsocketOption is a type we use to customise our websocket, it enables dynamic configuration in an easy to use API

func WithAutoReconnect

func WithAutoReconnect(autoReconnect bool) WebsocketOption

WithAutoReconnect allows you to disable auto reconnect behaviour by passing this option with 'false'

func WithCloudDNS

func WithCloudDNS(miniserverMac string) WebsocketOption

WithCloudDNS will initiate the websocket to resolve the protocol, hostname and port from Loxone's Cloud DNS

func WithConnectionTimeout

func WithConnectionTimeout(connectionTimeout time.Duration) WebsocketOption

WithConnectionTimeout allows you to set the connection timeout, the connection will close if nothing is received for this amount of time. If keepalive is enabled this will default to 3 * keepaliveTimeout, otherwise the connection will not timeout unless this option is specified. If keepalive is enabled this value must be higher than keepaliveInterval.

func WithHost

func WithHost(host string) WebsocketOption

WithHost connects using a given host name or ip address

func WithJWTToken

func WithJWTToken(tokenString string) WebsocketOption

WithJWTToken pre-sets the authentication token, at the moment there is no automatic refresh mechanism so it is safer to use alongside username and password authentication

func WithKeepAliveInterval

func WithKeepAliveInterval(keepAliveInterval time.Duration) WebsocketOption

WithKeepAliveInterval allows you to set the interval where keepalive messages are sent, a duration of 0 disables keepalive. If not specified it will default to 2 seconds as per Loxone's own LxCommunicator.

func WithPort

func WithPort(port uint16) WebsocketOption

WithPort set a custom port for the Miniserver

func WithReconnectTimeout

func WithReconnectTimeout(timeout time.Duration) WebsocketOption

WithReconnectTimeout sets the time between disconnection and reconnect attempts

func WithRegisterEvents

func WithRegisterEvents() WebsocketOption

WithRegisterEvents automatically registers for events upon connecting to the Miniserver

func WithURL

func WithURL(urlString string) WebsocketOption

WithURL allows initialising with a URL including schema, host and port e.g. http(s)://1.2.3.4:7494 or ws(s)://1.2.3.4:7494

func WithUsernameAndPassword

func WithUsernameAndPassword(username string, password string) WebsocketOption

WithUsernameAndPassword sets the username and password authentication, also used when supplied with a JWT to generate a new token if the provided token expires before being refreshed

func WithoutSSLVerification

func WithoutSSLVerification() WebsocketOption

WithoutSSLVerification skips certificate verification to allow self-signed certificates or connections directly to an IP address