kizcool

package module
v0.0.0-...-f7a6a58 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 26, 2023 License: Apache-2.0 Imports: 10 Imported by: 0

README

logo

Kizcool

A CLI and go package to control devices from Velux, Somfy and other vendors using the Overkiz platform.

Build Status

Components

  • Executable kizcool/exe/kizcmd is a command-line utility to control devices.
  • Package kizcool provides a high-level client with structs for events and devices. Documentation.
  • Package kizcool/api provides a lower-level api client that returns the raw responses from the server without parsing. Documentation.

Command line tool

Download and install kizcmd

go get -u github.com/sgrimee/kizcool/cmd/kizcmd
go install github.com/sgrimee/kizcool/cmd/kizcmd

Create a configuration file

kizcmd configure

Get all devices names

kizcmd get labels

Send a command to a device

kizcmd on "my light"
kizcmd off "my light"
kizcmd instensity "my light" 50

kizcmd open "my window"
kizcmd close "my window"

kizcmd open "my blind"
kizcmd close "my blind"
kizcmd closure "my blind" 75

Get all devices data

kizcmd get devices

Get one device in json format. Hint: jq is a nice json formatter

kizcmd get device "parents window" -ojson | jq

Continuously poll for events from the installation and display them on the console

kizcmd listen

Environment variables

As an alternative to the config file, configuration items can be given as environment variables:

  • KIZ_USERNAME
  • KIZ_PASSWORD
  • KIZ_BASE_URL

Requirements

Go version

Golang >= 1.13

Supported gateways

This packages interacts with the Overkiz API, as used by Somfy's Tahoma devices. It should work with other controllers but only Tahoma was tested.

Supported devices

Support is provided for the following devices:

  • Velux Integra electric window: GGL-GGU
  • Velux Integra electric roller shutter: SML
  • Velux Integra spotlight: KRA-100 (hard to find)

However, the Overkiz system supports many more devices from several vendors. Some may work out of the box. Support for others should be easy to add. Please file an issue to report other working devices or request the addition of new devices.

Supported platforms

This should work wherever go works. Tested on mac and linux. Efforts were made to support windows but it is not tested.

Roadmap

Upcoming features include:

  • KNX bridge to control velux devices from a KNX system (the main goal for this project).

Notice of Non-affiliation and Disclaimer

We are not affiliated, associated, authorized, endorsed by, or in any way officially connected with Overkiz, Velux, Somfy, any other trademark mentioned in this project, or any of its subsidiaries or its affiliates. We are grateful for the great products and services they provide.

Please see the License and Disclaimer notice.

Documentation

Overview

Package kizcool provides a high-level client to the Overkiz IoT API, used by velux, somfy and other vendors to control velux devices with a Tahoma box.

Index

Constants

View Source 
const (
	CmdClose         = "close"
	CmdDown          = "down"
	CmdIdentify      = "identify"
	CmdOff           = "off"
	CmdOn            = "on"
	CmdOpen          = "open"
	CmdSetIntensity  = "setIntensity"
	CmdSetClosure    = "setClosure"
	CmdStartIdentify = "startIdentify"
	CmdStop          = "stop"
	CmdStopIdentify  = "stopIdentify"
	CmdUp            = "up"
)

CommandNames

Variables

This section is empty.

Functions

func Output 

func Output(w io.Writer, format string, obj interface{}) error

Output prints the given object to the writer in the desired format format can be 'text', 'json' or 'yaml'

func SupportsCommand 

func SupportsCommand(device Device, command Command) bool

SupportsCommand returns true if the command is supported by the device.

Types

type Action 

type Action struct {
	DeviceURL DeviceURL `json:"deviceURL,omitempty"`
	Commands  []Command `json:"commands,omitempty"`
}

Action defines a list of commands

type ActionGroup 

type ActionGroup struct {
	CreationTime          int      `json:"creationTime,omitempty"`
	LastUpdateTime        int      `json:"lastUpdateTime,omitempty"`
	Label                 string   `json:"label,omitempty"`
	Shortcut              bool     `json:"shortcut,omitempty"`
	NotificationTypeMask  int      `json:"notificationTypeMask,omitempty"`
	NotificationCondition string   `json:"notificationCondition,omitempty"`
	Actions               []Action `json:"actions,omitempty"`
	OID                   string   `json:"oid,omitempty"`
}

ActionGroup is a list of Actions in sequence, with metadata. Think "scenario".

func ActionGroupWithOneCommand 

func ActionGroupWithOneCommand(device Device, command Command) (ActionGroup, error)

ActionGroupWithOneCommand returns an action group with a single command for the device

type Command 

type Command struct {
	Type       int         `json:"type,omitempty"`
	Name       string      `json:"name,omitempty"`
	Parameters interface{} `json:"parameters,omitempty"`
}

Command describes a command (duh)

type CommandDefinition 

type CommandDefinition struct {
	CommandName string `json:"commandName,omitempty"`
	Nparams     int    `json:"nparams,omitempty"`
}

CommandDefinition describes the fields of a Command

