uwscli 0.4.0__tar.gz → 0.5.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 (65) hide show
  1. {uwscli-0.4.0/src/uwscli.egg-info → uwscli-0.5.0}/PKG-INFO +47 -22
  2. {uwscli-0.4.0 → uwscli-0.5.0}/README.md +45 -19
  3. {uwscli-0.4.0 → uwscli-0.5.0}/pyproject.toml +3 -3
  4. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/__init__.py +4 -4
  5. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/cli.py +508 -86
  6. uwscli-0.5.0/src/uwscli/data/tl_frames/__init__.py +0 -0
  7. uwscli-0.5.0/src/uwscli/data/tl_frames/collide.xz +0 -0
  8. uwscli-0.5.0/src/uwscli/data/tl_frames/cover_cycle.xz +0 -0
  9. uwscli-0.5.0/src/uwscli/data/tl_frames/door.xz +0 -0
  10. uwscli-0.5.0/src/uwscli/data/tl_frames/electric_current.xz +0 -0
  11. uwscli-0.5.0/src/uwscli/data/tl_frames/intertwine.xz +0 -0
  12. uwscli-0.5.0/src/uwscli/data/tl_frames/kaleidoscope.xz +0 -0
  13. uwscli-0.5.0/src/uwscli/data/tl_frames/lottery.xz +0 -0
  14. uwscli-0.5.0/src/uwscli/data/tl_frames/meteor_shower.xz +0 -0
  15. uwscli-0.5.0/src/uwscli/data/tl_frames/mixing.xz +0 -0
  16. uwscli-0.5.0/src/uwscli/data/tl_frames/paint.xz +0 -0
  17. uwscli-0.5.0/src/uwscli/data/tl_frames/ping_pong.xz +0 -0
  18. uwscli-0.5.0/src/uwscli/data/tl_frames/racing.xz +0 -0
  19. uwscli-0.5.0/src/uwscli/data/tl_frames/reflect.xz +0 -0
  20. uwscli-0.5.0/src/uwscli/data/tl_frames/render.xz +0 -0
  21. uwscli-0.5.0/src/uwscli/data/tl_frames/ripple.xz +0 -0
  22. uwscli-0.5.0/src/uwscli/data/tl_frames/staggered.xz +0 -0
  23. uwscli-0.5.0/src/uwscli/data/tl_frames/tail_chasing.xz +0 -0
  24. uwscli-0.5.0/src/uwscli/data/tl_frames/tide.xz +0 -0
  25. uwscli-0.5.0/src/uwscli/data/tl_frames/voice.xz +0 -0
  26. uwscli-0.5.0/src/uwscli/data/tl_frames/wave.xz +0 -0
  27. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/lcd.py +254 -53
  28. uwscli-0.5.0/src/uwscli/sensor_screen.py +90 -0
  29. uwscli-0.5.0/src/uwscli/sensors.py +191 -0
  30. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/structs.py +19 -7
  31. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/system_usb.py +15 -15
  32. uwscli-0.5.0/src/uwscli/tinyuz.py +385 -0
  33. uwscli-0.5.0/src/uwscli/tl_effects.py +1009 -0
  34. uwscli-0.5.0/src/uwscli/tl_merge.py +420 -0
  35. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/tlcontroller.py +13 -8
  36. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/usbutil.py +31 -29
  37. uwscli-0.5.0/src/uwscli/wireless.py +1249 -0
  38. {uwscli-0.4.0 → uwscli-0.5.0/src/uwscli.egg-info}/PKG-INFO +47 -22
  39. uwscli-0.5.0/src/uwscli.egg-info/SOURCES.txt +57 -0
  40. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli.egg-info/requires.txt +1 -3
  41. {uwscli-0.4.0 → uwscli-0.5.0}/tests/test_cli_errors.py +33 -2
  42. {uwscli-0.4.0 → uwscli-0.5.0}/tests/test_cli_output.py +48 -20
  43. uwscli-0.5.0/tests/test_lcd_wireless.py +323 -0
  44. uwscli-0.5.0/tests/test_led_compression.py +154 -0
  45. uwscli-0.5.0/tests/test_sensor_screen.py +168 -0
  46. uwscli-0.5.0/tests/test_tl_merge.py +121 -0
  47. uwscli-0.5.0/tests/test_tl_prerendered.py +124 -0
  48. {uwscli-0.4.0 → uwscli-0.5.0}/tests/test_wireless_integration.py +35 -15
  49. uwscli-0.5.0/tests/test_wireless_led_packets.py +336 -0
  50. uwscli-0.4.0/src/uwscli/tinyuz.py +0 -192
  51. uwscli-0.4.0/src/uwscli/tl_effects.py +0 -1355
  52. uwscli-0.4.0/src/uwscli/wireless.py +0 -941
  53. uwscli-0.4.0/src/uwscli.egg-info/SOURCES.txt +0 -29
  54. uwscli-0.4.0/tests/test_led_compression.py +0 -97
  55. uwscli-0.4.0/tests/test_wireless_led_packets.py +0 -85
  56. {uwscli-0.4.0 → uwscli-0.5.0}/LICENSE +0 -0
  57. {uwscli-0.4.0 → uwscli-0.5.0}/setup.cfg +0 -0
  58. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/data/__init__.py +0 -0
  59. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/data/twinkle.bin +0 -0
  60. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/led.py +0 -0
  61. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli/logging_utils.py +0 -0
  62. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli.egg-info/dependency_links.txt +0 -0
  63. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli.egg-info/entry_points.txt +0 -0
  64. {uwscli-0.4.0 → uwscli-0.5.0}/src/uwscli.egg-info/top_level.txt +0 -0
  65. {uwscli-0.4.0 → uwscli-0.5.0}/tests/test_usbutil.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: uwscli
