Add in AP Mode device setup for new Broadlink devices. (#53)

3 files changed, 72 insertions, 0 deletions

diff --git a/README.md b/README.md
index 3d7598f5d88c..1305ea0f5a7b 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,20 @@ A simple Python API for controlling IR controllers from [Broadlink](http://www.i
 Example use
 -----------
 
+Setup a new device on your local wireless network:
+
+1. Put the device into AP Mode
+  1. Long press the reset button until the blue LED is blinking quickly.
+  2. Long press again until blue LED is blinking slowly.
+  3. Manually connect to the WiFi SSID named BroadlinkProv.
+2. Run setup() and provide your ssid, network password (if secured), and set the security mode
+  1. Security mode options are (0 = none, 1 = WEP, 2 = WPA1, 3 = WPA2, 4 = WPA1/2)
+```
+import broadlink
+
+broadlink.setup('myssid', 'mynetworkpass', 3)
+```
+
 Discover available devices on the local network:
 ```
 import broadlink
diff --git a/broadlink/__init__.py b/broadlink/__init__.py
index f875f5ba9013..68ad55990752 100644
--- a/broadlink/__init__.py
+++ b/broadlink/__init__.py
@@ -503,3 +503,40 @@ class rm2(rm):
     dev = discover()
     self.host = dev.host
     self.mac = dev.mac
+
+# Setup a new Broadlink device via AP Mode. Review the README to see how to enter AP Mode.
+# Only tested with Broadlink RM3 Mini (Blackbean)
+def setup(ssid, password, security_mode):
+  # Security mode options are (0 - none, 1 = WEP, 2 = WPA1, 3 = WPA2, 4 = WPA1/2)
+  payload = bytearray(0x88)
+  payload[0x26] = 0x14  # This seems to always be set to 14
+  # Add the SSID to the payload
+  ssid_start = 68
+  ssid_length = 0
+  for letter in ssid:
+    payload[(ssid_start + ssid_length)] = ord(letter)
+    ssid_length += 1
+  # Add the WiFi password to the payload
+  pass_start = 100
+  pass_length = 0
+  for letter in password:
+    payload[(pass_start + pass_length)] = ord(letter)
+    pass_length += 1
+
+  payload[0x84] = ssid_length  # Character length of SSID
+  payload[0x85] = pass_length  # Character length of password
+  payload[0x86] = security_mode  # Type of encryption (00 - none, 01 = WEP, 02 = WPA1, 03 = WPA2, 04 = WPA1/2)
+
+  checksum = 0xbeaf
+  for i in range(len(payload)):
+    checksum += payload[i]
+    checksum = checksum & 0xffff
+
+  payload[0x20] = checksum & 0xff  # Checksum 1 position
+  payload[0x21] = checksum >> 8  # Checksum 2 position
+
+  sock = socket.socket(socket.AF_INET,  # Internet
+                       socket.SOCK_DGRAM)  # UDP
+  sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+  sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+  sock.sendto(payload, ('255.255.255.255', 80))
\ No newline at end of file
diff --git a/protocol.md b/protocol.md
index fc58c32e55c5..e9ac99b13c3d 100644
--- a/protocol.md
+++ b/protocol.md
@@ -11,6 +11,25 @@ Checksum
 
 Construct the packet and set checksum bytes to zero. Add each byte to the starting value of 0xbeaf, wrapping after 0xffff.
 
+New device setup
+----------------
+
+To setup a new Broadlink device while in AP Mode a 136 byte packet needs to be sent to the device as follows:
+
+| Offset  | Contents |
+|---------|----------|
+|0x00-0x19|00|
+|0x20-0x21|Checksum as a little-endian 16 bit integer|
+|0x26|14 (Always 14)|
+|0x44-0x63|SSID Name (zero padding is appended)|
+|0x64-0x83|Password (zero padding is appended)|
+|0x84|Character length of SSID|
+|0x85|Character length of password|
+|0x86|Wireless security mode (00 - none, 01 = WEP, 02 = WPA1, 03 = WPA2, 04 = WPA1/2)|
+|0x87-88|00|
+
+Send this packet as a UDP broadcast to 255.255.255.255 on port 80.
+
 Network discovery
 -----------------
 
@@ -179,3 +198,5 @@ Todo
 
 * Support for other devices using the Broadlink protocol (various smart home devices)
 * Figure out what the format of the data packets actually is.
+* Deal with the response after AP Mode WiFi network setup.
+