type CommandExecutionStateChangedEvent 

type CommandExecutionStateChangedEvent struct {
	GenericEvent
	DeviceURL       DeviceURL `json:"deviceURL,omitempty"`
	ExecID          ExecID    `json:"execID,omitempty"`
	SetupOID        string    `json:"setupOID,omitempty"`
	NewState        string    `json:"newState,omitempty"`
	FailureType     string    `json:"failureType,omitempty"`
	FailureTypeCode int       `json:"failureTypeCode,omitempty"`
	Rank            int       `json:"rank,omitempty"`
}

CommandExecutionStateChangedEvent indicates a change in the state of the execution of a command

type Device 

type Device struct {
	CreationTime     int
	LastUpdateTime   int
	Label            string
	DeviceURL        DeviceURL
	Shortcut         bool
	ControllableName string
	Definition       DeviceDefinition
	States           []DeviceState
	Available        bool
	Enabled          bool
	PlaceOID         string
	Widget           string
	Type             int
	OID              string
	UIClass          string
}

Device representation of a single device

func DeviceFromListByLabel 

func DeviceFromListByLabel(label string, devices []Device) (Device, error)

DeviceFromListByLabel tries to match the given string to the Labels of the given devices and returns the found Device. An error is return is zero or more than one devices match.

type DeviceDefinition 

type DeviceDefinition struct {
	Commands      []CommandDefinition
	States        []StateDefinition
	WidgetName    string
	UIClass       string
	QualifiedName string
	Type          string
}

DeviceDefinition describes the fields of a Device

type DeviceState 

type DeviceState struct {
	Name  StateName
	Type  StateType
	Value interface{}
}

DeviceState encodes a device state

type DeviceStateChangedEvent 

type DeviceStateChangedEvent struct {
	GenericEvent
	SetupOID     string        `json:"setupOID,omitempty"`
	DeviceURL    DeviceURL     `json:"deviceURL,omitempty"`
	DeviceStates []DeviceState `json:"deviceStates,omitempty"`
}

DeviceStateChangedEvent indicates a change in the state of a device

type DeviceURL 

type DeviceURL string

DeviceURL is the full device URL including prefix e.g. io://1111-0000-4444/12345678

type EndUserLoginEvent 

type EndUserLoginEvent struct {
	GenericEvent
	SetupOID      string `json:"setupOID,omitempty"`
	UserID        string `json:"userId,omitempty"`
	UserAgentType string `json:"userAgentType,omitempty"`
}

EndUserLoginEvent happens when a user authenticates

type Event 

type Event interface {
	Kind() string
}

Event is an interface for any event

type Events 

type Events []Event

Events is a slide of Event, used for unmarshalling several events of unknown type from json

func (*Events) UnmarshalJSON 

func (events *Events) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals an event from json, detecting the right event type

type ExecID 

type ExecID string

ExecID is the id of an execution (job)

type ExecutionEvent 

type ExecutionEvent struct {
	ExecID   ExecID `json:"execID,omitempty"`
	SetupOID string `json:"setupOID,omitempty"`
	SubType  int    `json:"subType,omitempty"`
	Type     int    `json:"type,omitempty"`
}

ExecutionEvent is the minimal set of fields shared by all Execution events

type ExecutionRegisteredEvent 

type ExecutionRegisteredEvent struct {
	GenericEvent
	ExecutionEvent
	Label     string   `json:"label,omitempty"`
	Metadata  string   `json:"metadata,omitempty"`
	TriggerID string   `json:"triggerId,omitempty"`
	Actions   []Action `json:"actions,omitempty"`
}

ExecutionRegisteredEvent indicates an execution has been registered

type ExecutionStateChangedEvent 

type ExecutionStateChangedEvent struct {
	GenericEvent
	ExecutionEvent
	NewState        string `json:"newState,omitempty"`
	OldState        string `json:"oldState,omitempty"`
	OwnerKey        string `json:"ownerKey,omitempty"`
	TimeToNextState int    `json:"timeToNextState,omitempty"`
}

ExecutionStateChangedEvent indicates a change in the state of an execution

type GatewayAliveEvent 

type GatewayAliveEvent struct {
	GenericEvent
	GatewayEvent
}

GatewayAliveEvent indicates the gateway is accessible again

type GatewayDownEvent 

type GatewayDownEvent struct {
	GenericEvent
	GatewayEvent
}

GatewayDownEvent indicates the gateway has become unreachable

type GatewayEvent 

type GatewayEvent struct {
	GatewayID string `json:"gatewayId,omitempty"`
}

GatewayEvent indicates an event related to a gateway

type GatewaySynchronizationEndedEvent 

type GatewaySynchronizationEndedEvent struct {
	GenericEvent
	GatewayEvent
}

GatewaySynchronizationEndedEvent indicates the end of synchronization of a gateway

type GatewaySynchronizationStartedEvent 

type GatewaySynchronizationStartedEvent struct {
	GenericEvent
	GatewayEvent
}

GatewaySynchronizationStartedEvent indicates the start of synchronization of a gateway

type GenericEvent 

