dynet-cli 0.1.0__tar.gz → 0.2.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 (28) hide show
  1. dynet_cli-0.2.0/CHANGELOG.md +68 -0
  2. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/PKG-INFO +65 -9
  3. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/README.md +63 -7
  4. dynet_cli-0.2.0/RELEASING.md +165 -0
  5. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/docs/capturing-traffic.md +3 -1
  6. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/pyproject.toml +2 -2
  7. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/src/dynet_cli/capture.py +74 -23
  8. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/src/dynet_cli/cli.py +279 -40
  9. dynet_cli-0.2.0/src/dynet_cli/probe.py +274 -0
  10. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/src/dynet_cli/render.py +109 -19
  11. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/src/dynet_cli/sniff.py +29 -11
  12. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/tests/test_capture_render.py +205 -14
  13. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/tests/test_cli.py +126 -1
  14. dynet_cli-0.2.0/tests/test_probe.py +214 -0
  15. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/tests/test_sniff.py +69 -21
  16. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/uv.lock +5 -5
  17. dynet_cli-0.1.0/CHANGELOG.md +0 -7
  18. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/.github/workflows/ci.yml +0 -0
  19. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/.github/workflows/release.yml +0 -0
  20. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/.gitignore +0 -0
  21. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/.pre-commit-config.yaml +0 -0
  22. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/.python-version +0 -0
  23. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/LICENSE +0 -0
  24. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/scripts/build-pyz +0 -0
  25. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/src/dynet_cli/__init__.py +0 -0
  26. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/src/dynet_cli/__main__.py +0 -0
  27. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/src/dynet_cli/py.typed +0 -0
  28. {dynet_cli-0.1.0 → dynet_cli-0.2.0}/tests/__init__.py +0 -0
