connectsensors 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.
- connectsensors-0.1.0/.gitignore +9 -0
- connectsensors-0.1.0/PKG-INFO +196 -0
- connectsensors-0.1.0/pyproject.toml +42 -0
- connectsensors-0.1.0/python/README.md +177 -0
- connectsensors-0.1.0/python/connectsensors/__init__.py +203 -0
- connectsensors-0.1.0/python/connectsensors/py.typed +0 -0
- connectsensors-0.1.0/spec/LICENSE-CODE +21 -0
- connectsensors-0.1.0/spec/tools/csframe.py +1341 -0
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: connectsensors
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: ConnectSensors protocol: frames, proxy envelope, server-side helpers and pairing codes
|
|
5
|
+
Project-URL: Homepage, https://github.com/chrisuthe/ConnectSensors
|
|
6
|
+
Project-URL: Specification, https://github.com/chrisuthe/ConnectSensors/tree/main/spec
|
|
7
|
+
Project-URL: Issues, https://github.com/chrisuthe/ConnectSensors/issues
|
|
8
|
+
Author: Chris Uthe and ConnectSensors contributors
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: spec/LICENSE-CODE
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
14
|
+
Classifier: Topic :: Home Automation
|
|
15
|
+
Classifier: Typing :: Typed
|
|
16
|
+
Requires-Python: >=3.13
|
|
17
|
+
Requires-Dist: cryptography
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
|
|
20
|
+
# connectsensors
|
|
21
|
+
|
|
22
|
+
The [ConnectSensors](https://github.com/chrisuthe/ConnectSensors) v1 protocol for
|
|
23
|
+
Python network servers: sensor frames, the proxy envelope and sessions, uplink
|
|
24
|
+
deduplication, JOIN handling, reading payloads and pairing codes.
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
pip install connectsensors
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Python 3.13 or later. The only dependency is `cryptography`.
|
|
31
|
+
|
|
32
|
+
The code is the specification's reference implementation,
|
|
33
|
+
[`spec/tools/csframe.py`](https://github.com/chrisuthe/ConnectSensors/blob/main/spec/tools/csframe.py),
|
|
34
|
+
shipped unchanged as `connectsensors._csframe`; the test vectors are generated and
|
|
35
|
+
verified with the same file. Where it disagrees with the
|
|
36
|
+
[specification](https://github.com/chrisuthe/ConnectSensors/tree/main/spec), the
|
|
37
|
+
specification wins. `connectsensors` re-exports the supported surface under
|
|
38
|
+
csframe's names, so code reads the same as the spec's examples. The package is
|
|
39
|
+
typed (`py.typed`).
|
|
40
|
+
|
|
41
|
+
The protocol is a draft, and so is this API: expect breaking changes before 1.0.
|
|
42
|
+
|
|
43
|
+
## API
|
|
44
|
+
|
|
45
|
+
Section numbers refer to the specification documents.
|
|
46
|
+
|
|
47
|
+
**Frames (02).** `keys_from(base, dev_eui)` derives a `DeviceKeys` from `k_root` or
|
|
48
|
+
`k_session`. `seal(keys, ftype, net_tag, dev_tag, fcnt, plaintext)` builds a frame;
|
|
49
|
+
`open_frame(keys, frame)` checks its MIC and returns `(ParsedHeader, plaintext)`, or
|
|
50
|
+
raises. `parse_header(frame)` does a proxy's keyless checks and returns `None` for
|
|
51
|
+
anything that isn't a v1 frame. Tags: `derive_net_route(k_net)`, `epoch_of(unix)`,
|
|
52
|
+
`net_tag(k_net_route, epoch)`, `dev_tag(keys.k_dev_tag, epoch)`. Downlinks:
|
|
53
|
+
`downlink_payload(reply_to, server_time, flags, commands)` and `command(cmd_id, args)`.
|
|
54
|
+
Key exchange: `x25519_pub(priv)`, `derive_session(...)`. Constants: frame types
|
|
55
|
+
`T_*`, uplink and downlink flags `UF_*` and `DF_*`, commands `CMD_*`, sizes
|
|
56
|
+
`HEADER_LEN`, `MIC_LEN`, `MAX_PAYLOAD`, `MIN_FRAME`, `MAX_FRAME`.
|
|
57
|
+
|
|
58
|
+
**Payloads (03).** `decode_readings(data)` returns one dict per reading (`channel`,
|
|
59
|
+
`kind`, `name`, `value`) and keeps unknown kinds as hex; `encode_reading(channel,
|
|
60
|
+
kind, value)` encodes one. `KINDS` maps kind codes to names. `unwrap(...)` unwraps
|
|
61
|
+
16-bit counters.
|
|
62
|
+
|
|
63
|
+
**Pairing (04).** `qr_parse(code)` returns `dev_eui`, `k_root` (hex), `region` and
|
|
64
|
+
`profile`, or raises `ValueError` with the reason; `qr_encode(...)` builds a code.
|
|
65
|
+
`JoinResponder(k_root, dev_eui, root_fcnt_down)` answers JOINs for one device. Persist
|
|
66
|
+
its `root_fcnt_down` and keep it after the device is removed: the root counter never
|
|
67
|
+
resets. A retransmitted JOIN gets the cached answer back byte for byte. Call `paired()`
|
|
68
|
+
once SET_NETWORK is acknowledged.
|
|
69
|
+
|
|
70
|
+
**Proxy envelope (05).** `open_envelope(key, data)` checks the MAC and returns `type`,
|
|
71
|
+
`proxy_id` (hex), `boot_id`, `seq` and `body` (hex); `envelope(key, type, proxy_id,
|
|
72
|
+
boot_id, seq, body)` builds one. Bodies: `parse_uplink`, `parse_hello`,
|
|
73
|
+
`parse_tx_result` for messages from a proxy; `server_status_body`,
|
|
74
|
+
`hello_request_body`, `downlink_msg_body` for messages to it (and the inverse of each,
|
|
75
|
+
for tests). Message types `M_*`, capabilities `CAP_*`, `UPF_TS_UNCERTAIN`.
|
|
76
|
+
|
|
77
|
+
`ServerLink(new_nonce)` is a server's session with one proxy, in memory only. Feed it
|
|
78
|
+
every opened envelope with a monotonic millisecond clock; `receive` returns
|
|
79
|
+
`{"result": ...}`:
|
|
80
|
+
|
|
81
|
+
- `accepted`: a message of the current session; handle it.
|
|
82
|
+
- `switched`: a HELLO echoing the server's nonce started a session with a new boot;
|
|
83
|
+
handle it (answer the HELLO).
|
|
84
|
+
- `hello_request`: a boot the server has no session with; send a `M_HELLO_REQUEST`
|
|
85
|
+
carrying `nonce` to the sender, with that message's `boot_id` and seq 0.
|
|
86
|
+
- `ignored`: a replay, or a rate-limited request; drop it.
|
|
87
|
+
|
|
88
|
+
Number the messages you send with `next_seq()`. `new_nonce` returns a random nonzero
|
|
89
|
+
32-bit nonce.
|
|
90
|
+
|
|
91
|
+
**Network server (07).** `UplinkCollector(first_fcnt)` per device groups copies of a
|
|
92
|
+
transmission heard by several proxies and decides when to answer: `receive(frame,
|
|
93
|
+
arrived_ms)` returns `{"result": "copy"}` for a copy of a transmission already
|
|
94
|
+
handled, or `{"result": "transmission", "counter": "accept" | "accept_late" |
|
|
95
|
+
"duplicate" | "too_old", "answer": bool}`. A retransmitted confirmed frame is answered
|
|
96
|
+
again, up to `MAX_ANSWERS_AGAIN` times. `UplinkCounter` is its counter check alone.
|
|
97
|
+
|
|
98
|
+
## Server-side example
|
|
99
|
+
|
|
100
|
+
One proxy, one paired device whose session key is known. Error handling and device
|
|
101
|
+
lookup are left out.
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
import secrets
|
|
105
|
+
import time
|
|
106
|
+
|
|
107
|
+
import connectsensors as cs
|
|
108
|
+
|
|
109
|
+
proxy_key = bytes.fromhex("5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a")
|
|
110
|
+
link = cs.ServerLink(lambda: secrets.randbits(32) or 1)
|
|
111
|
+
session = cs.keys_from(k_session, dev_eui)
|
|
112
|
+
uplinks = cs.UplinkCollector(first_fcnt)
|
|
113
|
+
fcnt_down = 0
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def handle(data: bytes, reply) -> None:
|
|
117
|
+
global fcnt_down
|
|
118
|
+
m = cs.open_envelope(proxy_key, data) # raises ValueError on a bad MAC
|
|
119
|
+
pid = bytes.fromhex(m["proxy_id"])
|
|
120
|
+
now_ms = time.monotonic_ns() // 1_000_000
|
|
121
|
+
got = link.receive(m, now_ms)
|
|
122
|
+
|
|
123
|
+
def send(msg_type: int, body: bytes) -> None:
|
|
124
|
+
reply(cs.envelope(proxy_key, msg_type, pid, m["boot_id"], link.next_seq(), body))
|
|
125
|
+
|
|
126
|
+
if got["result"] == "hello_request":
|
|
127
|
+
reply(cs.envelope(proxy_key, cs.M_HELLO_REQUEST, pid, m["boot_id"], 0,
|
|
128
|
+
cs.hello_request_body(got["nonce"])))
|
|
129
|
+
return
|
|
130
|
+
if got["result"] == "ignored":
|
|
131
|
+
return
|
|
132
|
+
|
|
133
|
+
body = bytes.fromhex(m["body"])
|
|
134
|
+
if m["type"] == cs.M_HELLO:
|
|
135
|
+
now = int(time.time())
|
|
136
|
+
tags = [cs.net_tag(k_net_route, e) for e in range(cs.epoch_of(now) - 1, cs.epoch_of(now) + 2)]
|
|
137
|
+
send(cs.M_SERVER_STATUS, cs.server_status_body(now, tags, m["seq"]))
|
|
138
|
+
elif m["type"] == cs.M_UPLINK:
|
|
139
|
+
u = cs.parse_uplink(body)
|
|
140
|
+
h = cs.parse_header(u["frame"])
|
|
141
|
+
if h is None:
|
|
142
|
+
return
|
|
143
|
+
got = uplinks.receive(u["frame"], now_ms)
|
|
144
|
+
if got["result"] == "copy" or got["counter"] == "too_old":
|
|
145
|
+
return
|
|
146
|
+
h, plaintext = cs.open_frame(session, u["frame"])
|
|
147
|
+
if h.ftype in (cs.T_DATA, cs.T_DATA_CONFIRMED):
|
|
148
|
+
print(cs.decode_readings(plaintext[1:])) # after the uplink flags byte
|
|
149
|
+
if got["answer"]:
|
|
150
|
+
fcnt_down += 1 # persist it
|
|
151
|
+
ack = cs.seal(session, cs.T_DOWNLINK, h.net_tag, h.dev_tag, fcnt_down,
|
|
152
|
+
cs.downlink_payload(h.fcnt, int(time.time()), 0))
|
|
153
|
+
send(cs.M_DOWNLINK, cs.downlink_msg_body(u["rx_time_us"], 1_000_000, ack)) # RX1
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
The development server,
|
|
157
|
+
[`devtools/cs_testserver.py`](https://github.com/chrisuthe/ConnectSensors/blob/main/devtools/cs_testserver.py),
|
|
158
|
+
is a complete example, including pairing.
|
|
159
|
+
|
|
160
|
+
## Development
|
|
161
|
+
|
|
162
|
+
The package is built from the repository root (`pyproject.toml`). There is no copy of
|
|
163
|
+
the protocol code under `python/`: the wheel takes `spec/tools/csframe.py` and installs
|
|
164
|
+
it as `connectsensors/_csframe.py`. Change the protocol there, and keep the names this
|
|
165
|
+
package re-exports. An editable install (`pip install -e .`) has no `_csframe.py`, so
|
|
166
|
+
it loads `spec/tools/csframe.py` in place.
|
|
167
|
+
|
|
168
|
+
```
|
|
169
|
+
tests/package/check.sh
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
builds the sdist and the wheel (from the sdist), installs the wheel into a clean
|
|
173
|
+
Python 3.13 venv, runs `tests/package/smoke_test.py` against it from outside the
|
|
174
|
+
checkout and type-checks the smoke test with `mypy --strict`. It needs
|
|
175
|
+
[uv](https://docs.astral.sh/uv/).
|
|
176
|
+
|
|
177
|
+
## Releasing
|
|
178
|
+
|
|
179
|
+
The version lives in `python/connectsensors/__init__.py` (`__version__`). Bump it,
|
|
180
|
+
merge, then push a tag `v<version>`; the `Release` workflow
|
|
181
|
+
(`.github/workflows/release.yml`) checks that the tag matches, builds, and publishes
|
|
182
|
+
to PyPI with trusted publishing. No API token is stored anywhere.
|
|
183
|
+
|
|
184
|
+
One-time setup, before the first release:
|
|
185
|
+
|
|
186
|
+
1. On PyPI, under *Your projects → Publishing*, add a **pending publisher** (GitHub):
|
|
187
|
+
- PyPI project name: `connectsensors`
|
|
188
|
+
- Owner: `chrisuthe`
|
|
189
|
+
- Repository name: `ConnectSensors`
|
|
190
|
+
- Workflow name: `release.yml`
|
|
191
|
+
- Environment name: `pypi`
|
|
192
|
+
2. On GitHub, under *Settings → Environments*, create the environment `pypi`.
|
|
193
|
+
Optionally restrict it to `v*` tags and require a reviewer.
|
|
194
|
+
|
|
195
|
+
The first tagged release creates the project on PyPI and turns the pending publisher
|
|
196
|
+
into a regular one.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# The connectsensors package. Its protocol code is spec/tools/csframe.py, copied into
|
|
2
|
+
# the wheel as connectsensors/_csframe.py at build time; there is no second copy.
|
|
3
|
+
[build-system]
|
|
4
|
+
requires = ["hatchling>=1.27"]
|
|
5
|
+
build-backend = "hatchling.build"
|
|
6
|
+
|
|
7
|
+
[project]
|
|
8
|
+
name = "connectsensors"
|
|
9
|
+
dynamic = ["version"]
|
|
10
|
+
description = "ConnectSensors protocol: frames, proxy envelope, server-side helpers and pairing codes"
|
|
11
|
+
readme = "python/README.md"
|
|
12
|
+
license = "MIT"
|
|
13
|
+
license-files = ["spec/LICENSE-CODE"]
|
|
14
|
+
requires-python = ">=3.13"
|
|
15
|
+
dependencies = ["cryptography"]
|
|
16
|
+
authors = [{ name = "Chris Uthe and ConnectSensors contributors" }]
|
|
17
|
+
classifiers = [
|
|
18
|
+
"Development Status :: 3 - Alpha",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.13",
|
|
21
|
+
"Topic :: Home Automation",
|
|
22
|
+
"Typing :: Typed",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
[project.urls]
|
|
26
|
+
Homepage = "https://github.com/chrisuthe/ConnectSensors"
|
|
27
|
+
Specification = "https://github.com/chrisuthe/ConnectSensors/tree/main/spec"
|
|
28
|
+
Issues = "https://github.com/chrisuthe/ConnectSensors/issues"
|
|
29
|
+
|
|
30
|
+
[tool.hatch.version]
|
|
31
|
+
path = "python/connectsensors/__init__.py"
|
|
32
|
+
|
|
33
|
+
# The sdist keeps csframe.py at its repository path, so a wheel built from the sdist
|
|
34
|
+
# force-includes it exactly as a wheel built from the checkout does.
|
|
35
|
+
[tool.hatch.build.targets.sdist]
|
|
36
|
+
only-include = ["python", "spec/tools/csframe.py", "spec/LICENSE-CODE"]
|
|
37
|
+
|
|
38
|
+
[tool.hatch.build.targets.wheel]
|
|
39
|
+
packages = ["python/connectsensors"]
|
|
40
|
+
|
|
41
|
+
[tool.hatch.build.targets.wheel.force-include]
|
|
42
|
+
"spec/tools/csframe.py" = "connectsensors/_csframe.py"
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# connectsensors
|
|
2
|
+
|
|
3
|
+
The [ConnectSensors](https://github.com/chrisuthe/ConnectSensors) v1 protocol for
|
|
4
|
+
Python network servers: sensor frames, the proxy envelope and sessions, uplink
|
|
5
|
+
deduplication, JOIN handling, reading payloads and pairing codes.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
pip install connectsensors
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Python 3.13 or later. The only dependency is `cryptography`.
|
|
12
|
+
|
|
13
|
+
The code is the specification's reference implementation,
|
|
14
|
+
[`spec/tools/csframe.py`](https://github.com/chrisuthe/ConnectSensors/blob/main/spec/tools/csframe.py),
|
|
15
|
+
shipped unchanged as `connectsensors._csframe`; the test vectors are generated and
|
|
16
|
+
verified with the same file. Where it disagrees with the
|
|
17
|
+
[specification](https://github.com/chrisuthe/ConnectSensors/tree/main/spec), the
|
|
18
|
+
specification wins. `connectsensors` re-exports the supported surface under
|
|
19
|
+
csframe's names, so code reads the same as the spec's examples. The package is
|
|
20
|
+
typed (`py.typed`).
|
|
21
|
+
|
|
22
|
+
The protocol is a draft, and so is this API: expect breaking changes before 1.0.
|
|
23
|
+
|
|
24
|
+
## API
|
|
25
|
+
|
|
26
|
+
Section numbers refer to the specification documents.
|
|
27
|
+
|
|
28
|
+
**Frames (02).** `keys_from(base, dev_eui)` derives a `DeviceKeys` from `k_root` or
|
|
29
|
+
`k_session`. `seal(keys, ftype, net_tag, dev_tag, fcnt, plaintext)` builds a frame;
|
|
30
|
+
`open_frame(keys, frame)` checks its MIC and returns `(ParsedHeader, plaintext)`, or
|
|
31
|
+
raises. `parse_header(frame)` does a proxy's keyless checks and returns `None` for
|
|
32
|
+
anything that isn't a v1 frame. Tags: `derive_net_route(k_net)`, `epoch_of(unix)`,
|
|
33
|
+
`net_tag(k_net_route, epoch)`, `dev_tag(keys.k_dev_tag, epoch)`. Downlinks:
|
|
34
|
+
`downlink_payload(reply_to, server_time, flags, commands)` and `command(cmd_id, args)`.
|
|
35
|
+
Key exchange: `x25519_pub(priv)`, `derive_session(...)`. Constants: frame types
|
|
36
|
+
`T_*`, uplink and downlink flags `UF_*` and `DF_*`, commands `CMD_*`, sizes
|
|
37
|
+
`HEADER_LEN`, `MIC_LEN`, `MAX_PAYLOAD`, `MIN_FRAME`, `MAX_FRAME`.
|
|
38
|
+
|
|
39
|
+
**Payloads (03).** `decode_readings(data)` returns one dict per reading (`channel`,
|
|
40
|
+
`kind`, `name`, `value`) and keeps unknown kinds as hex; `encode_reading(channel,
|
|
41
|
+
kind, value)` encodes one. `KINDS` maps kind codes to names. `unwrap(...)` unwraps
|
|
42
|
+
16-bit counters.
|
|
43
|
+
|
|
44
|
+
**Pairing (04).** `qr_parse(code)` returns `dev_eui`, `k_root` (hex), `region` and
|
|
45
|
+
`profile`, or raises `ValueError` with the reason; `qr_encode(...)` builds a code.
|
|
46
|
+
`JoinResponder(k_root, dev_eui, root_fcnt_down)` answers JOINs for one device. Persist
|
|
47
|
+
its `root_fcnt_down` and keep it after the device is removed: the root counter never
|
|
48
|
+
resets. A retransmitted JOIN gets the cached answer back byte for byte. Call `paired()`
|
|
49
|
+
once SET_NETWORK is acknowledged.
|
|
50
|
+
|
|
51
|
+
**Proxy envelope (05).** `open_envelope(key, data)` checks the MAC and returns `type`,
|
|
52
|
+
`proxy_id` (hex), `boot_id`, `seq` and `body` (hex); `envelope(key, type, proxy_id,
|
|
53
|
+
boot_id, seq, body)` builds one. Bodies: `parse_uplink`, `parse_hello`,
|
|
54
|
+
`parse_tx_result` for messages from a proxy; `server_status_body`,
|
|
55
|
+
`hello_request_body`, `downlink_msg_body` for messages to it (and the inverse of each,
|
|
56
|
+
for tests). Message types `M_*`, capabilities `CAP_*`, `UPF_TS_UNCERTAIN`.
|
|
57
|
+
|
|
58
|
+
`ServerLink(new_nonce)` is a server's session with one proxy, in memory only. Feed it
|
|
59
|
+
every opened envelope with a monotonic millisecond clock; `receive` returns
|
|
60
|
+
`{"result": ...}`:
|
|
61
|
+
|
|
62
|
+
- `accepted`: a message of the current session; handle it.
|
|
63
|
+
- `switched`: a HELLO echoing the server's nonce started a session with a new boot;
|
|
64
|
+
handle it (answer the HELLO).
|
|
65
|
+
- `hello_request`: a boot the server has no session with; send a `M_HELLO_REQUEST`
|
|
66
|
+
carrying `nonce` to the sender, with that message's `boot_id` and seq 0.
|
|
67
|
+
- `ignored`: a replay, or a rate-limited request; drop it.
|
|
68
|
+
|
|
69
|
+
Number the messages you send with `next_seq()`. `new_nonce` returns a random nonzero
|
|
70
|
+
32-bit nonce.
|
|
71
|
+
|
|
72
|
+
**Network server (07).** `UplinkCollector(first_fcnt)` per device groups copies of a
|
|
73
|
+
transmission heard by several proxies and decides when to answer: `receive(frame,
|
|
74
|
+
arrived_ms)` returns `{"result": "copy"}` for a copy of a transmission already
|
|
75
|
+
handled, or `{"result": "transmission", "counter": "accept" | "accept_late" |
|
|
76
|
+
"duplicate" | "too_old", "answer": bool}`. A retransmitted confirmed frame is answered
|
|
77
|
+
again, up to `MAX_ANSWERS_AGAIN` times. `UplinkCounter` is its counter check alone.
|
|
78
|
+
|
|
79
|
+
## Server-side example
|
|
80
|
+
|
|
81
|
+
One proxy, one paired device whose session key is known. Error handling and device
|
|
82
|
+
lookup are left out.
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
import secrets
|
|
86
|
+
import time
|
|
87
|
+
|
|
88
|
+
import connectsensors as cs
|
|
89
|
+
|
|
90
|
+
proxy_key = bytes.fromhex("5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a")
|
|
91
|
+
link = cs.ServerLink(lambda: secrets.randbits(32) or 1)
|
|
92
|
+
session = cs.keys_from(k_session, dev_eui)
|
|
93
|
+
uplinks = cs.UplinkCollector(first_fcnt)
|
|
94
|
+
fcnt_down = 0
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def handle(data: bytes, reply) -> None:
|
|
98
|
+
global fcnt_down
|
|
99
|
+
m = cs.open_envelope(proxy_key, data) # raises ValueError on a bad MAC
|
|
100
|
+
pid = bytes.fromhex(m["proxy_id"])
|
|
101
|
+
now_ms = time.monotonic_ns() // 1_000_000
|
|
102
|
+
got = link.receive(m, now_ms)
|
|
103
|
+
|
|
104
|
+
def send(msg_type: int, body: bytes) -> None:
|
|
105
|
+
reply(cs.envelope(proxy_key, msg_type, pid, m["boot_id"], link.next_seq(), body))
|
|
106
|
+
|
|
107
|
+
if got["result"] == "hello_request":
|
|
108
|
+
reply(cs.envelope(proxy_key, cs.M_HELLO_REQUEST, pid, m["boot_id"], 0,
|
|
109
|
+
cs.hello_request_body(got["nonce"])))
|
|
110
|
+
return
|
|
111
|
+
if got["result"] == "ignored":
|
|
112
|
+
return
|
|
113
|
+
|
|
114
|
+
body = bytes.fromhex(m["body"])
|
|
115
|
+
if m["type"] == cs.M_HELLO:
|
|
116
|
+
now = int(time.time())
|
|
117
|
+
tags = [cs.net_tag(k_net_route, e) for e in range(cs.epoch_of(now) - 1, cs.epoch_of(now) + 2)]
|
|
118
|
+
send(cs.M_SERVER_STATUS, cs.server_status_body(now, tags, m["seq"]))
|
|
119
|
+
elif m["type"] == cs.M_UPLINK:
|
|
120
|
+
u = cs.parse_uplink(body)
|
|
121
|
+
h = cs.parse_header(u["frame"])
|
|
122
|
+
if h is None:
|
|
123
|
+
return
|
|
124
|
+
got = uplinks.receive(u["frame"], now_ms)
|
|
125
|
+
if got["result"] == "copy" or got["counter"] == "too_old":
|
|
126
|
+
return
|
|
127
|
+
h, plaintext = cs.open_frame(session, u["frame"])
|
|
128
|
+
if h.ftype in (cs.T_DATA, cs.T_DATA_CONFIRMED):
|
|
129
|
+
print(cs.decode_readings(plaintext[1:])) # after the uplink flags byte
|
|
130
|
+
if got["answer"]:
|
|
131
|
+
fcnt_down += 1 # persist it
|
|
132
|
+
ack = cs.seal(session, cs.T_DOWNLINK, h.net_tag, h.dev_tag, fcnt_down,
|
|
133
|
+
cs.downlink_payload(h.fcnt, int(time.time()), 0))
|
|
134
|
+
send(cs.M_DOWNLINK, cs.downlink_msg_body(u["rx_time_us"], 1_000_000, ack)) # RX1
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
The development server,
|
|
138
|
+
[`devtools/cs_testserver.py`](https://github.com/chrisuthe/ConnectSensors/blob/main/devtools/cs_testserver.py),
|
|
139
|
+
is a complete example, including pairing.
|
|
140
|
+
|
|
141
|
+
## Development
|
|
142
|
+
|
|
143
|
+
The package is built from the repository root (`pyproject.toml`). There is no copy of
|
|
144
|
+
the protocol code under `python/`: the wheel takes `spec/tools/csframe.py` and installs
|
|
145
|
+
it as `connectsensors/_csframe.py`. Change the protocol there, and keep the names this
|
|
146
|
+
package re-exports. An editable install (`pip install -e .`) has no `_csframe.py`, so
|
|
147
|
+
it loads `spec/tools/csframe.py` in place.
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
tests/package/check.sh
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
builds the sdist and the wheel (from the sdist), installs the wheel into a clean
|
|
154
|
+
Python 3.13 venv, runs `tests/package/smoke_test.py` against it from outside the
|
|
155
|
+
checkout and type-checks the smoke test with `mypy --strict`. It needs
|
|
156
|
+
[uv](https://docs.astral.sh/uv/).
|
|
157
|
+
|
|
158
|
+
## Releasing
|
|
159
|
+
|
|
160
|
+
The version lives in `python/connectsensors/__init__.py` (`__version__`). Bump it,
|
|
161
|
+
merge, then push a tag `v<version>`; the `Release` workflow
|
|
162
|
+
(`.github/workflows/release.yml`) checks that the tag matches, builds, and publishes
|
|
163
|
+
to PyPI with trusted publishing. No API token is stored anywhere.
|
|
164
|
+
|
|
165
|
+
One-time setup, before the first release:
|
|
166
|
+
|
|
167
|
+
1. On PyPI, under *Your projects → Publishing*, add a **pending publisher** (GitHub):
|
|
168
|
+
- PyPI project name: `connectsensors`
|
|
169
|
+
- Owner: `chrisuthe`
|
|
170
|
+
- Repository name: `ConnectSensors`
|
|
171
|
+
- Workflow name: `release.yml`
|
|
172
|
+
- Environment name: `pypi`
|
|
173
|
+
2. On GitHub, under *Settings → Environments*, create the environment `pypi`.
|
|
174
|
+
Optionally restrict it to `v*` tags and require a reviewer.
|
|
175
|
+
|
|
176
|
+
The first tagged release creates the project on PyPI and turns the pending publisher
|
|
177
|
+
into a regular one.
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
"""ConnectSensors protocol v1 for network servers.
|
|
2
|
+
|
|
3
|
+
The implementation is the spec's reference, ``spec/tools/csframe.py``, shipped as
|
|
4
|
+
``connectsensors._csframe``. This module is the supported surface; names match
|
|
5
|
+
csframe's so the spec and the package read the same.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import importlib.util
|
|
9
|
+
import os
|
|
10
|
+
import sys
|
|
11
|
+
|
|
12
|
+
if importlib.util.find_spec(__name__ + "._csframe") is None:
|
|
13
|
+
# An editable install or the checkout: only the wheel has _csframe.py, so load the
|
|
14
|
+
# spec's file in its place.
|
|
15
|
+
_spec = importlib.util.spec_from_file_location(
|
|
16
|
+
__name__ + "._csframe",
|
|
17
|
+
os.path.join(os.path.dirname(__file__), "..", "..", "spec", "tools", "csframe.py"),
|
|
18
|
+
)
|
|
19
|
+
assert _spec is not None and _spec.loader is not None
|
|
20
|
+
_module = importlib.util.module_from_spec(_spec)
|
|
21
|
+
sys.modules[_spec.name] = _module
|
|
22
|
+
_spec.loader.exec_module(_module)
|
|
23
|
+
|
|
24
|
+
from ._csframe import ( # noqa: E402
|
|
25
|
+
CAP_DOWNLINK,
|
|
26
|
+
CAP_FEDERATION,
|
|
27
|
+
CMD_KEY_EXCHANGE,
|
|
28
|
+
CMD_LEAVE,
|
|
29
|
+
CMD_SET_CHANNEL,
|
|
30
|
+
CMD_SET_HEARTBEAT,
|
|
31
|
+
CMD_SET_NETWORK,
|
|
32
|
+
DF_PENDING,
|
|
33
|
+
DIR_DOWN,
|
|
34
|
+
DIR_UP,
|
|
35
|
+
ENV_HEADER,
|
|
36
|
+
ENV_MAC,
|
|
37
|
+
ENV_VERSION,
|
|
38
|
+
EPOCH_SECONDS,
|
|
39
|
+
FRAME_MEMORY_MS,
|
|
40
|
+
HEADER_LEN,
|
|
41
|
+
KINDS,
|
|
42
|
+
M_DOWNLINK,
|
|
43
|
+
M_HELLO,
|
|
44
|
+
M_HELLO_REQUEST,
|
|
45
|
+
M_SERVER_STATUS,
|
|
46
|
+
M_TX_RESULT,
|
|
47
|
+
M_UPLINK,
|
|
48
|
+
MAGIC,
|
|
49
|
+
MAX_ANSWERS_AGAIN,
|
|
50
|
+
MAX_FRAME,
|
|
51
|
+
MAX_PAYLOAD,
|
|
52
|
+
MERGE_WINDOW_MS,
|
|
53
|
+
MIC_LEN,
|
|
54
|
+
MIN_FRAME,
|
|
55
|
+
REORDER_WINDOW,
|
|
56
|
+
REQUEST_BOOTS,
|
|
57
|
+
REQUEST_NONCE_MS,
|
|
58
|
+
REQUEST_RESEND_MS,
|
|
59
|
+
T_DATA,
|
|
60
|
+
T_DATA_CONFIRMED,
|
|
61
|
+
T_DOWNLINK,
|
|
62
|
+
T_HEARTBEAT,
|
|
63
|
+
T_HEARTBEAT_CONFIRMED,
|
|
64
|
+
T_JOIN,
|
|
65
|
+
T_SYNC,
|
|
66
|
+
UF_DL_ACK,
|
|
67
|
+
UF_TIME_UNSURE,
|
|
68
|
+
UPF_TS_UNCERTAIN,
|
|
69
|
+
VERSION,
|
|
70
|
+
ZERO_TAG,
|
|
71
|
+
DeviceKeys,
|
|
72
|
+
JoinResponder,
|
|
73
|
+
ParsedHeader,
|
|
74
|
+
ServerLink,
|
|
75
|
+
UplinkCollector,
|
|
76
|
+
UplinkCounter,
|
|
77
|
+
command,
|
|
78
|
+
decode_readings,
|
|
79
|
+
derive_net_route,
|
|
80
|
+
derive_session,
|
|
81
|
+
dev_tag,
|
|
82
|
+
downlink_msg_body,
|
|
83
|
+
downlink_payload,
|
|
84
|
+
encode_reading,
|
|
85
|
+
envelope,
|
|
86
|
+
epoch_of,
|
|
87
|
+
header,
|
|
88
|
+
hello_body,
|
|
89
|
+
hello_request_body,
|
|
90
|
+
is_downlink,
|
|
91
|
+
keys_from,
|
|
92
|
+
net_tag,
|
|
93
|
+
open_envelope,
|
|
94
|
+
open_frame,
|
|
95
|
+
parse_header,
|
|
96
|
+
parse_hello,
|
|
97
|
+
parse_server_status,
|
|
98
|
+
parse_tx_result,
|
|
99
|
+
parse_uplink,
|
|
100
|
+
qr_encode,
|
|
101
|
+
qr_parse,
|
|
102
|
+
seal,
|
|
103
|
+
server_status_body,
|
|
104
|
+
tx_result_body,
|
|
105
|
+
unwrap,
|
|
106
|
+
uplink_body,
|
|
107
|
+
x25519_pub,
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
__version__ = "0.1.0"
|
|
111
|
+
|
|
112
|
+
__all__ = [
|
|
113
|
+
# 02 frames: constants
|
|
114
|
+
"MAGIC",
|
|
115
|
+
"VERSION",
|
|
116
|
+
"HEADER_LEN",
|
|
117
|
+
"MIC_LEN",
|
|
118
|
+
"MAX_PAYLOAD",
|
|
119
|
+
"MIN_FRAME",
|
|
120
|
+
"MAX_FRAME",
|
|
121
|
+
"EPOCH_SECONDS",
|
|
122
|
+
"ZERO_TAG",
|
|
123
|
+
"T_DATA",
|
|
124
|
+
"T_DATA_CONFIRMED",
|
|
125
|
+
"T_HEARTBEAT",
|
|
126
|
+
"T_HEARTBEAT_CONFIRMED",
|
|
127
|
+
"T_JOIN",
|
|
128
|
+
"T_SYNC",
|
|
129
|
+
"T_DOWNLINK",
|
|
130
|
+
"DIR_UP",
|
|
131
|
+
"DIR_DOWN",
|
|
132
|
+
"UF_DL_ACK",
|
|
133
|
+
"UF_TIME_UNSURE",
|
|
134
|
+
"DF_PENDING",
|
|
135
|
+
"CMD_SET_NETWORK",
|
|
136
|
+
"CMD_SET_HEARTBEAT",
|
|
137
|
+
"CMD_LEAVE",
|
|
138
|
+
"CMD_KEY_EXCHANGE",
|
|
139
|
+
"CMD_SET_CHANNEL",
|
|
140
|
+
# 02 frames: keys, tags, sealing
|
|
141
|
+
"DeviceKeys",
|
|
142
|
+
"ParsedHeader",
|
|
143
|
+
"keys_from",
|
|
144
|
+
"derive_net_route",
|
|
145
|
+
"derive_session",
|
|
146
|
+
"x25519_pub",
|
|
147
|
+
"epoch_of",
|
|
148
|
+
"net_tag",
|
|
149
|
+
"dev_tag",
|
|
150
|
+
"header",
|
|
151
|
+
"parse_header",
|
|
152
|
+
"is_downlink",
|
|
153
|
+
"seal",
|
|
154
|
+
"open_frame",
|
|
155
|
+
"downlink_payload",
|
|
156
|
+
"command",
|
|
157
|
+
# 03 payload
|
|
158
|
+
"KINDS",
|
|
159
|
+
"encode_reading",
|
|
160
|
+
"decode_readings",
|
|
161
|
+
"unwrap",
|
|
162
|
+
# 04 pairing codes and JOIN
|
|
163
|
+
"qr_encode",
|
|
164
|
+
"qr_parse",
|
|
165
|
+
"JoinResponder",
|
|
166
|
+
# 05 proxy envelope
|
|
167
|
+
"ENV_VERSION",
|
|
168
|
+
"ENV_HEADER",
|
|
169
|
+
"ENV_MAC",
|
|
170
|
+
"M_UPLINK",
|
|
171
|
+
"M_HELLO",
|
|
172
|
+
"M_TX_RESULT",
|
|
173
|
+
"M_SERVER_STATUS",
|
|
174
|
+
"M_DOWNLINK",
|
|
175
|
+
"M_HELLO_REQUEST",
|
|
176
|
+
"UPF_TS_UNCERTAIN",
|
|
177
|
+
"CAP_DOWNLINK",
|
|
178
|
+
"CAP_FEDERATION",
|
|
179
|
+
"envelope",
|
|
180
|
+
"open_envelope",
|
|
181
|
+
"uplink_body",
|
|
182
|
+
"parse_uplink",
|
|
183
|
+
"hello_body",
|
|
184
|
+
"parse_hello",
|
|
185
|
+
"server_status_body",
|
|
186
|
+
"parse_server_status",
|
|
187
|
+
"hello_request_body",
|
|
188
|
+
"downlink_msg_body",
|
|
189
|
+
"tx_result_body",
|
|
190
|
+
"parse_tx_result",
|
|
191
|
+
"ServerLink",
|
|
192
|
+
"REQUEST_NONCE_MS",
|
|
193
|
+
"REQUEST_RESEND_MS",
|
|
194
|
+
"REQUEST_BOOTS",
|
|
195
|
+
# 07 network server
|
|
196
|
+
"UplinkCounter",
|
|
197
|
+
"UplinkCollector",
|
|
198
|
+
"REORDER_WINDOW",
|
|
199
|
+
"MERGE_WINDOW_MS",
|
|
200
|
+
"FRAME_MEMORY_MS",
|
|
201
|
+
"MAX_ANSWERS_AGAIN",
|
|
202
|
+
"__version__",
|
|
203
|
+
]
|
|
File without changes
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Chris Uthe and ConnectSensors contributors
|
|
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.
|