about summary refs log tree commit diff
path: root/third_party/python/broadlink/protocol.md

Broadlink RM2 network protocol

Encryption

Packets include AES-based encryption in CBC mode. The initial key is 0x09, 0x76, 0x28, 0x34, 0x3f, 0xe9, 0x9e, 0x23, 0x76, 0x5c, 0x15, 0x13, 0xac, 0xcf, 0x8b, 0x02. The IV is 0x56, 0x2e, 0x17, 0x99, 0x6d, 0x09, 0x3d, 0x28, 0xdd, 0xb3, 0xba, 0x69, 0x5a, 0x2e, 0x6f, 0x58.

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

To discover Broadlink devices on the local network, send a 48 byte packet with the following contents:

Offset Contents
0x00-0x07 00
0x08-0x0b Current offset from GMT as a little-endian 32 bit integer
0x0c-0x0d Current year as a little-endian 16 bit integer
0x0e Current number of seconds past the minute
0x0f Current number of minutes past the hour
0x10 Current number of hours past midnight
0x11 Current day of the week (Monday = 1, Tuesday = 2, etc)
0x12 Current day in month
0x13 Current month
0x14-0x17 00
0x18-0x1b Local IP address
0x1c-0x1d Source port as a little-endian 16 bit integer
0x1e-0x1f 00
0x20-0x21 Checksum as a little-endian 16 bit integer
0x22-0x25 00
0x26 06
0x27-0x2f 00

Send this packet as a UDP broadcast to 255.255.255.255 on port 80.

Response (any unicast response):

Offset Contents
0x34-0x35 Device type as a little-endian 16 bit integer (see device type mapping)
0x3a-0x3f MAC address of the target device

Device type mapping:

Device type in response packet Device type Treat as
0 SP1 SP1
0x2711 SP2 SP2
0x2719 or 0x7919 or 0x271a or 0x791a Honeywell SP2 SP2
0x2720 SPMini SP2
0x753e SP3 SP2
0x2728 SPMini2 SP2
0x2733 or 0x273e OEM branded SPMini SP2
>= 0x7530 and <= 0x7918 OEM branded SPMini2 SP2
0x2736 SPMiniPlus SP2
0x2712 RM2 RM
0x2737 RM Mini / RM3 Mini Blackbean RM
0x273d RM Pro Phicomm RM
0x2783 RM2 Home Plus RM
0x277c RM2 Home Plus GDT RM
0x272a RM2 Pro Plus RM
0x2787 RM2 Pro Plus2 RM
0x278b RM2 Pro Plus BL RM
0x278f RM Mini Shate RM
0x2714 A1 A1
0x4EB5 MP1 MP1

Command packet format

The command packet header is 56 bytes long with the following format:

Offset Contents
0x00 0x5a
0x01 0xa5
0x02 0xaa
0x03 0x55
0x04 0x5a
0x05 0xa5
0x06 0xaa
0x07 0x55
0x08-0x1f 00
0x20-0x21 Checksum of full packet as a little-endian 16 bit integer
0x22-0x23 00
0x24-0x25 Device type as a little-endian 16 bit integer
0x26-0x27 Command code as a little-endian 16 bit integer
0x28-0x29 Packet count as a little-endian 16 bit integer
0x2a-0x2f Local MAC address
0x30-0x33 Local device ID (obtained during authentication, 00 before authentication)
0x34-0x35 Checksum of unencrypted payload as a little-endian 16 bit integer
0x36-0x37 00

The payload is appended immediately after this. The checksum at 0x20 is calculated after the payload is appended, and covers the entire packet (including the checksum at 0x34). Therefore:

  1. Generate packet header with checksum values set to 0
  2. Set the checksum initialisation value to 0xbeaf and calculate the checksum of the unencrypted payload. Set 0x34-0x35 to this value.
  3. Encrypt and append the payload
  4. Set the checksum initialisation value to 0xbeaf and calculate the checksum of the entire packet. Set 0x20-0x21 to this value.

Authorisation

You must obtain an authorisation key from the device before you can communicate. To do so, generate an 80 byte packet with the following contents:

Offset Contents
0x00-0x03 00
0x04-0x12 A 15-digit value that represents this device. Broadlink's implementation uses the IMEI.
0x13 01
0x14-0x2c 00
0x2d 0x01
0x30-0x7f NULL-terminated ASCII string containing the device name

Send this payload with a command value of 0x0065. The response packet will contain an encrypted payload from byte 0x38 onwards. Decrypt this using the default key and IV. The format of the decrypted payload is:

Offset Contents
0x00-0x03 Device ID
0x04-0x13 Device encryption key

All further command packets must use this encryption key and device ID.

Entering learning mode

Send the following 16 byte payload with a command value of 0x006a:

Offset Contents
0x00 0x03
0x01-0x0f 0x00

Reading back data from learning mode

Send the following 16 byte payload with a command value of 0x006a:

Offset Contents
0x00 0x04
0x01-0x0f 0x00

Byte 0x22 of the response contains a little-endian 16 bit error code. If this is 0, a code has been obtained. Bytes 0x38 and onward of the response are encrypted. Decrypt them. Bytes 0x04 and onward of the decrypted payload contain the captured data.

Sending data

Send the following payload with a command byte of 0x006a

Offset Contents
0x00 0x02
0x01-0x03 0x00
0x04 0x26 = IR, 0xb2 for RF 433Mhz, 0xd7 for RF 315Mhz
0x05 repeat count, (0 = no repeat, 1 send twice, .....)
0x06-0x07 Length of the following data in little endian
0x08 .... Pulse lengths in 2^-15 s units (µs * 269 / 8192 works very well)
.... 0x0d 0x05 at the end for IR only

Each value is represented by one byte. If the length exceeds one byte then it is stored big endian with a leading 0.

Example: The header for my Optoma projector is 8920 4450
8920 * 269 / 8192 = 0x124
4450 * 269 / 8192 = 0x92

So the data starts with 0x00 0x1 0x24 0x92 ....

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.