aiodynet 0.1.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.
@@ -0,0 +1,15 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ build/
5
+ dist/
6
+ *.egg-info/
7
+ .coverage
8
+ .coverage.*
9
+ coverage.xml
10
+ htmlcov/
11
+ .mypy_cache/
12
+ .ruff_cache/
13
+ .pytest_cache/
14
+ .hypothesis/
15
+ .DS_Store
@@ -0,0 +1,20 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (2026-11-18)
4
+
5
+ First release.
6
+
7
+ - `Packet`, `PacketFramer`: DyNet 1 framing and checksums
8
+ - Typed messages for preset selection and reports, channel levels and their
9
+ reports and requests, and fading a channel to a preset; anything else is
10
+ passed through as `UnknownMessage`
11
+ - `Level` and fade handling with range checks
12
+ - `DynetClient`: connect, automatic reconnect with backoff, paced writes,
13
+ subscriptions, `query`, and a clean `close`
14
+ - `check_connection` for validating a host and port
15
+ - `aiodynet.testing.FakeGateway` for tests
16
+ - Typed messages for every other opcode whose layout the DyNet opcode list
17
+ defines clearly: area commands, area off/reset/panic, area and channel
18
+ fades, stop fade, the 0x71-0x73 channel levels, motion sync, user
19
+ preferences, preset levels, and the physical clock time and date
20
+ broadcasts
aiodynet-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sam Dunster
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,271 @@
1
+ Metadata-Version: 2.5
2
+ Name: aiodynet
3
+ Version: 0.1.0
4
+ Summary: Asyncio client for the Signify Dynalite DyNet lighting control bus
5
+ Project-URL: Homepage, https://github.com/sdunster/aiodynet
6
+ Project-URL: Issues, https://github.com/sdunster/aiodynet/issues
7
+ Project-URL: Changelog, https://github.com/sdunster/aiodynet/blob/main/CHANGELOG.md
8
+ Author-email: Sam Dunster <me@sdunster.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: asyncio,dynalite,dynet,home-assistant,lighting,signify
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Framework :: AsyncIO
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Topic :: Home Automation
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.13
23
+ Description-Content-Type: text/markdown
24
+
25
+ # aiodynet
26
+
27
+ An asyncio client for the Signify Dynalite **DyNet** lighting control bus,
28
+ through a DyNet TCP gateway (for example a PDEG).
29
+
30
+ aiodynet only reads and writes the bus. It has no idea what your site looks
31
+ like: there are no devices, rooms, names or templates here, only the areas,
32
+ channels, presets and levels that travel on the wire. That makes it a small,
33
+ predictable base for higher-level code such as the Home Assistant `dynalite`
34
+ integration.
35
+
36
+ - Typed, immutable messages that validate themselves, so an out-of-range value
37
+ fails where you wrote it, not on the bus
38
+ - One connection object with a clear lifecycle: connect, reconnect on its own,
39
+ close cleanly
40
+ - Writes are paced, because gateways drop packets that arrive too quickly
41
+ - No dependencies outside the standard library. Fully typed (`py.typed`) and
42
+ checked with `mypy --strict`
43
+ - A fake gateway in `aiodynet.testing` for testing your own code without
44
+ hardware
45
+
46
+ Requires Python 3.13 or newer.
47
+
48
+ ## Quick start
49
+
50
+ ```python
51
+ import asyncio
52
+
53
+ from aiodynet import DynetClient, Level, PresetSelect, Received, SetChannelLevel
54
+
55
+
56
+ def show(received: Received) -> None:
57
+ print(received.packet.hex(), received.message)
58
+
59
+
60
+ async def main() -> None:
61
+ async with DynetClient("192.0.2.10", 50000) as client:
62
+ client.subscribe(show)
63
+
64
+ # Recall preset 1 in area 12 over two seconds
65
+ await client.send(PresetSelect(area=12, preset=1, fade=2))
66
+
67
+ # Fade channel 3 of area 12 to 40 %
68
+ await client.send(
69
+ SetChannelLevel(area=12, channel=3, level=Level.from_percent(40), fade=1)
70
+ )
71
+
72
+ await asyncio.sleep(60) # watch the bus for a minute
73
+
74
+
75
+ asyncio.run(main())
76
+ ```
77
+
78
+ ## Concepts
79
+
80
+ ### Packets
81
+
82
+ A `Packet` is one 8-byte DyNet 1 frame. You rarely build one by hand, but it
83
+ is always available: every received message comes with the exact packet, and
84
+ `send` accepts packets as well as messages.
85
+
86
+ ```python
87
+ from aiodynet import Packet
88
+
89
+ Packet.from_hex("1c 0c 64 00 00 00 ff") # checksum added for you
90
+ Packet.from_hex("1c0c64000000ff75") # checksum checked
91
+ Packet.from_bytes(raw_8_bytes) # raises InvalidPacketError if bad
92
+ ```
93
+
94
+ ### Messages
95
+
96
+ Each message class maps to exactly one wire form. Fields are keyword-only and
97
+ checked when the object is built. Channels and presets are numbered from 1, as
98
+ in the DyNet tools and on keypads.
99
+
100
+ | Message | Opcode(s) | Meaning |
101
+ |---|---|---|
102
+ | `PresetSelect` | 0x00–0x03, 0x0A–0x0D | Select preset 1–2048 in an area, with a fade of up to 1310.7 s |
103
+ | `LinearPresetSelect` | 0x65 | Select preset 1–256 using the one-byte form some controllers send |
104
+ | `PresetReport` | 0x62 | An area reports its current preset |
105
+ | `RequestPreset` | 0x63 | Ask an area for its current preset |
106
+ | `SetChannelLevel` | 0x80–0x83 | Fade one channel (1–1024) to a level, with a fade of up to 5.1 s |
107
+ | `ChannelLevelReport` | 0x60 | A channel reports its target and actual level |
108
+ | `RequestChannelLevel` | 0x61 | Ask a channel for its level |
109
+ | `FadeChannelToPreset` | 0x6B | Fade one channel, or every channel, to a preset's level |
110
+ | `AreaCommand` | 0x05, 0x06, 0x08, 0x15, 0x16, 0x66 | Area commands with no data: step the area level down or up, program the current preset, disable or enable panels, save the current preset (`AreaCommandType`) |
111
+ | `AreaOff`, `ResetPreset`, `Panic`, `Unpanic` | 0x04, 0x0F, 0x17, 0x18 | Area commands with a preset-style fade |
112
+ | `AreaToLevel` | 0x79 | Fade every channel in an area to one level |
113
+ | `ChannelOff`, `ChannelOn` | 0x74, 0x75 | Fade a channel, or every channel, to off or full |
114
+ | `StopFade` | 0x76 | Stop a channel, or every channel, mid-fade |
115
+ | `FadeChannelToLevel` | 0x71–0x73 | The newer channel-level opcodes; `scale` names which one |
116
+ | `RestoreSavedPreset` | 0x67 | Return to the preset saved with `SAVE_CURRENT_PRESET` |
117
+ | `MotionActivitySync` | 0x2E | A motion sensor sharing its activity timer |
118
+ | `SetUserPreference`, `RequestUserPreference`, `UserPreferenceReport` | 0x48–0x4A | Device-specific 16-bit preference values |
119
+ | `RequestPresetLevel`, `PresetLevelReport` | 0x91, 0x92 | The level a channel has stored for a preset |
120
+ | `ClockTime`, `ClockDate` | physical 0x50, 0x53 | A device setting or broadcasting the time and date |
121
+ | `UnknownMessage` | anything else | Passed through unchanged, packet included |
122
+
123
+ Where an opcode can address one channel or the whole area, `channel=None`
124
+ means every channel. Fields whose unit the opcode list doesn't pin down are
125
+ kept raw and named `*_raw` (for example `fade_raw`, `time_raw`), rather than
126
+ guessed. Area links (0x20–0x23) are left undecoded because the opcode list
127
+ doesn't say which bit is which area.
128
+
129
+ `PresetSelect`, `LinearPresetSelect` and `PresetReport` share the base class
130
+ `AreaPresetMessage`, so `isinstance(message, AreaPresetMessage)` catches "this
131
+ area is now at preset N" however it was sent.
132
+
133
+ `decode(packet)` returns the union type `AnyMessage`, so a `match` statement
134
+ ending in `assert_never` is checked for exhaustiveness by mypy.
135
+
136
+ ### Levels
137
+
138
+ DyNet levels run backwards on the wire (0x01 is 100 %, 0xFF is off). `Level`
139
+ keeps the raw byte, so it always round-trips, and converts for you:
140
+
141
+ ```python
142
+ Level.from_percent(40)
143
+ Level.from_fraction(0.4)
144
+ Level(0x80) # the raw byte
145
+ Level.OFF, Level.FULL
146
+ level.percent, level.fraction, level.is_off
147
+ ```
148
+
149
+ Messages accept only `Level`, never a bare number, so a percentage can't be
150
+ sent as a raw byte by mistake.
151
+
152
+ ### Fades
153
+
154
+ Fades are seconds as `float`, rounded to the nearest 20 ms step. A fade that a
155
+ message can't carry raises `ValueError` rather than being wrapped or clamped:
156
+ `SetChannelLevel` holds up to `MAX_CHANNEL_FADE` (5.1 s) and preset messages up
157
+ to `MAX_PRESET_FADE` (1310.7 s).
158
+
159
+ ## The client
160
+
161
+ ```python
162
+ client = DynetClient(host, port)
163
+ await client.connect() # raises DynetConnectionError if unreachable
164
+ ...
165
+ await client.close() # always safe, any number of times
166
+ ```
167
+
168
+ or `async with DynetClient(host, port) as client:`.
169
+
170
+ - **Connecting.** `connect` makes one attempt and raises if it fails, which
171
+ suits "not ready yet, try later" handling. After a successful connect the
172
+ client reconnects on its own after any drop, waiting 1 s at first and up to
173
+ 60 s between attempts, until you call `close`.
174
+ - **Receiving.** `subscribe(callback)` calls `callback(received)` in the event
175
+ loop for every packet, where `received.packet` is the raw packet and
176
+ `received.message` its decoded meaning. It returns an unsubscribe function.
177
+ A callback that raises is logged and doesn't affect the others.
178
+ - **Connection changes.** `subscribe_connection(callback)` reports drops
179
+ (`False`) and reconnects (`True`). `client.connected` gives the current
180
+ state.
181
+ - **Sending.** `await send(message_or_packet)` returns once the packet has been
182
+ written. Packets go out one at a time, 0.2 s apart by default
183
+ (`send_interval`). If the client isn't connected, or the connection drops
184
+ before the packet is written, `send` raises `NotConnectedError`. Nothing is
185
+ kept to send later, so a command can't fire long after it was asked for.
186
+ - **Queries.** `await query(RequestPreset(area=12))` sends the request and
187
+ returns the matching `PresetReport` (or `ChannelLevelReport` for a
188
+ `RequestChannelLevel`), or raises `TimeoutError`.
189
+ - **Closing.** `close` cancels everything the client started and closes the
190
+ socket. No callbacks run after it begins.
191
+ - **Dead gateways.** TCP keepalive is enabled (30 s idle, then 3 probes 10 s
192
+ apart where the OS supports it), so a gateway that vanishes on a quiet bus
193
+ is still noticed.
194
+
195
+ `check_connection(host, port)` opens and closes a TCP connection without
196
+ sending anything. It's meant for validating a host and port in a setup flow.
197
+
198
+ ## Testing your code
199
+
200
+ `aiodynet.testing.FakeGateway` is a real TCP server on localhost that records
201
+ what clients send and sends whatever you tell it to:
202
+
203
+ ```python
204
+ from aiodynet import DynetClient, PresetReport, RequestPreset
205
+ from aiodynet.testing import FakeGateway
206
+
207
+
208
+ def site(packet):
209
+ if packet == RequestPreset(area=1).to_packet():
210
+ return [PresetReport(area=1, preset=4)]
211
+ return []
212
+
213
+
214
+ async def test_area_one_is_off():
215
+ async with FakeGateway(replies=site) as gateway:
216
+ async with DynetClient(gateway.host, gateway.port) as client:
217
+ report = await client.query(RequestPreset(area=1))
218
+ assert report.preset == 4
219
+ ```
220
+
221
+ ## How well each claim is verified
222
+
223
+ DyNet documentation is thin, so this is the evidence for each encoding:
224
+
225
+ | Encoding | Source |
226
+ |---|---|
227
+ | Packet layout, checksum | DyNet 1 opcode list; every packet in the test fixtures |
228
+ | `PresetSelect` (banks, fade in 20 ms steps, low byte then high byte) | Opcode list, plus byte-for-byte match with the packets `dynalite-devices` 0.1.47 sends |
229
+ | `SetChannelLevel` (bank byte offset by one, fade in 20 ms steps) | Byte-for-byte match with `dynalite-devices` 0.1.47 |
230
+ | `RequestPreset`, `RequestChannelLevel` | Byte-for-byte match with `dynalite-devices` 0.1.47 |
231
+ | `PresetReport`, `LinearPresetSelect`, `ChannelLevelReport`, `FadeChannelToPreset` | Opcode list, plus the meaning `dynalite-devices` 0.1.47 takes from them. Not yet checked against captured traffic |
232
+ | `FadeChannelToPreset` fade unit | Unknown, so it's kept as a raw byte |
233
+ | `MotionActivitySync`, `UserPreferenceReport`, `ClockTime`, `ClockDate` | Opcode list, plus packets captured on a real site (`tests/fixtures/site-capture.jsonl`). The clock bytes are BCD, and the date packs the day of the week into the top three bits of the month byte; both inferred from that capture |
234
+ | All other extended messages | Byte layout from the opcode list only |
235
+
236
+ The `dynalite-devices` comparison was made black-box: by driving its public
237
+ API against a fake gateway and recording the bytes, without reading its source.
238
+ Those vectors are in `tests/test_messages.py`.
239
+
240
+ ## Porting from dynalite-devices
241
+
242
+ aiodynet replaces the bus layer of `dynalite-devices`. The mapping of areas
243
+ and channels to entities, and naming, stay in the integration. To keep existing
244
+ installs behaving the same:
245
+
246
+ - **Brightness.** `dynalite-devices` sends HA brightness `b` (0–255) as the raw
247
+ level `max(1, 255 - b)`, and reads it back as `255 - raw`. Use
248
+ `Level(max(1, 255 - b))` and `255 - level.raw`, not `from_fraction`, to keep
249
+ the same bytes.
250
+ - **Channel fades** longer than 5.1 s were clamped to 5.1 s. aiodynet raises
251
+ instead, so clamp with `min(fade, MAX_CHANNEL_FADE)` first.
252
+ - **Preset fades** longer than 1310.7 s crashed `dynalite-devices` while it
253
+ built the packet. aiodynet raises a clear `ValueError` at the call.
254
+ - **Pacing.** `dynalite-devices` spaced writes 0.2 s apart. That's the default
255
+ here too.
256
+ - **Queued writes.** `dynalite-devices` queued writes while disconnected.
257
+ aiodynet raises `NotConnectedError` instead. Decide in the integration
258
+ whether to surface it or retry.
259
+
260
+ ## Development
261
+
262
+ ```sh
263
+ uv sync
264
+ uv run pytest --cov # 100 % branch coverage is enforced
265
+ uv run ruff check && uv run ruff format --check
266
+ uv run mypy
267
+ ```
268
+
269
+ ## Licence
270
+
271
+ MIT. Not affiliated with or endorsed by Signify.
@@ -0,0 +1,247 @@
1
+ # aiodynet
2
+
3
+ An asyncio client for the Signify Dynalite **DyNet** lighting control bus,
4
+ through a DyNet TCP gateway (for example a PDEG).
5
+
6
+ aiodynet only reads and writes the bus. It has no idea what your site looks
7
+ like: there are no devices, rooms, names or templates here, only the areas,
8
+ channels, presets and levels that travel on the wire. That makes it a small,
9
+ predictable base for higher-level code such as the Home Assistant `dynalite`
10
+ integration.
11
+
12
+ - Typed, immutable messages that validate themselves, so an out-of-range value
13
+ fails where you wrote it, not on the bus
14
+ - One connection object with a clear lifecycle: connect, reconnect on its own,
15
+ close cleanly
16
+ - Writes are paced, because gateways drop packets that arrive too quickly
17
+ - No dependencies outside the standard library. Fully typed (`py.typed`) and
18
+ checked with `mypy --strict`
19
+ - A fake gateway in `aiodynet.testing` for testing your own code without
20
+ hardware
21
+
22
+ Requires Python 3.13 or newer.
23
+
24
+ ## Quick start
25
+
26
+ ```python
27
+ import asyncio
28
+
29
+ from aiodynet import DynetClient, Level, PresetSelect, Received, SetChannelLevel
30
+
31
+
32
+ def show(received: Received) -> None:
33
+ print(received.packet.hex(), received.message)
34
+
35
+
36
+ async def main() -> None:
37
+ async with DynetClient("192.0.2.10", 50000) as client:
38
+ client.subscribe(show)
39
+
40
+ # Recall preset 1 in area 12 over two seconds
41
+ await client.send(PresetSelect(area=12, preset=1, fade=2))
42
+
43
+ # Fade channel 3 of area 12 to 40 %
44
+ await client.send(
45
+ SetChannelLevel(area=12, channel=3, level=Level.from_percent(40), fade=1)
46
+ )
47
+
48
+ await asyncio.sleep(60) # watch the bus for a minute
49
+
50
+
51
+ asyncio.run(main())
52
+ ```
53
+
54
+ ## Concepts
55
+
56
+ ### Packets
57
+
58
+ A `Packet` is one 8-byte DyNet 1 frame. You rarely build one by hand, but it
59
+ is always available: every received message comes with the exact packet, and
60
+ `send` accepts packets as well as messages.
61
+
62
+ ```python
63
+ from aiodynet import Packet
64
+
65
+ Packet.from_hex("1c 0c 64 00 00 00 ff") # checksum added for you
66
+ Packet.from_hex("1c0c64000000ff75") # checksum checked
67
+ Packet.from_bytes(raw_8_bytes) # raises InvalidPacketError if bad
68
+ ```
69
+
70
+ ### Messages
71
+
72
+ Each message class maps to exactly one wire form. Fields are keyword-only and
73
+ checked when the object is built. Channels and presets are numbered from 1, as
74
+ in the DyNet tools and on keypads.
75
+
76
+ | Message | Opcode(s) | Meaning |
77
+ |---|---|---|
78
+ | `PresetSelect` | 0x00–0x03, 0x0A–0x0D | Select preset 1–2048 in an area, with a fade of up to 1310.7 s |
79
+ | `LinearPresetSelect` | 0x65 | Select preset 1–256 using the one-byte form some controllers send |
80
+ | `PresetReport` | 0x62 | An area reports its current preset |
81
+ | `RequestPreset` | 0x63 | Ask an area for its current preset |
82
+ | `SetChannelLevel` | 0x80–0x83 | Fade one channel (1–1024) to a level, with a fade of up to 5.1 s |
83
+ | `ChannelLevelReport` | 0x60 | A channel reports its target and actual level |
84
+ | `RequestChannelLevel` | 0x61 | Ask a channel for its level |
85
+ | `FadeChannelToPreset` | 0x6B | Fade one channel, or every channel, to a preset's level |
86
+ | `AreaCommand` | 0x05, 0x06, 0x08, 0x15, 0x16, 0x66 | Area commands with no data: step the area level down or up, program the current preset, disable or enable panels, save the current preset (`AreaCommandType`) |
87
+ | `AreaOff`, `ResetPreset`, `Panic`, `Unpanic` | 0x04, 0x0F, 0x17, 0x18 | Area commands with a preset-style fade |
88
+ | `AreaToLevel` | 0x79 | Fade every channel in an area to one level |
89
+ | `ChannelOff`, `ChannelOn` | 0x74, 0x75 | Fade a channel, or every channel, to off or full |
90
+ | `StopFade` | 0x76 | Stop a channel, or every channel, mid-fade |
91
+ | `FadeChannelToLevel` | 0x71–0x73 | The newer channel-level opcodes; `scale` names which one |
92
+ | `RestoreSavedPreset` | 0x67 | Return to the preset saved with `SAVE_CURRENT_PRESET` |
93
+ | `MotionActivitySync` | 0x2E | A motion sensor sharing its activity timer |
94
+ | `SetUserPreference`, `RequestUserPreference`, `UserPreferenceReport` | 0x48–0x4A | Device-specific 16-bit preference values |
95
+ | `RequestPresetLevel`, `PresetLevelReport` | 0x91, 0x92 | The level a channel has stored for a preset |
96
+ | `ClockTime`, `ClockDate` | physical 0x50, 0x53 | A device setting or broadcasting the time and date |
97
+ | `UnknownMessage` | anything else | Passed through unchanged, packet included |
98
+
99
+ Where an opcode can address one channel or the whole area, `channel=None`
100
+ means every channel. Fields whose unit the opcode list doesn't pin down are
101
+ kept raw and named `*_raw` (for example `fade_raw`, `time_raw`), rather than
102
+ guessed. Area links (0x20–0x23) are left undecoded because the opcode list
103
+ doesn't say which bit is which area.
104
+
105
+ `PresetSelect`, `LinearPresetSelect` and `PresetReport` share the base class
106
+ `AreaPresetMessage`, so `isinstance(message, AreaPresetMessage)` catches "this
107
+ area is now at preset N" however it was sent.
108
+
109
+ `decode(packet)` returns the union type `AnyMessage`, so a `match` statement
110
+ ending in `assert_never` is checked for exhaustiveness by mypy.
111
+
112
+ ### Levels
113
+
114
+ DyNet levels run backwards on the wire (0x01 is 100 %, 0xFF is off). `Level`
115
+ keeps the raw byte, so it always round-trips, and converts for you:
116
+
117
+ ```python
118
+ Level.from_percent(40)
119
+ Level.from_fraction(0.4)
120
+ Level(0x80) # the raw byte
121
+ Level.OFF, Level.FULL
122
+ level.percent, level.fraction, level.is_off
123
+ ```
124
+
125
+ Messages accept only `Level`, never a bare number, so a percentage can't be
126
+ sent as a raw byte by mistake.
127
+
128
+ ### Fades
129
+
130
+ Fades are seconds as `float`, rounded to the nearest 20 ms step. A fade that a
131
+ message can't carry raises `ValueError` rather than being wrapped or clamped:
132
+ `SetChannelLevel` holds up to `MAX_CHANNEL_FADE` (5.1 s) and preset messages up
133
+ to `MAX_PRESET_FADE` (1310.7 s).
134
+
135
+ ## The client
136
+
137
+ ```python
138
+ client = DynetClient(host, port)
139
+ await client.connect() # raises DynetConnectionError if unreachable
140
+ ...
141
+ await client.close() # always safe, any number of times
142
+ ```
143
+
144
+ or `async with DynetClient(host, port) as client:`.
145
+
146
+ - **Connecting.** `connect` makes one attempt and raises if it fails, which
147
+ suits "not ready yet, try later" handling. After a successful connect the
148
+ client reconnects on its own after any drop, waiting 1 s at first and up to
149
+ 60 s between attempts, until you call `close`.
150
+ - **Receiving.** `subscribe(callback)` calls `callback(received)` in the event
151
+ loop for every packet, where `received.packet` is the raw packet and
152
+ `received.message` its decoded meaning. It returns an unsubscribe function.
153
+ A callback that raises is logged and doesn't affect the others.
154
+ - **Connection changes.** `subscribe_connection(callback)` reports drops
155
+ (`False`) and reconnects (`True`). `client.connected` gives the current
156
+ state.
157
+ - **Sending.** `await send(message_or_packet)` returns once the packet has been
158
+ written. Packets go out one at a time, 0.2 s apart by default
159
+ (`send_interval`). If the client isn't connected, or the connection drops
160
+ before the packet is written, `send` raises `NotConnectedError`. Nothing is
161
+ kept to send later, so a command can't fire long after it was asked for.
162
+ - **Queries.** `await query(RequestPreset(area=12))` sends the request and
163
+ returns the matching `PresetReport` (or `ChannelLevelReport` for a
164
+ `RequestChannelLevel`), or raises `TimeoutError`.
165
+ - **Closing.** `close` cancels everything the client started and closes the
166
+ socket. No callbacks run after it begins.
167
+ - **Dead gateways.** TCP keepalive is enabled (30 s idle, then 3 probes 10 s
168
+ apart where the OS supports it), so a gateway that vanishes on a quiet bus
169
+ is still noticed.
170
+
171
+ `check_connection(host, port)` opens and closes a TCP connection without
172
+ sending anything. It's meant for validating a host and port in a setup flow.
173
+
174
+ ## Testing your code
175
+
176
+ `aiodynet.testing.FakeGateway` is a real TCP server on localhost that records
177
+ what clients send and sends whatever you tell it to:
178
+
179
+ ```python
180
+ from aiodynet import DynetClient, PresetReport, RequestPreset
181
+ from aiodynet.testing import FakeGateway
182
+
183
+
184
+ def site(packet):
185
+ if packet == RequestPreset(area=1).to_packet():
186
+ return [PresetReport(area=1, preset=4)]
187
+ return []
188
+
189
+
190
+ async def test_area_one_is_off():
191
+ async with FakeGateway(replies=site) as gateway:
192
+ async with DynetClient(gateway.host, gateway.port) as client:
193
+ report = await client.query(RequestPreset(area=1))
194
+ assert report.preset == 4
195
+ ```
196
+
197
+ ## How well each claim is verified
198
+
199
+ DyNet documentation is thin, so this is the evidence for each encoding:
200
+
201
+ | Encoding | Source |
202
+ |---|---|
203
+ | Packet layout, checksum | DyNet 1 opcode list; every packet in the test fixtures |
204
+ | `PresetSelect` (banks, fade in 20 ms steps, low byte then high byte) | Opcode list, plus byte-for-byte match with the packets `dynalite-devices` 0.1.47 sends |
205
+ | `SetChannelLevel` (bank byte offset by one, fade in 20 ms steps) | Byte-for-byte match with `dynalite-devices` 0.1.47 |
206
+ | `RequestPreset`, `RequestChannelLevel` | Byte-for-byte match with `dynalite-devices` 0.1.47 |
207
+ | `PresetReport`, `LinearPresetSelect`, `ChannelLevelReport`, `FadeChannelToPreset` | Opcode list, plus the meaning `dynalite-devices` 0.1.47 takes from them. Not yet checked against captured traffic |
208
+ | `FadeChannelToPreset` fade unit | Unknown, so it's kept as a raw byte |
209
+ | `MotionActivitySync`, `UserPreferenceReport`, `ClockTime`, `ClockDate` | Opcode list, plus packets captured on a real site (`tests/fixtures/site-capture.jsonl`). The clock bytes are BCD, and the date packs the day of the week into the top three bits of the month byte; both inferred from that capture |
210
+ | All other extended messages | Byte layout from the opcode list only |
211
+
212
+ The `dynalite-devices` comparison was made black-box: by driving its public
213
+ API against a fake gateway and recording the bytes, without reading its source.
214
+ Those vectors are in `tests/test_messages.py`.
215
+
216
+ ## Porting from dynalite-devices
217
+
218
+ aiodynet replaces the bus layer of `dynalite-devices`. The mapping of areas
219
+ and channels to entities, and naming, stay in the integration. To keep existing
220
+ installs behaving the same:
221
+
222
+ - **Brightness.** `dynalite-devices` sends HA brightness `b` (0–255) as the raw
223
+ level `max(1, 255 - b)`, and reads it back as `255 - raw`. Use
224
+ `Level(max(1, 255 - b))` and `255 - level.raw`, not `from_fraction`, to keep
225
+ the same bytes.
226
+ - **Channel fades** longer than 5.1 s were clamped to 5.1 s. aiodynet raises
227
+ instead, so clamp with `min(fade, MAX_CHANNEL_FADE)` first.
228
+ - **Preset fades** longer than 1310.7 s crashed `dynalite-devices` while it
229
+ built the packet. aiodynet raises a clear `ValueError` at the call.
230
+ - **Pacing.** `dynalite-devices` spaced writes 0.2 s apart. That's the default
231
+ here too.
232
+ - **Queued writes.** `dynalite-devices` queued writes while disconnected.
233
+ aiodynet raises `NotConnectedError` instead. Decide in the integration
234
+ whether to surface it or retry.
235
+
236
+ ## Development
237
+
238
+ ```sh
239
+ uv sync
240
+ uv run pytest --cov # 100 % branch coverage is enforced
241
+ uv run ruff check && uv run ruff format --check
242
+ uv run mypy
243
+ ```
244
+
245
+ ## Licence
246
+
247
+ MIT. Not affiliated with or endorsed by Signify.
@@ -0,0 +1,101 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "aiodynet"
7
+ version = "0.1.0"
8
+ description = "Asyncio client for the Signify Dynalite DyNet lighting control bus"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Sam Dunster", email = "me@sdunster.com" }]
13
+ requires-python = ">=3.13"
14
+ dependencies = []
15
+ keywords = ["dynalite", "dynet", "signify", "lighting", "asyncio", "home-assistant"]
16
+ classifiers = [
17
+ "Development Status :: 3 - Alpha",
18
+ "Framework :: AsyncIO",
19
+ "Intended Audience :: Developers",
20
+ "Operating System :: OS Independent",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3 :: Only",
23
+ "Programming Language :: Python :: 3.13",
24
+ "Programming Language :: Python :: 3.14",
25
+ "Topic :: Home Automation",
26
+ "Typing :: Typed",
27
+ ]
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/sdunster/aiodynet"
31
+ Issues = "https://github.com/sdunster/aiodynet/issues"
32
+ Changelog = "https://github.com/sdunster/aiodynet/blob/main/CHANGELOG.md"
33
+
34
+ [dependency-groups]
35
+ dev = [
36
+ "hypothesis>=6.140",
37
+ "mypy>=2.4",
38
+ "pytest>=9.0",
39
+ "pytest-asyncio>=1.3",
40
+ "pytest-cov>=7.0",
41
+ "pytest-timeout>=2.4",
42
+ "ruff>=0.17",
43
+ ]
44
+
45
+ [tool.hatch.build.targets.sdist]
46
+ include = ["src", "tests", "CHANGELOG.md", "README.md", "LICENSE"]
47
+
48
+ [tool.pytest.ini_options]
49
+ addopts = ["--strict-markers", "--strict-config", "-ra", "--doctest-modules"]
50
+ asyncio_mode = "auto"
51
+ asyncio_default_fixture_loop_scope = "function"
52
+ asyncio_default_test_loop_scope = "function"
53
+ testpaths = ["tests", "src"]
54
+ xfail_strict = true
55
+ timeout = 30
56
+ filterwarnings = [
57
+ "error",
58
+ ]
59
+
60
+ [tool.coverage.run]
61
+ branch = true
62
+ source = ["aiodynet"]
63
+
64
+ [tool.coverage.report]
65
+ fail_under = 100
66
+ show_missing = true
67
+ skip_covered = true
68
+ exclude_also = [
69
+ "if TYPE_CHECKING:",
70
+ "@overload",
71
+ "raise AssertionError",
72
+ "assert_never\\(",
73
+ ]
74
+
75
+ [tool.mypy]
76
+ strict = true
77
+ python_version = "3.13"
78
+ warn_unreachable = true
79
+ enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool", "explicit-override"]
80
+ files = ["src", "tests"]
81
+
82
+ [tool.ruff]
83
+ target-version = "py313"
84
+ line-length = 88
85
+
86
+ [tool.ruff.lint]
87
+ select = ["ALL"]
88
+ ignore = [
89
+ "COM812", # conflicts with the formatter
90
+ "D203", # incompatible with D211
91
+ "D213", # incompatible with D212
92
+ "PLR2004", # magic values are the protocol
93
+ "CPY001", # the licence is in LICENSE
94
+ "ASYNC109", # network waits take an explicit timeout on purpose
95
+ ]
96
+
97
+ [tool.ruff.lint.per-file-ignores]
98
+ "tests/**" = ["D", "S101", "SLF001", "PLR0913", "FBT", "EM101", "TRY003", "SIM300"]
99
+
100
+ [tool.ruff.lint.pydocstyle]
101
+ convention = "pep257"