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.
- dynet_cli-0.1.0/.github/workflows/ci.yml +46 -0
- dynet_cli-0.1.0/.github/workflows/release.yml +36 -0
- dynet_cli-0.1.0/.gitignore +15 -0
- dynet_cli-0.1.0/.pre-commit-config.yaml +22 -0
- dynet_cli-0.1.0/.python-version +1 -0
- dynet_cli-0.1.0/CHANGELOG.md +7 -0
- dynet_cli-0.1.0/LICENSE +21 -0
- dynet_cli-0.1.0/PKG-INFO +154 -0
- dynet_cli-0.1.0/README.md +130 -0
- dynet_cli-0.1.0/docs/capturing-traffic.md +216 -0
- dynet_cli-0.1.0/pyproject.toml +99 -0
- dynet_cli-0.1.0/scripts/build-pyz +14 -0
- dynet_cli-0.1.0/src/dynet_cli/__init__.py +5 -0
- dynet_cli-0.1.0/src/dynet_cli/__main__.py +5 -0
- dynet_cli-0.1.0/src/dynet_cli/capture.py +198 -0
- dynet_cli-0.1.0/src/dynet_cli/cli.py +535 -0
- dynet_cli-0.1.0/src/dynet_cli/py.typed +0 -0
- dynet_cli-0.1.0/src/dynet_cli/render.py +201 -0
- dynet_cli-0.1.0/src/dynet_cli/sniff.py +223 -0
- dynet_cli-0.1.0/tests/__init__.py +0 -0
- dynet_cli-0.1.0/tests/test_capture_render.py +285 -0
- dynet_cli-0.1.0/tests/test_cli.py +383 -0
- dynet_cli-0.1.0/tests/test_sniff.py +237 -0
- dynet_cli-0.1.0/uv.lock +492 -0
|
@@ -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,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
|
dynet_cli-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.
|
dynet_cli-0.1.0/PKG-INFO
ADDED
|
@@ -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.
|