.| Package import | "zappem.net/pub/net/tplinky" |
|---|---|
| Documentation | https://pkg.go.dev/zappem.net/pub/net/tplinky |
| Sources | https://github.com/tinkerator/tplinky |
This package provides a Go API for communicating with a tp-link smartplug device.
An in depth discussion of these devices is available here: https://www.softscheck.com/en/blog/tp-link-reverse-engineering/ and a subset of the information found there was used to develop this package for some automation projects.
Automated documentation for this Go package is available from .
NOTE The following example assumes your computer network is
192.168.1.0/24. If you have configured your devices on a different
network, you will need to substitute your network addresses instead
as you follow along.
To use this device (on already configured devices, see Initial Setup section) you can try the following example:
$ git clone https://github.com/tinkerator/tplinky.git
$ cd tplinky
$ go build examples/tple.go
$ ./tple --scan=192.168.1.0/24
2024/12/01 12:53:33 192.168.1.110: F0:A7:31:xx:xx:xx on=true "what watt" #children=0
2024/12/01 12:53:33 192.168.1.135: 50:91:E3:yy:yy:yy on=false "no glow" #children=0
The "..." names are the aliases for the plugs that the user can
change. You can set this alias as follows:
$ ./tple --device=192.168.1.135 --alias="outside glow"
2024/12/01 13:00:26 192.168.1.135: 50:91:E3:yy:yy:yy on=false "outside glow" #children=0
Next, to turn on the ("outside glow") lights:
$ ./tple --device=192.168.1.135 --on
2024/12/01 13:00:28 192.168.1.135: 50:91:E3:yy:yy:yy on=true "outside glow" #children=0
To turn those lights off again, but not output any text status
(suitable for a crontab entry):
$ ./tple --device=192.168.1.135 --off --status=false
Power strips have more than one socket per device, which enumerate as follows:
$ ./tple --device=192.168.1.157
2024/12/15 18:46:20 192.168.1.157: 50:91:E3:yy:yy:yy on=[true true] "power couple" #children=2
Without specifying a socket for the action, the action will affect all of the socket relay states.
To set the enabled state of the sockets individually, specify the
index of the sockets with the --sockets=a,b argument. In the above
example, there are two scockets, indexed 0 and 1. For example, to
power off the 0th socket:
$ ./tple --device=192.168.1.157 --sockets=0 --off
2024/12/15 18:46:25 192.168.1.157: 50:91:E3:yy:yy:yy on=[false true] "power couple" #children=2
To enable both sockets:
$ ./tple --device=192.168.1.157 --sockets=0,1 --on
2024/12/15 18:46:30 192.168.1.157: 50:91:E3:yy:yy:yy on=[true true] "power couple" #children=2
The devices track time, and tple can initialize and read that
time. Note, the time is only settable with one second of precision, so
responses from the device are going to be up to one second wrong.
To update the time to be roughly the current time:
$ ./tple --device=192.168.1.157 --set-now
2024/12/17 06:30:53 device time is 2024-12-17 06:30:53 -0800 PST
To read the device’s time:
$ ./tple --device=192.168.1.157 --time
2024/12/17 06:32:29 device time is 2024-12-17 06:32:29 -0800 PST
When a device is newly unpacked, it comes without knowledge of how to connect to your WiFi network. You can use the following information to enable it to connect to that network.
When you first plug in the smart plug to a power source, it boots in
setup mode. You can also return a device to this state with the
--factory-reset command line option. In setup mode, the plug acts as
WiFi network all of its own. Its SSID is of the form, TP-LINK_Smart
Plug_XXYY. Where XXYY is the last 4 hex digits of the plug’s MAC
address. Typically, these are printed on the plug itself
somewhere. However, in most cases, it is unlikely you will be powering
up and configuring more than one plug at a time, so you can just use
your computer to try to connect to some WiFi network with a name like
this.
From a Rasperry Pi, networked via wired ethernet, you can find and connect to the plug’s setup network as follows:
$ sudo -s
# ifconfig wlan0 up
# iwlist wlan0 scan | grep ESSID
# iwconfig wlan0 essid "TP-LINK_Smart Plug_XXXX"
# dhclient wlan0
Alternatively, you can connect from any computer by selecting the WiFi network of that name.
To complete this operation you will need three things:
power.MyWiFi.Passphrase.From a computer connected to the TP-LINK_... network, run the
following commands (substituting your detailed parameters as
appropriate):
$ ./tple --scan=192.168.0.0/24
2000/01/02 12:39:48 192.168.0.1: F0:A7:31:WW:XX:YY on=true "TP-LINK_Smart Plug_XXYY" #children=0
$ ./tple --device=192.168.0.1 --set-now
2024/12/18 13:07:22 device time is 2024-12-18 13:07:21 -0800 PST
$ ./tple --device=192.168.0.1 --alias="power"
2024/12/18 13:08:31 192.168.0.1: F0:A7:31:WW:XX:YY on=true "power" #children=0
$ ./tple --device=192.168.0.1 --ssid="MyWiFi" --password="Passphrase"
2024/12/18 13:09:18 reconnect to device via "MyWiFi" WiFi network
$
If anything goes wrong, the plug will reestablish its TP-LINK_...
network, and you can try again. Note, I’ve found that it is required
to set an --alias for the networking change to take effect.
As noted above, you can use the --scan argument to locate the device
again from a computer networked to your MyWiFi network.
Nothing planned.
The tplinky package is distributed with the same BSD 3-clause license
as that used by golang itself.
Use the github tplinky bug tracker.