python-broadlink 1.0.0__tar.gz

python_broadlink-1.0.0/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+Keep a Changelog; versions follow Semantic Versioning.
+
+## 1.0.0 - 2026-09-05
+
+This is the first release of `python-broadlink`, a maintained fork of
+`mjg59/python-broadlink` (PyPI `broadlink`, last released as 0.19.0). The
+history below starts at that fork point.
+
+### Changed
+
+- **The library is asynchronous.** Every method that talks to a device is
+  now a coroutine: `await device.auth()`, `await device.send_data(...)`,
+  `await device.check_sensors()`, and so on. Discovery is
+  `await broadlink.discover(...)`, `broadlink.hello(...)` and `setup(...)`
+  are coroutines, and `xdiscover(...)` is an async generator. The packet
+  helpers (`pulses_to_data`, `data_to_pulses`), CRC and datetime helpers
+  stay synchronous. There is no synchronous compatibility layer: a call
+  without `await` returns a coroutine and does nothing.
+- Each device keeps one UDP endpoint for its lifetime (the previous
+  version opened a socket per call) and serializes requests on it with an
+  `asyncio.Lock`. The old code declared a lock but never acquired it.
+  `async with device:` or `await device.aclose()` releases the endpoint;
+  it reopens on the next call.
+- When a device reports that the session key has expired, the library
+  re-authenticates once and repeats the request. Callers no longer need
+  their own re-auth loop.
+- Retry and timeout behaviour is unchanged: a request is repeated every
+  second until `timeout` elapses, then `NetworkTimeoutError` is raised.
+- `dooya.set_percentage_and_wait` sleeps with `asyncio.sleep`.
+- The CLI tools run their body under `asyncio.run`. `broadlink_cli
+  --learn` and `--rflearn` use `capture()` / `capture_rf()`, so a learning
+  session no longer goes deaf when the device times out partway through;
+  `--window` sets how long to listen, `--keep` prints every code heard, and
+  `--send --durations --repeat N` sets the repeat count. The CLI README's
+  `--rfscanlearn` was a typo for `--rflearn` (mjg59/python-broadlink#803,
+  #830).
+- `pulses_to_data` returns `bytes` (it returned a `bytearray`, against its
+  own annotation).
+- Packaging moved to `pyproject.toml`; `setup.py` and the stale
+  `requirements.txt` pin are gone. The distribution name is now
+  `python-broadlink`; the import name stays `broadlink`. Python 3.13 or
+  newer is required.
+- Continuous integration now runs `ruff` and `pytest` on Python 3.13 and
+  3.14, and builds the sdist and wheel on every pull request. Releases are
+  published to PyPI from version tags using trusted publishing.
+
+### Fixed
+
+- The IR tick constant used by `pulses_to_data` and `data_to_pulses` is now
+  `TICK = 8192 / 269` (about 30.45 us), matching the device's 32768 Hz
+  timebase as documented in `protocol.md`. The previous value, 32.84, was
+  the inverse ratio applied the wrong way round and compressed IR codes
+  built from true microsecond timings by about 7 percent. Codes learned and
+  replayed through the same device were unaffected. Verified on an RM4 Pro
+  against an independent receiver in both directions.
+  (mjg59/python-broadlink#839, #841)
+- `pulses_to_data` rounds each duration to the nearest tick instead of
+  truncating, which removes up to one tick of systematic shortening per
+  pulse.
+
+### Added
+
+- `capture()` and `capture_rf()`, async generators that own the arm, poll,
+  timeout and re-arm loop of a learning session and yield each signal as a
+  `CapturedSignal` (device packet, decoded pulses at the correct tick,
+  kind, repeat count, and for RF the carrier frequency). They re-arm on a
+  timer, because the device leaves learning mode silently, and after any
+  `send_data`, because a transmission ends the session; both intervals and
+  the poll cadence were set from a bench on an RM4 Pro. Only one window can
+  be open per device. `capture_rf()` (Pro models only) takes the carrier
+  frequency directly and falls back to the on-device sweep when it is not
+  given.
+- Packet helpers: `pulses_to_data` takes `kind` and `repeat`, `parse_packet`
+  is its inverse, and `SignalKind` names the IR, 433 MHz and 315 MHz bands.
+  A device's returned RF packet does not always use the canonical type byte
+  (an RM4 Pro answers a 433 MHz capture with 0xB1, not 0xB2), so the kind is
+  read by band and a capture is tagged from what it armed rather than the
+  byte.
+- Devices, carried over from pull requests against the original repository
+  with their authors' commits intact: RM Max 0xAF8B (#838, Alexey Masolov);
+  RM5 plus 0x5224 with a new `rm5plus` class (#831, Anil Daoud); RM mini 3
+  OEM 0xA544 (#823, Bartłomiej Nogaś); RM mini 3 CMCC 0x27C8 (#802,
+  shuxin); LB26 R1 0xA517 (#812, techitapart); SP mini 3-AL 0x7D15 (#805,
+  bbcbbk); LEDVANCE SMART+ WIFI CEILING TW 24W 0x6498 (#799, Felipe Martins
+  Diel).
+- Devices reported in issues against the original repository, added by
+  model name to the existing class for that family and not yet confirmed on
+  hardware: MP1-1K3S2U 0x4EDA (#816) and SP4 0xA57A (#758). Please open an
+  issue if either does not behave.
+- `cryptography` 43 or newer is required, the first release with wheels for
+  Python 3.13 (supersedes mjg59/python-broadlink#749).
+- A test suite. The `tests/oracle` package records the exact request bytes
+  every public method of every device class sends, and the results it
+  decodes from canned responses, so that later changes to the transport
+  can be checked byte for byte against the original behavior.

python_broadlink-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Mike Ryan
+Copyright (c) 2016 Matthew Garrett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

python_broadlink-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE README.md CHANGELOG.md protocol.md TROUBLESHOOTING.md
+include pyproject.toml
+graft cli
+graft tests
+global-exclude __pycache__ *.py[cod] .DS_Store

python_broadlink-1.0.0/PKG-INFO

@@ -0,0 +1,360 @@
+Metadata-Version: 2.4
+Name: python-broadlink
+Version: 1.0.0
+Summary: Python API for controlling Broadlink devices
+Author: DAB-LABS
+Author-email: Matthew Garrett <mjg59@srcf.ucam.org>
+Maintainer: DAB-LABS
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/DAB-LABS/python-broadlink
+Project-URL: Repository, https://github.com/DAB-LABS/python-broadlink
+Project-URL: Issues, https://github.com/DAB-LABS/python-broadlink/issues
+Project-URL: Changelog, https://github.com/DAB-LABS/python-broadlink/blob/master/CHANGELOG.md
+Project-URL: Upstream, https://github.com/mjg59/python-broadlink
+Keywords: broadlink,infrared,rf,home-assistant,rm4,rm-pro
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=43
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# python-broadlink
+
+A Python module and CLI for controlling Broadlink devices locally.
+
+> **About this fork.** This repository is a maintained fork of
+> [mjg59/python-broadlink](https://github.com/mjg59/python-broadlink), which
+> has not accepted changes since 2024. It exists so that Home Assistant's
+> Broadlink integration has a library that can take fixes and new devices.
+> The distribution on PyPI is `python-broadlink`; the import name stays
+> `broadlink`. The first release corrects the IR timing constant reported in
+> upstream [#839](https://github.com/mjg59/python-broadlink/issues/839)
+> (fix in [#841](https://github.com/mjg59/python-broadlink/pull/841)) and
+> adds the devices waiting in upstream's pull request queue, including the
+> RM Max and RM5 Plus. Version 1.0 is asynchronous and adds `capture()`;
+> see `CHANGELOG.md`. Upstream's credit and MIT license are preserved.
+
+## Version 1.0 is asynchronous
+
+Every call that reaches a device is a coroutine and must be awaited. This
+is the whole change from the original library's API; method names,
+arguments and return values are the same.
+
+```python
+import asyncio
+import broadlink
+
+async def main():
+    devices = await broadlink.discover(timeout=5)
+    device = devices[0]
+    await device.auth()
+    print(await device.check_sensors())
+
+asyncio.run(main())
+```
+
+Calling a device method without `await` returns a coroutine object and
+sends nothing; Python prints a `RuntimeWarning: coroutine ... was never
+awaited` when it is garbage collected. If you need the old synchronous
+behaviour, pin the original distribution (`broadlink==0.19.0`) instead.
+
+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, RM4 TV mate, RM Max, RM5 plus
+- **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, SP mini 3-AL, 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, LB26 R1, LB27 R1, SB800TD, LEDVANCE SMART+ WIFI CEILING TW 24W
+- **Curtain motors**: Dooya DT360E-45/20
+- **Thermostats**: Hysen HY02B05H
+- **Hubs**: S3
+
+## Installation
+
+Use pip3 to install the latest version of this module.
+
+```
+pip3 install python-broadlink
+```
+
+If the original `broadlink` distribution is also installed in the same
+environment, remove it first (`pip3 uninstall broadlink`); both provide the
+`broadlink` package.
+
+## Basic functions
+
+The examples below are written as they would appear inside an `async def`
+function run with `asyncio.run(...)`, as in the snippet above. To try them
+interactively, start Python with `python3 -m asyncio`, which gives you a
+prompt where `await` works at the top level.
+
+```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
+await broadlink.setup('myssid', 'mynetworkpass', 3)
+```
+
+Security mode options are (0 = none, 1 = WEP, 2 = WPA1, 3 = WPA2, 4 = WPA1/2)
+
+#### Advanced options
+
+You may need to specify a broadcast address if setup is not working.
+```python3
+await broadlink.setup('myssid', 'mynetworkpass', 3, ip_address='192.168.0.255')
+```
+
+### Discovery
+
+Use this function to discover devices:
+
+```python3
+devices = await broadlink.discover()
+```
+
+#### Advanced options
+You may need to specify `local_ip_address` or `discover_ip_address` if discovery does not return any devices.
+
+Using the IP address of your local machine:
+```python3
+devices = await broadlink.discover(local_ip_address='192.168.0.100')
+```
+
+Using the broadcast address of your subnet:
+```python3
+devices = await broadlink.discover(discover_ip_address='192.168.0.255')
+```
+
+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 = await broadlink.hello('192.168.0.16')
+```
+
+If you are a perfomance freak, use `broadlink.xdiscover()` to create devices instantly:
+```python3
+async for device in broadlink.xdiscover():
+    print(device)  # Example action. Do whatever you want here.
+```
+
+### Authentication
+After discovering the device, call the `auth()` method to obtain the authentication key required for further communication:
+```python3
+await device.auth()
+```
+
+The next steps depend on the type of device you want to control.
+
+## Universal remotes
+
+### Learning IR codes
+
+Learning IR codes takes place in three steps.
+
+1. Enter learning mode:
+```python3
+await device.enter_learning()
+```
+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 = await device.check_data()
+```
+
+### Learning RF codes
+
+Learning RF codes takes place in six steps.
+
+1. Sweep the frequency:
+```python3
+await device.sweep_frequency()
+```
+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. Check if the frequency was successfully identified:
+```python3
+ok, frequency = await device.check_frequency()
+if ok:
+    print(f'Frequency found: {frequency} MHz')
+```
+4. Enter learning mode:
+```python3
+await device.find_rf_packet()
+```
+5. When the LED blinks, point the remote at the Broadlink device for the second time and short press the button you want to learn.
+6. Get the RF packet:
+```python3
+packet = await device.check_data()
+```
+
+#### Notes
+
+Universal remotes with product id 0x2712 use the same method for learning IR and RF codes. They don't need to sweep frequency. Just call `device.enter_learning()` and `device.check_data()`.
+
+### Canceling learning
+
+You can exit the learning mode in the middle of the process by calling this method:
+```python3
+await device.cancel_sweep_frequency()
+```
+
+### Capturing signals
+
+`capture()` wraps the arm, poll, timeout and re-arm dance above into one
+async generator that yields each signal it hears as a `CapturedSignal`:
+
+```python3
+from contextlib import aclosing
+
+async with aclosing(device.capture(window=30)) as signals:
+    async for signal in signals:
+        print(signal.kind, len(signal.pulses), "pulses")
+        await other_device.send_data(signal.packet)
+```
+
+By default the window closes after the first signal. Pass
+`stop_after_first=False` to keep it open for the whole `window` (in seconds;
+`window=0` runs until the generator is closed), re-arming after each signal
+because the device holds only one code per learning session. A universal
+remote has a single receiver, so only one capture window can be open on a
+device at a time.
+
+`CapturedSignal` carries the device's own `packet` bytes (ready for
+`send_data`), the decoded `pulses` in microseconds at the correct tick, the
+`kind` (`SignalKind.IR`, `RF_433` or `RF_315`), the `repeat` count, and for
+RF the `frequency_mhz` the packet itself does not record.
+
+RF works the same way on the Pro models, with the carrier as the one extra
+input:
+
+```python3
+async with aclosing(device.capture_rf(window=30, frequency=433.92)) as signals:
+    async for signal in signals:
+        ...
+```
+
+Pass `frequency` whenever you know it. Without it the device first sweeps
+for the carrier while you hold a button down, then learns the code from a
+fresh press; the sweep is unreliable on some firmware and can report a
+carrier it never really locked, so the known-frequency path is preferred.
+
+### Sending IR/RF packets
+```python3
+await device.send_data(packet)
+```
+
+### Fetching sensor data
+```python3
+data = await device.check_sensors()
+```
+
+## Switches
+
+### Setting power state
+```python3
+await device.set_power(True)
+await device.set_power(False)
+```
+
+### Checking power state
+```python3
+state = await device.check_power()
+```
+
+### Checking energy consumption
+```python3
+state = await device.get_energy()
+```
+
+## Power strips
+
+### Setting power state
+```python3
+await device.set_power(1, True)  # Example socket. It could be 2 or 3.
+await device.set_power(1, False)
+```
+
+### Checking power state
+```python3
+state = await device.check_power()
+```
+
+## Light bulbs
+
+### Fetching data
+```python3
+state = await device.get_state()
+```
+
+### Setting state attributes
+```python3
+await devices[0].set_state(pwr=0)
+await devices[0].set_state(pwr=1)
+await devices[0].set_state(brightness=75)
+await devices[0].set_state(bulb_colormode=0)
+await devices[0].set_state(blue=255)
+await devices[0].set_state(red=0)
+await devices[0].set_state(green=128)
+await devices[0].set_state(bulb_colormode=1)
+```
+
+## Environment sensors
+
+### Fetching sensor data
+```python3
+data = await device.check_sensors()
+```
+
+## Hubs
+
+### Discovering subdevices
+```python3
+await device.get_subdevices()
+```
+
+### Fetching data
+Use the DID obtained from get_subdevices() for the input parameter to query specific sub-device.
+
+```python3
+await device.get_state(did="00000000000000000000a043b0d06963")
+```
+
+### Setting state attributes
+The parameters depend on the type of subdevice that is being controlled. In this example, we are controlling LC-1 switches:
+
+#### Turn on
+```python3
+await device.set_state(did="00000000000000000000a043b0d0783a", pwr=1)
+await device.set_state(did="00000000000000000000a043b0d0783a", pwr1=1)
+await device.set_state(did="00000000000000000000a043b0d0783a", pwr2=1)
+```
+#### Turn off
+```python3
+await device.set_state(did="00000000000000000000a043b0d0783a", pwr=0)
+await device.set_state(did="00000000000000000000a043b0d0783a", pwr1=0)
+await device.set_state(did="00000000000000000000a043b0d0783a", pwr2=0)
+```