broadlink-async 1.2.1__tar.gz → 1.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/CHANGELOG.md +13 -0
  2. {broadlink_async-1.2.1/broadlink_async.egg-info → broadlink_async-1.3.0}/PKG-INFO +25 -1
  3. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/README.md +24 -0
  4. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/remote.py +114 -2
  5. {broadlink_async-1.2.1 → broadlink_async-1.3.0/broadlink_async.egg-info}/PKG-INFO +25 -1
  6. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async.egg-info/SOURCES.txt +2 -0
  7. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/protocol.md +15 -0
  8. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/pyproject.toml +1 -1
  9. broadlink_async-1.3.0/tests/fixtures/rm4pro_rf_bench.json +155 -0
  10. broadlink_async-1.3.0/tests/test_rm4_rf.py +241 -0
  11. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/LICENSE +0 -0
  12. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/MANIFEST.in +0 -0
  13. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/TROUBLESHOOTING.md +0 -0
  14. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/__init__.py +0 -0
  15. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/alarm.py +0 -0
  16. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/climate.py +0 -0
  17. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/const.py +0 -0
  18. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/cover.py +0 -0
  19. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/device.py +0 -0
  20. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/exceptions.py +0 -0
  21. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/helpers.py +0 -0
  22. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/hub.py +0 -0
  23. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/light.py +0 -0
  24. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/protocol.py +0 -0
  25. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/sensor.py +0 -0
  26. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async/switch.py +0 -0
  27. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async.egg-info/dependency_links.txt +0 -0
  28. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async.egg-info/requires.txt +0 -0
  29. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/broadlink_async.egg-info/top_level.txt +0 -0
  30. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/cli/README.md +0 -0
  31. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/cli/broadlink_cli +0 -0
  32. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/cli/broadlink_discovery +0 -0
  33. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/setup.cfg +0 -0
  34. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/__init__.py +0 -0
  35. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/oracle/__init__.py +0 -0
  36. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/oracle/cases.py +0 -0
  37. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/oracle/fixtures.json +0 -0
  38. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/oracle/harness.py +0 -0
  39. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/oracle/record.py +0 -0
  40. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/test_capture.py +0 -0
  41. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/test_fl_state_rename.py +0 -0
  42. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/test_helpers.py +0 -0
  43. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/test_loopback.py +0 -0
  44. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/test_oracle.py +0 -0
  45. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/test_realign.py +0 -0
  46. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/test_remote.py +0 -0
  47. {broadlink_async-1.2.1 → broadlink_async-1.3.0}/tests/test_transport.py +0 -0
@@ -3,6 +3,19 @@
3
3
  All notable changes to this project are recorded here. The format follows
4
4
  Keep a Changelog; versions follow Semantic Versioning.
5
5
 
6
+ ## 1.3.0 - 2026-11-16
7
+
8
+ ### Added
9
+
10
+ - `pulses_to_rm4_rf` builds an RM4 Pro RF packet with its frequency in it,
11
+ so the device sends on the frequency asked for.
12
+
13
+ ### Fixed
14
+
15
+ - A duration under half a tick no longer breaks the rest of a packet. It is
16
+ written as one tick.
17
+ - A duration over about 2 seconds raises a clear `ValueError`.
18
+
6
19
  ## 1.2.1 - 2026-11-04
7
20
 
8
21
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: broadlink-async
3
- Version: 1.2.1
3
+ Version: 1.3.0
4
4
  Summary: Python API for controlling Broadlink devices
5
5
  Author: DAB-LABS
6
6
  Author-email: Matthew Garrett <mjg59@srcf.ucam.org>
@@ -373,6 +373,30 @@ carrier it never really locked, so the known-frequency path is preferred.
373
373
  await device.send_data(packet)
374
374
  ```
375
375
 
376
+ #### Building an RF packet for an RM4 Pro
377
+
378
+ An RM4 Pro sends an RF packet of type 0xB1 on the carrier written inside
379
+ it. `pulses_to_rm4_rf` builds one from a frame of signed microsecond
380
+ timings (positive is carrier on, negative is carrier off, starting with a
381
+ pulse), written out `frames` times:
382
+
383
+ ```python3
384
+ from broadlink_async.remote import pulses_to_rm4_rf
385
+
386
+ packet = pulses_to_rm4_rf(timings, 433.92, frames=4, gap_us=12881, tail_us=45680)
387
+ await device.send_data(packet)
388
+ ```
389
+
390
+ A frame that ends on an off time keeps it as the gap between frames; one
391
+ that ends on a pulse needs `gap_us`. The packet always ends on an off
392
+ time, `tail_us` when given. On the bench a plug's code sent as one frame
393
+ did nothing and as 4 or 10 frames worked, so send more than one. Built
394
+ packets were tested up to about 530 bytes, the size of a learned packet;
395
+ the device's own limit is not known. The builder does not check the
396
+ carrier against any band. Only the RM4 Pro has been
397
+ tested with this layout; `pulses_to_data` with `kind=SignalKind.RF_433`
398
+ builds the older layout, which has no carrier field.
399
+
376
400
  ### Fetching sensor data
377
401
  ```python3