3
- Version: 0.4.0
3
+ Version: 0.5.0
4
4
  Summary: Uni-Wireless-Sync: wireless control toolkit for TL fan receivers
5
5
  Author: Study Hsueh
6
6
  License: MIT License
@@ -45,14 +45,13 @@ License-File: LICENSE
45
45
  Requires-Dist: hidapi>=0.14
46
46
  Requires-Dist: pyusb>=1.2
47
47
  Requires-Dist: pycryptodomex>=3.17
48
+ Requires-Dist: Pillow>=10.1
48
49
  Provides-Extra: dev
49
50
  Requires-Dist: pytest>=7.0; extra == "dev"
50
51
  Requires-Dist: pytest-cov>=4.0; extra == "dev"
51
52
  Requires-Dist: ruff>=0.5; extra == "dev"
52
53
  Requires-Dist: black>=24.0; extra == "dev"
53
54
  Requires-Dist: mypy>=1.8; extra == "dev"
54
- Provides-Extra: images
55
- Requires-Dist: Pillow>=10.0; extra == "images"
56
55
  Dynamic: license-file
57
56
 
58
57
  # Uni Wireless Sync CLI
@@ -73,15 +72,20 @@ Other Uni Fan series are currently not supported.
73
72
  ## Features
74
73
 
75
74
  - Discover TL LCD USB devices and 2.4 GHz wireless fan controllers.
76
- - Query LCD firmware and handshake data.
77
- - Send JPEG frames or apply control settings (mode, brightness, rotation) to the LCD.
78
- - Keep the wireless TL LCD awake by emitting periodic handshakes.
79
- - List wireless fan receivers with metadata (MAC, master MAC, channel, device type, fan speeds, PWM targets).
75
+ - Query LCD firmware and the panel's group index.
76
+ - Show images (JPEG or PNG, scaled to the panel) or play videos on the TL Wireless LCD, optionally keeping an image as the power-on image.
77
+ - Set LCD brightness and rotation.
78
+ - Show live sensor gauges (CPU/GPU temperature and load, fan speed) or a clock on the TL Wireless LCD.
79
+ - Keep the wireless TL LCD awake with the same heartbeat the vendor app sends.
80
+ - List wireless fan receivers with metadata (MAC, master MAC, channel, device type, fan speeds, PWM targets, fan types, RF firmware version, running LED effect).
80
81
  - List detected master controller MAC addresses to simplify binding workflows.
81
82
  - Send one-shot PWM commands to TL wireless fans over the 2.4 GHz dongle.
82
- - Bind or unbind wireless receivers against the active master controller.
83
+ - Bind or unbind wireless receivers against the attached master controller.
84
+ - Make a device flash to find it, or restart the LCD panels of a TL Wireless LCD fan over RF.
83
85
  - Toggle motherboard PWM sync mode for one receiver or every bound receiver.
84
- - Broadcast static RGB payloads to wireless receivers (experimental).
86
+ - Send LED effects to wireless receivers; the CLI waits until the device reports the new effect and resends it if needed.
87
+ - All 29 TL effects with the vendor app's colours, speeds and brightness levels, and merge mode (one effect running across fan groups).
88
+ - Move every bound device to another RF channel.
85
89
 
86
90
  ### Fan wiring modes
87
91
 
@@ -98,8 +102,6 @@ Other Uni Fan series are currently not supported.
98
102
 