type GenericEvent struct {
	Timestamp int    `json:"timestamp,omitempty"`
	Name      string `json:"name,omitempty"`
}

GenericEvent is the minimal set of fields shared by all events

func (*GenericEvent) Kind 

func (e *GenericEvent) Kind() string

Kind returns a partial text description of the event

type Kiz 

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

Kiz high-level client

func New 

func New(username, password, baseURL, sessionID string) (*Kiz, error)

New returns an initialized Kiz sessionID is optional and used for external caching of sessions

func NewWithAPIClient 

func NewWithAPIClient(c *api.Client) (*Kiz, error)

NewWithAPIClient returns an initialized Kiz from an existing API client

func (*Kiz) Close 

func (k *Kiz) Close(device Device) (ExecID, error)

Close closes a device

func (*Kiz) Execute 

func (k *Kiz) Execute(ag ActionGroup) (ExecID, error)

Execute runs an action group and returns a (job) ExecID

func (*Kiz) GetActionGroups 

func (k *Kiz) GetActionGroups() ([]ActionGroup, error)

GetActionGroups returns the list of action groups defined on the box

func (*Kiz) GetDevice 

func (k *Kiz) GetDevice(deviceURL DeviceURL) (Device, error)

GetDevice returns a single device

func (*Kiz) GetDeviceByText 

func (k *Kiz) GetDeviceByText(text string) (Device, error)

GetDeviceByText returns a Device from a text string If first tries to match a DeviceURL. If no match, it tries to match a device Label

func (*Kiz) GetDeviceState 

func (k *Kiz) GetDeviceState(deviceURL DeviceURL, stateName StateName) (DeviceState, error)

GetDeviceState returns the current state with name stateName for the device with URL deviceURL

func (*Kiz) GetDevices 

func (k *Kiz) GetDevices() ([]Device, error)

GetDevices returns the list of devices

func (*Kiz) Login 

func (k *Kiz) Login() error

Login to the api server to obtain a session ID cookie This is normally called automatically from the methods that need it

func (*Kiz) Off 

func (k *Kiz) Off(device Device) (ExecID, error)

Off turns a device off

func (*Kiz) On 

func (k *Kiz) On(device Device) (ExecID, error)

On turns a device on

func (*Kiz) Open 

func (k *Kiz) Open(device Device) (ExecID, error)

Open opens a device

func (*Kiz) PollEvents 

func (k *Kiz) PollEvents() (Events, error)

PollEvents polls for events on the stored listener

func (*Kiz) PollEventsContinuous 

func (k *Kiz) PollEventsContinuous(ev chan<- Event, e chan<- error, finish <-chan struct{})

PollEventsContinuous calls PollEventsContinuousWithSleepTime with a reasonable polling interval

func (*Kiz) PollEventsContinuousWithSleepTime 

func (k *Kiz) PollEventsContinuousWithSleepTime(ev chan<- Event, e chan<- error, finish <-chan struct{}, sleepTime time.Duration)

PollEventsContinuousWithSleepTime polls for events at given intervals and sends received events and errors on given channels. In case of error, polling will resume after a moment. Close the finish channel to indicate that this method should stop polling and return. It can be used in a goroutine.

func (*Kiz) RefreshStates 

func (k *Kiz) RefreshStates() error

RefreshStates tells the server send the state of all devices as events

func (*Kiz) SessionID 

func (k *Kiz) SessionID() string

SessionID is the latest known sessionID value It can be used for caching sessions externally.

func (*Kiz) SetClosure 

func (k *Kiz) SetClosure(device Device, position int) (ExecID, error)

SetClosure sets the device closure/position to given value

func (*Kiz) SetIntensity 

func (k *Kiz) SetIntensity(device Device, intensity int) (ExecID, error)

SetIntensity sets the light intensity to given value

func (*Kiz) Stop 

func (k *Kiz) Stop(device Device) (ExecID, error)

Stop interrupts the current activity

type RefreshAllDevicesStatesCompletedEvent 

type RefreshAllDevicesStatesCompletedEvent struct {
	GenericEvent
	GatewayEvent
	ProtocolType int `json:"protocolType,omitempty"`
}

RefreshAllDevicesStatesCompletedEvent indicates the end of a request to get the state of all devices

type StateDefinition 

type StateDefinition struct {
	Type          string
	QualifiedName string
	Values        []string
}

StateDefinition describes the fields of a State

type StateName 

type StateName string

StateName is the name of a State

type StateType 

type StateType int

StateType has value 1 (int), 2 (float) or 3 (string) 

const (
	StateInt    StateType = 1
	StateFloat  StateType = 2
	StateString StateType = 3
)

States have types determining the value of their type

Source Files

View all Source files

Directories

Path Synopsis
Package api provides a low-level client to the overkiz api JSON responses are not unmarshalled and are returned as-is.
 Package api provides a low-level client to the overkiz api JSON responses are not unmarshalled and are returned as-is.
cmd
kizcmd
kizcmd/cmd
Package config provides handling of configuration through a config file
 Package config provides handling of configuration through a config file

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.