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.
Files changed (68) hide show
  1. esp32tl/__init__.py +9 -0
  2. esp32tl/backends/__init__.py +5 -0
  3. esp32tl/backends/clock.py +275 -0
  4. esp32tl/backends/esp32sim.py +1324 -0
  5. esp32tl/backends/serial.py +594 -0
  6. esp32tl/bluetooth/__init__.py +2 -0
  7. esp32tl/bluetooth/air.py +366 -0
  8. esp32tl/bluetooth/controller.py +1825 -0
  9. esp32tl/bluetooth/guest.py +67 -0
  10. esp32tl/bluetooth/peer.py +676 -0
  11. esp32tl/boards/__init__.py +289 -0
  12. esp32tl/boards/capabilities.py +139 -0
  13. esp32tl/boards/capabilities.toml +32 -0
  14. esp32tl/boards/esp32-devkitc.toml +26 -0
  15. esp32tl/boards/gps-alarm-clock.toml +14 -0
  16. esp32tl/boards/lilygo-t-a7670g-r2.toml +44 -0
  17. esp32tl/boards/sd-data-logger.toml +20 -0
  18. esp32tl/build.py +297 -0
  19. esp32tl/cli.py +302 -0
  20. esp32tl/flash.py +465 -0
  21. esp32tl/interfaces/__init__.py +21 -0
  22. esp32tl/interfaces/bluetooth.py +364 -0
  23. esp32tl/interfaces/board.py +197 -0
  24. esp32tl/interfaces/card_cache.py +212 -0
  25. esp32tl/interfaces/condition.py +54 -0
  26. esp32tl/interfaces/console.py +342 -0
  27. esp32tl/interfaces/gnss.py +118 -0
  28. esp32tl/interfaces/lines.py +356 -0
  29. esp32tl/interfaces/modem.py +236 -0
  30. esp32tl/interfaces/sd_card.py +779 -0
  31. esp32tl/interfaces/uart.py +348 -0
  32. esp32tl/interfaces/wifi.py +406 -0
  33. esp32tl/link/__init__.py +1 -0
  34. esp32tl/link/boardlink.py +919 -0
  35. esp32tl/link/protocol.py +819 -0
  36. esp32tl/matching.py +275 -0
  37. esp32tl/net/__init__.py +588 -0
  38. esp32tl/net/bridge.py +263 -0
  39. esp32tl/net/client.py +282 -0
  40. esp32tl/net/dhcp.py +153 -0
  41. esp32tl/net/dns.py +56 -0
  42. esp32tl/net/ethernet.py +157 -0
  43. esp32tl/net/http.py +272 -0
  44. esp32tl/net/http_client.py +282 -0
  45. esp32tl/net/ip.py +439 -0
  46. esp32tl/net/mqtt.py +955 -0
  47. esp32tl/net/ntp.py +54 -0
  48. esp32tl/net/ppp.py +289 -0
  49. esp32tl/net/station.py +253 -0
  50. esp32tl/net/tls.py +726 -0
  51. esp32tl/py.typed +0 -0
  52. esp32tl/pytest_plugin.py +655 -0
  53. esp32tl/recording.py +481 -0
  54. esp32tl/report.py +182 -0
  55. esp32tl/runtime.py +174 -0
  56. esp32tl/sources/__init__.py +1 -0
  57. esp32tl/sources/model/__init__.py +199 -0
  58. esp32tl/sources/model/gnss.py +318 -0
  59. esp32tl/sources/model/modem.py +508 -0
  60. esp32tl/sources/real.py +234 -0
  61. esp32tl/sources/replay.py +40 -0
  62. esp32tl/tap.py +89 -0
  63. esp32tl/units.py +512 -0
  64. esp32tl-0.1.0.dist-info/METADATA +237 -0
  65. esp32tl-0.1.0.dist-info/RECORD +68 -0
  66. esp32tl-0.1.0.dist-info/WHEEL +4 -0
  67. esp32tl-0.1.0.dist-info/entry_points.txt +5 -0
  68. 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