99
103
  ```bash
100
104
  pip install uwscli
101
- # optional image helpers
102
- pip install uwscli[images]
103
105
 
104
106
  python -m venv .venv
105
107
  source .venv/bin/activate
@@ -118,13 +120,25 @@ uws fan list
118
120
  # Display operations
119
121
  uws lcd info --serial <usb-serial>
120
122
  uws lcd send-jpg --serial <usb-serial> --file assets/sample_lcd.jpg
121
- uws lcd keep-alive --serial <usb-serial> --interval 5
123
+ uws lcd send-jpg --serial <usb-serial> --file photo.png --save # also keep it as the power-on image
124
+ uws lcd play-video --serial <usb-serial> --file clip.mp4 --loop
125
+ uws lcd control --serial <usb-serial> --brightness 40 --rotation 90
126
+ uws lcd keep-alive --serial <usb-serial>
127
+ uws lcd sensor --serial <usb-serial> --metric cpu-temp --color blue
122
128
 
123
129
  # Fan receiver operations
124
130
  uws fan set-fan --mac aa:bb:cc:dd:ee:ff --pwm 120 # direct PWM control
125
131
  uws fan pwm-sync --mode receiver --all # receiver mode receivers (sets PWM=6)
126
132
  uws fan bind --mac aa:bb:cc:dd:ee:ff
127
133
  uws fan unbind --mac aa:bb:cc:dd:ee:ff
134
+ uws fan identify --mac aa:bb:cc:dd:ee:ff # the device flashes
135
+ uws fan reboot-lcd --mac aa:bb:cc:dd:ee:ff
136
+ uws fan set-channel --channel 7
137
+
138
+ # Lighting
139
+ uws fan set-led --all --mode static --color 255,0,0
140
+ uws fan set-led --all --mode effect --effect meteor --speed 3
141
+ uws fan set-led --all --mode merge --effect wave
128
142
  uws fan pwm-sync --all
129
143
  uws fan pwm-sync --mac aa:bb:cc:dd:ee:ff --once
130
144
  ```
@@ -134,22 +148,32 @@ uws fan pwm-sync --mac aa:bb:cc:dd:ee:ff --once
134
148
  ## Command Reference
135
149
 
136
150
  - `uws lcd list` – enumerate TL LCD devices and show their USB serial numbers.