@@ -0,0 +1,68 @@
1
+ # Changelog
2
+
3
+ ## Unreleased
4
+
5
+ Needs aiodynet 0.2.0.
6
+
7
+ - `monitor`, `decode` and `sniff` show and record DyNet 2 frames (sync byte
8
+ 0xAC) raw, as `{"dynet2": "<hex>"}` capture lines, instead of losing them as
9
+ noise. `decode --summary` lists them.
10
+ - New `probe` command: read-only requests of every kind (preset, channel
11
+ level, user preference, preset level, and with `--signon DEVICE:BOX,...`
12
+ a DyNet 2 sign-on request to each device), then a summary of anything that
13
+ didn't decode.
14
+ - DyNet 2 sign-on replies and sign-on requests are decoded everywhere, in
15
+ text and JSON. Frames go through the same output as packets: JSON lines
16
+ carry the decoded message's `type` and fields, and `decode --summary`
17
+ counts frames apart from packets and lists unknown ones under "Undecoded".
18
+ - New `exercise AREA` command: one of each harmless command to one area,
19
+ showing the replies, then the area's starting preset restored. Only a
20
+ dry run unless `--yes` is given.
21
+ - Describes aiodynet's newly decoded opcodes: area cascading sync, hold
22
+ timer and occupancy detection suspend/resume, program levels to preset,
23
+ Device Identify, Report Device Status and Request Firmware Version.
24
+ Temperature reports (preference 0x0C) read as °C, and physical packets
25
+ addressed to 0xAA/0x55 say "all devices".
26
+ - Nothing read from the gateway is dropped silently. Bytes that aren't part
27
+ of any packet or frame become `noise` events with their hex, in stream
28
+ order: in `sniff` (which used to keep only a byte count, after the
29
+ segment's packets), `monitor` (shown and recorded), `probe`, `exercise`,
30
+ and `decode` of raw hex. A partial packet cut off by a gap, a close or a
31
+ reconnect is kept as noise too, and `decode --summary` totals noise bytes.
32
+
33
+ ## 0.2.0 (2026-11-19)
34
+
35
+ Needs aiodynet 0.2.0.
36
+
37
+ - DyNet 2 (0xAC) frames are shown, decoded and recorded instead of being
38
+ lost as noise. Capture files get a `{"t", "dir", "dynet2": hex}` line for
39
+ each frame, and device sign-on replies decode to their address, firmware
40
+ version and packet sizes.
41
+ - New `probe` command: sends only requests (preset, channel level, user
42
+ preference, preset level) to the areas you name and prints every reply.
43
+ `--signon DEVICE:BOX,...` asks devices to sign on one at a time (`all`
44
+ broadcasts, which some sites ignore).
45
+ - New `exercise AREA` command: sends one of each harmless command to an
46
+ area, then restores its starting preset. Without `--yes` it only prints
47
+ the plan.
48
+ - Every byte from the gateway is kept. Bytes outside any packet or frame
49
+ are shown and recorded as `noise` events, with their `hex`, by `monitor`,
50
+ `sniff`, `probe`, `exercise` and `decode`, in stream order. That includes
51
+ partial packets cut off by a gap, close or reconnect. `decode --summary`
52
+ totals them.
53
+ - Describes the newly decoded opcodes: 0x09, 0x2F, 0x30, 0x31, 0x3A, 0x3B,
54
+ physical 0x00, 0x41 and 0x80, and temperature reports (preference 0x0C)
55
+ in °C.
56
+ - The physical address 0xAA/0x55 now prints as "all devices", including in
57
+ the clock broadcasts, which used to say "device 0xaa box 85".
58
+ - `decode --summary` counts DyNet 2 frames apart from packets and lists
59
+ undecoded packets and frames together under "Undecoded".
60
+
61
+ Capture files written by 0.1.0 read the same as before. A capture with
62
+ `dynet2` lines can't be read by 0.1.0.
63
+
64
+ ## 0.1.0 (2026-11-18)
65
+
66
+ First release: `check`, `monitor`, `preset`, `level`, `query`, `scan`, `send`,
67
+ `decode` and `sniff`, plus `scripts/build-pyz` for a single-file build, and
68
+ a guide to capturing traffic (`docs/capturing-traffic.md`).
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: dynet-cli
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: Command-line tool to watch, control and capture a Signify Dynalite DyNet bus
5
5
  Project-URL: Homepage, https://github.com/sdunster/dynet-cli
6
6
  Project-URL: Issues, https://github.com/sdunster/dynet-cli/issues
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.14
19
19
  Classifier: Topic :: Home Automation
20
20
  Classifier: Typing :: Typed
21
21
  Requires-Python: >=3.13
22
- Requires-Dist: aiodynet>=0.1.0
22
+ Requires-Dist: aiodynet>=0.2.0
23
23
  Description-Content-Type: text/markdown
24
24
 
25
25
  # dynet-cli
@@ -54,6 +54,8 @@ export DYNET_HOST=192.0.2.10 DYNET_PORT=50000
54
54
  | `dynet query preset AREA` | Asks an area for its current preset and waits for the answer | Yes (one request) |
55
55
  | `dynet query level AREA CHANNEL` | Asks a channel for its level | Yes (one request) |
56
56
  | `dynet scan` | Asks every area for its preset, to find the areas in use | Yes (one request per area) |
57
+ | `dynet probe` | Sends read-only requests of every kind and checks every reply decodes | Yes (several requests per area) |
58
+ | `dynet exercise AREA` | Sends one of each harmless command to one area and shows the replies | Yes, with `--yes`. Changes that area's lights |
57
59
  | `dynet send HEX...` | Sends raw packets (the checksum is added if you leave it off) | Yes |
58
60
  | `dynet decode [FILE]` | Decodes hex or a capture file. Needs no gateway | No |
59
61
  | `dynet sniff HOST:PORT` | Passively records another client's gateway traffic (Linux, root) | No |
@@ -67,9 +69,14 @@ $ dynet monitor
67
69
  -- watching 192.0.2.10:50000
68
70
  19:02:11.402 1c 0c 00 00 00 00 ff d9 area 12: select preset 1
69
71
  19:02:11.630 1c 0c 00 60 01 01 ff 77 area 12 channel 1: is at 100%
70
- 19:02:15.017 5c aa 55 53 18 71 26 a3 device 0xaa box 85: physical opcode 0x53 (not decoded)
72
+ 19:02:15.017 5c aa 55 53 18 71 26 a3 all devices: date is 2026-11-18 (day of week 3)
73
+ 19:02:16.250 ac 04 82 dc 00 5a aa 55 55 00 0c 00 00 00 00 00 00 00 43 c8 DyNet 2 frame, 20 bytes (not decoded)
71
74
  ```
72
75
 
76
+ DyNet 2 frames (sync byte `0xAC`, sent by some gateways after each connect and
77
+ by devices signing on) are shown raw, with their length. Sign-on replies are
78
+ decoded; aiodynet doesn't understand any other frame yet.
79
+
73
80
  - `--area 1-10,12` shows only those areas.
74
81
  - `--json` prints one JSON object per line.
75
82
  - `--record FILE` also appends every packet to a capture file.
@@ -94,6 +101,44 @@ the ones that answer. It sends one packet per area, 0.2 s apart, so a full
94
101
  scan takes about a minute. Some areas only answer for a channel they actually
95
102
  have, so try `--channel` if an area you know about stays silent.
96
103
 
104
+ ### Checking that everything decodes
105
+
106
+ A quiet bus only shows the traffic it happens to carry. These two commands
107
+ make devices talk, so you can check that aiodynet decodes all of it. Both
108
+ print each packet sent (`>`) and received (`<`), take `--record FILE`, and
109
+ end with the same summary as `decode --summary`.
110
+
111
+ `dynet probe` only asks questions. It asks each area in `--areas` (default
112
+ 1-255) for its preset, and each area that answers for its channel levels
113
+ (`--channels`, default 1), user preferences (`--preferences`, default 0x0c,
114
+ temperature) and preset levels (`--presets`, default 1). Pass `none` to skip
115
+ a kind. `--signon 0xb3:42,...` first asks each listed device (device code:box) to sign
116
+ on, with physical opcode 0x40 and sub-opcode 0x0a ("Do D2 Signon" in the DyNet
117
+ opcode list). Each device answers with a DyNet 2 sign-on reply giving its
118
+ firmware version and packet sizes, and probe moves on as soon as it arrives.
119
+ `--signon all` sends one request to every device (0xaa:0x55) instead, but some
120
+ sites have that turned off, and then nothing answers. The device codes and
121
+ boxes on your bus show up in `monitor` as physical packets, for example a
122
+ Device Identify (`5c b3 2a 00 ...` is device 0xb3, box 42).
123
+
124
+ ```console
125
+ $ dynet probe --areas 19 --signon 0xb3:42
126
+ 19:40:01.120 > 5c b3 2a 40 00 00 0a 7d device 0xb3 box 42: sign on
127
+ 19:40:01.173 < ac 04 81 b3 00 2a aa 55 55 01 00 00 02 11 1f 1f 00 00 3f b4 device 0xb3 box 42: signed on to all devices, firmware 02.11, max rx 128 / tx 128 bytes, port 0, slave 0
128
+ 19:40:06.130 > 1c 13 00 63 00 00 ff 6f area 19: which preset? (channel 1)
129
+ 19:40:06.190 < 1c 13 00 62 00 00 ff 70 area 19: is at preset 1
130
+ ...
131
+ -- 1 area(s) answered; sent 5 request(s), 4 answered
132
+ ```
133
+
134
+ `dynet exercise AREA` sends one of each harmless command aiodynet can build
135
+ to one area: preset selects, channel levels and fades, on and off, stop fade,
136
+ level up and down, and area off. Then it puts the area back on the preset it
137
+ started on. It never programs or saves presets, disables panels, panics,
138
+ writes user preferences or sends physical messages. It changes the area's
139
+ lights, so pick an area that's safe to play with. Without `--yes` it only
140
+ prints what it would send.
141
+
97
142
  ### Capturing traffic
98
143
 
99
144
  There are two ways to record traffic to a file:
@@ -108,9 +153,17 @@ There are two ways to record traffic to a file:
108
153
 
109
154
  [Capturing DyNet traffic](https://github.com/sdunster/dynet-cli/blob/main/docs/capturing-traffic.md) covers both step by
110
155
  step, including running a capture for a day under systemd. Each line of the file is one packet (`{"t": ..., "dir": "rx"|"tx", "hex":
111
- ...}`) or one event (`connect`, `close`, `reset`, `gap`, `noise`). TCP is put
112
- back in order first: keepalive probes and retransmits are dropped, and lost
113
- data shows up as a `gap` rather than as a bogus packet.
156
+ ...}`), one DyNet 2 frame (the same, with its hex under `dynet2`), or one event
157
+ (`connect`, `close`, `reset`, `gap`, `noise`). TCP is put back in order
158
+ first: keepalive probes and retransmits are dropped, and lost data shows up as
159
+ a `gap` rather than as a bogus packet.
160
+
161
+ Nothing read from the gateway is dropped silently. Bytes that aren't part of
162
+ any packet or frame are written as a `noise` event, in stream order, with the
163
+ bytes themselves as `hex`. That includes a partial packet cut off by a gap, a
164
+ closed connection or a reconnect. `sniff`, `monitor --record`, `probe` and
165
+ `exercise` all record noise, `monitor` shows it as it arrives, and `decode`
166
+ reports it for raw hex streams too. `decode --summary` totals it.
114
167
 
