kasa

README

kasa

A library and command line utility for interacting with tp-link Kasa devices on your local network.

Command Line

Full kasautil options:

$ kasautil
NAME:
   kasautil - Control Kasa devices on the local network

USAGE:
   kasautil [global options] command [command options] [arguments...]

COMMANDS:
   list, ls  List kasa devices on the local network.
   off       Set a kasa device to "off"
   on        Set a kasa device to "on"
   help, h   Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help (default: false)

You may discover Kasa devices locally with the list command of kasautil.

$ kasautil list
Address          Alias             State
10.24.6.14:9999  ADSL Modem        On
10.23.6.15:9999  Living Room Lamp  On

The only currently-supported control function is setting the relay state on supported devices. To do this, provide the Kasa device's address to the on or off commands of kasautil.

$ kasautil off 10.24.6.14:9999
$ kasautil list
Address          Alias             State
10.24.6.14:9999  ADSL Modem        Off
10.23.6.15:9999  Living Room Lamp  On

Broadcast Issues

Discovery relies on UDP packets sent to a broadcast address. This can fail when the host on which kasautil has many network interfaces or multiple network addresses on a single interface. This is known to happen on Linux with a single interface on multiple VLANs, for example.

In this case, you have two options:

1. Specify a local address using -L / --local on the correct network from which to send the Kasa request

2. Specify a device or broadcast address using -d / --device / --discover on the correct network to which the Kasa request should be sent

$ kasautil list -L 10.24.6.15:54321
Address          Alias             State
10.24.6.14:9999  ADSL Modem        On
10.23.6.15:9999  Living Room Lamp  On
$ kasautil list -d 10.24.6.255:9999
Address          Alias             State
10.24.6.14:9999  ADSL Modem        On
10.23.6.15:9999  Living Room Lamp  On

Documentation

Index

• Variables
• func DecodeAPIMessage(raw []byte, message *APIMessage) error
• func ParseAddr(addr string) (*net.UDPAddr, error)
• func SetRelayState(ctx context.Context, raddr, laddr *net.UDPAddr, state bool) error
• type APIMessage
  • func Send(ctx context.Context, message *APIMessage, raddr, laddr *net.UDPAddr, ...) ([]*APIMessage, error)
  • func (p *APIMessage) Encode() ([]byte, error)
  • func (p *APIMessage) GetModule(module string) (map[string]interface{}, bool)
• type SystemInformation
  • func GetSystemInformation(ctx context.Context, raddr, laddr *net.UDPAddr, allOrNothing bool) ([]*SystemInformation, error)
  • func (p SystemInformation) Err() error
  • func (i *SystemInformation) FromAPIMessage(msg *APIMessage) error

Variables

var ErrGetSysinfoFailed = errors.New("get_sysinfo failed")

ErrGetSysinfoFailed is returned by a Kasa device when get_sysinfo fails.

Functions

func DecodeAPIMessage

func DecodeAPIMessage(raw []byte, message *APIMessage) error

DecodeAPIMessage from the "encrypted" Kasa wire format.

func ParseAddr

func ParseAddr(addr string) (*net.UDPAddr, error)

ParseAddr from host:port string.

func SetRelayState

func SetRelayState(ctx context.Context, raddr, laddr *net.UDPAddr, state bool) error

SetRelayState on the specified address.

Types

type APIMessage

type APIMessage struct {
	RemoteAddress *net.UDPAddr           `json:"-"`
	System        map[string]interface{} `json:"system"`
}

APIMessage wraps requests to and responses from Kasa devices. Does not currently support emeter details.

func Send

func Send(ctx context.Context, message *APIMessage, raddr, laddr *net.UDPAddr, expectResponse bool) ([]*APIMessage, error)

Send an APIMessage to a UDP address. The address can be either an individual Kasa device's address, or a broadcast address. If expectResponse is true, then receive is called and any responses are returned. If expectResponse is false, the returned APIMessage slice will always be nil.

func (*APIMessage) Encode

func (p *APIMessage) Encode() ([]byte, error)

Encode an API message into the wire format expected by Kasa devices. This is a JSON payload with no trailing whitespace, "encrypted" using the encrypt function.

func (*APIMessage) GetModule

func (p *APIMessage) GetModule(module string) (map[string]interface{}, bool)

GetModule from the APIMessage. A "module" is the command or response to a command inside the system object of the Kasa API message. Examples include get_sysinfo and set_relate_state.

This is a utility intended for use with mapstructure or similar.

type SystemInformation

type SystemInformation struct {
	RemoteAddress *net.UDPAddr `json:"-"`

	ErrorCode int    `json:"err_code,omitempty" mapstructure:"err_code"`
	Error     string `json:"error_msg,omitempty" mapstructure:"error_msg"`

	ActiveMode      string `json:"active_mode,omitempty" mapstructure:"active_mode"`
	Alias           string `json:"alias,omitempty" mapstructure:"alias"`
	DeviceID        string `json:"deviceId,omitempty" mapstructure:"deviceId"`
	DevName         string `json:"dev_name,omitempty" mapstructure:"dev_name"`
	Feature         string `json:"feature,omitempty" mapstructure:"feature"`
	HardwareID      string `json:"hwId,omitempty" mapstructure:"hwId"`
	HardwareVersion string `json:"hw_ver,omitempty" mapstructure:"hw_ver"`
	IconHash        string `json:"icon_hash,omitempty" mapstructure:"icon_hash"`
	LEDOff          int    `json:"led_off,omitempty" mapstructure:"led_off"`
	MAC             string `json:"mac,omitempty" mapstructure:"mac"`
	MicType         string `json:"mic_type,omitempty" mapstructure:"mic_type"`
	Model           string `json:"model,omitempty" mapstructure:"model"`
	NTCCode         int    `json:"ntc_code,omitempty" mapstructure:"ntc_code"`
	OEMID           string `json:"oemId,omitempty" mapstructure:"oemId"`
	OnTime          int    `json:"on_time,omitempty" mapstructure:"on_time"`
	RelayState      int    `json:"relay_state,omitempty" mapstructure:"relay_state"`
	RSSI            int    `json:"rssi,omitempty" mapstructure:"rssi"`
	SoftwareVersion string `json:"sw_ver,omitempty" mapstructure:"sw_ver"`
	Status          string `json:"status,omitempty" mapstructure:"status"`
	Updating        int    `json:"updating,omitempty" mapstructure:"updating"`

	NextAction *struct {
		Type int `json:"type,omitempty"`
	} `json:"next_action,omitempty"`
}

SystemInformation gives structure to the response to get_sysinfo requests.

func GetSystemInformation

func GetSystemInformation(ctx context.Context, raddr, laddr *net.UDPAddr, allOrNothing bool) ([]*SystemInformation, error)

GetSystemInformation sends a get_sysinfo request to the UDP address, and returns any responses received before the deadline.

func (SystemInformation) Err

func (p SystemInformation) Err() error

Err converts any error details in a get_sysinfo response to a Go error.

func (*SystemInformation) FromAPIMessage

func (i *SystemInformation) FromAPIMessage(msg *APIMessage) error

FromAPIMessage populates a SystemInformation from an APIMessage.