package module
Version: v0.0.0-...-0bf5ebb Latest Latest

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

Go to latest
Published: Apr 16, 2022 License: BSD-2-Clause Imports: 8 Imported by: 0


LICENSE GoReportCard GoDoc


Go library to control TP-Link Kasa devices. This library uses the local API, not the cloud API. It uses UDP rather than TCP where possible for better performance.

Includes a small cli tool

This is still a work-in-progress, but works for most operations.

If you need to control your Kasa devices from Apple HomeKit, I have built a bridge which works well.


CLI examples

discover devices on the local subnets

% kasa discover
read udp [::]:48781: i/o timeout
found 25 devices HS220(US)             Fireplace Can Dimmer [state: 0] [brightness:  25] HS200(US)           Dining Room Chandelier [state: 0] [brightness:   0] HS200(US)            Back Porch Floodlight [state: 1] [brightness:   0] HS200(US)                   Breakfast Nook [state: 0] [brightness:   0] HS220(US)        Master Bath Shower Lights [state: 0] [brightness:  50] HS220(US)           Master Bath Can Lights [state: 0] [brightness:  50] HS200(US)              Master Bath Mirrors [state: 0] [brightness:   0] HS200(US)               Front Door Pendant [state: 0] [brightness:   0] HS200(US)                       Front Room [state: 0] [brightness:   0] HS210(US)                  Front Hallway 1 [state: 0] [brightness:   0] HS210(US)                  Front Hallway 2 [state: 0] [brightness:   0] HS220(US)             Master Bedroom Light [state: 0] [brightness:  40] HS200(US)               Laundry Room Light [state: 1] [brightness:   0] HS200(US)       Laundry Room Extractor Fan [state: 0] [brightness:   0] HS200(US)               Hallway Side Light [state: 1] [brightness:   0] HS200(US)      Living Room Overhead Lights [state: 0] [brightness:   0] HS200(US)                  Living Room Fan [state: 0] [brightness:   0] HS200(US)               Kitchen Sink Light [state: 0] [brightness:   0] KP303(US) TP-LINK_Power Strip_2BAB
    ID: 8006D442E080440F22A89B072F2E67FB1D9B3DFE02               Guppie Light [state: 0]
    ID: 8006D442E080440F22A89B072F2E67FB1D9B3DFE01              Guppie Heater [state: 1]
    ID: 8006D442E080440F22A89B072F2E67FB1D9B3DFE00              Guppie Filter [state: 1] KP303(US) TP-LINK_Power Strip_2C77
    ID: 8006972A91D031658289D308866206E11D9B838A02               Edgar Heater [state: 1]
    ID: 8006972A91D031658289D308866206E11D9B838A01              Edgar Bubbler [state: 1]
    ID: 8006972A91D031658289D308866206E11D9B838A00               Edgar Filter [state: 1] KP303(US) TP-LINK_Power Strip_34EC
    ID: 800661DA15771003D2531C57BE527BA61D9B40E400               Gofish Light [state: 0]
    ID: 800661DA15771003D2531C57BE527BA61D9B40E401              Gofish Heater [state: 1]
    ID: 800661DA15771003D2531C57BE527BA61D9B40E402              Gofish Filter [state: 1] HS103(US)                Living Room Spare [state: 0] [brightness:   0] HS103(US)                Scot Bedside Lamp [state: 0] [brightness:   0] HS103(US)                 Jen Bedside Lamp [state: 0] [brightness:   0] HS103(US)              Scot’s Office Spare [state: 0] [brightness:   0]

disable the cloud service for all devices on the local subnets

% kasa nocloud

toggle one switch

% kasa switch false

adjust the brightness on a dimmer switch

% kasa brightness 100

show dimmer status and timeings for all dimmer-enabled devices (this needs to be prettier...)

% kasa getalldimmer
read udp [::]:58322: i/o timeout &{MinThreshold:0 FadeOnTime:2000 FadeOffTime:2000 GentleOnTime:3000 GentleOffTime:10000 RampRate:30 BulbType:1 ErrCode:0 ErrMsg:} &{MinThreshold:1 FadeOnTime:1000 FadeOffTime:2000 GentleOnTime:3000 GentleOffTime:60000 RampRate:30 BulbType:1 ErrCode:0 ErrMsg:} &{MinThreshold:9 FadeOnTime:1000 FadeOffTime:1000 GentleOnTime:3000 GentleOffTime:10000 RampRate:30 BulbType:0 ErrCode:0 ErrMsg:} &{MinThreshold:0 FadeOnTime:1000 FadeOffTime:2000 GentleOnTime:3000 GentleOffTime:30000 RampRate:30 BulbType:1 ErrCode:0 ErrMsg:}