378
402
  data = await device.check_sensors()
@@ -342,6 +342,30 @@ carrier it never really locked, so the known-frequency path is preferred.
342
342
  await device.send_data(packet)
343
343
  ```
344
344
 
345
+ #### Building an RF packet for an RM4 Pro
346
+
347
+ An RM4 Pro sends an RF packet of type 0xB1 on the carrier written inside
348
+ it. `pulses_to_rm4_rf` builds one from a frame of signed microsecond
349
+ timings (positive is carrier on, negative is carrier off, starting with a
350
+ pulse), written out `frames` times:
351
+
352
+ ```python3
353
+ from broadlink_async.remote import pulses_to_rm4_rf
354
+
355
+ packet = pulses_to_rm4_rf(timings, 433.92, frames=4, gap_us=12881, tail_us=45680)
356
+ await device.send_data(packet)
357
+ ```
358
+
359
+ A frame that ends on an off time keeps it as the gap between frames; one
360
+ that ends on a pulse needs `gap_us`. The packet always ends on an off
361
+ time, `tail_us` when given. On the bench a plug's code sent as one frame
362
+ did nothing and as 4 or 10 frames worked, so send more than one. Built
363
+ packets were tested up to about 530 bytes, the size of a learned packet;
364
+ the device's own limit is not known. The builder does not check the
365
+ carrier against any band. Only the RM4 Pro has been
366
+ tested with this layout; `pulses_to_data` with `kind=SignalKind.RF_433`
367
+ builds the older layout, which has no carrier field.
368
+
345
369
  ### Fetching sensor data
346
370
  ```python3
347
371
  data = await device.check_sensors()
@@ -3,10 +3,12 @@
3
3
  import asyncio
4
4
  import contextlib
5
5
  import enum
6
+ import itertools
6
7
  import logging
8
+ import math
7
9
  import struct
8
10
  import time
9
- from collections.abc import AsyncGenerator, Awaitable, Callable
11
+ from collections.abc import AsyncGenerator, Awaitable, Callable, Sequence
10
12
  from dataclasses import dataclass, field
11
13
  from typing import Self
12
14
 
