Improve README.md (#625)
This commit is contained in:
Felipe Martins Diel
GitHub
parent
e29170c754
commit
a721087c07
229
README.md
229
README.md
|
|
@ -1,150 +1,184 @@
|
|||
Python control for Broadlink devices
|
||||
===============================================
|
||||
# python-broadlink
|
||||
|
||||
A simple Python API for controlling Broadlink devices. At present, the following devices are supported:
|
||||
A Python module and CLI for controlling Broadlink devices locally. The following devices are supported:
|
||||
|
||||
- **Universal remotes**: RM home, RM mini 3, RM plus, RM pro, RM pro+, RM4 mini, RM4 pro, RM4C mini, RM4S
|
||||
- **Smart plugs**: SP mini, SP mini 3, SP mini+, SP1, SP2, SP2-BR, SP2-CL, SP2-IN, SP2-UK, SP3, SP3-EU, SP3S-EU, SP3S-US, SP4L-AU, SP4L-EU, SP4L-UK, SP4M, SP4M-US
|
||||
- **Power strips**: MP1-1K3S2U, MP1-1K4S, MP2
|
||||
- **Wi-Fi controlled switches**: MCB1, SC1, SCB1E
|
||||
- **Environment sensors**: A1
|
||||
- **Alarm kits**: S2KIT
|
||||
- **Light bulbs**: LB1, SB800TD
|
||||
|
||||
Other devices with Broadlink DNA:
|
||||
- **Smart plugs**: Ankuoo NEO, Ankuoo NEO PRO, BG AHC/U-01, Efergy Ego
|
||||
- **Smart plugs**: SP mini, SP mini 3, SP mini+, SP1, SP2, SP2-BR, SP2-CL, SP2-IN, SP2-UK, SP3, SP3-EU, SP3S-EU, SP3S-US, SP4L-AU, SP4L-EU, SP4L-UK, SP4M, SP4M-US, Ankuoo NEO, Ankuoo NEO PRO, Efergy Ego, BG AHC/U-01
|
||||
- **Switches**: MCB1, SC1, SCB1E, SCB2
|
||||
- **Outlets**: BG 800, BG 900
|
||||
- **Power strips**: MP1-1K3S2U, MP1-1K4S, MP2
|
||||
- **Environment sensors**: A1
|
||||
- **Alarm kits**: S1C, S2KIT
|
||||
- **Light bulbs**: LB1, LB2, SB800TD
|
||||
- **Curtain motors**: Dooya DT360E-45/20
|
||||
- **Thermostats**: Hysen HY02B05H
|
||||
|
||||
There is currently no support for the cloud API.
|
||||
## Installation
|
||||
|
||||
Example use
|
||||
-----------
|
||||
Use pip3 to install the latest version of this module.
|
||||
|
||||
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
|
||||
pip3 install broadlink
|
||||
```
|
||||
|
||||
## Basic functions
|
||||
|
||||
First, open Python 3 and import this module.
|
||||
|
||||
```
|
||||
python3
|
||||
```
|
||||
```python3
|
||||
import broadlink
|
||||
```
|
||||
|
||||
Now let's try some functions...
|
||||
|
||||
### Setup
|
||||
|
||||
In order to control the device, you need to connect it to your local network. If you have already configured the device with the Broadlink app, this step is not necessary.
|
||||
|
||||
1. Put the device into AP Mode.
|
||||
- Long press the reset button until the blue LED is blinking quickly.
|
||||
- Long press again until blue LED is blinking slowly.
|
||||
- Manually connect to the WiFi SSID named BroadlinkProv.
|
||||
2. Connect the device to your local network with the setup function.
|
||||
```python3
|
||||
broadlink.setup('myssid', 'mynetworkpass', 3)
|
||||
```
|
||||
|
||||
Discover available devices on the local network:
|
||||
```
|
||||
import broadlink
|
||||
Security mode options are (0 = none, 1 = WEP, 2 = WPA1, 3 = WPA2, 4 = WPA1/2)
|
||||
|
||||
devices = broadlink.discover(timeout=5)
|
||||
### Discovery
|
||||
|
||||
Use this function to discover devices:
|
||||
|
||||
```python3
|
||||
devices = broadlink.discover()
|
||||
```
|
||||
|
||||
#### Advanced options
|
||||
You may need to specify `local_ip_address` or `discover_ip_address` if discovery does not return any devices.
|
||||
|
||||
|
||||
Using your machine's IP address with `local_ip_address`
|
||||
```
|
||||
import broadlink
|
||||
|
||||
devices = broadlink.discover(timeout=5, local_ip_address='192.168.0.100')
|
||||
```python3
|
||||
devices = broadlink.discover(local_ip_address='192.168.0.100') # IP address of your local machine.
|
||||
```
|
||||
|
||||
Using your subnet's broadcast address with `discover_ip_address`
|
||||
|
||||
```
|
||||
import broadlink
|
||||
|
||||
devices = broadlink.discover(timeout=5, discover_ip_address='192.168.0.255')
|
||||
```python3
|
||||
devices = broadlink.discover(discover_ip_address='192.168.0.255') # Broadcast address of your subnet.
|
||||
```
|
||||
|
||||
Obtain the authentication key required for further communication:
|
||||
```
|
||||
devices[0].auth()
|
||||
If the device is locked, it may not be discoverable with broadcast. In such cases, you can use the unicast version `broadlink.hello()` for direct discovery:
|
||||
```python3
|
||||
device = broadlink.hello('192.168.0.16') # IP address of your Broadlink device.
|
||||
```
|
||||
|
||||
Enter learning mode:
|
||||
```
|
||||
devices[0].enter_learning()
|
||||
If you are a perfomance freak, use `broadlink.xdiscover()` to create devices instantly:
|
||||
```python3
|
||||
for device in broadlink.xdiscover():
|
||||
print(device) # Example action. Do whatever you want here.
|
||||
```
|
||||
|
||||
Sweep RF frequencies:
|
||||
```
|
||||
devices[0].sweep_frequency()
|
||||
### Authentication
|
||||
After discovering the device, call the `auth()` method to obtain the authentication key required for further communication:
|
||||
```python3
|
||||
device.auth()
|
||||
```
|
||||
|
||||
Cancel sweep RF frequencies:
|
||||
```
|
||||
devices[0].cancel_sweep_frequency()
|
||||
```
|
||||
Check whether a frequency has been found:
|
||||
```
|
||||
found = devices[0].check_frequency()
|
||||
```
|
||||
(This will return True if the RM has locked onto a frequency, False otherwise)
|
||||
The next steps depend on the type of device you want to control.
|
||||
|
||||
Attempt to learn an RF packet:
|
||||
```
|
||||
found = devices[0].find_rf_packet()
|
||||
```
|
||||
(This will return True if a packet has been found, False otherwise)
|
||||
## Universal remotes
|
||||
|
||||
Obtain an IR or RF packet while in learning mode:
|
||||
```
|
||||
ir_packet = devices[0].check_data()
|
||||
```
|
||||
(This will return None if the device does not have a packet to return)
|
||||
### Learning IR codes
|
||||
|
||||
Send an IR or RF packet:
|
||||
Learning IR codes takes place in three steps.
|
||||
|
||||
1. Enter learning mode:
|
||||
```python3
|
||||
device.enter_learning()
|
||||
```
|
||||
devices[0].send_data(ir_packet)
|
||||
2. When the LED blinks, point the remote at the Broadlink device and press the button you want to learn.
|
||||
3. Get the IR packet.
|
||||
```python3
|
||||
packet = device.check_data()
|
||||
```
|
||||
|
||||
Obtain temperature data from an RM2:
|
||||
### Learning RF codes
|
||||
|
||||
Learning IR codes takes place in five steps.
|
||||
|
||||
1. Sweep the frequency:
|
||||
```python3
|
||||
device.sweep_frequency()
|
||||
```
|
||||
devices[0].check_temperature()
|
||||
2. When the LED blinks, point the remote at the Broadlink device for the first time and long press the button you want to learn.
|
||||
3. Enter learning mode:
|
||||
```python3
|
||||
device.find_rf_packet()
|
||||
```
|
||||
4. When the LED blinks, point the remote at the Broadlink device for the second time and short press the button you want to learn.
|
||||
5. Get the RF packet:
|
||||
```python3
|
||||
packet = device.check_data()
|
||||
```
|
||||
|
||||
Obtain sensor data from an A1:
|
||||
```
|
||||
data = devices[0].check_sensors()
|
||||
### Canceling learning
|
||||
|
||||
You can exit the learning mode in the middle of the process by calling this method:
|
||||
```python3
|
||||
device.cancel_sweep_frequency()
|
||||
```
|
||||
|
||||
Set power state on a SmartPlug SP2/SP3/SP4:
|
||||
```
|
||||
devices[0].set_power(True)
|
||||
### Sending IR/RF packets
|
||||
```python3
|
||||
device.send_data(packet)
|
||||
```
|
||||
|
||||
Check power state on a SmartPlug:
|
||||
```
|
||||
state = devices[0].check_power()
|
||||
### Fetching sensor data
|
||||
```python3
|
||||
data = device.check_sensors()
|
||||
```
|
||||
|
||||
Check energy consumption on a SmartPlug:
|
||||
```
|
||||
state = devices[0].get_energy()
|
||||
## Switches
|
||||
|
||||
### Setting power state
|
||||
```python3
|
||||
device.set_power(True)
|
||||
device.set_power(False)
|
||||
```
|
||||
|
||||
Set power state for S1 on a SmartPowerStrip MP1:
|
||||
```
|
||||
devices[0].set_power(1, True)
|
||||
### Checking power state
|
||||
```python3
|
||||
state = device.check_power()
|
||||
```
|
||||
|
||||
Check power state on a SmartPowerStrip:
|
||||
```
|
||||
state = devices[0].check_power()
|
||||
### Checking energy consumption
|
||||
```python3
|
||||
state = device.get_energy()
|
||||
```
|
||||
|
||||
Get state on a bulb
|
||||
```
|
||||
state=devices[0].get_state()
|
||||
## Power strips
|
||||
|
||||
### Setting power state
|
||||
```python3
|
||||
device.set_power(1, True) # Example socket. It could be 2 or 3.
|
||||
device.set_power(1, False)
|
||||
```
|
||||
|
||||
Set a state on a bulb
|
||||
### Checking power state
|
||||
```python3
|
||||
state = device.check_power()
|
||||
```
|
||||
|
||||
## Light bulbs
|
||||
|
||||
### Fetching data
|
||||
```python3
|
||||
state = device.get_state()
|
||||
```
|
||||
|
||||
### Setting state attributes
|
||||
```python3
|
||||
devices[0].set_state(pwr=0)
|
||||
devices[0].set_state(pwr=1)
|
||||
devices[0].set_state(brightness=75)
|
||||
|
|
@ -154,3 +188,10 @@ devices[0].set_state(red=0)
|
|||
devices[0].set_state(green=128)
|
||||
devices[0].set_state(bulb_colormode=1)
|
||||
```
|
||||
|
||||
## Environment sensors
|
||||
|
||||
### Fetching sensor data
|
||||
```python3
|
||||
data = device.check_sensors()
|
||||
```
|
||||
Loading…
Reference in New Issue