115
168
  ### Checking a capture
116
169
 
@@ -124,12 +177,13 @@ By type:
124
177
  1 PresetReport
125
178
  1 Unknown physical 0x53
126
179
  Areas: 12 (3)
127
- Undecoded packets (1 distinct):
180
+ Undecoded (1 distinct):
128
181
  1 5caa5553187126a3
129
182
  ```
130
183
 
131
- The "Undecoded packets" list shows everything aiodynet doesn't yet have a
132
- typed message for. Without `--summary`, `decode` prints each packet the same
184
+ The "Undecoded" list shows every packet and DyNet 2 frame aiodynet doesn't
185
+ yet have a typed message for. DyNet 2 frames are counted apart from packets
186
+ in the first line. Without `--summary`, `decode` prints each packet the same
133
187
  way `monitor` does, or as JSON with `--json`.
134
188
 
135
189
  ## Exit codes
@@ -149,6 +203,8 @@ uv run pytest --cov # 100 % branch coverage is enforced
149
203
  uv run ruff check && uv run ruff format --check && uv run mypy
150
204
  ```
151
205
 
206
+ To cut a release, see [RELEASING.md](https://github.com/sdunster/dynet-cli/blob/main/RELEASING.md).
207
+
152
208
  ## Licence
153
209
 
154
210
  MIT. Not affiliated with or endorsed by Signify.
@@ -30,6 +30,8 @@ export DYNET_HOST=192.0.2.10 DYNET_PORT=50000
30
30
  | `dynet query preset AREA` | Asks an area for its current preset and waits for the answer | Yes (one request) |
31
31
  | `dynet query level AREA CHANNEL` | Asks a channel for its level | Yes (one request) |
32
32
  | `dynet scan` | Asks every area for its preset, to find the areas in use | Yes (one request per area) |
33
+ | `dynet probe` | Sends read-only requests of every kind and checks every reply decodes | Yes (several requests per area) |
34
+ | `dynet exercise AREA` | Sends one of each harmless command to one area and shows the replies | Yes, with `--yes`. Changes that area's lights |
33
35
  | `dynet send HEX...` | Sends raw packets (the checksum is added if you leave it off) | Yes |
34
36
  | `dynet decode [FILE]` | Decodes hex or a capture file. Needs no gateway | No |
35
37
  | `dynet sniff HOST:PORT` | Passively records another client's gateway traffic (Linux, root) | No |
@@ -43,9 +45,14 @@ $ dynet monitor
43
45
  -- watching 192.0.2.10:50000
44
46
  19:02:11.402 1c 0c 00 00 00 00 ff d9 area 12: select preset 1
45
47
  19:02:11.630 1c 0c 00 60 01 01 ff 77 area 12 channel 1: is at 100%
46
- 19:02:15.017 5c aa 55 53 18 71 26 a3 device 0xaa box 85: physical opcode 0x53 (not decoded)
48
+ 19:02:15.017 5c aa 55 53 18 71 26 a3 all devices: date is 2026-11-18 (day of week 3)
49
+ 19:02:16.250 ac 04 82 dc 00 5a aa 55 55 00 0c 00 00 00 00 00 00 00 43 c8 DyNet 2 frame, 20 bytes (not decoded)
47
50
  ```
48
51
 
52
+ DyNet 2 frames (sync byte `0xAC`, sent by some gateways after each connect and
53
+ by devices signing on) are shown raw, with their length. Sign-on replies are
54
+ decoded; aiodynet doesn't understand any other frame yet.
55
+
49
56
  - `--area 1-10,12` shows only those areas.
50
57
  - `--json` prints one JSON object per line.
51
58
  - `--record FILE` also appends every packet to a capture file.
@@ -70,6 +77,44 @@ the ones that answer. It sends one packet per area, 0.2 s apart, so a full
70
77
  scan takes about a minute. Some areas only answer for a channel they actually
71
78
  have, so try `--channel` if an area you know about stays silent.
72
79
 
80
+ ### Checking that everything decodes
81
+
82
+ A quiet bus only shows the traffic it happens to carry. These two commands
83
+ make devices talk, so you can check that aiodynet decodes all of it. Both
84
+ print each packet sent (`>`) and received (`<`), take `--record FILE`, and
85
+ end with the same summary as `decode --summary`.
86
+
87
+ `dynet probe` only asks questions. It asks each area in `--areas` (default
88
+ 1-255) for its preset, and each area that answers for its channel levels
89
+ (`--channels`, default 1), user preferences (`--preferences`, default 0x0c,
90
+ temperature) and preset levels (`--presets`, default 1). Pass `none` to skip
91
+ a kind. `--signon 0xb3:42,...` first asks each listed device (device code:box) to sign
92
+ on, with physical opcode 0x40 and sub-opcode 0x0a ("Do D2 Signon" in the DyNet
93
+ opcode list). Each device answers with a DyNet 2 sign-on reply giving its
94
+ firmware version and packet sizes, and probe moves on as soon as it arrives.
95
+ `--signon all` sends one request to every device (0xaa:0x55) instead, but some
96
+ sites have that turned off, and then nothing answers. The device codes and
97
+ boxes on your bus show up in `monitor` as physical packets, for example a
98
+ Device Identify (`5c b3 2a 00 ...` is device 0xb3, box 42).
99
+
100
+ ```console
101
+ $ dynet probe --areas 19 --signon 0xb3:42
102
+ 19:40:01.120 > 5c b3 2a 40 00 00 0a 7d device 0xb3 box 42: sign on
103
+ 19:40:01.173 < ac 04 81 b3 00 2a aa 55 55 01 00 00 02 11 1f 1f 00 00 3f b4 device 0xb3 box 42: signed on to all devices, firmware 02.11, max rx 128 / tx 128 bytes, port 0, slave 0
104
+ 19:40:06.130 > 1c 13 00 63 00 00 ff 6f area 19: which preset? (channel 1)
105
+ 19:40:06.190 < 1c 13 00 62 00 00 ff 70 area 19: is at preset 1
106
+ ...
107
+ -- 1 area(s) answered; sent 5 request(s), 4 answered
108
+ ```
109
+
110
+ `dynet exercise AREA` sends one of each harmless command aiodynet can build
111
+ to one area: preset selects, channel levels and fades, on and off, stop fade,
112
+ level up and down, and area off. Then it puts the area back on the preset it
113
+ started on. It never programs or saves presets, disables panels, panics,
114
+ writes user preferences or sends physical messages. It changes the area's
115
+ lights, so pick an area that's safe to play with. Without `--yes` it only
116
+ prints what it would send.
117
+
73
118
  ### Capturing traffic
74
119
 
75
120
  There are two ways to record traffic to a file:
@@ -84,9 +129,17 @@ There are two ways to record traffic to a file:
84
129
 
85
130
  [Capturing DyNet traffic](https://github.com/sdunster/dynet-cli/blob/main/docs/capturing-traffic.md) covers both step by
86
131
  step, including running a capture for a day under systemd. Each line of the file is one packet (`{"t": ..., "dir": "rx"|"tx", "hex":
87
- ...}`) or one event (`connect`, `close`, `reset`, `gap`, `noise`). TCP is put
88
- back in order first: keepalive probes and retransmits are dropped, and lost
89
- data shows up as a `gap` rather than as a bogus packet.
132
+ ...}`), one DyNet 2 frame (the same, with its hex under `dynet2`), or one event
133
+ (`connect`, `close`, `reset`, `gap`, `noise`). TCP is put back in order
134
+ first: keepalive probes and retransmits are dropped, and lost data shows up as
135
+ a `gap` rather than as a bogus packet.
136
+
137
+ Nothing read from the gateway is dropped silently. Bytes that aren't part of
138
+ any packet or frame are written as a `noise` event, in stream order, with the
139
+ bytes themselves as `hex`. That includes a partial packet cut off by a gap, a
140
+ closed connection or a reconnect. `sniff`, `monitor --record`, `probe` and
141
+ `exercise` all record noise, `monitor` shows it as it arrives, and `decode`
142
+ reports it for raw hex streams too. `decode --summary` totals it.
90
143
 
