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.
- aiodynet-0.1.0/.gitignore +15 -0
- aiodynet-0.1.0/CHANGELOG.md +20 -0
- aiodynet-0.1.0/LICENSE +21 -0
- aiodynet-0.1.0/PKG-INFO +271 -0
- aiodynet-0.1.0/README.md +247 -0
- aiodynet-0.1.0/pyproject.toml +101 -0
- aiodynet-0.1.0/src/aiodynet/__init__.py +123 -0
- aiodynet-0.1.0/src/aiodynet/client.py +416 -0
- aiodynet-0.1.0/src/aiodynet/errors.py +22 -0
- aiodynet-0.1.0/src/aiodynet/framing.py +72 -0
- aiodynet-0.1.0/src/aiodynet/messages.py +1279 -0
- aiodynet-0.1.0/src/aiodynet/packet.py +156 -0
- aiodynet-0.1.0/src/aiodynet/py.typed +0 -0
- aiodynet-0.1.0/src/aiodynet/testing.py +174 -0
- aiodynet-0.1.0/src/aiodynet/values.py +116 -0
- aiodynet-0.1.0/tests/__init__.py +0 -0
- aiodynet-0.1.0/tests/conftest.py +36 -0
- aiodynet-0.1.0/tests/fixtures/site-capture.jsonl +60 -0
- aiodynet-0.1.0/tests/test_client.py +592 -0
- aiodynet-0.1.0/tests/test_framing.py +93 -0
- aiodynet-0.1.0/tests/test_messages.py +370 -0
- aiodynet-0.1.0/tests/test_messages_extended.py +347 -0
- aiodynet-0.1.0/tests/test_packet.py +116 -0
- aiodynet-0.1.0/tests/test_testing.py +136 -0
- aiodynet-0.1.0/tests/test_values.py +111 -0
|
@@ -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.
|
aiodynet-0.1.0/PKG-INFO
ADDED
|
@@ -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.
|
aiodynet-0.1.0/README.md
ADDED
|
@@ -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"
|