@@ -127,8 +129,25 @@ next copy (home-assistant/core#190257). RF has not been tested for this.
127
129
  """
128
130
 
129
131
 
132
+ _MAX_TICKS = 0xFFFF
133
+ """The longest duration a packet can hold, in device ticks (about 2 s)."""
134
+
135
+
130
136
  def _append_ticks(result: bytearray, ticks: int) -> None:
131
- """Append one duration, already in device ticks, to a packet."""
137
+ """Append one duration, already in device ticks, to a packet.
138
+
139
+ A duration that rounded to 0 ticks is written as 1 tick: a lone 0x00
140
+ byte is the start of the three-byte long form, so writing it would make
141
+ the device misread every timing after it. A duration longer than
142
+ ``_MAX_TICKS`` has no encoding and raises ``ValueError``.
143
+ """
144
+ if ticks > _MAX_TICKS:
145
+ raise ValueError(
146
+ f"A duration of {ticks} ticks is too long for a Broadlink packet,"
147
+ f" which holds at most {_MAX_TICKS} ticks (about 2 s) per duration"
148
+ )
149
+ if ticks == 0:
150
+ ticks = 1
132
151
  div, mod = divmod(ticks, 256)
133
152
  if div:
134
153
  result.append(0)
@@ -177,6 +196,99 @@ def pulses_to_data(
177
196
  return bytes(result)
178
197
 
179
198
 
199
+ _RM4_RF_BYTE1 = 0xC0
200
+ """Byte 1 of an 0xB1 packet, as every capture has it (see ``RM4_RF_TYPE``)."""
201
+
202
+
203
+ def pulses_to_rm4_rf(
204
+ timings: Sequence[int],
205
+ carrier_mhz: float,
206
+ *,
207
+ frames: int = 1,
208
+ gap_us: int | None = None,
209
+ tail_us: int | None = None,
210
+ tick: float = TICK,
211
+ ) -> bytes:
212
+ """Build an RM4 Pro RF packet (type 0xB1) that sends on ``carrier_mhz``.
213
+
214
+ This is the layout an RM4 Pro returns when it learns an RF code, and
215
+ the device transmits it on the carrier the packet carries (protocol.md).
216
+ The packet is ``frames`` copies of one frame, written out in full,
217
+ because byte 1 of an 0xB1 packet is not a repeat count.
218
+
219
+ ``timings`` is one frame in signed microseconds, starting with a pulse:
220
+ positive is carrier on and negative is carrier off, as rf-protocols'
221
+ ``get_raw_timings()`` gives them. The signs must alternate.
222
+
223
+ Between frames, a frame that ends on an off time keeps it as the gap; a
224
+ frame that ends on a pulse needs ``gap_us`` (unless it is sent once
225
+ with ``tail_us``). When given, ``gap_us`` replaces a trailing off time
226
+ rather than adding to it. The packet always ends on an off time: the
227
+ gap, or ``tail_us`` when given (every learned packet ends on about
228
+ 45,680 us).
229
+
230
+ The carrier is written in kHz and is not checked against any band.
231
+ There is no size limit beyond the packet's length field. The device's
232
+ own limit is not known: built packets were tested on an RM4 Pro up to
233
+ about 530 bytes, the size of a learned packet.
234
+
235
+ Raises ``ValueError`` for timings that do not start with a pulse or do
236
+ not alternate, ``frames`` below 1, a carrier that does not fit the field,
237
+ a gap or tail that is not positive, or a packet too long for its length
238
+ field.
239
+ """
240
+ frame = list(timings)
241
+ if not all(math.isfinite(t) for t in frame):
242
+ raise ValueError("RF timings must be finite numbers")
243
+ if not frame or frame[0] <= 0:
244
+ raise ValueError("RF timings must start with a pulse (a positive value)")
245
+ for before, after in itertools.pairwise(frame):
246
+ if (before > 0) == (after > 0) or after == 0:
247
+ raise ValueError(
248
+ "RF timings must alternate between pulses (positive) and off"
249
+ " times (negative)"
250
+ )
251
+ if not isinstance(frames, int) or frames < 1:
252
+ raise ValueError("frames must be a whole number, at least 1")
253
+ for name, value in (("gap_us", gap_us), ("tail_us", tail_us)):
254
+ if value is not None and not (value > 0 and math.isfinite(value)):
255
+ raise ValueError(f"{name} must be positive")
256
+ if not math.isfinite(carrier_mhz):
257
+ raise ValueError("carrier_mhz must be a finite number")
258
+ carrier_khz = round(carrier_mhz * 1000)
259
+ if not 0 < carrier_khz <= 0xFFFFFFFF:
260
+ raise ValueError(f"A carrier of {carrier_mhz} MHz does not fit an 0xB1 packet")
261
+
262
+ gap = gap_us
263
+ if frame[-1] < 0:
264
+ off = -frame.pop()
265
+ if gap is None:
266
+ gap = off
267
+ tail = tail_us if tail_us is not None else gap
268
+ if tail is None or (gap is None and frames > 1):
269
+ raise ValueError("A frame that ends on a pulse needs gap_us")
270
+
271
+ encoded = bytearray()
272
+ for duration in frame:
273
+ _append_ticks(encoded, round(abs(duration) / tick))
274
+ between = bytearray(encoded)
275
+ if frames > 1:
276
+ _append_ticks(between, round(gap / tick))
277
+ last = bytearray(encoded)
278
+ _append_ticks(last, round(tail / tick))
279
+
280
+ size = _RM4_RF_HEADER_LEN + (frames - 1) * len(between) + len(last)
281
+ if size - 4 > 0xFFFF:
282
+ raise ValueError(
283
+ f"The RF packet would be {size} bytes, too long for its length field"
284
+ )
285
+ result = bytearray([RM4_RF_TYPE, _RM4_RF_BYTE1])
286
+ result += (size - 4).to_bytes(2, "little")
287
+ result += carrier_khz.to_bytes(4, "little")
288
+ result += bytes(between) * (frames - 1) + last
289
+ return bytes(result)
290
+
291
+
180
292
  def data_to_pulses(data: bytes, tick: float = TICK) -> list[int]:
181
293
  """Parse a Broadlink packet into a microsecond duration sequence.
182
294
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: broadlink-async
3
- Version: 1.2.1
3
+ Version: 1.3.0
4
4
  Summary: Python API for controlling Broadlink devices
5
5
  Author: DAB-LABS
6
6
  Author-email: Matthew Garrett <mjg59@srcf.ucam.org>
@@ -373,6 +373,30 @@ carrier it never really locked, so the known-frequency path is preferred.
373
373
  await device.send_data(packet)
374
374
  ```
375
375
 
376
+ #### Building an RF packet for an RM4 Pro
377
+
378
+ An RM4 Pro sends an RF packet of type 0xB1 on the carrier written inside
379
+ it. `pulses_to_rm4_rf` builds one from a frame of signed microsecond
380
+ timings (positive is carrier on, negative is carrier off, starting with a
381
+ pulse), written out `frames` times:
382
+
383
+ ```python3
384
+ from broadlink_async.remote import pulses_to_rm4_rf
385
+
386
+ packet = pulses_to_rm4_rf(timings, 433.92, frames=4, gap_us=12881, tail_us=45680)
387
+ await device.send_data(packet)
388
+ ```
389
+
390
+ A frame that ends on an off time keeps it as the gap between frames; one
391
+ that ends on a pulse needs `gap_us`. The packet always ends on an off
392
+ time, `tail_us` when given. On the bench a plug's code sent as one frame
393
+ did nothing and as 4 or 10 frames worked, so send more than one. Built
394
+ packets were tested up to about 530 bytes, the size of a learned packet;
395
+ the device's own limit is not known. The builder does not check the
396
+ carrier against any band. Only the RM4 Pro has been
397
+ tested with this layout; `pulses_to_data` with `kind=SignalKind.RF_433`
398
+ builds the older layout, which has no carrier field.
399
+
376
400
  ### Fetching sensor data
377
401
  ```python3
378
402
  data = await device.check_sensors()
@@ -35,7 +35,9 @@ tests/test_loopback.py
35
35
  tests/test_oracle.py
36
36
  tests/test_realign.py
37
37
  tests/test_remote.py
38
+ tests/test_rm4_rf.py
38
39
  tests/test_transport.py
40
+ tests/fixtures/rm4pro_rf_bench.json
39
41
  tests/oracle/__init__.py
40
42
  tests/oracle/cases.py
41
43
  tests/oracle/fixtures.json
@@ -207,6 +207,21 @@ code with 315000 there is not transmitted at 433.92MHz. A code built with
207
207
  0xb2 and no carrier field, as described above, is also accepted and sent at
208
208
  433.92MHz. Tested on an RM4 Pro, firmware 52079.
209
209
 
210
+ Built codes in this layout are sent too. On the same RM4 Pro, a plug's On
211
+ and Off frames written out 4 or 10 times, with a 12.9ms off time between
212
+ frames and 45.7ms at the end, switched the plug at 433920, 433000 and
213
+ 434790kHz; the On frame written once did nothing. With 315000 in the
214
+ carrier field the plug, a 433.92MHz receiver, did not respond, which shows
215
+ the device uses the field. With 0 it sent nothing. A CC1101 receiver
216
+ nearby saw the carrier move with the field. Built codes were tested up to
217
+ about 530 bytes, the size of a learned code; the device's limit is not
218
+ known.
219
+ `pulses_to_rm4_rf` builds this layout.
220
+
221
+ A duration that rounds to 0 is not written as a lone 0x00, which would
222
+ start the long form above; the library writes 1 instead. The long form
223
+ holds at most 0xffff, about 2 seconds.
224
+
210
225
  Leaving learning mode
211
226
  ---------------------
212
227
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "broadlink-async"
7
- version = "1.2.1"
7
+ version = "1.3.0"
8
8
  description = "Python API for controlling Broadlink devices"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -0,0 +1,155 @@
1
+ {
2
+ "note": "RM4 Pro (firmware 52079) bench for 433 MHz RF sends, 2026-11-13. 'frames' holds one frame of a Bench Plug's On and Off codes in signed microseconds (positive is carrier on). Each 'built' packet was sent with a 12881 us gap between frames and a 45680 us tail; 'plug' is what the plug did. 'learned' are two 0xB1 packets the device returned from learning on the same bench (bench267/on and bench267/taps).",
3
+ "frames": {
4
+ "on": [
5
+ 1279,
6
+ -365,
7
+ 456,
8
+ -1218,
9
+ 456,
10
+ -1218,
11
+ 1279,
12
+ -365,
13
+ 456,
14
+ -1218,
15
+ 1279,
16
+ -395,
17
+ 456,
18
+ -1218,
19
+ 1279,
20
+ -395,
21
+ 426,
22
+ -1218,
23
+ 456,
24
+ -1218,
25
+ 456,
26
+ -1218,
27
+ 456,
28
+ -1218,
29
+ 1279,
30
+ -380,
31
+ 1279,
32
+ -395,
33
+ 1279,
34
+ -395,
35
+ 426,
36
+ -1218,
37
+ 441,
38
+ -1218,
39
+ 1279,
40
+ -395,
41
+ 426,
42
+ -1218,
43
+ 426,
44
+ -1218,
45
+ 1279,
46
+ -395,
47
+ 426,
48
+ -1218,
49
+ 426,
50
+ -1218,
51
+ 1279,
52
+ -395,
53
+ 456
54
+ ],
55
+ "off": [
56
+ 1279,
57
+ -380,
58
+ 456,
59
+ -1218,
60
+ 456,
61
+ -1218,
62
+ 1279,
63
+ -395,
64
+ 456,
65
+ -1218,
66
+ 1279,
67
+ -395,
68
+ 456,
69
+ -1218,
70
+ 1279,
71
+ -395,
72
+ 441,
73
+ -1218,
74
+ 456,
75
+ -1218,
76
+ 441,
77
+ -1218,
78
+ 456,
79
+ -1218,
80
+ 1279,
81
+ -395,
82
+ 1279,
83
+ -395,
84
+ 1279,
85
+ -395,
86
+ 426,
87
+ -1233,
88
+ 426,
89
+ -1218,
90
+ 1279,
91
+ -395,
92
+ 426,
93
+ -1233,
94
+ 426,
95
+ -1218,
96
+ 441,
97
+ -1218,
98
+ 441,
99
+ -1218,
100
+ 426,
101
+ -1218,
102
+ 1279,
103
+ -395,
104
+ 456
105
+ ]
106
+ },
107
+ "built": {
108
+ "leg2_3_off_x10_433920": {
109
+ "frame": "off",
110
+ "frames": 10,
111
+ "carrier_khz": 433920,
112
+ "plug": "switched off",
113
+ "packet": "b1c00c02009f06002a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0005dc"
114
+ },
115
+ "leg2_4_on_x1_433920": {
116
+ "frame": "on",
117
+ "frames": 1,
118
+ "carrier_khz": 433920,
119
+ "plug": "no change",
120
+ "packet": "b1c03800009f06002a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0005dc"
121
+ },
122
+ "leg2_5_on_x4_433920": {
123
+ "frame": "on",
124
+ "frames": 4,
125
+ "carrier_khz": 433920,
126
+ "plug": "switched on",
127
+ "packet": "b1c0d400009f06002a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0005dc"
128
+ },
129
+ "leg3_6_off_x10_315000": {
130
+ "frame": "off",
131
+ "frames": 10,
132
+ "carrier_khz": 315000,
133
+ "plug": "no change",
134
+ "packet": "b1c00c0278ce04002a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0005dc"
135
+ },
136
+ "leg3_7_off_x10_433000": {
137
+ "frame": "off",
138
+ "frames": 10,
139
+ "carrier_khz": 433000,
140
+ "plug": "switched off",
141
+ "packet": "b1c00c02689b06002a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0001a72a0c0f280f282a0d0f282a0d0f282a0d0e280f280e280f282a0d2a0d2a0d0e280e282a0d0e280e280e280e280e282a0d0f0005dc"
142
+ },
143
+ "leg3_8_on_x10_434790": {
144
+ "frame": "on",
145
+ "frames": 10,
146
+ "carrier_khz": 434790,
147
+ "plug": "switched on",
148
+ "packet": "b1c00c0266a206002a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f280f282a0c2a0d2a0d0e280e282a0d0e280e282a0d0e280e282a0d0f0005dc"
149
+ }
150
+ },
151
+ "learned": {
152
+ "taps": "b1c00e02ec9e06000e0001a62b0c0f280f282a0c0f282a0d0f282a0d0e280f280e290e282a0d2a0d290e0e280f282a0d0e280f282a0d0e29290d2a0d0e0001a82a0c0f280f282a0d0e282a0d0f282a0c0f280f280f280e282a0d2a0d2a0d0e280f282a0d0e290e282a0d0e292a0c2a0d0e0001a82a0d0e280f282a0d0f282a0c0f282a0d0e280f280f280f282a0c2a0d2a0d0e290e282a0d0e290e282a0d0f282a0d2a0d0e0001a72a0d0f270f282a0d0f282a0c0f282a0d0e290e280f280f282a0c2a0d2a0d0e290e282a0d0f280f28290d0f282a0d2a0d0e0001a72b0c0f280e282b0c0f282a0d0e282a0d0f280f270f280f282a0d2a0c2a0d0f280e29290d0f280f282a0d0e282a0d2a960e0001a72a0d0f280f272b0c0f282a0d0e282a0d0f280f280e280f282a0d2a0c2a0d0f280e292a0c0f280f282a0c0f282a0d2a0d0e0001a72b0c0f280f282a0c0f282a0d0f28290d0f280f280e280f282a0d2a0d290e0e280f282a0d0e290e282a0d0e282a0d2a0d0e0001a82a0c0f280f282a0c0f282a0d0f282a0d0e280f280f270f282a0d2a0d2a0d0e280f282a0d0e280f282a0d0e29290e290d0f0001a72a0c0f280f282a0d0e282b0c0f282a0d0e280f280f280e282b0c2a0d2a0d0e290e282a0d0e290e282b0c0f282a0d290d0f0001a72a0d0f270f282a0d0f272b0c0f282a0d0e290e280f280f282a0c2a0d2a0d0e290e282a0d0f280e29290d0f282a0d2a0005dc",
153
+ "on": "b1c00e02b09e06000f0001a62b0c0f2710272b0c0f282a0d0f272b0c0f280e290e280f282a0d2a0d290d0f280f282a0d0e280f282a0d0e280f282a0d0e0001a72b0c0f280f282a0d0e282a0d0f282a0d0e280f280f280e282a0d2a0d2a0d0e280f282a0d0e280f282a0d0e290e282a0d0e0001a82a0c0f280f282a0d0e282b0c0f282a0d0e280f280f280f272a0d2a0d2a0d0e280f282a0d0e290e282a0d0f280e282a0d0f0001a72a0d0f270f282a0d0f282a0c0f282a0d0e280f280f280f282a0c2a0d2a0d0e290e282a0d0e290e282a0d0f280f282a0c0f0001a72a0d0f270f282a0d0f282a0c0f282a0d0f280e280f280f282a0d2a0d290d0e290e282a0d0f280f28290d0f280f282a950f0001a72a0d0f2710272a0d0f282a0d0e282a0d0f280e280f280f282a0d2a0c2a0d0e290e282a0d0f280e292a0c0f280f282a0d0e0001a72a0d0f280f272b0c0f282a0d0e282a0d0f280e290e280f282a0d2a0c2a0d0f280e292a0c0f280f282a0d0e280f282a0d0e0001a72b0c0f280f282a0c0f282a0d0f272a0d0f280f280e280f282a0d2a0d290e0e280f282a0d0e280f282a0d0e280f282a0d0f0001a72a0c0f280f282a0c0f282a0d0f282a0d0e280f280f270f282a0d2a0d2a0d0e280f282a0d0e280f282a0d0f280e282a0d0f0001a72a0c0f280f282a0d0e282b0c0f282a0d0e280f280f280e282b0c2a0d2a0d0e280f282a0d0e290e282a0d0f280e282a0005dc"
154
+ }
155
+ }
@@ -0,0 +1,241 @@
1
+ """Building RM4 Pro RF packets (type 0xB1) that carry their own carrier.
2
+
3
+ The fixture is from an RM4 Pro bench (firmware 52079, 2026-11-13): one
4
+ frame each of a plug's On and Off codes, the six packets built from them
5
+ that were sent (with what the plug did), and two packets the device
6
+ returned from learning.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ from pathlib import Path
13
+
14
+ import pytest
15
+
16
+ from broadlink_async.remote import (
17
+ RM4_RF_TYPE,
18
+ TICK,
19
+ SignalKind,
20
+ data_to_pulses,
21
+ parse_packet,
22
+ pulses_to_data,
23
+ pulses_to_rm4_rf,
24
+ realign_rf_packet,
25
+ rf_carrier_mhz,
26
+ )
27
+
28
+ FIXTURE = Path(__file__).parent / "fixtures" / "rm4pro_rf_bench.json"
29
+ BENCH = json.loads(FIXTURE.read_text())
30
+ ON = BENCH["frames"]["on"]
31
+ BUILT = BENCH["built"]
32
+ LEARNED = {name: bytes.fromhex(packet) for name, packet in BENCH["learned"].items()}
33
+
34
+ GAP = 12881
35
+ TAIL = 45680
36
+
37
+
38
+ def signed(durations: list[int]) -> list[int]:
39
+ """Unsigned durations, starting with a pulse, as signed timings."""
40
+ return [d if i % 2 == 0 else -d for i, d in enumerate(durations)]
41
+
42
+
43
+ @pytest.mark.parametrize("name", sorted(BUILT))
44
+ def test_matches_the_packets_sent_on_the_bench(name):
45
+ sent = BUILT[name]
46
+ packet = pulses_to_rm4_rf(
47
+ BENCH["frames"][sent["frame"]],
48
+ sent["carrier_khz"] / 1000,
49
+ frames=sent["frames"],
50
+ gap_us=GAP,
51
+ tail_us=TAIL,
52
+ )
53
+ assert packet == bytes.fromhex(sent["packet"])
54
+
55
+
56
+ def test_header():
57
+ packet = pulses_to_rm4_rf([328, -656], 433.42)
58
+ assert packet[0] == RM4_RF_TYPE == 0xB1
59
+ assert packet[1] == 0xC0
60
+ assert int.from_bytes(packet[2:4], "little") == len(packet) - 4
61
+ assert int.from_bytes(packet[4:8], "little") == 433420
62
+ assert packet[8:] == bytes([11, 22])
63
+
64
+
65
+ def test_carrier_reads_back():
66
+ for mhz in (433.0, 433.42, 433.92, 434.79, 315.0):
67
+ assert rf_carrier_mhz(pulses_to_rm4_rf([328, -656], mhz)) == mhz
68
+
69
+
70
+ @pytest.mark.parametrize("name", sorted(LEARNED))
71
+ def test_learned_packet_reads_back_through_the_builder(name):
72
+ # A learned packet's own timings rebuild it byte for byte.
73
+ packet = LEARNED[name]
74
+ assert len(packet) == 530
75
+ rebuilt = pulses_to_rm4_rf(signed(data_to_pulses(packet)), rf_carrier_mhz(packet))
76
+ assert rebuilt == packet
77
+
78
+
79
+ def test_round_trip_through_parse_packet():
80
+ packet = pulses_to_rm4_rf(ON, 433.92, frames=4, gap_us=GAP, tail_us=TAIL)
81
+ parsed = parse_packet(packet)
82
+ assert parsed.kind is SignalKind.RF_433
83
+ assert parsed.type_byte == 0xB1
84
+ assert parsed.frequency_mhz == 433.92
85
+ assert len(parsed.pulses) == 4 * (len(ON) + 1)
86
+ frame = [abs(t) for t in ON] + [GAP]
87
+ expected = frame * 3 + frame[:-1] + [TAIL]
88
+ for a, b in zip(parsed.pulses, expected, strict=True):
89
+ assert abs(a - b) <= TICK / 2 + 1
90
+
91
+
92
+ def test_frame_ending_on_an_off_time_keeps_it_as_the_gap():
93
+ packet = pulses_to_rm4_rf([328, -656, 328, -9000], 433.92, frames=2)
94
+ gap = round(9000 / TICK)
95
+ long = bytes([0, gap >> 8, gap & 0xFF])
96
+ assert packet[8:] == bytes([11, 22, 11]) + long + bytes([11, 22, 11]) + long
97
+
98
+
99
+ def test_gap_us_replaces_a_trailing_off_time():
100
+ with_gap = pulses_to_rm4_rf([328, -656, 328, -9000], 433.92, frames=2, gap_us=656)
101
+ assert with_gap[8:] == bytes([11, 22, 11, 22]) * 2
102
+
103
+
104
+ def test_frame_ending_on_a_pulse_needs_gap_us():
105
+ with pytest.raises(ValueError, match="gap_us"):
106
+ pulses_to_rm4_rf([328, -656, 328], 433.92)
107
+ packet = pulses_to_rm4_rf([328, -656, 328], 433.92, frames=2, gap_us=656)
108
+ assert packet[8:] == bytes([11, 22, 11, 22]) * 2
109
+
110
+
111
+ def test_the_packet_always_ends_on_an_off_time():
112
+ packet = pulses_to_rm4_rf([328], 433.92, gap_us=656)
113
+ assert data_to_pulses(packet) == [int(11 * TICK), int(22 * TICK)]
114
+
115
+
116
+ def test_tail_us_is_the_last_off_time_only():
117
+ packet = pulses_to_rm4_rf([328, -656], 433.92, frames=3, tail_us=984)
118
+ assert packet[8:] == bytes([11, 22, 11, 22, 11, 32])
119
+
120
+
121
+ def test_one_frame_is_written_as_one_frame():
122
+ # The library writes the frames it is given; any floor is the caller's.
123
+ packet = pulses_to_rm4_rf(ON, 433.92, gap_us=GAP, tail_us=TAIL)
124
+ assert len(data_to_pulses(packet)) == len(ON) + 1
125
+
126
+
127
+ def test_explicit_tick():
128
+ packet = pulses_to_rm4_rf([328, -656], 433.92, tick=32.84)
129
+ assert packet[8:] == bytes([10, 20])
130
+
131
+
132
+ def test_no_size_limit_below_the_length_field():
133
+ packet = pulses_to_rm4_rf(ON, 433.92, frames=20, gap_us=GAP, tail_us=TAIL)
134
+ assert len(packet) == 1048
135
+ assert len(data_to_pulses(packet)) == 20 * (len(ON) + 1)
136
+
137
+
138
+ def test_refuses_a_packet_too_long_for_its_length_field():
139
+ with pytest.raises(ValueError, match="length field"):
140
+ pulses_to_rm4_rf([328, -656], 433.92, frames=40_000)
141
+
142
+
143
+ @pytest.mark.parametrize(
144
+ "timings",
145
+ [
146
+ pytest.param([], id="empty"),
147
+ pytest.param([-328, 656], id="starts_on_an_off_time"),
148
+ pytest.param([0, -656], id="starts_on_zero"),
149
+ pytest.param([328, 656], id="two_pulses"),
150
+ pytest.param([328, -656, -328], id="two_off_times"),
151
+ pytest.param([328, 0, 328], id="zero_in_the_middle"),
152
+ ],
153
+ )
154
+ def test_refuses_timings_that_do_not_alternate(timings):
155
+ with pytest.raises(ValueError, match="RF timings"):
156
+ pulses_to_rm4_rf(timings, 433.92, gap_us=GAP)
157
+
158
+
159
+ @pytest.mark.parametrize("frames", [0, -1])
160
+ def test_refuses_fewer_than_one_frame(frames):
161
+ with pytest.raises(ValueError, match="frames"):
162
+ pulses_to_rm4_rf([328, -656], 433.92, frames=frames)
163
+
164
+
165
+ @pytest.mark.parametrize(
166
+ "carrier", [0, 0.0004, -433.92, float("nan"), float("inf"), 4_294_968]
167
+ )
168
+ def test_refuses_a_carrier_that_does_not_fit(carrier):
169
+ with pytest.raises(ValueError, match="carrier"):
170
+ pulses_to_rm4_rf([328, -656], carrier)
171
+
172
+
173
+ def test_does_not_check_bands():
174
+ # 433.00 MHz is outside Home Assistant's declared range but the device
175
+ # sends it; bands are the caller's business.
176
+ assert rf_carrier_mhz(pulses_to_rm4_rf([328, -656], 433.0)) == 433.0
177
+
178
+
179
+ @pytest.mark.parametrize(("gap_us", "tail_us"), [(0, None), (-1, None), (None, 0)])
180
+ def test_refuses_a_gap_or_tail_that_is_not_positive(gap_us, tail_us):
181
+ with pytest.raises(ValueError, match="must be positive"):
182
+ pulses_to_rm4_rf([328, -656], 433.92, gap_us=gap_us, tail_us=tail_us)
183
+
184
+
185
+ # The shared tick encoder, used by pulses_to_data and pulses_to_rm4_rf.
186
+
187
+
188
+ def test_a_duration_under_half_a_tick_is_written_as_one_tick():
189
+ # A lone 0x00 would start the long form and swallow the next two bytes.
190
+ data = pulses_to_data([328, 10, 328, 656])
191
+ assert data[4:] == bytes([11, 1, 11, 22])
192
+ assert len(data_to_pulses(data)) == 4
193
+ packet = pulses_to_rm4_rf([328, -10, 328, -656], 433.92)
194
+ assert packet[8:] == bytes([11, 1, 11, 22])
195
+ assert len(data_to_pulses(packet)) == 4
196
+
197
+
198
+ def test_the_longest_duration_still_fits():
199
+ assert pulses_to_data([328, 0xFFFF * TICK])[4:] == bytes([11, 0, 0xFF, 0xFF])
200
+
201
+
202
+ @pytest.mark.parametrize("us", [65536 * TICK, 3_000_000])
203
+ def test_a_duration_over_the_longest_raises(us):
204
+ with pytest.raises(ValueError, match="too long"):
205
+ pulses_to_data([328, us])
206
+ with pytest.raises(ValueError, match="too long"):
207
+ pulses_to_rm4_rf([328, -us], 433.92)
208
+ with pytest.raises(ValueError, match="too long"):
209
+ pulses_to_rm4_rf([328], 433.92, gap_us=us)
210
+
211
+
212
+ def test_one_pulse_frame_sent_once_needs_only_a_tail():
213
+ packet = pulses_to_rm4_rf([328, -656, 328], 433.92, tail_us=984)
214
+ assert packet[8:] == bytes([11, 22, 11, 32])
215
+ with pytest.raises(ValueError, match="gap_us"):
216
+ pulses_to_rm4_rf([328, -656, 328], 433.92, frames=2, tail_us=984)
217
+
218
+
219
+ def test_one_frame_ends_on_the_tail():
220
+ packet = pulses_to_rm4_rf(ON, 433.92, gap_us=GAP, tail_us=TAIL)
221
+ assert data_to_pulses(packet)[-1] == int(round(TAIL / TICK) * TICK)
222
+
223
+
224
+ @pytest.mark.parametrize("frames", [1, 4, 10])
225
+ def test_realign_leaves_a_built_packet_alone(frames):
226
+ packet = pulses_to_rm4_rf(ON, 433.92, frames=frames, gap_us=GAP, tail_us=TAIL)
227
+ assert realign_rf_packet(packet) == packet
228
+
229
+
230
+ @pytest.mark.parametrize("frames", [2.0, 2.5, "2"])
231
+ def test_refuses_frames_that_are_not_whole_numbers(frames):
232
+ with pytest.raises(ValueError, match="frames"):
233
+ pulses_to_rm4_rf([328, -656], 433.92, frames=frames)
234
+
235
+
236
+ @pytest.mark.parametrize("bad", [float("inf"), float("nan")])
237
+ def test_refuses_timings_that_are_not_finite(bad):
238
+ with pytest.raises(ValueError, match="finite"):
239
+ pulses_to_rm4_rf([328, -656, bad, -656], 433.92)
240
+ with pytest.raises(ValueError, match="must be positive"):
241
+ pulses_to_rm4_rf([328, -656], 433.92, gap_us=bad)
File without changes