broadlink

README

broadlink

A Go package to control BroadLink RM mini 3 "Black Bean" IR remote controller.

Disclaimer

I built this package just to control my own home appliances, and the RM mini 3 is the only device I have. For other devices, you can fork and implement yourselves. :p

Code Sample

Detect all reachable BroadLink devices

devs, err := broadlink.DiscoverDevices(100*time.Millisecond, 0)
fmt.Println(devs)
// d := devs[0]

Register and auth local machine to detected BroadLink device

myname := "my test server"  // Your local machine's name.
myid := make([]byte, 15)    // Must be 15 bytes long.
// Fill myid[] with some unique ID for your local machine.

err = d.Auth(myid, myname) // d.ID and d.AESKey will be updated on success.

Capture an IR Remote code

var rtype RemoteType
var ircode []byte

// Enter capturing mode.
err = d.StartCaptureRemoteControlCode()

// Point a remote controller toward the device and press a button to have some signal.

// Poll captured data. (Certainly you can do much better than this ;p)
ok := false
for i:=0; i<30; i++ {
	remotetype, ircode, err = d.ReadCapturedRemoteControlCode()
	if err == nil {
		ok = true
		break
	}
	if err != ErrNotCaptured {
		return err // real error
	}
	time.Sleep(time.Second)
	continue
}

if ok {
	// ircode now have captured data
}

Fire an IR code

err = d.SendIRRemoteCode(ircode, 1)	// 1 means once, 2 is twice, ...
// Note that sending IR signals may take a few hundred milliseconds. Set network timout accordingly.

Try to connect a New BroadLink device to local Wifi network

err = broadlink.SetupDeviceWifi("YOUR_WIFI_SSID", "YOUR_WIFI_PASSWORD", broadlink.WIFI_SECURITY_WPA_TKIP, nil)
// try to detect devices below
// devs, err := broadlink.DiscoverDevices(100*time.Millisecond, 0)

References

Note that references may have incorrect and inconsistent information.

• mjg59's Python-broadlink tool: https://github.com/mjg59/python-broadlink
• Broadlink smart home devices complete protocol hack: https://blog.ipsumdomus.com/broadlink-smart-home-devices-complete-protocol-hack-bc0b4b397af1

Documentation

Overview

package broadlink implements functions to control BroadLink RM mini 3 IR-control devices.

Index

• Variables
• func SetupDeviceWifi(ssid, password string, security WifiSecurity, localaddr *net.UDPAddr) (err error)
• type Device
  • func DiscoverDevices(listentime time.Duration, listenUDPPort int) (devlist []Device, err error)
  • func DiscoverDevicesFromAddr(listentime time.Duration, localaddr *net.UDPAddr) (devlist []Device, err error)
  • func (d *Device) Auth(localID []byte, localName string) (err error)
  • func (d *Device) Call(cmd byte, payload []byte) (result []byte, err error)
  • func (d *Device) Cmd(cmd byte, payload []byte) (result []byte, err error)
  • func (d *Device) Decrypt(data []byte) []byte
  • func (d *Device) DeviceName() (name, class string)
  • func (d *Device) Encrypt(data []byte) []byte
  • func (d *Device) GetAESKey() []byte
  • func (d *Device) ReadCapturedRemoteControlCode() (rtype RemoteType, code []byte, err error)
  • func (d *Device) SendIRRemoteCode(code []byte, count int) (err error)
  • func (d *Device) SendRemoteControlCode(rtype RemoteType, code []byte, count int) (err error)
  • func (d *Device) SetAESKey(key []byte)
  • func (d *Device) StartCaptureRemoteControlCode() (err error)
• type RemoteType
• type WifiSecurity

Variables

var (
	// Port number of broadlink device
	BroadLinkDevicePort = 80
)

var (
	ErrNotCaptured = fmt.Errorf("signal not captured") // Remote controller signal not captured (yet)
)

Functions

func SetupDeviceWifi

func SetupDeviceWifi(ssid, password string, security WifiSecurity, localaddr *net.UDPAddr) (err error)

Try to set up a wifi connection of BroadLink device by broadcasting wifi password over UDP network. ssid, password parameter pair is WIFI name and password. wifiSecurity is type of WIFI security. Should be a WIFI_SECURITY_xxxx values. localaddr will be directly passed to net.ListenUDP(), which means; If the IP field of laddr is nil or an unspecified IP address, ListenUDP listens on all available IP addresses of the local system except multicast IP addresses. If the Port field of laddr is 0, a port number is automatically chosen.

