uwscli 0.3.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 (70) hide show
  1. uwscli-0.5.0/PKG-INFO +234 -0
  2. uwscli-0.5.0/README.md +178 -0
  3. {uwscli-0.3.0 → uwscli-0.5.0}/pyproject.toml +6 -6
  4. {uwscli-0.3.0 → uwscli-0.5.0}/src/uwscli/__init__.py +4 -4
  5. uwscli-0.5.0/src/uwscli/cli.py +1422 -0
  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.3.0 → uwscli-0.5.0}/src/uwscli/lcd.py +256 -55
  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.3.0 → uwscli-0.5.0}/src/uwscli/structs.py +19 -7
  31. {uwscli-0.3.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.3.0 → uwscli-0.5.0}/src/uwscli/tlcontroller.py +14 -9
  36. {uwscli-0.3.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.5.0/src/uwscli.egg-info/PKG-INFO +234 -0
  39. uwscli-0.5.0/src/uwscli.egg-info/SOURCES.txt +57 -0
  40. {uwscli-0.3.0 → uwscli-0.5.0}/src/uwscli.egg-info/requires.txt +1 -3
  41. uwscli-0.5.0/tests/test_cli_errors.py +132 -0
  42. {uwscli-0.3.0 → uwscli-0.5.0}/tests/test_cli_output.py +484 -5
  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.3.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.3.0/PKG-INFO +0 -194
  51. uwscli-0.3.0/README.md +0 -137
  52. uwscli-0.3.0/src/uwscli/cli.py +0 -801
  53. uwscli-0.3.0/src/uwscli/tinyuz.py +0 -192
  54. uwscli-0.3.0/src/uwscli/tl_effects.py +0 -1355
  55. uwscli-0.3.0/src/uwscli/wireless.py +0 -916
  56. uwscli-0.3.0/src/uwscli.egg-info/PKG-INFO +0 -194
  57. uwscli-0.3.0/src/uwscli.egg-info/SOURCES.txt +0 -29
  58. uwscli-0.3.0/tests/test_cli_errors.py +0 -49
  59. uwscli-0.3.0/tests/test_led_compression.py +0 -97
  60. uwscli-0.3.0/tests/test_wireless_led_packets.py +0 -85
  61. {uwscli-0.3.0 → uwscli-0.5.0}/LICENSE +0 -0
  62. {uwscli-0.3.0 → uwscli-0.5.0}/setup.cfg +0 -0
  63. {uwscli-0.3.0 → uwscli-0.5.0}/src/uwscli/data/__init__.py +0 -0
  64. {uwscli-0.3.0 → uwscli-0.5.0}/src/uwscli/data/twinkle.bin +0 -0
  65. {uwscli-0.3.0 → uwscli-0.5.0}/src/uwscli/led.py +0 -0
  66. {uwscli-0.3.0 → uwscli-0.5.0}/src/uwscli/logging_utils.py +0 -0
  67. {uwscli-0.3.0 → uwscli-0.5.0}/src/uwscli.egg-info/dependency_links.txt +0 -0
  68. {uwscli-0.3.0 → uwscli-0.5.0}/src/uwscli.egg-info/entry_points.txt +0 -0
  69. {uwscli-0.3.0 → uwscli-0.5.0}/src/uwscli.egg-info/top_level.txt +0 -0
  70. {uwscli-0.3.0 → uwscli-0.5.0}/tests/test_usbutil.py +0 -0
uwscli-0.5.0/PKG-INFO ADDED
@@ -0,0 +1,234 @@
1
+ Metadata-Version: 2.4
2
+ Name: uwscli
3
+ Version: 0.5.0
4
+ Summary: Uni-Wireless-Sync: wireless control toolkit for TL fan receivers
5
+ Author: Study Hsueh
6
+ License: MIT License
7
+
8
+ Copyright (c) 2025 Study Hsueh
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+ Project-URL: Homepage, https://github.com/phstudy/uni-wireless-sync
28
+ Project-URL: Issues, https://github.com/phstudy/uni-wireless-sync/issues
29
+ Keywords: lian-li,uni-fan,wireless,lcd
30
+ Classifier: Development Status :: 3 - Alpha
31
+ Classifier: Environment :: Console
32
+ Classifier: Intended Audience :: System Administrators
33
+ Classifier: License :: OSI Approved :: MIT License
34
+ Classifier: Operating System :: MacOS
35
+ Classifier: Operating System :: POSIX :: Linux
36
+ Classifier: Programming Language :: Python
37
+ Classifier: Programming Language :: Python :: 3
38
+ Classifier: Programming Language :: Python :: 3.10
39
+ Classifier: Programming Language :: Python :: 3.11
40
+ Classifier: Programming Language :: Python :: 3.12
41
+ Classifier: Topic :: System :: Hardware :: Universal Serial Bus (USB)
42
+ Requires-Python: >=3.10
43
+ Description-Content-Type: text/markdown
44
+ License-File: LICENSE
45
+ Requires-Dist: hidapi>=0.14
46
+ Requires-Dist: pyusb>=1.2
47
+ Requires-Dist: pycryptodomex>=3.17
48
+ Requires-Dist: Pillow>=10.1
49
+ Provides-Extra: dev
50
+ Requires-Dist: pytest>=7.0; extra == "dev"
51
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
52
+ Requires-Dist: ruff>=0.5; extra == "dev"
53
+ Requires-Dist: black>=24.0; extra == "dev"
54
+ Requires-Dist: mypy>=1.8; extra == "dev"
55
+ Dynamic: license-file
56
+
57
+ # Uni Wireless Sync CLI
58
+
59
+ Warning: This is an unofficial implementation; use at your own risk.
60
+
61
+ ## Overview
62
+
63
+ Uni Wireless Sync (UWS) CLI provides command-line utilities for managing Uni Fan Wireless controllers, L-Wireless receivers, and LCD panels. Each command re-opens the required USB or RF device so no background daemon is left running, and lower-level HID/USB errors are surfaced directly to simplify scripting.
64
+
65
+ ## Supported Hardware
66
+
67
+ - UNI FAN TL wireless LCD panels
68
+ - UNI FAN TL wireless fans (non-LCD)
69
+
70
+ Other Uni Fan series are currently not supported.
71
+
72
+ ## Features
73
+
74
+ - Discover TL LCD USB devices and 2.4 GHz wireless fan controllers.
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).
81
+ - List detected master controller MAC addresses to simplify binding workflows.
82
+ - Send one-shot PWM commands to TL wireless fans over the 2.4 GHz dongle.
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.
85
+ - Toggle motherboard PWM sync mode for one receiver or every bound receiver.
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.
89
+
90
+ ### Fan wiring modes
91
+
92
+ - **USB + PWM header (controller mode):** leave the receiver's PWM lead unplugged; control every fan via `uws fan set-fan` (any PWM value 0-255). The reported `fan_pwm` reflects your last command.
93
+ - **USB-only (receiver mode, PWM lead connected to motherboard):** the CLI writes a PWM of 6 (e.g. `uws fan pwm-sync --mode receiver --all`) so the receiver keeps syncing to the motherboard header. Sending another `set-fan` value at any time overrides the sync immediately; writing 6 (or re-running the sync helper) hands control back to the motherboard.
94
+
95
+ ## FAQ
96
+
97
+ - **How do I mount the L-Wireless Controller (v1)?** The thicker dongle supports two options: (1) plug into a USB Type-A port—this wiring is equivalent to `pwm-sync` receiver mode; (2) plug the header into a 9-pin USB port on the motherboard—this matches `pwm-sync` controller mode, but 2.4 GHz signal strength drops because the dongle lives inside the chassis.
98
+ - **How do I mount the L-Wireless Controller (v2)?** The slimmer dongle only supports option (1): plug into a USB Type-A port (`pwm-sync` receiver mode).
99
+ - **What is the difference between L-Wireless Receiver (v1) and (v2)?** Receiver v1 exposes both USB and a 2-pin PWM lead only on the LCD bundle (USB powers the LCD, the 2-pin lead powers fans); non-LCD receiver v1 units ship with just the 2-pin power lead. Receiver v2 adds a dedicated 4-pin PWM header; plug it into the motherboard when you want it to mirror the motherboard duty cycle via `pwm-sync --mode receiver`, or leave it disconnected and the controller will keep driving fan PWM directly.
100
+
101
+ ## Installation
102
+
103
+ ```bash
104
+ pip install uwscli
105
+
106
+ python -m venv .venv
107
+ source .venv/bin/activate
108
+ pip install -e .
109
+ # or include dev extras
110
+ pip install -e .[dev]
111
+ ```
112
+
113
+ ## Usage Examples
114
+
115
+ ```bash
116
+ # Enumerate connected devices
117
+ uws lcd list
118
+ uws fan list
119
+
120
+ # Display operations
121
+ uws lcd info --serial <usb-serial>
122
+ uws lcd send-jpg --serial <usb-serial> --file assets/sample_lcd.jpg
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
128
+
129
+ # Fan receiver operations
130
+ uws fan set-fan --mac aa:bb:cc:dd:ee:ff --pwm 120 # direct PWM control
131
+ uws fan pwm-sync --mode receiver --all # receiver mode receivers (sets PWM=6)
132
+ uws fan bind --mac aa:bb:cc:dd:ee:ff
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
142
+ uws fan pwm-sync --all
143
+ uws fan pwm-sync --mac aa:bb:cc:dd:ee:ff --once
144
+ ```
145
+
146
+ `uws lcd list` prints JSON rows that include a `serial` field—copy that value when invoking other LCD subcommands.
147
+
148
+ ## Command Reference
149
+
150
+ - `uws lcd list` – enumerate TL LCD devices and show their USB serial numbers.
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`).
158
+ - `uws fan list-masters` – enumerate master controllers and associated wireless receivers.
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.
167
+
168
+ ### `uws fan set-led` modes
169
+
170
+ - `static`: requires `--color R,G,B` or `--color-list R,G,B;...` to paint the LED strip once.
171
+ - `rainbow`: procedural rainbow; optional `--frames N` (default 24) and `--interval-ms` (default 50).
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).
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.
177
+ - `random-effect`: picks a random preset each time; accepts the same brightness/direction/scope flags as `effect`.
178
+
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`.
180
+
181
+ Example:
182
+
183
+ ```
184
+ uws fan set-led --mac aa:bb:cc:dd:ee:ff --mode effect --effect twinkle --effect-brightness 180 --effect-direction 0 --effect-scope both
185
+ ```
186
+
187
+ Random example:
188
+
189
+ ```
190
+ uws fan set-led --mac aa:bb:cc:dd:ee:ff --mode random-effect --effect-brightness 200 --effect-direction 1
191
+ ```
192
+ - `uws fan pwm-sync --all|--mac [--mode controller|receiver] [--interval seconds] [--once] [--sequence-index N]` – default `receiver` mode writes PWM=6 so fans follow the motherboard; `controller` mode polls and replays PWM from the motherboard (supports `--interval`/`--once` for polling loops; `--sequence-index` applies to receiver broadcasts).
193
+
194
+ ## Dependencies
195
+
196
+ - `hidapi` (via `hid`) for TL LCD HID access.
197
+ - `pyusb` for the RF sender/receiver WinUSB endpoints.
198
+ - `pycryptodomex` for the DES-CBC transport used by the wireless LCD receiver.
199
+ - `Pillow` to prepare images for the LCD.
200
+ - `FFmpeg` (`ffmpeg` and `ffprobe` on the PATH) for `uws lcd play-video` only.
201
+
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.
203
+
204
+ ## Linux udev Permissions
205
+
206
+ Grant non-root access to the TL wireless dongles by adding `/etc/udev/rules.d/99-tl-wireless.rules` with:
207
+
208
+ ```
209
+ # Winbond SLV3RX_V1.6 (receiver)
210
+ SUBSYSTEM=="usb", ATTR{idVendor}=="0416", ATTR{idProduct}=="8041", MODE="0666", GROUP="plugdev"
211
+ SUBSYSTEM=="usb_device", ATTR{idVendor}=="0416", ATTR{idProduct}=="8041", MODE="0666", GROUP="plugdev"
212
+ SUBSYSTEM=="usb_interface", ATTRS{idVendor}=="0416", ATTRS{idProduct}=="8041", MODE="0666", GROUP="plugdev"
213
+
214
+ # Winbond SLV3TX_V1.6 (transmitter)
215
+ SUBSYSTEM=="usb", ATTR{idVendor}=="0416", ATTR{idProduct}=="8040", MODE="0666", GROUP="plugdev"
216
+ SUBSYSTEM=="usb_device", ATTR{idVendor}=="0416", ATTR{idProduct}=="8040", MODE="0666", GROUP="plugdev"
217
+ SUBSYSTEM=="usb_interface", ATTRS{idVendor}=="0416", ATTRS{idProduct}=="8040", MODE="0666", GROUP="plugdev"
218
+
219
+ # Luminary Micro TL-LCD Wireless-1.3
220
+ SUBSYSTEM=="usb", ATTR{idVendor}=="1cbe", ATTR{idProduct}=="0006", MODE="0666", GROUP="plugdev"
221
+ SUBSYSTEM=="usb_device", ATTR{idVendor}=="1cbe", ATTR{idProduct}=="0006", MODE="0666", GROUP="plugdev"
222
+ SUBSYSTEM=="usb_interface", ATTRS{idVendor}=="1cbe", ATTRS{idProduct}=="0006", MODE="0666", GROUP="plugdev"
223
+ ```
224
+
225
+ Reload the rules and replug the dongles:
226
+
227
+ ```
228
+ sudo udevadm control --reload
229
+ sudo udevadm trigger
230
+ ```
231
+
232
+ ## License
233
+
234
+ Released under the MIT License. See `LICENSE` for details.
uwscli-0.5.0/README.md ADDED
@@ -0,0 +1,178 @@
1
+ # Uni Wireless Sync CLI
2
+
3
+ Warning: This is an unofficial implementation; use at your own risk.
4
+
5
+ ## Overview
6
+
7
+ Uni Wireless Sync (UWS) CLI provides command-line utilities for managing Uni Fan Wireless controllers, L-Wireless receivers, and LCD panels. Each command re-opens the required USB or RF device so no background daemon is left running, and lower-level HID/USB errors are surfaced directly to simplify scripting.
8
+
9
+ ## Supported Hardware
10
+
11
+ - UNI FAN TL wireless LCD panels
12
+ - UNI FAN TL wireless fans (non-LCD)
13
+
14
+ Other Uni Fan series are currently not supported.
15
+
16
+ ## Features
17
+
18
+ - Discover TL LCD USB devices and 2.4 GHz wireless fan controllers.
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).
25
+ - List detected master controller MAC addresses to simplify binding workflows.
26
+ - Send one-shot PWM commands to TL wireless fans over the 2.4 GHz dongle.
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.
29
+ - Toggle motherboard PWM sync mode for one receiver or every bound receiver.
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.
33
+
34
+ ### Fan wiring modes
35
+
36
+ - **USB + PWM header (controller mode):** leave the receiver's PWM lead unplugged; control every fan via `uws fan set-fan` (any PWM value 0-255). The reported `fan_pwm` reflects your last command.
37
+ - **USB-only (receiver mode, PWM lead connected to motherboard):** the CLI writes a PWM of 6 (e.g. `uws fan pwm-sync --mode receiver --all`) so the receiver keeps syncing to the motherboard header. Sending another `set-fan` value at any time overrides the sync immediately; writing 6 (or re-running the sync helper) hands control back to the motherboard.
38
+
39
+ ## FAQ
40
+
41
+ - **How do I mount the L-Wireless Controller (v1)?** The thicker dongle supports two options: (1) plug into a USB Type-A port—this wiring is equivalent to `pwm-sync` receiver mode; (2) plug the header into a 9-pin USB port on the motherboard—this matches `pwm-sync` controller mode, but 2.4 GHz signal strength drops because the dongle lives inside the chassis.
42
+ - **How do I mount the L-Wireless Controller (v2)?** The slimmer dongle only supports option (1): plug into a USB Type-A port (`pwm-sync` receiver mode).
43
+ - **What is the difference between L-Wireless Receiver (v1) and (v2)?** Receiver v1 exposes both USB and a 2-pin PWM lead only on the LCD bundle (USB powers the LCD, the 2-pin lead powers fans); non-LCD receiver v1 units ship with just the 2-pin power lead. Receiver v2 adds a dedicated 4-pin PWM header; plug it into the motherboard when you want it to mirror the motherboard duty cycle via `pwm-sync --mode receiver`, or leave it disconnected and the controller will keep driving fan PWM directly.
44
+
45
+ ## Installation
46
+
47
+ ```bash
48
+ pip install uwscli
49
+
50
+ python -m venv .venv
51
+ source .venv/bin/activate
52
+ pip install -e .
53
+ # or include dev extras
54
+ pip install -e .[dev]
55
+ ```
56
+
57
+ ## Usage Examples
58
+
59
+ ```bash
60
+ # Enumerate connected devices
61
+ uws lcd list
62
+ uws fan list
63
+
64
+ # Display operations
65
+ uws lcd info --serial <usb-serial>
66
+ uws lcd send-jpg --serial <usb-serial> --file assets/sample_lcd.jpg
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
72
+
73
+ # Fan receiver operations
74
+ uws fan set-fan --mac aa:bb:cc:dd:ee:ff --pwm 120 # direct PWM control
75
+ uws fan pwm-sync --mode receiver --all # receiver mode receivers (sets PWM=6)
76
+ uws fan bind --mac aa:bb:cc:dd:ee:ff
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
86
+ uws fan pwm-sync --all
87
+ uws fan pwm-sync --mac aa:bb:cc:dd:ee:ff --once
88
+ ```
89
+
90
+ `uws lcd list` prints JSON rows that include a `serial` field—copy that value when invoking other LCD subcommands.
91
+
92
+ ## Command Reference
93
+
94
+ - `uws lcd list` – enumerate TL LCD devices and show their USB serial numbers.
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`).
102
+ - `uws fan list-masters` – enumerate master controllers and associated wireless receivers.
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.
111
+
112
+ ### `uws fan set-led` modes
113
+
114
+ - `static`: requires `--color R,G,B` or `--color-list R,G,B;...` to paint the LED strip once.
115
+ - `rainbow`: procedural rainbow; optional `--frames N` (default 24) and `--interval-ms` (default 50).
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).
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.
121
+ - `random-effect`: picks a random preset each time; accepts the same brightness/direction/scope flags as `effect`.
122
+
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`.
124
+
125
+ Example:
126
+
127
+ ```
128
+ uws fan set-led --mac aa:bb:cc:dd:ee:ff --mode effect --effect twinkle --effect-brightness 180 --effect-direction 0 --effect-scope both
129
+ ```
130
+
131
+ Random example:
132
+
133
+ ```
134
+ uws fan set-led --mac aa:bb:cc:dd:ee:ff --mode random-effect --effect-brightness 200 --effect-direction 1
135
+ ```
136
+ - `uws fan pwm-sync --all|--mac [--mode controller|receiver] [--interval seconds] [--once] [--sequence-index N]` – default `receiver` mode writes PWM=6 so fans follow the motherboard; `controller` mode polls and replays PWM from the motherboard (supports `--interval`/`--once` for polling loops; `--sequence-index` applies to receiver broadcasts).
137
+
138
+ ## Dependencies
139
+
140
+ - `hidapi` (via `hid`) for TL LCD HID access.
141
+ - `pyusb` for the RF sender/receiver WinUSB endpoints.
142
+ - `pycryptodomex` for the DES-CBC transport used by the wireless LCD receiver.
143
+ - `Pillow` to prepare images for the LCD.
144
+ - `FFmpeg` (`ffmpeg` and `ffprobe` on the PATH) for `uws lcd play-video` only.
145
+
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.
147
+
148
+ ## Linux udev Permissions
149
+
150
+ Grant non-root access to the TL wireless dongles by adding `/etc/udev/rules.d/99-tl-wireless.rules` with:
151
+
152
+ ```
153
+ # Winbond SLV3RX_V1.6 (receiver)
154
+ SUBSYSTEM=="usb", ATTR{idVendor}=="0416", ATTR{idProduct}=="8041", MODE="0666", GROUP="plugdev"
155
+ SUBSYSTEM=="usb_device", ATTR{idVendor}=="0416", ATTR{idProduct}=="8041", MODE="0666", GROUP="plugdev"
156
+ SUBSYSTEM=="usb_interface", ATTRS{idVendor}=="0416", ATTRS{idProduct}=="8041", MODE="0666", GROUP="plugdev"
157
+
158
+ # Winbond SLV3TX_V1.6 (transmitter)
159
+ SUBSYSTEM=="usb", ATTR{idVendor}=="0416", ATTR{idProduct}=="8040", MODE="0666", GROUP="plugdev"
160
+ SUBSYSTEM=="usb_device", ATTR{idVendor}=="0416", ATTR{idProduct}=="8040", MODE="0666", GROUP="plugdev"
161
+ SUBSYSTEM=="usb_interface", ATTRS{idVendor}=="0416", ATTRS{idProduct}=="8040", MODE="0666", GROUP="plugdev"
162
+
163
+ # Luminary Micro TL-LCD Wireless-1.3
164
+ SUBSYSTEM=="usb", ATTR{idVendor}=="1cbe", ATTR{idProduct}=="0006", MODE="0666", GROUP="plugdev"
165
+ SUBSYSTEM=="usb_device", ATTR{idVendor}=="1cbe", ATTR{idProduct}=="0006", MODE="0666", GROUP="plugdev"
166
+ SUBSYSTEM=="usb_interface", ATTRS{idVendor}=="1cbe", ATTRS{idProduct}=="0006", MODE="0666", GROUP="plugdev"
167
+ ```
168
+
169
+ Reload the rules and replug the dongles:
170
+
171
+ ```
172
+ sudo udevadm control --reload
173
+ sudo udevadm trigger
174
+ ```
175
+
176
+ ## License
177
+
178
+ Released under the MIT License. See `LICENSE` for details.
@@ -1,7 +1,7 @@
1
1
  [project]
2
2
  name = "uwscli"
3
- version = "0.3.0"
4
- description = "Uni-Wireless-Sync: wireless control toolkit for TL LCD fan hubs"
3
+ version = "0.5.0"
4
+ description = "Uni-Wireless-Sync: wireless control toolkit for TL fan receivers"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
7
7
  license = {file = "LICENSE"}
@@ -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,11 +36,10 @@ 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
- Homepage = "https://github.com/phstudy/tlv2-lcd"
42
- Issues = "https://github.com/phstudy/tlv2-lcd/issues"
41
+ Homepage = "https://github.com/phstudy/uni-wireless-sync"
42
+ Issues = "https://github.com/phstudy/uni-wireless-sync/issues"
43
43
 
44
44
  [project.scripts]
45
45
  uws = "uwscli.cli:main"
@@ -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.3.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
  ]