137
- - `uws lcd info --serial <usb-serial>` – read firmware and handshake data.
138
- - `uws lcd send-jpg --serial <usb-serial> --file <image.jpg>` – stream a JPEG asset.
139
- - `uws lcd keep-alive --serial <usb-serial> [--interval seconds]` – emit periodic handshakes to prevent the wireless panel from dimming.
140
- - `uws lcd control --serial <usb-serial> [--mode show-jpg|show-app-sync|lcd-test] [--jpg-index N] [--brightness 0-100] [--fps N] [--rotation 0|90|180|270] [--test-color R,G,B]` – send an `LCDControlSetting` payload.
141
- - `uws fan list` – fetch a snapshot of bound wireless receivers via the RF receiver.
151
+ - `uws lcd info --serial <usb-serial>` – read the firmware version and the panel's group index.
152
+ - `uws lcd send-jpg --serial <usb-serial> --file <image> [--raw] [--save]` – show a JPEG or PNG. On the TL Wireless LCD the image is scaled to 400x400 and re-encoded as JPEG (quality 95, lowered until it fits in 100000 bytes), as the vendor app does; `--raw` sends the file unchanged; `--save` also stores it as the image the panel shows at power-on.
153
+ - `uws lcd play-video --serial <usb-serial> --file <video> [--fps N] [--loop]` – decode a video with FFmpeg and send it frame by frame (TL Wireless LCD; default: the video's own frame rate).
154
+ - `uws lcd sensor --serial <usb-serial> --metric cpu-temp|cpu-load|gpu-temp|gpu-load|fan-rpm|clock [--color blue|green|purple|red] [--fan <mac>] [--interval seconds] [--once] [--output preview.png]` – show a live ring gauge (or a clock) on the TL Wireless LCD, updated every second like the vendor app's sensor screens. CPU temperature comes from hwmon (k10temp, zenpower or coretemp), GPU from `nvidia-smi` or amdgpu, fan speed from the RF receiver (the average of a group's running fans). Runs until Ctrl+C; `--output` writes one frame to a PNG instead.
155
+ - `uws lcd keep-alive --serial <usb-serial> [--interval seconds]` – send the vendor app's heartbeat (default every second) to keep the wireless panel awake.
156
+ - `uws lcd control --serial <usb-serial> [--brightness 0-100] [--rotation 0|90|180|270]` – on the TL Wireless LCD, change only the settings given. Brightness is sent as is (the vendor app's 0/25/50/75/100% steps send 0/10/30/40/100). On the wired TL LCD the full `LCDControlSetting` is sent (`--mode show-jpg|show-app-sync|lcd-test`, `--jpg-index N`, `--fps N`, `--test-color R,G,B`; brightness defaults to 50, rotation to 0).
157
+ - `uws fan list` – fetch a snapshot of wireless receivers via the RF receiver (master controllers are listed by `list-masters`).
142
158
  - `uws fan list-masters` – enumerate master controllers and associated wireless receivers.
143
- - `uws fan set-fan --mac <aa:bb:..> --pwm <0-255> [--sequence-index N]` – send a single shot PWM update to one receiver; `--all` broadcasts to every bound receiver.
144
- - `uws fan pwm-sync --mac|--all [--mode controller|receiver] [--interval seconds] [--once] [--sequence-index N]` – synchronize receiver speeds. `controller` polls motherboard PWM and replays the value via RF (`--interval` / `--once` apply here); `receiver` sets PWM=6 so the receiver tracks the motherboard header directly (`--sequence-index` applies here).
145
- - `uws fan set-led --mac <aa:bb:..> --mode static|rainbow|frames|effect|random-effect` – apply wireless LED effects (**experimental**).
159
+ - `uws fan set-fan --mac <aa:bb:..> --pwm <0-255> [--sequence-index N]` – send a single shot PWM update to one receiver; `--all` sends it to every receiver bound to the attached master. The device number sent with it defaults to the device's position among the master's devices, as the vendor app does.
160
+ - `uws fan bind --mac <aa:bb:..> [--rx-type 1-13]` / `uws fan unbind --mac <aa:bb:..>` – bind to or unbind from the attached master; the master saves its configuration afterwards. A device that follows the motherboard keeps doing so after binding.
161
+ - `uws fan identify --mac <aa:bb:..>` – make the device flash so you can find it.
162
+ - `uws fan set-channel --channel <1|7|11|15|17|21|25|29|31|33|35|39|8>` – move every device bound to the attached controller to another RF channel (the vendor app's choices; 8 is its automatic default). Fan speeds and lighting are kept.
163
+ - Commands reach every bound device, whichever controller it is bound to. Devices bound to a controller that is not attached receive short commands, but longer LED effects rarely get through to them; bind them to the attached controller (`fan unbind`, then `fan bind`) for reliable effects.
164
+ - `uws fan reboot-lcd --mac <aa:bb:..>` – restart the LCD panels of a TL Wireless LCD fan over RF.
165
+ - `uws fan pwm-sync --mac|--all [--mode controller|receiver] [--interval seconds] [--once] [--sequence-index N]` – synchronize receiver speeds. `receiver` (default) sets PWM=6 so the receiver tracks the motherboard header directly; as the vendor app, only for devices whose MAC ends in `e1`. `controller` polls motherboard PWM and replays the value via RF (`--interval` / `--once` apply here).
166
+ - `uws fan set-led --mac <aa:bb:..> --mode static|rainbow|frames|effect|random-effect` – apply wireless LED effects. The effect is compressed (at most 12288 bytes, as the vendor app allows), sent, and resent until the device reports it; then the master saves its configuration.
146
167
 
147
168
  ### `uws fan set-led` modes
148
169
 
149
170
  - `static`: requires `--color R,G,B` or `--color-list R,G,B;...` to paint the LED strip once.
150
171
  - `rainbow`: procedural rainbow; optional `--frames N` (default 24) and `--interval-ms` (default 50).
151
172
  - `frames`: feed a JSON animation via `--frames-file`. Each frame is an array of `[R, G, B]` triples; see `examples/tl_frames_sample.json` for a minimal illustration (the CLI will pad or truncate per device LED count).
152
- - `effect`: drives any of the 29 TL presets. Choose an effect with `--effect <name>` (e.g. `twinkle`, `meteor_shower`), adjust brightness 0‑255 via `--effect-brightness`, pick direction with `--effect-direction 0|1`, and select which segment to update using `--effect-scope front|behind|both` (default `both`).
173
+ - `effect`: drives any of the 29 TL presets, with the same frames the vendor app sends. Choose an effect with `--effect <name>` (e.g. `twinkle`, `meteor_shower`), adjust brightness 0‑255 via `--effect-brightness`, pick direction with `--effect-direction 0|1` (0 clockwise, the app's default), the speed level with `--speed 1-5` (default 4, the app's default), swap the front and behind halves with `--flip` (the app's up/down swap), and select which segment to update using `--effect-scope front|behind|both` (default `both`; the two sides are combined as the app does).
174
+ - Each effect starts with the colours the app's lighting page uses for it (e.g. purple, cyan, green and yellow for `static_color`). `--effect-colors R,G,B;...` replaces them (up to four) for the nine computed effects: `rainbow`, `rainbow_morph`, `static_color`, `breathing`, `runway`, `meteor`, `color_cycle`, `stack` and `twinkle`.
175
+ - The other 20 are shipped as frames rendered by the vendor app with its default colours for each effect, for each fan count, direction and its 5 brightness levels (0, 64, 128, 192, 255; other brightness values use the closest level). `voice`, `meteor_shower` and `kaleidoscope` are random in the app; one rendering of each is shipped.
176
+ - `merge`: one effect running across fan groups, like the vendor app's merge mode (`--all`, or `--order mac1,mac2,...` for the sequence; `--reverse mac,...` runs it the other way on those groups). Merged effects: `rainbow`, `static_color`, `breathing`, `runway`, `meteor`, `color_cycle`, `cover_cycle`, `wave`, `meteor_shower`; `rainbow_morph` and `twinkle` run on each group on its own, as in the app. Speed, brightness, direction and colours work as for `effect` (merged effects step 12 ms per speed level). All groups are sent the effect before uws waits for them, so they start together.
153
177
  - `random-effect`: picks a random preset each time; accepts the same brightness/direction/scope flags as `effect`.
154
178
 
155
179
  Available effect names (case-insensitive): `rainbow`, `rainbow_morph`, `static_color`, `breathing`, `runway`, `meteor`, `color_cycle`, `staggered`, `tide`, `mixing`, `voice`, `door`, `render`, `ripple`, `reflect`, `tail_chasing`, `paint`, `ping_pong`, `stack`, `cover_cycle`, `wave`, `racing`, `lottery`, `intertwine`, `meteor_shower`, `collide`, `electric_current`, `kaleidoscope`, `twinkle`.
@@ -172,7 +196,8 @@ uws fan pwm-sync --mac aa:bb:cc:dd:ee:ff --once
172
196
  - `hidapi` (via `hid`) for TL LCD HID access.
173
197
  - `pyusb` for the RF sender/receiver WinUSB endpoints.
174
198
  - `pycryptodomex` for the DES-CBC transport used by the wireless LCD receiver.
175
- - `Pillow` is optional for JPEG frame validation.
199
+ - `Pillow` to prepare images for the LCD.
200
+ - `FFmpeg` (`ffmpeg` and `ffprobe` on the PATH) for `uws lcd play-video` only.
176
201
 
177
202
  Each command expects the TL LCD USB display (vendor 0x04FC or 0x1CBE) and the wireless transmitter/receiver pair (vendor 0x0416) to be attached when the command executes.
178
203
 
@@ -16,15 +16,20 @@ Other Uni Fan series are currently not supported.
16
16
  ## Features
17
17
 
18
18
  - Discover TL LCD USB devices and 2.4 GHz wireless fan controllers.
19
- - Query LCD firmware and handshake data.
20
- - Send JPEG frames or apply control settings (mode, brightness, rotation) to the LCD.
21
- - Keep the wireless TL LCD awake by emitting periodic handshakes.
22
- - List wireless fan receivers with metadata (MAC, master MAC, channel, device type, fan speeds, PWM targets).
19
+ - Query LCD firmware and the panel's group index.
20
+ - Show images (JPEG or PNG, scaled to the panel) or play videos on the TL Wireless LCD, optionally keeping an image as the power-on image.
21
+ - Set LCD brightness and rotation.
22
+ - Show live sensor gauges (CPU/GPU temperature and load, fan speed) or a clock on the TL Wireless LCD.
23
+ - Keep the wireless TL LCD awake with the same heartbeat the vendor app sends.
24
+ - List wireless fan receivers with metadata (MAC, master MAC, channel, device type, fan speeds, PWM targets, fan types, RF firmware version, running LED effect).
23
25
  - List detected master controller MAC addresses to simplify binding workflows.
24
26
  - Send one-shot PWM commands to TL wireless fans over the 2.4 GHz dongle.
25
- - Bind or unbind wireless receivers against the active master controller.
27
+ - Bind or unbind wireless receivers against the attached master controller.
28
+ - Make a device flash to find it, or restart the LCD panels of a TL Wireless LCD fan over RF.
26
29
  - Toggle motherboard PWM sync mode for one receiver or every bound receiver.
27
- - Broadcast static RGB payloads to wireless receivers (experimental).
30
+ - Send LED effects to wireless receivers; the CLI waits until the device reports the new effect and resends it if needed.
31
+ - All 29 TL effects with the vendor app's colours, speeds and brightness levels, and merge mode (one effect running across fan groups).
32
+ - Move every bound device to another RF channel.
28
33
 
29
34
  ### Fan wiring modes
30
35
 
@@ -41,8 +46,6 @@ Other Uni Fan series are currently not supported.
41
46
 
42
47
  ```bash
43
48
  pip install uwscli
44
- # optional image helpers
45
- pip install uwscli[images]
46
49
 
47
50
  python -m venv .venv
48
51
  source .venv/bin/activate
@@ -61,13 +64,25 @@ uws fan list
61
64
  # Display operations
62
65
  uws lcd info --serial <usb-serial>
63
66
  uws lcd send-jpg --serial <usb-serial> --file assets/sample_lcd.jpg
64
- uws lcd keep-alive --serial <usb-serial> --interval 5
67
+ uws lcd send-jpg --serial <usb-serial> --file photo.png --save # also keep it as the power-on image
68
+ uws lcd play-video --serial <usb-serial> --file clip.mp4 --loop
69
+ uws lcd control --serial <usb-serial> --brightness 40 --rotation 90
70
+ uws lcd keep-alive --serial <usb-serial>
71
+ uws lcd sensor --serial <usb-serial> --metric cpu-temp --color blue
65
72
 
66
73
  # Fan receiver operations
67
74
  uws fan set-fan --mac aa:bb:cc:dd:ee:ff --pwm 120 # direct PWM control
68
75
  uws fan pwm-sync --mode receiver --all # receiver mode receivers (sets PWM=6)
69
76
  uws fan bind --mac aa:bb:cc:dd:ee:ff
70
77
  uws fan unbind --mac aa:bb:cc:dd:ee:ff
78
+ uws fan identify --mac aa:bb:cc:dd:ee:ff # the device flashes
79
+ uws fan reboot-lcd --mac aa:bb:cc:dd:ee:ff
80
+ uws fan set-channel --channel 7
81
+
82
+ # Lighting
83
+ uws fan set-led --all --mode static --color 255,0,0
84
+ uws fan set-led --all --mode effect --effect meteor --speed 3
85
+ uws fan set-led --all --mode merge --effect wave
71
86
  uws fan pwm-sync --all
72
87
  uws fan pwm-sync --mac aa:bb:cc:dd:ee:ff --once
73
88
  ```
@@ -77,22 +92,32 @@ uws fan pwm-sync --mac aa:bb:cc:dd:ee:ff --once
77
92
  ## Command Reference
78
93
 
79
94
  - `uws lcd list` – enumerate TL LCD devices and show their USB serial numbers.
80
- - `uws lcd info --serial <usb-serial>` – read firmware and handshake data.
81
- - `uws lcd send-jpg --serial <usb-serial> --file <image.jpg>` – stream a JPEG asset.
82
- - `uws lcd keep-alive --serial <usb-serial> [--interval seconds]` – emit periodic handshakes to prevent the wireless panel from dimming.
83
- - `uws lcd control --serial <usb-serial> [--mode show-jpg|show-app-sync|lcd-test] [--jpg-index N] [--brightness 0-100] [--fps N] [--rotation 0|90|180|270] [--test-color R,G,B]` – send an `LCDControlSetting` payload.
84
- - `uws fan list` – fetch a snapshot of bound wireless receivers via the RF receiver.
95
+ - `uws lcd info --serial <usb-serial>` – read the firmware version and the panel's group index.
96
+ - `uws lcd send-jpg --serial <usb-serial> --file <image> [--raw] [--save]` – show a JPEG or PNG. On the TL Wireless LCD the image is scaled to 400x400 and re-encoded as JPEG (quality 95, lowered until it fits in 100000 bytes), as the vendor app does; `--raw` sends the file unchanged; `--save` also stores it as the image the panel shows at power-on.
97
+ - `uws lcd play-video --serial <usb-serial> --file <video> [--fps N] [--loop]` – decode a video with FFmpeg and send it frame by frame (TL Wireless LCD; default: the video's own frame rate).
98
+ - `uws lcd sensor --serial <usb-serial> --metric cpu-temp|cpu-load|gpu-temp|gpu-load|fan-rpm|clock [--color blue|green|purple|red] [--fan <mac>] [--interval seconds] [--once] [--output preview.png]` – show a live ring gauge (or a clock) on the TL Wireless LCD, updated every second like the vendor app's sensor screens. CPU temperature comes from hwmon (k10temp, zenpower or coretemp), GPU from `nvidia-smi` or amdgpu, fan speed from the RF receiver (the average of a group's running fans). Runs until Ctrl+C; `--output` writes one frame to a PNG instead.
99
+ - `uws lcd keep-alive --serial <usb-serial> [--interval seconds]` – send the vendor app's heartbeat (default every second) to keep the wireless panel awake.
100
+ - `uws lcd control --serial <usb-serial> [--brightness 0-100] [--rotation 0|90|180|270]` – on the TL Wireless LCD, change only the settings given. Brightness is sent as is (the vendor app's 0/25/50/75/100% steps send 0/10/30/40/100). On the wired TL LCD the full `LCDControlSetting` is sent (`--mode show-jpg|show-app-sync|lcd-test`, `--jpg-index N`, `--fps N`, `--test-color R,G,B`; brightness defaults to 50, rotation to 0).
101
+ - `uws fan list` – fetch a snapshot of wireless receivers via the RF receiver (master controllers are listed by `list-masters`).
85
102
  - `uws fan list-masters` – enumerate master controllers and associated wireless receivers.
86
- - `uws fan set-fan --mac <aa:bb:..> --pwm <0-255> [--sequence-index N]` – send a single shot PWM update to one receiver; `--all` broadcasts to every bound receiver.
87
- - `uws fan pwm-sync --mac|--all [--mode controller|receiver] [--interval seconds] [--once] [--sequence-index N]` – synchronize receiver speeds. `controller` polls motherboard PWM and replays the value via RF (`--interval` / `--once` apply here); `receiver` sets PWM=6 so the receiver tracks the motherboard header directly (`--sequence-index` applies here).
88
- - `uws fan set-led --mac <aa:bb:..> --mode static|rainbow|frames|effect|random-effect` – apply wireless LED effects (**experimental**).
103
+ - `uws fan set-fan --mac <aa:bb:..> --pwm <0-255> [--sequence-index N]` – send a single shot PWM update to one receiver; `--all` sends it to every receiver bound to the attached master. The device number sent with it defaults to the device's position among the master's devices, as the vendor app does.
104
+ - `uws fan bind --mac <aa:bb:..> [--rx-type 1-13]` / `uws fan unbind --mac <aa:bb:..>` – bind to or unbind from the attached master; the master saves its configuration afterwards. A device that follows the motherboard keeps doing so after binding.
105
+ - `uws fan identify --mac <aa:bb:..>` – make the device flash so you can find it.
106
+ - `uws fan set-channel --channel <1|7|11|15|17|21|25|29|31|33|35|39|8>` – move every device bound to the attached controller to another RF channel (the vendor app's choices; 8 is its automatic default). Fan speeds and lighting are kept.
107
+ - Commands reach every bound device, whichever controller it is bound to. Devices bound to a controller that is not attached receive short commands, but longer LED effects rarely get through to them; bind them to the attached controller (`fan unbind`, then `fan bind`) for reliable effects.
108
+ - `uws fan reboot-lcd --mac <aa:bb:..>` – restart the LCD panels of a TL Wireless LCD fan over RF.
109
+ - `uws fan pwm-sync --mac|--all [--mode controller|receiver] [--interval seconds] [--once] [--sequence-index N]` – synchronize receiver speeds. `receiver` (default) sets PWM=6 so the receiver tracks the motherboard header directly; as the vendor app, only for devices whose MAC ends in `e1`. `controller` polls motherboard PWM and replays the value via RF (`--interval` / `--once` apply here).
110
+ - `uws fan set-led --mac <aa:bb:..> --mode static|rainbow|frames|effect|random-effect` – apply wireless LED effects. The effect is compressed (at most 12288 bytes, as the vendor app allows), sent, and resent until the device reports it; then the master saves its configuration.
89
111
 
90
112
  ### `uws fan set-led` modes
91
113
 
92
114
  - `static`: requires `--color R,G,B` or `--color-list R,G,B;...` to paint the LED strip once.
93
115
  - `rainbow`: procedural rainbow; optional `--frames N` (default 24) and `--interval-ms` (default 50).
94
116
  - `frames`: feed a JSON animation via `--frames-file`. Each frame is an array of `[R, G, B]` triples; see `examples/tl_frames_sample.json` for a minimal illustration (the CLI will pad or truncate per device LED count).
95
- - `effect`: drives any of the 29 TL presets. Choose an effect with `--effect <name>` (e.g. `twinkle`, `meteor_shower`), adjust brightness 0‑255 via `--effect-brightness`, pick direction with `--effect-direction 0|1`, and select which segment to update using `--effect-scope front|behind|both` (default `both`).
117
+ - `effect`: drives any of the 29 TL presets, with the same frames the vendor app sends. Choose an effect with `--effect <name>` (e.g. `twinkle`, `meteor_shower`), adjust brightness 0‑255 via `--effect-brightness`, pick direction with `--effect-direction 0|1` (0 clockwise, the app's default), the speed level with `--speed 1-5` (default 4, the app's default), swap the front and behind halves with `--flip` (the app's up/down swap), and select which segment to update using `--effect-scope front|behind|both` (default `both`; the two sides are combined as the app does).
118
+ - Each effect starts with the colours the app's lighting page uses for it (e.g. purple, cyan, green and yellow for `static_color`). `--effect-colors R,G,B;...` replaces them (up to four) for the nine computed effects: `rainbow`, `rainbow_morph`, `static_color`, `breathing`, `runway`, `meteor`, `color_cycle`, `stack` and `twinkle`.
119
+ - The other 20 are shipped as frames rendered by the vendor app with its default colours for each effect, for each fan count, direction and its 5 brightness levels (0, 64, 128, 192, 255; other brightness values use the closest level). `voice`, `meteor_shower` and `kaleidoscope` are random in the app; one rendering of each is shipped.
120
+ - `merge`: one effect running across fan groups, like the vendor app's merge mode (`--all`, or `--order mac1,mac2,...` for the sequence; `--reverse mac,...` runs it the other way on those groups). Merged effects: `rainbow`, `static_color`, `breathing`, `runway`, `meteor`, `color_cycle`, `cover_cycle`, `wave`, `meteor_shower`; `rainbow_morph` and `twinkle` run on each group on its own, as in the app. Speed, brightness, direction and colours work as for `effect` (merged effects step 12 ms per speed level). All groups are sent the effect before uws waits for them, so they start together.
96
121
  - `random-effect`: picks a random preset each time; accepts the same brightness/direction/scope flags as `effect`.
97
122
 
98
123
  Available effect names (case-insensitive): `rainbow`, `rainbow_morph`, `static_color`, `breathing`, `runway`, `meteor`, `color_cycle`, `staggered`, `tide`, `mixing`, `voice`, `door`, `render`, `ripple`, `reflect`, `tail_chasing`, `paint`, `ping_pong`, `stack`, `cover_cycle`, `wave`, `racing`, `lottery`, `intertwine`, `meteor_shower`, `collide`, `electric_current`, `kaleidoscope`, `twinkle`.
@@ -115,7 +140,8 @@ uws fan pwm-sync --mac aa:bb:cc:dd:ee:ff --once
115
140
  - `hidapi` (via `hid`) for TL LCD HID access.
116
141
  - `pyusb` for the RF sender/receiver WinUSB endpoints.
117
142
  - `pycryptodomex` for the DES-CBC transport used by the wireless LCD receiver.
118
- - `Pillow` is optional for JPEG frame validation.
143
+ - `Pillow` to prepare images for the LCD.
144
+ - `FFmpeg` (`ffmpeg` and `ffprobe` on the PATH) for `uws lcd play-video` only.
119
145
 
120
146
  Each command expects the TL LCD USB display (vendor 0x04FC or 0x1CBE) and the wireless transmitter/receiver pair (vendor 0x0416) to be attached when the command executes.
121
147
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "uwscli"
3
- version = "0.4.0"
3
+ version = "0.5.0"
4
4
  description = "Uni-Wireless-Sync: wireless control toolkit for TL fan receivers"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
@@ -25,6 +25,7 @@ dependencies = [
25
25
  "hidapi>=0.14",
26
26
  "pyusb>=1.2",
27
27
  "pycryptodomex>=3.17",
28
+ "Pillow>=10.1", # ImageFont.load_default(size=...) for the sensor screens
28
29
  ]
29
30
 
30
31
  [project.optional-dependencies]
@@ -35,7 +36,6 @@ dev = [
35
36
  "black>=24.0",
36
37
  "mypy>=1.8",
37
38
  ]
38
- images = ["Pillow>=10.0"]
39
39
 
40
40
  [project.urls]
41
41
  Homepage = "https://github.com/phstudy/uni-wireless-sync"
@@ -49,7 +49,7 @@ where = ["src"]
49
49
  include = ["uwscli", "uwscli.*"]
50
50
 
51
51
  [tool.setuptools.package-data]
52
- "uwscli" = ["data/twinkle.bin"]
52
+ "uwscli" = ["data/twinkle.bin", "data/tl_frames/*.xz"]
53
53
 
54
54
  [tool.pytest.ini_options]
55
55
  pythonpath = ["src"]
@@ -1,14 +1,14 @@
1
1
  """UWS CLI package."""
2
2
 
3
- __version__ = "0.4.0"
3
+ __version__ = "0.5.0"
4
4
 
5
5
  __all__ = [
6
6
  "cli",
7
7
  "lcd",
8
8
  "led",
9
- "tinyuz",
10
- "wireless",
11
9
  "structs",
12
- "usbutil",
10
+ "tinyuz",
13
11
  "tl_effects",
12
+ "usbutil",
13
+ "wireless",
14
14
  ]