Types

type Device

type Device struct {
	Type uint16 // Type code of the device

	MACAddr []byte      // MAC address of the device
	UDPAddr net.UDPAddr // IP address of the device

	LocalAddr net.UDPAddr   // Local machine's IP address and port
	Timeout   time.Duration // timeout for a command call

	ID uint32 // Local machine's ID returned on Auth command
	// contains filtered or unexported fields
}

A Broadlink Device. Information in this structure may updated by device discovery and authorization functions. After a device is successfully discovered and authorized, it is safe to store and reuse informations somewhere for later use. Just be sure to store AES encryption key alongside using GetAESKey() and SetAESKey().

func DiscoverDevices

func DiscoverDevices(listentime time.Duration, listenUDPPort int) (devlist []Device, err error)

Try to discover all reachable BroadLink devices. The function waits listentime for reply from devices. listenport is a UDP port number to be listened on. If listenport is zero, a port number will be chosen automatically. Be sure the port is not blocked by firewalls.

func DiscoverDevicesFromAddr

func DiscoverDevicesFromAddr(listentime time.Duration, localaddr *net.UDPAddr) (devlist []Device, err error)

Searches for BroadLink devices can be reached from given localaddr. The function always waits listentime if no error occurs. When localaddr.Port is 0, a random port will be used.

func (*Device) Auth

func (d *Device) Auth(localID []byte, localName string) (err error)

Authorize local machine to remote device. localID uniquely identifies local machine to the device. The BroadLink device may remember the localID and returns same ID and AES encryption key. localName is a human-readable name. When succeed, d.ID and d's AES key will be updated.

func (*Device) Call

func (d *Device) Call(cmd byte, payload []byte) (result []byte, err error)

Send a command to device and read response.

func (*Device) Cmd

func (d *Device) Cmd(cmd byte, payload []byte) (result []byte, err error)

Send a command to device but not waits for response.

func (*Device) Decrypt

func (d *Device) Decrypt(data []byte) []byte

Decrypt packet data using d.aesKey.

func (*Device) DeviceName

func (d *Device) DeviceName() (name, class string)

Lookup device name using Device.Type from known device list.

func (*Device) Encrypt

func (d *Device) Encrypt(data []byte) []byte

Encrypt data using d.aesKey.

func (*Device) GetAESKey

func (d *Device) GetAESKey() []byte

Get the devices's current AES key

func (*Device) ReadCapturedRemoteControlCode

func (d *Device) ReadCapturedRemoteControlCode() (rtype RemoteType, code []byte, err error)

Read captured remote control code. The device must be in signal capture mode to capture a signal. If no signal is captured, this function returns err = ErrNotCaptured. if err is nil, rtype and code will have captured data.

func (*Device) SendIRRemoteCode

func (d *Device) SendIRRemoteCode(code []byte, count int) (err error)

Send out a IR remote code. Same function with calling SendRemoteControlCode() with rtype=REMOTE_IR.

func (*Device) SendRemoteControlCode

func (d *Device) SendRemoteControlCode(rtype RemoteType, code []byte, count int) (err error)

Send out a remote control code. rtype is remote controller signal type. code is some byte stream captured by ReadCapturedRemoteControlCode(). count is repeat count. 1 for once, 2 for twice, ...

func (*Device) SetAESKey

func (d *Device) SetAESKey(key []byte)

Set a new AES key for the device.

func (*Device) StartCaptureRemoteControlCode

func (d *Device) StartCaptureRemoteControlCode() (err error)

Set the device to enter IR/RF remote controller signal capture mode.

type RemoteType

type RemoteType int

Type of remote controller signal for SendRemoteControlCode().

const (
	REMOTE_IR       RemoteType = 0x26 // Infra-Red remote
	REMOTE_RF433Mhz RemoteType = 0xb2 // RF remote of 433Mhz band
	REMOTE_RF315Mhz RemoteType = 0xd7 // RF remote of 315Mhz band
)

type WifiSecurity

type WifiSecurity int

Wifi security code for SetupDeviceWifi()

const (
	WIFI_SECURITY_NONE WifiSecurity = iota
	WIFI_SECURITY_WEP
	WIFI_SECURITY_WPA1
	WIFI_SECURITY_WPA2
	WIFI_SECURITY_WPA_CCMP // WPA1/2 CCMP
	WIFI_SECURITY_5_UNKNOWN
	WIFI_SECURITY_WPA_TKIP // WPA1/2 TKIP
)