91
144
  ### Checking a capture
92
145
 
@@ -100,12 +153,13 @@ By type:
100
153
  1 PresetReport
101
154
  1 Unknown physical 0x53
102
155
  Areas: 12 (3)
103
- Undecoded packets (1 distinct):
156
+ Undecoded (1 distinct):
104
157
  1 5caa5553187126a3
105
158
  ```
106
159
 
107
- The "Undecoded packets" list shows everything aiodynet doesn't yet have a
108
- typed message for. Without `--summary`, `decode` prints each packet the same
160
+ The "Undecoded" list shows every packet and DyNet 2 frame aiodynet doesn't
161
+ yet have a typed message for. DyNet 2 frames are counted apart from packets
162
+ in the first line. Without `--summary`, `decode` prints each packet the same
109
163
  way `monitor` does, or as JSON with `--json`.
110
164
 
111
165
  ## Exit codes
@@ -125,6 +179,8 @@ uv run pytest --cov # 100 % branch coverage is enforced
125
179
  uv run ruff check && uv run ruff format --check && uv run mypy
126
180
  ```
127
181
 
182
+ To cut a release, see [RELEASING.md](https://github.com/sdunster/dynet-cli/blob/main/RELEASING.md).
183
+
128
184
  ## Licence
129
185
 
130
186
  MIT. Not affiliated with or endorsed by Signify.
@@ -0,0 +1,165 @@
1
+ # Releasing dynet-cli
2
+
3
+ Releases go to [PyPI](https://pypi.org/project/dynet-cli/) from GitHub
4
+ Actions, using PyPI trusted publishing: no API token is stored anywhere.
5
+ Publishing a GitHub release whose tag is `vX.Y.Z` does everything else,
6
+ including attaching a single-file `dynet.pyz` to the release.
7
+
8
+ ## Choosing the version
9
+
10
+ dynet-cli follows [semantic versioning](https://semver.org/). Its "API" is
11
+ what scripts and people rely on: command names, options, exit codes, the JSON
12
+ output, and the capture file format. Before 1.0:
13
+
14
+ - **Patch** (`0.1.0` → `0.1.1`): bug fixes, new options or commands, and
15
+ describing more message types.
16
+ - **Minor** (`0.1.0` → `0.2.0`): renaming or removing a command or option,
17
+ changing exit codes, or changing the JSON output or capture file format in
18
+ a way that breaks existing readers.
19
+
20
+ Capture files people have already sent in must stay readable by
21
+ `dynet decode`.
22
+
23
+ ## If it needs a new aiodynet
24
+
25
+ dynet-cli installs aiodynet from PyPI. If this release needs features from an
26
+ aiodynet release:
27
+
28
+ 1. Release aiodynet first (see its `RELEASING.md`), and wait until
29
+ <https://pypi.org/project/aiodynet/> shows the new version.
30
+ 2. Raise the requirement in `pyproject.toml` (for example
31
+ `"aiodynet>=0.2.0"`), then update the lockfile:
32
+
33
+ ```sh
34
+ uv lock --upgrade-package aiodynet
35
+ uv sync && uv run pytest
36
+ ```
37
+
38
+ ## Steps
39
+
40
+ 1. **Start from a green `main`.** Check that the latest CI run on `main`
41
+ passed:
42
+
43
+ ```sh
44
+ git switch main && git pull
45
+ gh run list --branch main --limit 1
46
+ ```
47
+
48
+ 2. **Bump the version.** This updates both `pyproject.toml` and `uv.lock`:
49
+
50
+ ```sh
51
+ uv version --bump patch # or: minor, major, or an exact version
52
+ ```
53
+
54
+ 3. **Update `CHANGELOG.md`.** Add a section at the top in this form:
55
+
56
+ ```markdown
57
+ ## 0.1.1 (2026-12-01)
58
+
59
+ - What changed, written for people using the tool.
60
+ ```
61
+
62
+ 4. **Commit and push**, then wait for CI to pass on that commit:
63
+
64
+ ```sh
65
+ git commit -am "Release 0.1.1"
66
+ git push
67
+ gh run watch "$(gh run list --branch main --limit 1 --json databaseId -q '.[0].databaseId')"
68
+ ```
69
+
70
+ 5. **Publish the GitHub release.** The tag must be `v` plus the exact
71
+ version in `pyproject.toml`:
72
+
73
+ ```sh
74
+ gh release create v0.1.1 --target main --title "dynet-cli 0.1.1" \
75
+ --notes "Short summary; see CHANGELOG.md."
76
+ ```
77
+
78
+ Or use *Releases → Draft a new release* on GitHub, create the tag
79
+ `v0.1.1` on `main`, and click *Publish release*. Saving a draft doesn't
80
+ start anything; only publishing does.
81
+
82
+ 6. **Watch the release workflow** until it succeeds:
83
+
84
+ ```sh
85
+ gh run watch "$(gh run list --workflow release.yml --limit 1 --json databaseId -q '.[0].databaseId')"
86
+ ```
87
+
88
+ 7. **Check the result.** Install it the way the capture guide tells people
89
+ to, from a clean environment:
90
+
91
+ ```sh
92
+ uv tool run --isolated --no-cache --from dynet-cli==0.1.1 dynet --version
93
+ curl -sLO https://github.com/sdunster/dynet-cli/releases/latest/download/dynet.pyz
94
+ python3 dynet.pyz --version
95
+ ```
96
+
97
+ The GitHub release should have the wheel, sdist and `dynet.pyz` attached.
98
+
99
+ ## What the release workflow does
100
+
101
+ [`.github/workflows/release.yml`](.github/workflows/release.yml) runs when a
102
+ release is *published*. In order, it:
103
+
104
+ 1. fails unless the tag is exactly `v` plus the version in `pyproject.toml`;
105
+ 2. installs from the lockfile (`uv sync --locked`) and runs the tests;
106
+ 3. builds the sdist and wheel, and checks them with `twine check --strict`;
107
+ 4. publishes to PyPI with trusted publishing (`uv publish --trusted-publishing always`);
108
+ 5. builds `dynet.pyz` with `scripts/build-pyz`, which takes aiodynet from PyPI;
109
+ 6. attaches the sdist, wheel and `dynet.pyz` to the GitHub release.
110
+
111
+ The job runs in the `pypi` GitHub environment, which only accepts tags
112
+ matching `v*`. A workflow run from a branch can't publish.
113
+
114
+ The capture guide links to
115
+ `releases/latest/download/dynet.pyz`, so every release must have a
116
+ `dynet.pyz` attached, or that link breaks.
117
+
118
+ ## When something goes wrong
119
+
120
+ - **The workflow fails before "publish"** (wrong tag, a failing test, a bad
121
+ build). Nothing reached PyPI. Fix the problem on `main`, then delete the
122
+ release and its tag and create them again:
123
+
124
+ ```sh
125
+ gh release delete v0.1.1 --cleanup-tag --yes
126
+ ```
127
+
128
+ - **Publishing fails with a trusted-publishing error.** The PyPI side of the
129
+ setup is missing or wrong; see [Trusted publisher](#trusted-publisher)
130
+ below. Fix it on PyPI, then re-run the failed job
131
+ (`gh run rerun <run-id> --failed`).
132
+
133
+ - **PyPI has the release but building or attaching `dynet.pyz` failed.**
134
+ Don't re-run the job, because PyPI rejects a second upload of the same
135
+ version. Build locally from the tag and attach the files by hand:
136
+
137
+ ```sh
138
+ git switch --detach v0.1.1
139
+ rm -rf dist && uv build && mkdir -p release-files && mv dist/* release-files/
140
+ scripts/build-pyz && mv dist/dynet.pyz release-files/
141
+ gh release upload v0.1.1 release-files/* --clobber
142
+ git switch main && rm -rf release-files
143
+ ```
144
+
145
+ - **A broken version reached PyPI.** A version number can never be uploaded
146
+ twice, even after deleting it. Release a fixed patch version. If the broken
147
+ one is harmful, also *yank* it on PyPI (project → *Manage* → *Releases* →
148
+ *Options* → *Yank*), which hides it from new installs without breaking
149
+ existing pins.
150
+
151
+ ## Trusted publisher
152
+
153
+ PyPI accepts uploads from this repository through a trusted publisher. If it
154
+ ever needs recreating, it's under *dynet-cli → Manage → Publishing* on PyPI,
155
+ with these settings:
156
+
157
+ | Field | Value |
158
+ |---|---|
159
+ | Owner | `sdunster` |
160
+ | Repository name | `dynet-cli` |
161
+ | Workflow name | `release.yml` |
162
+ | Environment name | `pypi` |
163
+
164
+ The GitHub side is the `pypi` environment in *Settings → Environments*. Its
165
+ deployment rule allows only tags matching `v*`.
@@ -11,7 +11,9 @@ It takes about ten minutes to set up, then runs on its own.
11
11
  ## What gets recorded, and what doesn't
12
12
 
13
13
  The capture holds one line per DyNet packet: the time, the direction (from or
14
- to the gateway), and the eight bytes of the packet. From those, anyone can see:
14
+ to the gateway), and the bytes of the packet. Newer gateways also send longer
15
+ DyNet 2 frames, which are recorded the same way, and any bytes that don't form
16
+ a packet are kept as `noise` lines, so nothing the gateway sends is left out. From those, anyone can see:
15
17
 
16
18
  - area, channel and preset numbers, and channel levels;
17
19
  - *when* things happened: when lights went on, keypads were pressed or
@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "dynet-cli"
7
- version = "0.1.0"
7
+ version = "0.2.0"
8
8
  description = "Command-line tool to watch, control and capture a Signify Dynalite DyNet bus"
9
9
  readme = "README.md"
10
10
  license = "MIT"
11
11
  license-files = ["LICENSE"]
12
12
  authors = [{ name = "Sam Dunster", email = "me@sdunster.com" }]
13
13
  requires-python = ">=3.13"
14
- dependencies = ["aiodynet>=0.1.0"]
14
+ dependencies = ["aiodynet>=0.2.0"]
15
15
  keywords = ["dynalite", "dynet", "signify", "lighting", "cli"]
16
16
  classifiers = [
17
17
  "Development Status :: 3 - Alpha",