esp32tl 0.1.0__py3-none-any.whl
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.
- esp32tl/__init__.py +9 -0
- esp32tl/backends/__init__.py +5 -0
- esp32tl/backends/clock.py +275 -0
- esp32tl/backends/esp32sim.py +1324 -0
- esp32tl/backends/serial.py +594 -0
- esp32tl/bluetooth/__init__.py +2 -0
- esp32tl/bluetooth/air.py +366 -0
- esp32tl/bluetooth/controller.py +1825 -0
- esp32tl/bluetooth/guest.py +67 -0
- esp32tl/bluetooth/peer.py +676 -0
- esp32tl/boards/__init__.py +289 -0
- esp32tl/boards/capabilities.py +139 -0
- esp32tl/boards/capabilities.toml +32 -0
- esp32tl/boards/esp32-devkitc.toml +26 -0
- esp32tl/boards/gps-alarm-clock.toml +14 -0
- esp32tl/boards/lilygo-t-a7670g-r2.toml +44 -0
- esp32tl/boards/sd-data-logger.toml +20 -0
- esp32tl/build.py +297 -0
- esp32tl/cli.py +302 -0
- esp32tl/flash.py +465 -0
- esp32tl/interfaces/__init__.py +21 -0
- esp32tl/interfaces/bluetooth.py +364 -0
- esp32tl/interfaces/board.py +197 -0
- esp32tl/interfaces/card_cache.py +212 -0
- esp32tl/interfaces/condition.py +54 -0
- esp32tl/interfaces/console.py +342 -0
- esp32tl/interfaces/gnss.py +118 -0
- esp32tl/interfaces/lines.py +356 -0
- esp32tl/interfaces/modem.py +236 -0
- esp32tl/interfaces/sd_card.py +779 -0
- esp32tl/interfaces/uart.py +348 -0
- esp32tl/interfaces/wifi.py +406 -0
- esp32tl/link/__init__.py +1 -0
- esp32tl/link/boardlink.py +919 -0
- esp32tl/link/protocol.py +819 -0
- esp32tl/matching.py +275 -0
- esp32tl/net/__init__.py +588 -0
- esp32tl/net/bridge.py +263 -0
- esp32tl/net/client.py +282 -0
- esp32tl/net/dhcp.py +153 -0
- esp32tl/net/dns.py +56 -0
- esp32tl/net/ethernet.py +157 -0
- esp32tl/net/http.py +272 -0
- esp32tl/net/http_client.py +282 -0
- esp32tl/net/ip.py +439 -0
- esp32tl/net/mqtt.py +955 -0
- esp32tl/net/ntp.py +54 -0
- esp32tl/net/ppp.py +289 -0
- esp32tl/net/station.py +253 -0
- esp32tl/net/tls.py +726 -0
- esp32tl/py.typed +0 -0
- esp32tl/pytest_plugin.py +655 -0
- esp32tl/recording.py +481 -0
- esp32tl/report.py +182 -0
- esp32tl/runtime.py +174 -0
- esp32tl/sources/__init__.py +1 -0
- esp32tl/sources/model/__init__.py +199 -0
- esp32tl/sources/model/gnss.py +318 -0
- esp32tl/sources/model/modem.py +508 -0
- esp32tl/sources/real.py +234 -0
- esp32tl/sources/replay.py +40 -0
- esp32tl/tap.py +89 -0
- esp32tl/units.py +512 -0
- esp32tl-0.1.0.dist-info/METADATA +237 -0
- esp32tl-0.1.0.dist-info/RECORD +68 -0
- esp32tl-0.1.0.dist-info/WHEEL +4 -0
- esp32tl-0.1.0.dist-info/entry_points.txt +5 -0
- esp32tl-0.1.0.dist-info/licenses/LICENSE +21 -0
esp32tl/__init__.py
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""esp32tl: test unmodified ESP32 firmware through its wires."""
|
|
2
|
+
|
|
3
|
+
from importlib.metadata import version
|
|
4
|
+
|
|
5
|
+
__version__ = version("esp32tl")
|
|
6
|
+
|
|
7
|
+
from esp32tl.interfaces.board import Board as Board
|
|
8
|
+
from esp32tl.interfaces.condition import Condition as Condition
|
|
9
|
+
from esp32tl.interfaces.condition import condition as condition
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
"""Backends: `esp32sim` (the runner, emulated clock) and `serial` (a real board, wall clock)."""
|
|
2
|
+
|
|
3
|
+
# The `embedded_services` each backend runs under, in the order tests are parametrised; None is no
|
|
4
|
+
# service, pytest-embedded's base `Dut`. Serial is opt-in through --esp32tl-backend serial.
|
|
5
|
+
SERVICES: dict[str, str | None] = {"esp32sim": None, "serial": "esp,idf"}
|
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
"""The board's clock, held by the test: emulated time moves only while the test waits.
|
|
2
|
+
|
|
3
|
+
The runner stops at every turn of the link and waits for the harness's `wait` (protocol §4).
|
|
4
|
+
`HeldClock` keeps the link's thread in each turn for as long as the test is not waiting, so the
|
|
5
|
+
guest stands still while the test body runs, and whatever the test changes lands at the emulated
|
|
6
|
+
instant the test saw. `wait` lets the run go to a time; `wait_until` lets it go in steps of at
|
|
7
|
+
most `STEP_NS`, and asks the test's condition at every turn, in the test's own thread, while the
|
|
8
|
+
link is held. `wait_for_event` lets it go to its deadline at once, with a `latency` that has the
|
|
9
|
+
runner take a turn soon after each event, and asks its condition at those turns only: the wait
|
|
10
|
+
through a deep sleep, in which nothing happens until the chip wakes. `dump_flash` has the link
|
|
11
|
+
ask the runner for the flash in the turn it is held at, on the link's thread, and the turn goes
|
|
12
|
+
on: the board's time does not move. Times here are nanoseconds on the board's clock, from
|
|
13
|
+
power-on.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
import threading
|
|
17
|
+
from collections.abc import Callable
|
|
18
|
+
from typing import TypeVar
|
|
19
|
+
|
|
20
|
+
from esp32tl.interfaces import NeverHappened, RunEnded
|
|
21
|
+
from esp32tl.link.boardlink import RunTo
|
|
22
|
+
from esp32tl.link.protocol import FlashDump, FlashDumpAck
|
|
23
|
+
from esp32tl.units import Duration
|
|
24
|
+
|
|
25
|
+
# How far the run may go between two looks at a condition, 100 emulated milliseconds: how late
|
|
26
|
+
# after what it waits for a `wait_until` returns, when no other turn of the link comes sooner.
|
|
27
|
+
STEP_NS = 100_000_000
|
|
28
|
+
|
|
29
|
+
T = TypeVar("T")
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class HeldClock:
|
|
33
|
+
"""The link's `Hold` for a run on the test's clock, and the test's side of it.
|
|
34
|
+
|
|
35
|
+
The link calls `turn` from its thread; the test calls `wait` and `wait_until` from its own.
|
|
36
|
+
`stop` is the link's alone: from then on the link stops the run at the turn it is held at, or
|
|
37
|
+
at its next one, as at the end of the test. `end` is for the backend once the run is over: a
|
|
38
|
+
test that waits gets `RunEnded` with the reason.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
def __init__(self, step: int = STEP_NS) -> None:
|
|
42
|
+
self._step = step
|
|
43
|
+
self._cv = threading.Condition()
|
|
44
|
+
self._now = 0
|
|
45
|
+
# The turns the link has been held at, so that the test can tell the next one.
|
|
46
|
+
self._turns = 0
|
|
47
|
+
# Whether the link's thread is in a turn, waiting for the test.
|
|
48
|
+
self._held = False
|
|
49
|
+
# How far the test lets the run go from the turn it is held at; None while it does not.
|
|
50
|
+
self._until: int | None = None
|
|
51
|
+
# How soon after an event the test wants the next turn; None for no sooner than _until.
|
|
52
|
+
self._latency: int | None = None
|
|
53
|
+
# The test asks for the flash in the turn; the runner's answer, once it has come.
|
|
54
|
+
self._dump_asked = False
|
|
55
|
+
self._dumped: FlashDumpAck | None = None
|
|
56
|
+
self._stopped = False
|
|
57
|
+
self._ended: str | None = None
|
|
58
|
+
# Where the run ended, when the runner said so in its stats.
|
|
59
|
+
self._ended_at: int | None = None
|
|
60
|
+
|
|
61
|
+
# The link's side.
|
|
62
|
+
|
|
63
|
+
def turn(self, now: int) -> int | RunTo | FlashDump | None:
|
|
64
|
+
"""Holds the link's turn at the block point `now` until the test waits; then returns
|
|
65
|
+
the latest time of the next turn, as a `RunTo` when the wait asks for a turn soon after
|
|
66
|
+
each event, or `None` once the test is over or the run has ended, for the link to stop
|
|
67
|
+
the run. Returns `FlashDump` when the test asks for the flash."""
|
|
68
|
+
with self._cv:
|
|
69
|
+
self._now = now
|
|
70
|
+
self._turns += 1
|
|
71
|
+
self._until = None
|
|
72
|
+
self._latency = None
|
|
73
|
+
return self._hold_turn()
|
|
74
|
+
|
|
75
|
+
def dumped(self, ack: FlashDumpAck) -> int | RunTo | FlashDump | None:
|
|
76
|
+
"""The runner's answer goes to the test, and the same turn is held on: as `turn`."""
|
|
77
|
+
with self._cv:
|
|
78
|
+
self._dumped = ack
|
|
79
|
+
return self._hold_turn()
|
|
80
|
+
|
|
81
|
+
def _hold_turn(self) -> int | RunTo | FlashDump | None:
|
|
82
|
+
self._held = True
|
|
83
|
+
self._cv.notify_all()
|
|
84
|
+
while (
|
|
85
|
+
self._until is None
|
|
86
|
+
and not self._dump_asked
|
|
87
|
+
and not self._stopped
|
|
88
|
+
and self._ended is None
|
|
89
|
+
):
|
|
90
|
+
self._cv.wait()
|
|
91
|
+
self._held = False
|
|
92
|
+
if self._stopped or self._ended:
|
|
93
|
+
return None
|
|
94
|
+
if self._dump_asked:
|
|
95
|
+
self._dump_asked = False
|
|
96
|
+
return FlashDump()
|
|
97
|
+
if self._latency is not None and self._until is not None:
|
|
98
|
+
return RunTo(self._until, self._latency)
|
|
99
|
+
return self._until
|
|
100
|
+
|
|
101
|
+
def stop(self) -> bool:
|
|
102
|
+
"""The link stops the run at its turn, and holds no turn any more. Returns whether the
|
|
103
|
+
link is held at one now, so that the stop goes out at once."""
|
|
104
|
+
with self._cv:
|
|
105
|
+
self._stopped = True
|
|
106
|
+
self._cv.notify_all()
|
|
107
|
+
return self._held
|
|
108
|
+
|
|
109
|
+
def end(self, reason: str, at: int | None = None) -> None:
|
|
110
|
+
"""The run is over, for `reason`, at the board's time `at` when it is known: a test that
|
|
111
|
+
waits, or waits later, gets `RunEnded`."""
|
|
112
|
+
with self._cv:
|
|
113
|
+
if self._ended is None:
|
|
114
|
+
self._ended = reason
|
|
115
|
+
self._ended_at = at
|
|
116
|
+
self._cv.notify_all()
|
|
117
|
+
|
|
118
|
+
# The test's side.
|
|
119
|
+
|
|
120
|
+
def check(self, step: str) -> None:
|
|
121
|
+
"""Raises `RunEnded` once the run has ended: `step`, a call on the board, can no longer
|
|
122
|
+
reach it."""
|
|
123
|
+
with self._cv:
|
|
124
|
+
if self._ended is not None:
|
|
125
|
+
raise RunEnded(f"the run ended {self._when()} before {step}: {self._ended}")
|
|
126
|
+
|
|
127
|
+
@property
|
|
128
|
+
def now(self) -> int:
|
|
129
|
+
"""The block point of the turn the link was last held at: 0 until the first."""
|
|
130
|
+
with self._cv:
|
|
131
|
+
return self._now
|
|
132
|
+
|
|
133
|
+
@property
|
|
134
|
+
def ended(self) -> bool:
|
|
135
|
+
"""Whether the run is over: no turn is coming, and nothing more reaches the runner."""
|
|
136
|
+
with self._cv:
|
|
137
|
+
return self._ended is not None
|
|
138
|
+
|
|
139
|
+
def dump_flash(self) -> FlashDumpAck | None:
|
|
140
|
+
"""Has the runner write the flash in the turn the link is held at, and returns its answer;
|
|
141
|
+
`None` once the run is over, when the runner has written it for the last time. Emulated
|
|
142
|
+
time does not move."""
|
|
143
|
+
with self._cv:
|
|
144
|
+
while not self._held and self._ended is None:
|
|
145
|
+
self._cv.wait()
|
|
146
|
+
if self._ended is not None:
|
|
147
|
+
return None
|
|
148
|
+
self._dumped = None
|
|
149
|
+
self._dump_asked = True
|
|
150
|
+
self._cv.notify_all()
|
|
151
|
+
while self._dumped is None and self._ended is None:
|
|
152
|
+
self._cv.wait()
|
|
153
|
+
self._dump_asked = False
|
|
154
|
+
return self._dumped
|
|
155
|
+
|
|
156
|
+
def wait(self, duration: int) -> None:
|
|
157
|
+
"""Lets the run go for `duration` from now, and returns at the turn at its end."""
|
|
158
|
+
with self._cv:
|
|
159
|
+
self._settle(f"until {seconds(self._now + duration)}")
|
|
160
|
+
deadline = self._now + duration
|
|
161
|
+
while self._now < deadline:
|
|
162
|
+
self._advance(deadline, f"until {seconds(deadline)}")
|
|
163
|
+
|
|
164
|
+
def wait_until(self, condition: Callable[[], T | None], within: int, description: str) -> T:
|
|
165
|
+
"""Lets the run go until `condition` returns something true, asked now and at every
|
|
166
|
+
turn, for at most `within` from now; returns what it returned. `description` names it
|
|
167
|
+
in `NeverHappened` and `RunEnded`."""
|
|
168
|
+
return self._wait(condition, within, description, self._step, None)
|
|
169
|
+
|
|
170
|
+
def wait_for_event(
|
|
171
|
+
self, condition: Callable[[], T | None], within: int, description: str, latency: int
|
|
172
|
+
) -> T:
|
|
173
|
+
"""`wait_until` without its steps: lets the run go to `within` from now, and asks
|
|
174
|
+
`condition` now and at every turn the link takes, which comes no later than `latency`
|
|
175
|
+
after each event the runner sends. For a condition only an event can make true, as a
|
|
176
|
+
chip's reset; a wait through a stretch without events takes no turn."""
|
|
177
|
+
return self._wait(condition, within, description, None, latency)
|
|
178
|
+
|
|
179
|
+
def _wait(
|
|
180
|
+
self,
|
|
181
|
+
condition: Callable[[], T | None],
|
|
182
|
+
within: int,
|
|
183
|
+
description: str,
|
|
184
|
+
step: int | None,
|
|
185
|
+
latency: int | None,
|
|
186
|
+
) -> T:
|
|
187
|
+
what = f"for {description}"
|
|
188
|
+
with self._cv:
|
|
189
|
+
try:
|
|
190
|
+
self._settle(what)
|
|
191
|
+
except RunEnded as ended:
|
|
192
|
+
over: RunEnded | None = ended
|
|
193
|
+
else:
|
|
194
|
+
over = None
|
|
195
|
+
start = self._now
|
|
196
|
+
if over is not None:
|
|
197
|
+
# The run is over, and all it did is in: what it left may still hold.
|
|
198
|
+
value = condition()
|
|
199
|
+
if value:
|
|
200
|
+
return value
|
|
201
|
+
raise over
|
|
202
|
+
deadline = start + within
|
|
203
|
+
while True:
|
|
204
|
+
# Outside the lock, in the test's thread: the link is held, or done.
|
|
205
|
+
value = condition()
|
|
206
|
+
if value:
|
|
207
|
+
return value
|
|
208
|
+
with self._cv:
|
|
209
|
+
if self._now >= deadline:
|
|
210
|
+
raise NeverHappened(
|
|
211
|
+
f"{description} did not happen within {seconds(within)}: waited from"
|
|
212
|
+
f" {seconds(start)} to {seconds(self._now)} of the board's time"
|
|
213
|
+
)
|
|
214
|
+
until = deadline if step is None else min(deadline, self._now + step)
|
|
215
|
+
try:
|
|
216
|
+
self._advance(until, what, latency)
|
|
217
|
+
except RunEnded as ended:
|
|
218
|
+
error = ended
|
|
219
|
+
else:
|
|
220
|
+
continue
|
|
221
|
+
# What the run did last is in by the time it has ended.
|
|
222
|
+
value = condition()
|
|
223
|
+
if value:
|
|
224
|
+
return value
|
|
225
|
+
raise error
|
|
226
|
+
|
|
227
|
+
def _settle(self, what: str) -> None:
|
|
228
|
+
"""Waits, holding the lock, until the link is held at a turn: from power-on to the
|
|
229
|
+
first `sync`, while the runner loads the images."""
|
|
230
|
+
while not self._held and self._ended is None:
|
|
231
|
+
self._cv.wait()
|
|
232
|
+
if not self._held:
|
|
233
|
+
raise self._run_ended(what)
|
|
234
|
+
|
|
235
|
+
def _advance(self, until: int, what: str, latency: int | None = None) -> None:
|
|
236
|
+
"""Lets the run go to `until` at most, with a turn no later than `latency` after each
|
|
237
|
+
event when it is given, holding the lock, and returns at the next turn."""
|
|
238
|
+
self._settle(what)
|
|
239
|
+
turns = self._turns
|
|
240
|
+
self._until = until
|
|
241
|
+
self._latency = latency
|
|
242
|
+
self._cv.notify_all()
|
|
243
|
+
while self._turns == turns and self._ended is None:
|
|
244
|
+
self._cv.wait()
|
|
245
|
+
if self._turns == turns:
|
|
246
|
+
raise self._run_ended(what)
|
|
247
|
+
|
|
248
|
+
def _run_ended(self, what: str) -> RunEnded:
|
|
249
|
+
return RunEnded(f"the run ended {self._when()} while the test waited {what}: {self._ended}")
|
|
250
|
+
|
|
251
|
+
def _when(self) -> str:
|
|
252
|
+
# The last turn is no more than a bound on where the run ended: the runner may have run
|
|
253
|
+
# on to its next block point, or have died anywhere before it.
|
|
254
|
+
if self._ended_at is not None:
|
|
255
|
+
return f"at {seconds(self._ended_at)}"
|
|
256
|
+
if self._turns == 0:
|
|
257
|
+
return "before its first turn"
|
|
258
|
+
return f"after the turn at {seconds(self._now)}"
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
def seconds(ns: int) -> str:
|
|
262
|
+
"""`ns` as seconds, without trailing zeros: `12.5 s`, `30 s`."""
|
|
263
|
+
return str(Duration(ns))
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
def nanoseconds(value: Duration, what: str) -> int:
|
|
267
|
+
"""`value`, a `Duration` of the board's time, 0 or more, in nanoseconds; a `TypeError` for
|
|
268
|
+
anything else, which names `what` took it, and a `ValueError` for one below 0."""
|
|
269
|
+
if not isinstance(value, Duration):
|
|
270
|
+
plain = isinstance(value, int | float) and not isinstance(value, bool)
|
|
271
|
+
example = f"seconds({value!r})" if plain else "seconds(5)"
|
|
272
|
+
raise TypeError(f"{what} takes a Duration, as {example}, not {value!r}")
|
|
273
|
+
if value.ns < 0:
|
|
274
|
+
raise ValueError(f"{what} takes a Duration of 0 or more, not {value}")
|
|
275
|
+
return value.ns
|