details about a single device

% kasa info
Alias:		Fireplace Can Dimmer
DevName:	Wi-Fi Smart Dimmer
Model:		HS220(US) [2.0]
Device ID:	xxx
OEM ID:		xxx
Hardware ID:	xxx
Software:	1.0.5 Build 201211 Rel.085320
MAC:		60:32:B1:00:00:00
LED Off:	0
Active Mode:	none
Relay:	0	Brightness:	25%

Get real-time usage

% kasa emeter
CurrentMA:	1807
VoltageMV:	122209
PowerMW:	175494
TotalWH:	2097

Get daily stats for a month (Feb 2021)

% kasa emeter 02 2021
2021-02-06 Total WH:	842
2021-02-07 Total WH:	1257

Get Countdown Rules (needs to be prettier)

% kasa countdown
{ID:8725326BB2D0C0DD8D521379163C7D67 Name:TooFar Enable:0 Delay:0 Active:1 Remaining:0}

Clear Countdown rules

% kasa countdown delete




View Source
const (
	CmdSetRelayState = `{"system":{"set_relay_state":{"state":%d}}}` // 0 or 1
	CmdGetSysinfo    = `{"system":{"get_sysinfo":{}}}`
	CmdReboot        = `{"system":{"reboot":{"delay":2}}}`
	CmdLEDOff        = `{"system":{"set_led_off":{"off":%d}}}` // off = 1, on = 0
	CmdDeviceAlias   = `{"system":{"set_dev_alias":{"alias":"%s"}}}`
	CmdSetMode       = `{"system":{"set_mode":{"mode":"%s"}}}` // "none", "count_down", ???

	CmdGetEmeter           = `{"emeter":{"get_realtime":{}}}`
	CmdGetEmeterGetDaystat = `{"emeter":{"get_daystat":{"month":%d,"year":%d}}}`
	CmdGetEmeterVgain      = `{"emeter":{"get_vgain_igain":{}}}`
	CmdSetEmeterVgain      = `{"emeter":{"set_vgain_igain":{"vgain":%d,"igain":%d}}}`       // int, int
	CmdEmeterCalibration   = `{"emeter":{"start_calibration":{"vtarget":%d,"itarget":%d}}}` // int, int
	CmdEmeterGetMonth      = `{"emeter":{"get_daystat":{"month":%d,"year":%d}}}`            // 1-12, 4-digit-year
	CmdEmeterGetYear       = `{"emeter":{"get_monthstat":{"year":%d}}}`                     // 4-digit-year
	CmdEmeterErase         = `{"emeter":{"erase_emeter_stat":null}}`

	CmdGetEmeterChild = `{"context":{"child_ids":["%s"]},"emeter":{"get_realtime":{}}}`

	CmdWifiStainfo = `{"netif":{"get_stainfo":{}}}`

	CmdSetRelayStateChild      = `{"context":{"child_ids":["%s"]},"system":{"set_relay_state":{"state":%d}}}` // index (e.g. ".....00"), 0/1
	CmdSetRelayStateChildMulti = `{"context":{"child_ids":[%s]},"system":{"set_relay_state":{"state":%d}}}`   // indexes (e.g. `"....00","....03"`), 0/1
	CmdChildAlias              = `{"context":{"child_ids":["%s"]},"system":{"set_dev_alias":{"alias":"%s"}}}` // index (e.g. "....01"), name

	CmdGetDimmer        = `{"smartlife.iot.dimmer":{"get_dimmer_parameters":{}}}`
	CmdSetBrightness    = `{"smartlife.iot.dimmer":{"set_brightness":{"brightness":%d}}}`    // 0-100
	CmdSetFadeOffTime   = `{"smartlife.iot.dimmer":{"set_fade_off_time":{"fadeTime":%d}}}`   // ms
	CmdSetFadeOnTime    = `{"smartlife.iot.dimmer":{"set_fade_on_time":{"fadeTime":%d}}}`    // ms
	CmdSetGentleOffTime = `{"smartlife.iot.dimmer":{"set_gentle_off_time":{"fadeTime":%d}}}` // ms
	CmdSetGentleOnTime  = `{"smartlife.iot.dimmer":{"set_gentle_on_time":{"fadeTime":%d}}}`  // ms

	CmdGetRules = `{"smartlife.iot.common.schedule":{"get_rules":{}}}`

	CmdGetCountdownRules = `{"count_down":{"get_rules":{}}}`
	CmdDeleteAllRules    = `{"count_down":{"delete_all_rules":{}}}`
	CmdAddCountdownRule  = `{"count_down":{"add_rule":{"enable":1,"delay":%d,"act":%d,"name":"%s"}}}` // 0-3600, 0/1, string

	CmdCloudUnbind    = `{"cnCloud":{"unbind":null}}`
	CmdSetServerURL   = `{"cnCloud":{"set_server_url":{"server":"%s"}}}`          // bare hostname, no protocol spec
	CmdSetServerCreds = `{"cnCloud":{"bind":{"username":"%s", "password":"%s"}}}` // alice@home.com / mikeisagoat

Request strings


This section is empty.


func BroadcastAddresses

func BroadcastAddresses() ([]net.IP, error)

BroadcastAddresses - probably belongs in its own library, get all broadcast addresses

func BroadcastDimmerParameters

func BroadcastDimmerParameters(timeout, probes int) (map[string]*DimmerParameters, error)

BroadcastDimmerParameters queries all devices on all attached subnets for dimmer state

func BroadcastDiscovery

func BroadcastDiscovery(timeout, probes int) (map[string]*Sysinfo, error)

BroadcastDiscovery pulls every attached subnet for kasa devices and returns whatever is discovered

func BroadcastEmeter

func BroadcastEmeter(timeout, probes int) (map[string]string, error)

BroadcastEmeter pulls all devices on all attached subnets for emeter data

func BroadcastWifiParameters

func BroadcastWifiParameters(timeout, probes int) (map[string]*StaInfo, error)

BroadcastWifiParameters polls all devices on all attached subnets for wifi status. This is handy when you have one device that never wants to respond, seeing how its wifi status changes over time

func Scramble

func Scramble(plaintext string) []byte

Scramble is simpler. UDP doesn't require the length header, just allocates and write to a slice.

func ScrambleTCP

func ScrambleTCP(plaintext string) []byte

ScrambleTCP is for TCP, It writes the length in the first byte. It uses a binary buffer and writer.

func SetLogger

func SetLogger(l kasalogger)

SetLogger allows applications to register their own logging interface

func Unscramble

func Unscramble(ciphertext []byte) []byte

Unscramble turns the response from the Kasa into parsable JSON it works in place -- be careful with your buffers


type AddRule

type AddRule struct {
	ID           string `json:"id"`
	ErrorCode    int8   `json:"err_code"`
	ErrorMessage string `json:"err_msg"`

AddRule is defined by kasa devices

type Child

type Child struct {
	ID         string `json:"id"`
	RelayState uint8  `json:"state"`
	Alias      string `json:"alias"`
	OnTime     int    `json:"on_time"`

Child is defined by kasa devices

type Countdown

type Countdown struct {
	GetRules GetRules `json:"get_rules"`
	DelRules DelRules `json:"delete_all_rules"`
	AddRule  AddRule  `json:"add_rule"`

Countdown is defined by kasa devices

type DelRules

type DelRules struct {
	ErrorCode    int8   `json:"err_code"`
	ErrorMessage string `json:"err_msg"`

DelRules is defined by kasa devices

type Device

type Device struct {
	IP string

	Debug bool
	// contains filtered or unexported fields

Device is the primary type, commands are called from the device

func NewDevice

func NewDevice(ip string) (*Device, error)

NewDevice sets up a new Kasa device for polling

func (*Device) AddCountdownRule

func (d *Device) AddCountdownRule(dur int, target bool, name string) error

AddCountdownRule adds a new countdown

func (*Device) ClearCountdownRules

func (d *Device) ClearCountdownRules() error

ClearCountdownRules resets all countdown rules on the device

func (*Device) DisableCloud

func (d *Device) DisableCloud() error

DisableCloud sets the device to "local only" mode. TODO: forget any cloud settings

func (*Device) GetCountdownRules

func (d *Device) GetCountdownRules() (*[]Rule, error)

GetCountdownRules returns a list of the countdown timers on a device

func (*Device) GetDimmerParameters

func (d *Device) GetDimmerParameters() (*DimmerParameters, error)

GetDimmerParameters returns the dimmer parameters from dimmer-capable devices

func (*Device) GetEmeter

func (d *Device) GetEmeter() (*EmeterRealtime, error)

GetEmeter returns emeter data from the device

func (*Device) GetEmeterChild

func (d *Device) GetEmeterChild(child string) (*EmeterRealtime, error)

GetEmeter returns emeter data from the device

func (*Device) GetEmeterMonth

func (d *Device) GetEmeterMonth(month, year int) (*EmeterDaystat, error)

GetEmeterMonth returns a single month's emeter data from the device

func (*Device) GetRules

func (d *Device) GetRules() (string, error)

GetRules returns the rule information from a device

func (*Device) GetSettings

func (d *Device) GetSettings() (*Sysinfo, error)

GetSettings gets the device sys info

func (*Device) GetWIFIStatus

func (d *Device) GetWIFIStatus() (string, error)

GetWIFIStatus returns the WiFi station info

func (*Device) Reboot

func (d *Device) Reboot() error

Reboot instructs the device to reboot

func (*Device) SendRawCommand

func (d *Device) SendRawCommand(cmd string) error

func (*Device) SetAlias

func (d *Device) SetAlias(s string) error

SetAlias sets a device name

func (*Device) SetBrightness

func (d *Device) SetBrightness(newval int) error

SetBrightness adjust the brightness setting on a dimmer-capable device (1-100)

func (*Device) SetChildAlias

func (d *Device) SetChildAlias(childID, s string) error

SetChildAlias sets the name of an individual relay on a multi-relay device, I don't think this works

func (*Device) SetFadeOffTime

func (d *Device) SetFadeOffTime(newval int) error

func (*Device) SetFadeOnTime

func (d *Device) SetFadeOnTime(newval int) error

func (*Device) SetGentleOffTime

func (d *Device) SetGentleOffTime(newval int) error

func (*Device) SetGentleOnTime

func (d *Device) SetGentleOnTime(newval int) error

func (*Device) SetLEDOff

func (d *Device) SetLEDOff(t bool) error

SetLEDOff is insanely named... it should be SetLED, but I'm just going with what TP-Link called these things internally...

func (*Device) SetMode

func (d *Device) SetMode(m string) error

SetMode sets the target mode of the system

func (*Device) SetRelayState

func (d *Device) SetRelayState(newstate bool) error

SetRelayState changes the relay state of the device -- for multi-relay devices use SetRelayStateChild

func (*Device) SetRelayStateChild

func (d *Device) SetRelayStateChild(childID string, newstate bool) error

SetRelayStateChild adjusts a single relay on a multi-relay device

func (*Device) SetRelayStateChildMulti

func (d *Device) SetRelayStateChildMulti(newstate bool, children ...string) error

SetRelayStateChildMulti adjusts multiple relays on a multi-relay device

type Dimmer

type Dimmer struct {
	Parameters DimmerParameters `json:"get_dimmer_parameters"`
	ErrCode    int8             `json:"err_code"`
	ErrMsg     string           `json:"err_msg"`

Dimmer is defined by kasa devices

type DimmerParameters

type DimmerParameters struct {
	MinThreshold  uint16 `json:"minThreshold"`
	FadeOnTime    uint16 `json:"fadeOnTime"`
	FadeOffTime   uint16 `json:"fadeOffTime"`
	GentleOnTime  uint16 `json:"gentleOnTime"`
	GentleOffTime uint16 `json:"gentleOffTime"`
	RampRate      uint16 `json:"rampRate"`
	BulbType      uint8  `json:"bulb_type"`
	ErrCode       int8   `json:"err_code"`
	ErrMsg        string `json:"err_msg"`

DimmerParameters is defined by kasa devices

type EmeterDay

type EmeterDay struct {
	Year  uint16 `json:"year"`
	Month uint8  `json:"month"`
	Day   uint8  `json:"day"`
	WH    uint16 `json:"energy_wh"`

EmeterDay is defined by kasa devices

type EmeterDaystat

type EmeterDaystat struct {
	List    []EmeterDay `json:"day_list"`
	ErrCode int8        `json:"err_code"`
	ErrMsg  string      `json:"err_msg"`

EmeterDaystat is defined by kasa devices

type EmeterRealtime

type EmeterRealtime struct {
	Slot      uint8  `json:"slot_id"`
	CurrentMA uint   `json:"current_ma"`
	VoltageMV uint   `json:"voltage_mv"`
	PowerMW   uint   `json:"power_mw"`
	TotalWH   uint   `json:"total_wh"`
	ErrCode   int8   `json:"err_code"`
	ErrMsg    string `json:"err_msg"`

EmeterRealtime is defined by kasa devices

type EmeterSub

type EmeterSub struct {
	Realtime EmeterRealtime `json:"get_realtime"`
	DayStat  EmeterDaystat  `json:"get_daystat"`

EmeterSub is defined by kasa devices

type GetRules

type GetRules struct {
	RuleList     []Rule `json:"rule_list"`
	ErrorCode    int8   `json:"err_code"`
	ErrorMessage string `json:"err_msg"`

GetRules is defined by kasa devices

type GetSysinfo

type GetSysinfo struct {
	Sysinfo Sysinfo `json:"get_sysinfo"`

GetSysinfo is defined by kasa devices

type KasaDevice

type KasaDevice struct {
	GetSysinfo GetSysinfo `json:"system"`
	Dimmer     Dimmer     `json:"smartlife.iot.dimmer"`
	NetIf      NetIf      `json:"netif"`
	Countdown  Countdown  `json:"count_down"`
	Emeter     EmeterSub  `json:"emeter"`

KasaDevice is the primary type, defined by kasa devices

type NetIf

type NetIf struct {
	StaInfo StaInfo `json:"get_stainfo"`
	ErrCode int8    `json:"err_code"`
	ErrMsg  string  `json:"err_msg"`

NetIf is defined by kasa devices {"netif":{"get_stainfo":{"ssid":"IoT8417","key_type":3,"rssi":-61,"err_code":0}}}

type Preset

type Preset struct {
	Index      uint8 `json:"index"`
	Brightness uint8 `json:"brightness"`

Preset is defined by kasa devices

type Rule

type Rule struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Enable    uint8  `json:"enable"`
	Delay     uint16 `json:"delay"`
	Active    uint8  `json:"act"`
	Remaining uint16 `json:"remain"`

Rule is defined by kasa devices

type StaInfo

type StaInfo struct {
	SSID    string `json:"ssid"`
	KeyType int8   `json:"key_type"`
	RSSI    int8   `json:"rssi"`
	ErrCode int8   `json:"err_code"`
	ErrMsg  string `json:"err_msg"`

StaInfo is defined by kasa devices

type Sysinfo

type Sysinfo struct {
	SWVersion      string   `json:"sw_ver"`
	HWVersion      string   `json:"hw_ver"`
	Model          string   `json:"model"`
	DeviceID       string   `json:"deviceId"`
	OEMID          string   `json:"oemId"`
	HWID           string   `json:"hwId"`
	RSSI           int8     `json:"rssi"`
	Longitude      int      `json:"longitude_i"`
	Latitude       int      `json:"latitude_i"`
	Alias          string   `json:"alias"`
	Status         string   `json:"status"`
	MIC            string   `json:"mic_type"`
	Feature        string   `json:"feature"`
	MAC            string   `json:"mac"`
	Updating       uint8    `json""updating"`
	LEDOff         uint8    `json:"led_off"`
	RelayState     uint8    `json:"relay_state"`
	Brightness     uint8    `json:"brightness"`
	OnTime         int      `json:"on_time"`
	ActiveMode     string   `json:"active_mode"`
	DevName        string   `json:"dev_name"`
	Children       []Child  `json:"children"`
	NumChildren    uint8    `json:"child_num"`
	NTCState       int      `json:"ntc_state"`
	PreferredState []Preset `json:"preferred_state"`
	ErrCode        int8     `json:"error_code"`

Sysinfo is defined by kasa devices


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL