dynet-cli 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,46 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ lint:
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - uses: actions/checkout@v7
16
+ - uses: astral-sh/setup-uv@v10.3.3
17
+ - run: uv sync --locked
18
+ - run: uv run ruff format --check
19
+ - run: uv run ruff check
20
+ - run: uv run mypy
21
+
22
+ test:
23
+ runs-on: ${{ matrix.os }}
24
+ strategy:
25
+ fail-fast: false
26
+ matrix:
27
+ os: [ubuntu-latest, macos-latest]
28
+ python: ["3.13", "3.14"]
29
+ steps:
30
+ - uses: actions/checkout@v7
31
+ - uses: astral-sh/setup-uv@v10.3.3
32
+ with:
33
+ python-version: ${{ matrix.python }}
34
+ - run: uv sync --locked
35
+ - run: uv run pytest --cov --cov-report=term-missing
36
+
37
+ build:
38
+ runs-on: ubuntu-latest
39
+ steps:
40
+ - uses: actions/checkout@v7
41
+ - uses: astral-sh/setup-uv@v10.3.3
42
+ - run: uv build
43
+ - uses: actions/upload-artifact@v7
44
+ with:
45
+ name: dist
46
+ path: dist/
@@ -0,0 +1,36 @@
1
+ name: Release
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ jobs:
8
+ publish:
9
+ runs-on: ubuntu-latest
10
+ environment: pypi
11
+ permissions:
12
+ id-token: write # PyPI trusted publishing, no API token stored
13
+ contents: write # attach the built files to the GitHub release
14
+ steps:
15
+ - uses: actions/checkout@v7
16
+ - uses: astral-sh/setup-uv@v10.3.3
17
+ - name: Check the tag matches the package version
18
+ run: |
19
+ version=$(uv version --short)
20
+ test "v${version}" = "${GITHUB_REF_NAME}" || {
21
+ echo "Tag ${GITHUB_REF_NAME} does not match version ${version}"; exit 1; }
22
+ - run: uv sync --locked
23
+ - run: uv run pytest
24
+ - run: uv build
25
+ - run: uvx twine check --strict dist/*
26
+ - run: uv publish --trusted-publishing always
27
+ - name: Build the single-file dynet.pyz
28
+ run: |
29
+ mkdir -p pyz-out
30
+ mv dist pypi-dist
31
+ scripts/build-pyz
32
+ mv dist/dynet.pyz pyz-out/
33
+ - name: Attach the files to the GitHub release
34
+ env:
35
+ GH_TOKEN: ${{ github.token }}
36
+ run: gh release upload "${GITHUB_REF_NAME}" pypi-dist/* pyz-out/dynet.pyz
@@ -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,22 @@
1
+ repos:
2
+ - repo: https://github.com/astral-sh/ruff-pre-commit
3
+ rev: v0.17.5
4
+ hooks:
5
+ - id: ruff-check
6
+ args: [--fix]
7
+ - id: ruff-format
8
+ - repo: https://github.com/pre-commit/pre-commit-hooks
9
+ rev: v6.0.0
10
+ hooks:
11
+ - id: check-toml
12
+ - id: check-yaml
13
+ - id: end-of-file-fixer
14
+ - id: trailing-whitespace
15
+ - repo: local
16
+ hooks:
17
+ - id: mypy
18
+ name: mypy
19
+ entry: uv run mypy
20
+ language: system
21
+ types: [python]
22
+ pass_filenames: false
@@ -0,0 +1 @@
1
+ 3.13
@@ -0,0 +1,7 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (2026-11-18)
4
+
5
+ First release: `check`, `monitor`, `preset`, `level`, `query`, `scan`, `send`,
6
+ `decode` and `sniff`, plus `scripts/build-pyz` for a single-file build, and
7
+ a guide to capturing traffic (`docs/capturing-traffic.md`).
@@ -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,154 @@
1
+ Metadata-Version: 2.5
2
+ Name: dynet-cli
3
+ Version: 0.1.0
4
+ Summary: Command-line tool to watch, control and capture a Signify Dynalite DyNet bus
5
+ Project-URL: Homepage, https://github.com/sdunster/dynet-cli
6
+ Project-URL: Issues, https://github.com/sdunster/dynet-cli/issues
7
+ Author-email: Sam Dunster <me@sdunster.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: cli,dynalite,dynet,lighting,signify
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: End Users/Desktop
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Home Automation
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.13
22
+ Requires-Dist: aiodynet>=0.1.0
23
+ Description-Content-Type: text/markdown
24
+
25
+ # dynet-cli
26
+
27
+ `dynet` is a command-line tool for the Signify Dynalite **DyNet** bus: watch
28
+ traffic, recall presets, set channel levels, query state, discover areas, and
29
+ capture or decode traffic for later analysis. It is built on
30
+ [aiodynet](https://github.com/sdunster/aiodynet) and doubles as a worked
31
+ example of that library.
32
+
33
+ Requires Python 3.13 or newer. Install it with
34
+ [uv](https://docs.astral.sh/uv/), which also fetches a suitable Python if
35
+ needed, or with pipx:
36
+
37
+ ```sh
38
+ uv tool install dynet-cli # or: pipx install dynet-cli
39
+ export DYNET_HOST=192.0.2.10 DYNET_PORT=50000
40
+ ```
41
+
42
+ > **Asked to capture traffic from your system?** Follow
43
+ > [Capturing DyNet traffic](https://github.com/sdunster/dynet-cli/blob/main/docs/capturing-traffic.md). It walks through
44
+ > recording a day of traffic and sending it in.
45
+
46
+ ## Commands
47
+
48
+ | Command | What it does | Sends to the bus? |
49
+ |---|---|---|
50
+ | `dynet check` | Checks the gateway accepts TCP connections | No |
51
+ | `dynet monitor` | Shows bus traffic as it happens, decoded | No |
52
+ | `dynet preset AREA PRESET` | Selects a preset | Yes |
53
+ | `dynet level AREA CHANNEL LEVEL` | Fades a channel to a level | Yes |
54
+ | `dynet query preset AREA` | Asks an area for its current preset and waits for the answer | Yes (one request) |
55
+ | `dynet query level AREA CHANNEL` | Asks a channel for its level | Yes (one request) |
56
+ | `dynet scan` | Asks every area for its preset, to find the areas in use | Yes (one request per area) |
57
+ | `dynet send HEX...` | Sends raw packets (the checksum is added if you leave it off) | Yes |
58
+ | `dynet decode [FILE]` | Decodes hex or a capture file. Needs no gateway | No |
59
+ | `dynet sniff HOST:PORT` | Passively records another client's gateway traffic (Linux, root) | No |
60
+
61
+ Run `dynet COMMAND --help` for every option.
62
+
63
+ ### Watching the bus
64
+
65
+ ```console
66
+ $ dynet monitor
67
+ -- watching 192.0.2.10:50000
68
+ 19:02:11.402 1c 0c 00 00 00 00 ff d9 area 12: select preset 1
69
+ 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)
71
+ ```
72
+
73
+ - `--area 1-10,12` shows only those areas.
74
+ - `--json` prints one JSON object per line.
75
+ - `--record FILE` also appends every packet to a capture file.
76
+ - `--duration SECONDS` stops after that long.
77
+
78
+ ### Control
79
+
80
+ ```sh
81
+ dynet preset 12 1 --fade 2 # area 12, preset 1, 2 s fade
82
+ dynet level 12 3 40% --fade 1 # area 12 channel 3 to 40 %
83
+ dynet level 12 3 off
84
+ dynet level 12 3 raw:0x80 # the raw DyNet level byte
85
+ ```
86
+
87
+ Out-of-range values are rejected before anything is sent. For example, a
88
+ channel fade is at most 5.1 s, which is all the packet can carry.
89
+
90
+ ### Finding your areas
91
+
92
+ `dynet scan --areas 1-255` asks each area for its current preset and lists
93
+ the ones that answer. It sends one packet per area, 0.2 s apart, so a full
94
+ scan takes about a minute. Some areas only answer for a channel they actually
95
+ have, so try `--channel` if an area you know about stays silent.
96
+
97
+ ### Capturing traffic
98
+
99
+ There are two ways to record traffic to a file:
100
+
101
+ - `dynet sniff GATEWAY:PORT -i IFACE` records the traffic between a gateway
102
+ and a client already connected to it, such as Home Assistant, from that
103
+ client's machine. It never connects to the gateway and never sends
104
+ anything. It needs Linux and root, because it reads raw frames from the
105
+ network interface.
106
+ - `dynet monitor --record FILE` records through its own connection to the
107
+ gateway, on any OS.
108
+
109
+ [Capturing DyNet traffic](https://github.com/sdunster/dynet-cli/blob/main/docs/capturing-traffic.md) covers both step by
110
+ 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.
114
+
115
+ ### Checking a capture
116
+
117
+ ```console
118
+ $ dynet decode --summary sample.jsonl
119
+ 4 packet(s) over 24.00 h
120
+ direction: rx 3, tx 1
121
+ By type:
122
+ 1 PresetSelect
123
+ 1 RequestPreset
124
+ 1 PresetReport
125
+ 1 Unknown physical 0x53
126
+ Areas: 12 (3)
127
+ Undecoded packets (1 distinct):
128
+ 1 5caa5553187126a3
129
+ ```
130
+
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
133
+ way `monitor` does, or as JSON with `--json`.
134
+
135
+ ## Exit codes
136
+
137
+ | Code | Meaning |
138
+ |---|---|
139
+ | 0 | Success |
140
+ | 1 | Gateway or file error |
141
+ | 2 | Bad arguments |
142
+ | 3 | `query` got no answer in time |
143
+
144
+ ## Development
145
+
146
+ ```sh
147
+ uv sync
148
+ uv run pytest --cov # 100 % branch coverage is enforced
149
+ uv run ruff check && uv run ruff format --check && uv run mypy
150
+ ```
151
+
152
+ ## Licence
153
+
154
+ MIT. Not affiliated with or endorsed by Signify.
@@ -0,0 +1,130 @@
1
+ # dynet-cli
2
+
3
+ `dynet` is a command-line tool for the Signify Dynalite **DyNet** bus: watch
4
+ traffic, recall presets, set channel levels, query state, discover areas, and
5
+ capture or decode traffic for later analysis. It is built on
6
+ [aiodynet](https://github.com/sdunster/aiodynet) and doubles as a worked
7
+ example of that library.
8
+
9
+ Requires Python 3.13 or newer. Install it with
10
+ [uv](https://docs.astral.sh/uv/), which also fetches a suitable Python if
11
+ needed, or with pipx:
12
+
13
+ ```sh
14
+ uv tool install dynet-cli # or: pipx install dynet-cli
15
+ export DYNET_HOST=192.0.2.10 DYNET_PORT=50000
16
+ ```
17
+
18
+ > **Asked to capture traffic from your system?** Follow
19
+ > [Capturing DyNet traffic](https://github.com/sdunster/dynet-cli/blob/main/docs/capturing-traffic.md). It walks through
20
+ > recording a day of traffic and sending it in.
21
+
22
+ ## Commands
23
+
24
+ | Command | What it does | Sends to the bus? |
25
+ |---|---|---|
26
+ | `dynet check` | Checks the gateway accepts TCP connections | No |
27
+ | `dynet monitor` | Shows bus traffic as it happens, decoded | No |
28
+ | `dynet preset AREA PRESET` | Selects a preset | Yes |
29
+ | `dynet level AREA CHANNEL LEVEL` | Fades a channel to a level | Yes |
30
+ | `dynet query preset AREA` | Asks an area for its current preset and waits for the answer | Yes (one request) |
31
+ | `dynet query level AREA CHANNEL` | Asks a channel for its level | Yes (one request) |
32
+ | `dynet scan` | Asks every area for its preset, to find the areas in use | Yes (one request per area) |
33
+ | `dynet send HEX...` | Sends raw packets (the checksum is added if you leave it off) | Yes |
34
+ | `dynet decode [FILE]` | Decodes hex or a capture file. Needs no gateway | No |
35
+ | `dynet sniff HOST:PORT` | Passively records another client's gateway traffic (Linux, root) | No |
36
+
37
+ Run `dynet COMMAND --help` for every option.
38
+
39
+ ### Watching the bus
40
+
41
+ ```console
42
+ $ dynet monitor
43
+ -- watching 192.0.2.10:50000
44
+ 19:02:11.402 1c 0c 00 00 00 00 ff d9 area 12: select preset 1
45
+ 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)
47
+ ```
48
+
49
+ - `--area 1-10,12` shows only those areas.
50
+ - `--json` prints one JSON object per line.
51
+ - `--record FILE` also appends every packet to a capture file.
52
+ - `--duration SECONDS` stops after that long.
53
+
54
+ ### Control
55
+
56
+ ```sh
57
+ dynet preset 12 1 --fade 2 # area 12, preset 1, 2 s fade
58
+ dynet level 12 3 40% --fade 1 # area 12 channel 3 to 40 %
59
+ dynet level 12 3 off
60
+ dynet level 12 3 raw:0x80 # the raw DyNet level byte
61
+ ```
62
+
63
+ Out-of-range values are rejected before anything is sent. For example, a
64
+ channel fade is at most 5.1 s, which is all the packet can carry.
65
+
66
+ ### Finding your areas
67
+
68
+ `dynet scan --areas 1-255` asks each area for its current preset and lists
69
+ the ones that answer. It sends one packet per area, 0.2 s apart, so a full
70
+ scan takes about a minute. Some areas only answer for a channel they actually
71
+ have, so try `--channel` if an area you know about stays silent.
72
+
73
+ ### Capturing traffic
74
+
75
+ There are two ways to record traffic to a file:
76
+
77
+ - `dynet sniff GATEWAY:PORT -i IFACE` records the traffic between a gateway
78
+ and a client already connected to it, such as Home Assistant, from that
79
+ client's machine. It never connects to the gateway and never sends
80
+ anything. It needs Linux and root, because it reads raw frames from the
81
+ network interface.
82
+ - `dynet monitor --record FILE` records through its own connection to the
83
+ gateway, on any OS.
84
+
85
+ [Capturing DyNet traffic](https://github.com/sdunster/dynet-cli/blob/main/docs/capturing-traffic.md) covers both step by
86
+ 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.
90
+
91
+ ### Checking a capture
92
+
93
+ ```console
94
+ $ dynet decode --summary sample.jsonl
95
+ 4 packet(s) over 24.00 h
96
+ direction: rx 3, tx 1
97
+ By type:
98
+ 1 PresetSelect
99
+ 1 RequestPreset
100
+ 1 PresetReport
101
+ 1 Unknown physical 0x53
102
+ Areas: 12 (3)
103
+ Undecoded packets (1 distinct):
104
+ 1 5caa5553187126a3
105
+ ```
106
+
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
109
+ way `monitor` does, or as JSON with `--json`.
110
+
111
+ ## Exit codes
112
+
113
+ | Code | Meaning |
114
+ |---|---|
115
+ | 0 | Success |
116
+ | 1 | Gateway or file error |
117
+ | 2 | Bad arguments |
118
+ | 3 | `query` got no answer in time |
119
+
120
+ ## Development
121
+
122
+ ```sh
123
+ uv sync
124
+ uv run pytest --cov # 100 % branch coverage is enforced
125
+ uv run ruff check && uv run ruff format --check && uv run mypy
126
+ ```
127
+
128
+ ## Licence
129
+
130
+ MIT. Not affiliated with or endorsed by Signify.
@@ -0,0 +1,216 @@
1
+ # Capturing DyNet traffic
2
+
3
+ This guide is for anyone asked to record the traffic on their Dynalite system,
4
+ for example to help support for their hardware get added to
5
+ [aiodynet](https://github.com/sdunster/aiodynet) or the Home Assistant
6
+ `dynalite` integration. A day of real traffic shows which messages your
7
+ keypads, sensors and controllers send, and that's hard to learn any other way.
8
+
9
+ It takes about ten minutes to set up, then runs on its own.
10
+
11
+ ## What gets recorded, and what doesn't
12
+
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:
15
+
16
+ - area, channel and preset numbers, and channel levels;
17
+ - *when* things happened: when lights went on, keypads were pressed or
18
+ motion sensors fired;
19
+ - any clock time your system broadcasts.
20
+
21
+ It also records when the connection to the gateway opened or closed, along
22
+ with the IP address and port of the machine connected to it (the
23
+ `connect`/`close`/`gap` lines).
24
+
25
+ It does **not** record anything else on your network, or any passwords. Names
26
+ aren't recorded either: DyNet only carries numbers. [Before you
27
+ send it](#before-you-send-it) shows how to remove the real times if you'd
28
+ rather not share them.
29
+
30
+ Recording never sends anything to your Dynalite system.
31
+
32
+ ## Pick a method
33
+
34
+ | | **A. Passive capture** (preferred) | **B. Record through a second connection** |
35
+ |---|---|---|
36
+ | Use it when | Home Assistant, or another controller, is already connected to the gateway | Nothing else is connected, or you can't use A |
37
+ | Runs on | The Linux machine that's connected to the gateway, with root access | Any computer that can reach the gateway (tested on Linux and macOS) |
38
+ | Records | Both directions: what the gateway sends **and** what Home Assistant sends | Only what the gateway sends |
39
+ | Touches the gateway | No. It only listens to the existing connection | Yes. It opens its own TCP connection |
40
+
41
+ Method A watches the network traffic between the gateway and the machine
42
+ already connected to it, so the gateway doesn't know it's there. Method B is
43
+ simpler, but some gateways may refuse a second connection, or drop the first
44
+ one when a second arrives. That hasn't been tested, so if Home Assistant is
45
+ connected, try B for a minute first and check that Home Assistant stays
46
+ connected.
47
+
48
+ Method A was tested on a Raspberry Pi running Raspberry Pi OS (Debian), with
49
+ Home Assistant in a container using host networking. On **Home Assistant
50
+ OS** the usual SSH add-ons can't see raw network traffic, so use method B
51
+ from another computer.
52
+
53
+ ## Find your gateway's address and port
54
+
55
+ You need the gateway's IP address and TCP port, the same ones Home Assistant
56
+ uses:
57
+
58
+ - **Address:** in Home Assistant go to *Settings → Devices & services →
59
+ Signify Dynalite* (Home Assistant currently lists it as *Philips
60
+ Dynalite*). The entry is named after the gateway's address.
61
+ - **Port:** it's in the bridge settings in the *Dynalite* panel in the Home
62
+ Assistant sidebar. If you set the integration up yourself, it's the port you
63
+ entered then.
64
+
65
+ The examples below use `192.0.2.10:50000`. Replace it with yours.
66
+
67
+ ## Install `dynet`
68
+
69
+ `dynet` needs Python 3.13 or newer. The easiest install is with
70
+ [uv](https://docs.astral.sh/uv/), which also fetches a suitable Python if
71
+ your system's is older:
72
+
73
+ ```sh
74
+ curl -LsSf https://astral.sh/uv/install.sh | sh # installs uv
75
+ uv tool install dynet-cli
76
+ dynet --version
77
+ ```
78
+
79
+ If `dynet` isn't found afterwards, open a new terminal, or run
80
+ `uv tool update-shell`.
81
+
82
+ <details>
83
+ <summary>Alternative: a single file, with nothing to install on the capturing machine</summary>
84
+
85
+ Download `dynet.pyz` from the
86
+ [latest release](https://github.com/sdunster/dynet-cli/releases/latest) and
87
+ copy it to the capturing machine:
88
+
89
+ ```sh
90
+ curl -LO https://github.com/sdunster/dynet-cli/releases/latest/download/dynet.pyz
91
+ scp dynet.pyz you@capture-host:
92
+ ```
93
+
94
+ On the capturing machine (which needs Python 3.13 or newer), run
95
+ `python3 dynet.pyz` wherever this guide says `dynet`.
96
+ </details>
97
+
98
+ ## Method A: passive capture (Linux, root)
99
+
100
+ ### 1. Find the network interface
101
+
102
+ On the machine that's connected to the gateway:
103
+
104
+ ```sh
105
+ ip -br addr
106
+ ```
107
+
108
+ Pick the interface that has this machine's LAN address. It's usually `eth0`,
109
+ `end0` or `enp…` for wired, or `wlan0` for Wi-Fi.
110
+
111
+ ### 2. Check it works
112
+
113
+ Run a one-minute test. It needs root to read raw network traffic, so pass
114
+ `sudo` the full path to `dynet`:
115
+
116
+ ```sh
117
+ sudo "$(command -v dynet)" sniff 192.0.2.10:50000 -i eth0 --duration 60
118
+ ```
119
+
120
+ While it runs, press a keypad button or switch something on in Home
121
+ Assistant. Each packet prints as a line of JSON. If you see
122
+ `-- captured 0 packet(s)` after doing something, check the interface, the
123
+ address and the port.
124
+
125
+ ### 3. Capture for a day
126
+
127
+ On a system with systemd (most Linux distributions), this runs the capture in
128
+ the background for 24 hours. It keeps running after you log out:
129
+
130
+ ```sh
131
+ sudo systemd-run --unit dynet-capture --property=RuntimeMaxSec=90000 \
132
+ "$(command -v dynet)" sniff 192.0.2.10:50000 -i eth0 \
133
+ --duration 86400 -o "$HOME/dynet-capture.jsonl"
134
+ ```
135
+
136
+ Check on it at any time:
137
+
138
+ ```sh
139
+ systemctl status dynet-capture # still running?
140
+ wc -l ~/dynet-capture.jsonl # how many lines so far
141
+ dynet decode ~/dynet-capture.jsonl | tail # the latest packets, readable
142
+ ```
143
+
144
+ It stops by itself after 24 hours. To stop it early, run
145
+ `sudo systemctl stop dynet-capture`. A reboot also stops it. Every line is
146
+ written straight away, so a capture that stops early is still useful.
147
+
148
+ Without systemd, run the same `sniff` command inside `tmux` or `screen`, or
149
+ with `sudo nohup … &`.
150
+
151
+ ## Method B: record through a second connection
152
+
153
+ On any computer that can reach the gateway:
154
+
155
+ ```sh
156
+ dynet check --host 192.0.2.10 --port 50000 # can we connect at all?
157
+ dynet monitor --host 192.0.2.10 --port 50000 \
158
+ --duration 86400 --record dynet-capture.jsonl
159
+ ```
160
+
161
+ `monitor` prints each packet as it arrives and appends it to
162
+ `dynet-capture.jsonl`. Leave the terminal open, or run it in `tmux` or
163
+ `screen`. Press Ctrl-C to stop early. If Home Assistant is connected to the
164
+ same gateway, watch it for the first few minutes and stop if it loses its
165
+ connection.
166
+
167
+ ## Before you send it
168
+
169
+ ### Check what you've got
170
+
171
+ ```sh
172
+ dynet decode --summary dynet-capture.jsonl
173
+ ```
174
+
175
+ This counts the packets by type and lists every packet the library can't
176
+ decode yet. Those are the interesting ones, so include this output in your
177
+ message.
178
+
179
+ ### Optional: remove the real times
180
+
181
+ To share only the time *between* packets, not when they happened:
182
+
183
+ ```sh
184
+ python3 -c 'import json,sys
185
+ rows = [json.loads(line) for line in open(sys.argv[1])]
186
+ start = rows[0]["t"]
187
+ for row in rows:
188
+ row["t"] = round(row["t"] - start, 3)
189
+ row.pop("client", None)
190
+ print(json.dumps(row))' dynet-capture.jsonl > dynet-capture-shared.jsonl
191
+ ```
192
+
193
+ This also drops the IP address in the connection lines. Any clock time your
194
+ system broadcasts stays in the packets themselves.
195
+
196
+ ### Compress it
197
+
198
+ ```sh
199
+ gzip -k dynet-capture.jsonl # makes dynet-capture.jsonl.gz
200
+ ```
201
+
202
+ Each packet takes about 60 bytes, so even a busy day stays small.
203
+
204
+ ## Sending it
205
+
206
+ Open an issue at <https://github.com/sdunster/aiodynet/issues> and include:
207
+
208
+ - the `dynet decode --summary` output;
209
+ - what you did while it ran, if anything specific, such as "pressed the
210
+ hallway keypad's button 2 at 19:05";
211
+ - your gateway model, and other Dynalite hardware if you know it;
212
+ - which method you used.
213
+
214
+ GitHub issues are public. Attach the capture there if you're happy for it to
215
+ be public. Otherwise, say so in the issue and we'll arrange another way to
216
+ send it.