esp32tl 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.
Files changed (355) hide show
  1. esp32tl-0.1.0/.agents/skills/create-pr/SKILL.md +278 -0
  2. esp32tl-0.1.0/.claude/rules/documentation.md +55 -0
  3. esp32tl-0.1.0/.github/actions/restore-firmware/action.yml +55 -0
  4. esp32tl-0.1.0/.github/pull_request_template.md +43 -0
  5. esp32tl-0.1.0/.github/scripts/release-version.py +102 -0
  6. esp32tl-0.1.0/.github/scripts/test-pair.py +121 -0
  7. esp32tl-0.1.0/.github/workflows/build-firmware.yml +223 -0
  8. esp32tl-0.1.0/.github/workflows/build-runner.yml +97 -0
  9. esp32tl-0.1.0/.github/workflows/ci.yml +239 -0
  10. esp32tl-0.1.0/.github/workflows/prepare-release.yml +64 -0
  11. esp32tl-0.1.0/.github/workflows/publish-pypi.yml +53 -0
  12. esp32tl-0.1.0/.github/workflows/release-on-merge.yml +54 -0
  13. esp32tl-0.1.0/.github/workflows/runtime-release.yml +211 -0
  14. esp32tl-0.1.0/.github/workflows/test-platform.yml +138 -0
  15. esp32tl-0.1.0/.gitignore +37 -0
  16. esp32tl-0.1.0/.pre-commit-config.yaml +49 -0
  17. esp32tl-0.1.0/AGENTS.md +80 -0
  18. esp32tl-0.1.0/CLAUDE.md +1 -0
  19. esp32tl-0.1.0/CONTRIBUTING.md +135 -0
  20. esp32tl-0.1.0/LICENSE +21 -0
  21. esp32tl-0.1.0/Makefile +107 -0
  22. esp32tl-0.1.0/PKG-INFO +237 -0
  23. esp32tl-0.1.0/README.md +196 -0
  24. esp32tl-0.1.0/docs/README.md +24 -0
  25. esp32tl-0.1.0/docs/cicd.md +583 -0
  26. esp32tl-0.1.0/docs/decisions/README.md +372 -0
  27. esp32tl-0.1.0/docs/decisions/ci.md +690 -0
  28. esp32tl-0.1.0/docs/decisions/docs.md +281 -0
  29. esp32tl-0.1.0/docs/decisions/firmware.md +477 -0
  30. esp32tl-0.1.0/docs/decisions/harness.md +3884 -0
  31. esp32tl-0.1.0/docs/decisions/runner.md +1041 -0
  32. esp32tl-0.1.0/docs/features/README.md +102 -0
  33. esp32tl-0.1.0/docs/features/bluetooth-peer-technical.md +946 -0
  34. esp32tl-0.1.0/docs/features/bluetooth-peer-user.md +507 -0
  35. esp32tl-0.1.0/docs/features/board-profiles-technical.md +322 -0
  36. esp32tl-0.1.0/docs/features/board-profiles-user.md +334 -0
  37. esp32tl-0.1.0/docs/features/builds-technical.md +206 -0
  38. esp32tl-0.1.0/docs/features/builds-user.md +136 -0
  39. esp32tl-0.1.0/docs/features/cli-user.md +195 -0
  40. esp32tl-0.1.0/docs/features/esp32sim-backend-technical.md +737 -0
  41. esp32tl-0.1.0/docs/features/esp32sim-backend-user.md +365 -0
  42. esp32tl-0.1.0/docs/features/examples-technical.md +385 -0
  43. esp32tl-0.1.0/docs/features/examples-user.md +483 -0
  44. esp32tl-0.1.0/docs/features/flash-contents-technical.md +226 -0
  45. esp32tl-0.1.0/docs/features/flash-contents-user.md +176 -0
  46. esp32tl-0.1.0/docs/features/matching-technical.md +92 -0
  47. esp32tl-0.1.0/docs/features/matching-user.md +83 -0
  48. esp32tl-0.1.0/docs/features/models-technical.md +186 -0
  49. esp32tl-0.1.0/docs/features/models-user.md +282 -0
  50. esp32tl-0.1.0/docs/features/modem-technical.md +161 -0
  51. esp32tl-0.1.0/docs/features/modem-user.md +304 -0
  52. esp32tl-0.1.0/docs/features/network-technical.md +772 -0
  53. esp32tl-0.1.0/docs/features/network-user.md +1213 -0
  54. esp32tl-0.1.0/docs/features/pytest-plugin-technical.md +835 -0
  55. esp32tl-0.1.0/docs/features/pytest-plugin-user.md +1337 -0
  56. esp32tl-0.1.0/docs/features/real-source-technical.md +163 -0
  57. esp32tl-0.1.0/docs/features/real-source-user.md +162 -0
  58. esp32tl-0.1.0/docs/features/replay-technical.md +112 -0
  59. esp32tl-0.1.0/docs/features/replay-user.md +140 -0
  60. esp32tl-0.1.0/docs/features/run-report-technical.md +328 -0
  61. esp32tl-0.1.0/docs/features/run-report-user.md +262 -0
  62. esp32tl-0.1.0/docs/features/runner-technical.md +1151 -0
  63. esp32tl-0.1.0/docs/features/runner-user.md +488 -0
  64. esp32tl-0.1.0/docs/features/runtime-user.md +92 -0
  65. esp32tl-0.1.0/docs/features/serial-backend-technical.md +385 -0
  66. esp32tl-0.1.0/docs/features/serial-backend-user.md +303 -0
  67. esp32tl-0.1.0/docs/features/validation-firmware-technical.md +1045 -0
  68. esp32tl-0.1.0/docs/features/validation-firmware-user.md +814 -0
  69. esp32tl-0.1.0/docs/guides/development.md +281 -0
  70. esp32tl-0.1.0/docs/guides/documentation.md +252 -0
  71. esp32tl-0.1.0/docs/guides/testing.md +524 -0
  72. esp32tl-0.1.0/docs/guides/writing-tests.md +462 -0
  73. esp32tl-0.1.0/docs/implementation-plan.md +830 -0
  74. esp32tl-0.1.0/docs/invariants.md +1912 -0
  75. esp32tl-0.1.0/docs/protocol.md +1552 -0
  76. esp32tl-0.1.0/docs/recording-format.md +258 -0
  77. esp32tl-0.1.0/docs/stage0-findings.md +307 -0
  78. esp32tl-0.1.0/esp32tl/__init__.py +9 -0
  79. esp32tl-0.1.0/esp32tl/backends/__init__.py +5 -0
  80. esp32tl-0.1.0/esp32tl/backends/clock.py +275 -0
  81. esp32tl-0.1.0/esp32tl/backends/esp32sim.py +1324 -0
  82. esp32tl-0.1.0/esp32tl/backends/serial.py +594 -0
  83. esp32tl-0.1.0/esp32tl/bluetooth/__init__.py +2 -0
  84. esp32tl-0.1.0/esp32tl/bluetooth/air.py +366 -0
  85. esp32tl-0.1.0/esp32tl/bluetooth/controller.py +1825 -0
  86. esp32tl-0.1.0/esp32tl/bluetooth/guest.py +67 -0
  87. esp32tl-0.1.0/esp32tl/bluetooth/peer.py +676 -0
  88. esp32tl-0.1.0/esp32tl/boards/__init__.py +289 -0
  89. esp32tl-0.1.0/esp32tl/boards/capabilities.py +139 -0
  90. esp32tl-0.1.0/esp32tl/boards/capabilities.toml +32 -0
  91. esp32tl-0.1.0/esp32tl/boards/esp32-devkitc.toml +26 -0
  92. esp32tl-0.1.0/esp32tl/boards/gps-alarm-clock.toml +14 -0
  93. esp32tl-0.1.0/esp32tl/boards/lilygo-t-a7670g-r2.toml +44 -0
  94. esp32tl-0.1.0/esp32tl/boards/sd-data-logger.toml +20 -0
  95. esp32tl-0.1.0/esp32tl/build.py +297 -0
  96. esp32tl-0.1.0/esp32tl/cli.py +302 -0
  97. esp32tl-0.1.0/esp32tl/flash.py +465 -0
  98. esp32tl-0.1.0/esp32tl/interfaces/__init__.py +21 -0
  99. esp32tl-0.1.0/esp32tl/interfaces/bluetooth.py +364 -0
  100. esp32tl-0.1.0/esp32tl/interfaces/board.py +197 -0
  101. esp32tl-0.1.0/esp32tl/interfaces/card_cache.py +212 -0
  102. esp32tl-0.1.0/esp32tl/interfaces/condition.py +54 -0
  103. esp32tl-0.1.0/esp32tl/interfaces/console.py +342 -0
  104. esp32tl-0.1.0/esp32tl/interfaces/gnss.py +118 -0
  105. esp32tl-0.1.0/esp32tl/interfaces/lines.py +356 -0
  106. esp32tl-0.1.0/esp32tl/interfaces/modem.py +236 -0
  107. esp32tl-0.1.0/esp32tl/interfaces/sd_card.py +779 -0
  108. esp32tl-0.1.0/esp32tl/interfaces/uart.py +348 -0
  109. esp32tl-0.1.0/esp32tl/interfaces/wifi.py +406 -0
  110. esp32tl-0.1.0/esp32tl/link/__init__.py +1 -0
  111. esp32tl-0.1.0/esp32tl/link/boardlink.py +919 -0
  112. esp32tl-0.1.0/esp32tl/link/protocol.py +819 -0
  113. esp32tl-0.1.0/esp32tl/matching.py +275 -0
  114. esp32tl-0.1.0/esp32tl/net/__init__.py +588 -0
  115. esp32tl-0.1.0/esp32tl/net/bridge.py +263 -0
  116. esp32tl-0.1.0/esp32tl/net/client.py +282 -0
  117. esp32tl-0.1.0/esp32tl/net/dhcp.py +153 -0
  118. esp32tl-0.1.0/esp32tl/net/dns.py +56 -0
  119. esp32tl-0.1.0/esp32tl/net/ethernet.py +157 -0
  120. esp32tl-0.1.0/esp32tl/net/http.py +272 -0
  121. esp32tl-0.1.0/esp32tl/net/http_client.py +282 -0
  122. esp32tl-0.1.0/esp32tl/net/ip.py +439 -0
  123. esp32tl-0.1.0/esp32tl/net/mqtt.py +955 -0
  124. esp32tl-0.1.0/esp32tl/net/ntp.py +54 -0
  125. esp32tl-0.1.0/esp32tl/net/ppp.py +289 -0
  126. esp32tl-0.1.0/esp32tl/net/station.py +253 -0
  127. esp32tl-0.1.0/esp32tl/net/tls.py +726 -0
  128. esp32tl-0.1.0/esp32tl/py.typed +0 -0
  129. esp32tl-0.1.0/esp32tl/pytest_plugin.py +655 -0
  130. esp32tl-0.1.0/esp32tl/recording.py +481 -0
  131. esp32tl-0.1.0/esp32tl/report.py +182 -0
  132. esp32tl-0.1.0/esp32tl/runtime.py +174 -0
  133. esp32tl-0.1.0/esp32tl/sources/__init__.py +1 -0
  134. esp32tl-0.1.0/esp32tl/sources/model/__init__.py +199 -0
  135. esp32tl-0.1.0/esp32tl/sources/model/gnss.py +318 -0
  136. esp32tl-0.1.0/esp32tl/sources/model/modem.py +508 -0
  137. esp32tl-0.1.0/esp32tl/sources/real.py +234 -0
  138. esp32tl-0.1.0/esp32tl/sources/replay.py +40 -0
  139. esp32tl-0.1.0/esp32tl/tap.py +89 -0
  140. esp32tl-0.1.0/esp32tl/units.py +512 -0
  141. esp32tl-0.1.0/examples/README.md +27 -0
  142. esp32tl-0.1.0/examples/gps_alarm_clock/CMakeLists.txt +3 -0
  143. esp32tl-0.1.0/examples/gps_alarm_clock/main/CMakeLists.txt +5 -0
  144. esp32tl-0.1.0/examples/gps_alarm_clock/main/main.c +98 -0
  145. esp32tl-0.1.0/examples/gps_alarm_clock/sdkconfig.defaults +1 -0
  146. esp32tl-0.1.0/examples/gps_alarm_clock/tests/test_alarm.py +160 -0
  147. esp32tl-0.1.0/examples/obd_reader/CMakeLists.txt +3 -0
  148. esp32tl-0.1.0/examples/obd_reader/main/CMakeLists.txt +2 -0
  149. esp32tl-0.1.0/examples/obd_reader/main/main.c +465 -0
  150. esp32tl-0.1.0/examples/obd_reader/sdkconfig.defaults +9 -0
  151. esp32tl-0.1.0/examples/obd_reader/tests/elm327.py +124 -0
  152. esp32tl-0.1.0/examples/obd_reader/tests/test_elm327.py +79 -0
  153. esp32tl-0.1.0/examples/obd_reader/tests/test_obd_reader.py +255 -0
  154. esp32tl-0.1.0/examples/periodic_wake/CMakeLists.txt +3 -0
  155. esp32tl-0.1.0/examples/periodic_wake/main/CMakeLists.txt +2 -0
  156. esp32tl-0.1.0/examples/periodic_wake/main/main.c +36 -0
  157. esp32tl-0.1.0/examples/periodic_wake/sdkconfig.defaults +3 -0
  158. esp32tl-0.1.0/examples/periodic_wake/tests/boards/periodic-wake.toml +8 -0
  159. esp32tl-0.1.0/examples/periodic_wake/tests/test_periodic_wake.py +116 -0
  160. esp32tl-0.1.0/examples/position_tracker/CMakeLists.txt +16 -0
  161. esp32tl-0.1.0/examples/position_tracker/main/CMakeLists.txt +4 -0
  162. esp32tl-0.1.0/examples/position_tracker/main/main.c +197 -0
  163. esp32tl-0.1.0/examples/position_tracker/sdkconfig.defaults +9 -0
  164. esp32tl-0.1.0/examples/position_tracker/tests/test_tracker.py +284 -0
  165. esp32tl-0.1.0/examples/position_tracker/tests/test_tracker_support.py +144 -0
  166. esp32tl-0.1.0/examples/position_tracker/tests/tracker_support.py +105 -0
  167. esp32tl-0.1.0/examples/sd_data_logger/CMakeLists.txt +3 -0
  168. esp32tl-0.1.0/examples/sd_data_logger/main/CMakeLists.txt +4 -0
  169. esp32tl-0.1.0/examples/sd_data_logger/main/main.c +154 -0
  170. esp32tl-0.1.0/examples/sd_data_logger/sdkconfig.defaults +1 -0
  171. esp32tl-0.1.0/examples/sd_data_logger/tests/test_logger.py +333 -0
  172. esp32tl-0.1.0/firmware/arduino_shell/platformio.ini +8 -0
  173. esp32tl-0.1.0/firmware/arduino_shell/src/main.cpp +152 -0
  174. esp32tl-0.1.0/firmware/bt_spp_initiator_psram/sdkconfig.defaults +7 -0
  175. esp32tl-0.1.0/firmware/build-platformio.sh +158 -0
  176. esp32tl-0.1.0/firmware/build.sh +221 -0
  177. esp32tl-0.1.0/firmware/console_repl/CMakeLists.txt +3 -0
  178. esp32tl-0.1.0/firmware/console_repl/main/CMakeLists.txt +1 -0
  179. esp32tl-0.1.0/firmware/console_repl/main/main.c +11 -0
  180. esp32tl-0.1.0/firmware/gpio_echo/CMakeLists.txt +3 -0
  181. esp32tl-0.1.0/firmware/gpio_echo/main/CMakeLists.txt +1 -0
  182. esp32tl-0.1.0/firmware/gpio_echo/main/Kconfig.projbuild +23 -0
  183. esp32tl-0.1.0/firmware/gpio_echo/main/main.c +70 -0
  184. esp32tl-0.1.0/firmware/http_server/CMakeLists.txt +3 -0
  185. esp32tl-0.1.0/firmware/http_server/main/CMakeLists.txt +3 -0
  186. esp32tl-0.1.0/firmware/http_server/main/main.c +118 -0
  187. esp32tl-0.1.0/firmware/modem_at/CMakeLists.txt +3 -0
  188. esp32tl-0.1.0/firmware/modem_at/main/CMakeLists.txt +1 -0
  189. esp32tl-0.1.0/firmware/modem_at/main/main.c +88 -0
  190. esp32tl-0.1.0/firmware/modem_recovery/CMakeLists.txt +15 -0
  191. esp32tl-0.1.0/firmware/modem_recovery/main/CMakeLists.txt +2 -0
  192. esp32tl-0.1.0/firmware/modem_recovery/main/main.c +141 -0
  193. esp32tl-0.1.0/firmware/modem_recovery/sdkconfig.defaults +6 -0
  194. esp32tl-0.1.0/firmware/mqtt_session/CMakeLists.txt +16 -0
  195. esp32tl-0.1.0/firmware/mqtt_session/main/CMakeLists.txt +2 -0
  196. esp32tl-0.1.0/firmware/mqtt_session/main/main.c +114 -0
  197. esp32tl-0.1.0/firmware/mqtt_session/sdkconfig.defaults +6 -0
  198. esp32tl-0.1.0/firmware/nmea_reader/CMakeLists.txt +3 -0
  199. esp32tl-0.1.0/firmware/nmea_reader/main/CMakeLists.txt +1 -0
  200. esp32tl-0.1.0/firmware/nmea_reader/main/Kconfig.projbuild +31 -0
  201. esp32tl-0.1.0/firmware/nmea_reader/main/main.c +83 -0
  202. esp32tl-0.1.0/firmware/nmea_reader/main/nmea.c +113 -0
  203. esp32tl-0.1.0/firmware/nmea_reader/main/nmea.h +21 -0
  204. esp32tl-0.1.0/firmware/nvs_reader/CMakeLists.txt +3 -0
  205. esp32tl-0.1.0/firmware/nvs_reader/main/CMakeLists.txt +1 -0
  206. esp32tl-0.1.0/firmware/nvs_reader/main/main.c +46 -0
  207. esp32tl-0.1.0/firmware/ota_state/CMakeLists.txt +3 -0
  208. esp32tl-0.1.0/firmware/ota_state/main/CMakeLists.txt +1 -0
  209. esp32tl-0.1.0/firmware/ota_state/main/main.c +93 -0
  210. esp32tl-0.1.0/firmware/ota_state/sdkconfig.defaults +5 -0
  211. esp32tl-0.1.0/firmware/persistence/CMakeLists.txt +3 -0
  212. esp32tl-0.1.0/firmware/persistence/main/CMakeLists.txt +2 -0
  213. esp32tl-0.1.0/firmware/persistence/main/main.c +110 -0
  214. esp32tl-0.1.0/firmware/pppos_client/prepare.py +32 -0
  215. esp32tl-0.1.0/firmware/pppos_client/sdkconfig.defaults +8 -0
  216. esp32tl-0.1.0/firmware/sd_remount/CMakeLists.txt +3 -0
  217. esp32tl-0.1.0/firmware/sd_remount/main/CMakeLists.txt +1 -0
  218. esp32tl-0.1.0/firmware/sd_remount/main/main.c +97 -0
  219. esp32tl-0.1.0/firmware/timer_wake/CMakeLists.txt +3 -0
  220. esp32tl-0.1.0/firmware/timer_wake/main/CMakeLists.txt +2 -0
  221. esp32tl-0.1.0/firmware/timer_wake/main/main.c +26 -0
  222. esp32tl-0.1.0/pyproject.toml +106 -0
  223. esp32tl-0.1.0/recordings/gnss-generated-1.jsonl +61 -0
  224. esp32tl-0.1.0/recordings/gnss-generated-2.jsonl +61 -0
  225. esp32tl-0.1.0/runner/Cargo.lock +106 -0
  226. esp32tl-0.1.0/runner/Cargo.toml +54 -0
  227. esp32tl-0.1.0/runner/build.rs +10 -0
  228. esp32tl-0.1.0/runner/rust-toolchain.toml +9 -0
  229. esp32tl-0.1.0/runner/src/cli/tests.rs +339 -0
  230. esp32tl-0.1.0/runner/src/cli.rs +438 -0
  231. esp32tl-0.1.0/runner/src/hci/tests.rs +59 -0
  232. esp32tl-0.1.0/runner/src/hci.rs +59 -0
  233. esp32tl-0.1.0/runner/src/main.rs +475 -0
  234. esp32tl-0.1.0/runner/src/protocol/tests.rs +488 -0
  235. esp32tl-0.1.0/runner/src/protocol.rs +721 -0
  236. esp32tl-0.1.0/runner/src/sd_card/tests.rs +946 -0
  237. esp32tl-0.1.0/runner/src/sd_card.rs +1003 -0
  238. esp32tl-0.1.0/runner/src/session/tests.rs +3972 -0
  239. esp32tl-0.1.0/runner/src/session.rs +1849 -0
  240. esp32tl-0.1.0/runner/src/socket_board/tests.rs +129 -0
  241. esp32tl-0.1.0/runner/src/socket_board.rs +178 -0
  242. esp32tl-0.1.0/runner/src/tests.rs +86 -0
  243. esp32tl-0.1.0/runner/src/transport/tests.rs +223 -0
  244. esp32tl-0.1.0/runner/src/transport.rs +336 -0
  245. esp32tl-0.1.0/scripts/check-determinism.py +226 -0
  246. esp32tl-0.1.0/scripts/check-docs.py +759 -0
  247. esp32tl-0.1.0/scripts/check-release.py +73 -0
  248. esp32tl-0.1.0/scripts/compare-backends.py +239 -0
  249. esp32tl-0.1.0/scripts/decisions-index.py +216 -0
  250. esp32tl-0.1.0/scripts/fetch-rom-elf +85 -0
  251. esp32tl-0.1.0/scripts/generate-gnss-recordings.py +149 -0
  252. esp32tl-0.1.0/scripts/package-runtime.py +34 -0
  253. esp32tl-0.1.0/scripts/test-wheel-runtime.py +86 -0
  254. esp32tl-0.1.0/scripts/venv-tool +11 -0
  255. esp32tl-0.1.0/tests/boards/aux-uart.toml +16 -0
  256. esp32tl-0.1.0/tests/conftest.py +101 -0
  257. esp32tl-0.1.0/tests/test_air.py +177 -0
  258. esp32tl-0.1.0/tests/test_alarm_example.py +66 -0
  259. esp32tl-0.1.0/tests/test_arduino_shell.py +58 -0
  260. esp32tl-0.1.0/tests/test_arduino_softap.py +146 -0
  261. esp32tl-0.1.0/tests/test_bluetooth_guest.py +1060 -0
  262. esp32tl-0.1.0/tests/test_board_api.py +77 -0
  263. esp32tl-0.1.0/tests/test_boardlink.py +1100 -0
  264. esp32tl-0.1.0/tests/test_boards.py +440 -0
  265. esp32tl-0.1.0/tests/test_bt_spp_initiator.py +292 -0
  266. esp32tl-0.1.0/tests/test_card_cache.py +463 -0
  267. esp32tl-0.1.0/tests/test_card_image.py +290 -0
  268. esp32tl-0.1.0/tests/test_check_determinism.py +253 -0
  269. esp32tl-0.1.0/tests/test_check_docs.py +546 -0
  270. esp32tl-0.1.0/tests/test_ci_test_pair.py +231 -0
  271. esp32tl-0.1.0/tests/test_cli.py +375 -0
  272. esp32tl-0.1.0/tests/test_clock.py +720 -0
  273. esp32tl-0.1.0/tests/test_compare_backends.py +257 -0
  274. esp32tl-0.1.0/tests/test_condition.py +67 -0
  275. esp32tl-0.1.0/tests/test_console_input.py +32 -0
  276. esp32tl-0.1.0/tests/test_console_writes.py +49 -0
  277. esp32tl-0.1.0/tests/test_decisions_index.py +128 -0
  278. esp32tl-0.1.0/tests/test_deep_sleep.py +47 -0
  279. esp32tl-0.1.0/tests/test_determinism.py +201 -0
  280. esp32tl-0.1.0/tests/test_duration_model.py +442 -0
  281. esp32tl-0.1.0/tests/test_firmware_build.py +449 -0
  282. esp32tl-0.1.0/tests/test_firmware_images.py +375 -0
  283. esp32tl-0.1.0/tests/test_flash.py +785 -0
  284. esp32tl-0.1.0/tests/test_flash_snapshot.py +142 -0
  285. esp32tl-0.1.0/tests/test_gnss_fixture.py +222 -0
  286. esp32tl-0.1.0/tests/test_gnss_model.py +443 -0
  287. esp32tl-0.1.0/tests/test_gnss_recordings.py +93 -0
  288. esp32tl-0.1.0/tests/test_gpio_echo.py +98 -0
  289. esp32tl-0.1.0/tests/test_hello_world.py +17 -0
  290. esp32tl-0.1.0/tests/test_http_request.py +244 -0
  291. esp32tl-0.1.0/tests/test_http_server.py +186 -0
  292. esp32tl-0.1.0/tests/test_lines.py +361 -0
  293. esp32tl-0.1.0/tests/test_link_protocol.py +339 -0
  294. esp32tl-0.1.0/tests/test_matching.py +314 -0
  295. esp32tl-0.1.0/tests/test_model_bases.py +240 -0
  296. esp32tl-0.1.0/tests/test_modem_fixture.py +201 -0
  297. esp32tl-0.1.0/tests/test_modem_model.py +1280 -0
  298. esp32tl-0.1.0/tests/test_modem_recovery.py +178 -0
  299. esp32tl-0.1.0/tests/test_mqtt_session.py +184 -0
  300. esp32tl-0.1.0/tests/test_net_bridge.py +370 -0
  301. esp32tl-0.1.0/tests/test_net_client.py +489 -0
  302. esp32tl-0.1.0/tests/test_net_ethernet.py +289 -0
  303. esp32tl-0.1.0/tests/test_net_http.py +252 -0
  304. esp32tl-0.1.0/tests/test_net_http_client.py +224 -0
  305. esp32tl-0.1.0/tests/test_net_ip.py +144 -0
  306. esp32tl-0.1.0/tests/test_net_mqtt.py +601 -0
  307. esp32tl-0.1.0/tests/test_net_mqtt_failures.py +216 -0
  308. esp32tl-0.1.0/tests/test_net_mqtt_policy.py +360 -0
  309. esp32tl-0.1.0/tests/test_net_mqtt_sessions.py +639 -0
  310. esp32tl-0.1.0/tests/test_net_mru.py +136 -0
  311. esp32tl-0.1.0/tests/test_net_path.py +490 -0
  312. esp32tl-0.1.0/tests/test_net_ppp.py +145 -0
  313. esp32tl-0.1.0/tests/test_net_services.py +73 -0
  314. esp32tl-0.1.0/tests/test_net_station.py +301 -0
  315. esp32tl-0.1.0/tests/test_net_tls.py +550 -0
  316. esp32tl-0.1.0/tests/test_nmea_reader.py +155 -0
  317. esp32tl-0.1.0/tests/test_nmea_reader_model.py +150 -0
  318. esp32tl-0.1.0/tests/test_nvs_reader.py +43 -0
  319. esp32tl-0.1.0/tests/test_ota_state.py +83 -0
  320. esp32tl-0.1.0/tests/test_package.py +22 -0
  321. esp32tl-0.1.0/tests/test_platformio_build.py +756 -0
  322. esp32tl-0.1.0/tests/test_platformio_firmware_build.py +273 -0
  323. esp32tl-0.1.0/tests/test_power.py +214 -0
  324. esp32tl-0.1.0/tests/test_pppos_client.py +164 -0
  325. esp32tl-0.1.0/tests/test_pytest_plugin.py +2180 -0
  326. esp32tl-0.1.0/tests/test_real_source.py +1008 -0
  327. esp32tl-0.1.0/tests/test_recording.py +394 -0
  328. esp32tl-0.1.0/tests/test_release.py +119 -0
  329. esp32tl-0.1.0/tests/test_release_version.py +134 -0
  330. esp32tl-0.1.0/tests/test_replay.py +288 -0
  331. esp32tl-0.1.0/tests/test_run_report.py +88 -0
  332. esp32tl-0.1.0/tests/test_runner_link.py +231 -0
  333. esp32tl-0.1.0/tests/test_runtime.py +249 -0
  334. esp32tl-0.1.0/tests/test_sd_card_slot.py +228 -0
  335. esp32tl-0.1.0/tests/test_sd_faults.py +329 -0
  336. esp32tl-0.1.0/tests/test_sd_remount.py +196 -0
  337. esp32tl-0.1.0/tests/test_sdspi.py +338 -0
  338. esp32tl-0.1.0/tests/test_serial_backend.py +964 -0
  339. esp32tl-0.1.0/tests/test_shard.py +111 -0
  340. esp32tl-0.1.0/tests/test_spp_peer.py +3876 -0
  341. esp32tl-0.1.0/tests/test_tap.py +240 -0
  342. esp32tl-0.1.0/tests/test_timer_wake.py +111 -0
  343. esp32tl-0.1.0/tests/test_uart_model.py +346 -0
  344. esp32tl-0.1.0/tests/test_units.py +210 -0
  345. esp32tl-0.1.0/tests/test_wifi.py +186 -0
  346. esp32tl-0.1.0/tools/benchtime.py +141 -0
  347. esp32tl-0.1.0/tools/cryptobench/CMakeLists.txt +3 -0
  348. esp32tl-0.1.0/tools/cryptobench/main/CMakeLists.txt +1 -0
  349. esp32tl-0.1.0/tools/cryptobench/main/main.c +269 -0
  350. esp32tl-0.1.0/tools/cryptobench/sdkconfig.defaults +11 -0
  351. esp32tl-0.1.0/tools/cryptobench/sdkconfig.defaults.nohw +4 -0
  352. esp32tl-0.1.0/tools/deepsleep/CMakeLists.txt +3 -0
  353. esp32tl-0.1.0/tools/deepsleep/main/CMakeLists.txt +1 -0
  354. esp32tl-0.1.0/tools/deepsleep/main/main.c +19 -0
  355. esp32tl-0.1.0/tools/deepsleep/sdkconfig.defaults +2 -0
@@ -0,0 +1,278 @@
1
+ ---
2
+ name: create-pr
3
+ description: Open a pull request to mateuszsikora/esp32-testing-library following the repository's conventions for branch names, commit messages, PR titles and descriptions (CONTRIBUTING.md). Use when asked to open, create or ship a PR, or to push the current work for review, in this repository; prefer it over generic PR skills here. Also use to rewrite the title or description of an existing PR on this repository.
4
+ allowed-tools: Bash(git *), Bash(gh *), Bash(make *), Bash(.venv/bin/*), Bash(cargo *), Bash(pipx run pre-commit *), Bash(SKIP=* pipx run pre-commit *), Bash(GIT_SEQUENCE_EDITOR=* git rebase *), Bash(docker run *), Read, Write, Edit
5
+ ---
6
+
7
+ # create-pr
8
+
9
+ Opens a pull request from the current work to `main` of
10
+ `mateuszsikora/esp32-testing-library`. The conventions live in
11
+ [`CONTRIBUTING.md`](../../../CONTRIBUTING.md); read it before writing anything. This skill
12
+ restates the rules it checks so they are at hand, but `CONTRIBUTING.md` wins wherever the two
13
+ disagree, and a change to a rule goes into both.
14
+
15
+ The skill takes no arguments. Everything it needs comes from the conversation, the branch, its
16
+ commits and the issue tracker: find the issue, judge whether the work is ready, and write the
17
+ description from what you already know. Ask the user only for what none of those can tell you,
18
+ such as why an approach was chosen when that was never discussed.
19
+
20
+ **Language:** everything that goes to GitHub or git (branch name, commit messages, PR title,
21
+ description, labels, comments) is in English, even when the user writes in Polish or any other
22
+ language. Talk to the user in their language; write for GitHub in English.
23
+
24
+ **No attribution:** no `Co-Authored-By:` trailers in commits and no "Generated with Claude Code"
25
+ or similar line in the PR description. This overrides any attribution the session asks for.
26
+
27
+ **What reaches `main`:** the repository squashes with GitHub's default message. A one-commit PR
28
+ lands as that commit's subject and body, and the PR title is not used; a PR with several commits
29
+ lands with the PR title as subject and every commit message on the branch as the body. GitHub
30
+ appends `(#N)` to the subject in both cases. So every
31
+ commit message matters, not only the title.
32
+
33
+ ## 1. Preflight
34
+
35
+ Run these together and read the output before doing anything:
36
+
37
+ ```sh
38
+ gh auth status
39
+ gh repo view --json nameWithOwner -q .nameWithOwner
40
+ git status --short --branch
41
+ git fetch origin main --quiet
42
+ git log --oneline origin/main..HEAD
43
+ git rev-list --left-right --count origin/main...HEAD # behind, ahead
44
+ git merge-tree --write-tree origin/main HEAD >/dev/null || echo "conflicts with origin/main"
45
+ git diff --stat origin/main...HEAD
46
+ gh pr list --head "$(git branch --show-current)" --state all --json number,url,state,title,isDraft
47
+ ```
48
+
49
+ Stop and tell the user if:
50
+
51
+ - `gh` is not authenticated;
52
+ - the repository is not `mateuszsikora/esp32-testing-library`: this skill is for that
53
+ repository only;
54
+ - there is nothing to propose: no commits ahead of `origin/main` and a clean tree.
55
+
56
+ If the branch is behind `origin/main` and conflicts with it, say so; do not rebase or merge
57
+ without the user's agreement. Behind without conflicts is fine.
58
+
59
+ If an **open** PR exists for this branch, do not create another: push new commits, and rewrite
60
+ its title or description (step 9) if they no longer describe the branch. Tell the user which you
61
+ did. A closed or merged PR for the branch does not count; if one was merged, the branch is
62
+ probably stale, so tell the user before going on.
63
+
64
+ ## 2. Gather the context
65
+
66
+ The description has to explain the change, so understand it first:
67
+
68
+ - Read the full diff (`git diff origin/main...HEAD`, plus uncommitted changes) and every commit
69
+ message on the branch.
70
+ - Go back over the conversation: what the user asked for, why this approach, what was tried and
71
+ rejected, what was measured. That goes into **Decisions** and **Verification**; the diff
72
+ cannot show it.
73
+ - Find the issue yourself, in this order: the branch name, `Closes`/`Refs` lines in the commits,
74
+ issue numbers mentioned in the conversation, then `gh issue list --state open --limit 50`
75
+ matched against the change. Read the candidate with `gh issue view <N>` and link it only if
76
+ the PR really is part of it. If no issue fits, the PR has none; do not invent one and do not
77
+ ask the user to create one.
78
+ - From the issue, note which of its items this PR does and which it leaves. That decides
79
+ `Closes` against `Refs` and feeds step 4.
80
+
81
+ ## 3. Verify
82
+
83
+ Run what covers the change and keep the exact commands and results for **Verification**:
84
+
85
+ | Change touches | Run |
86
+ |---|---|
87
+ | Anything | `make docs-check`: every behaviour change carries its documentation (`AGENTS.md`, "Documentation contract"). On a failure, write the documents it names before going on; never push with `SKIP_DOCS_CHECK`. If you merge `origin/main` into the branch, run it again after the merge |
88
+ | Anything | `.venv/bin/pre-commit run --files <changed files>`. Without `.venv`, and only if no Python changed: `SKIP=ruff-check,ruff-format,mypy pipx run pre-commit run --files <changed files>` |
89
+ | Python (`esp32tl/`, `tests/`, `tools/*.py`), `pyproject.toml` | `make lint` (it creates `.venv` if missing), then `.venv/bin/pytest` |
90
+ | A tool in `tools/*.py` | also run it once on a sample input and check its output |
91
+ | `runner/` | `make test-runner` and `make build-runner`. Not `cargo --manifest-path runner/Cargo.toml` from the root: rustup takes the toolchain pinned in `runner/rust-toolchain.toml` only when cargo runs in `runner/` |
92
+ | `firmware/` | `make firmware` if Docker is available; otherwise say it was not built |
93
+ | An ESP-IDF project in `tools/` | if Docker is available, build each `sdkconfig.defaults*` variant the change affects into its own directory, with the command below; otherwise say it was not built |
94
+ | `Makefile` | `make -n <each changed target>`, then run each changed target except `firmware`, which follows its own row. Run `clean` only if it changed, last, and then `make setup`: it deletes `.venv`, which the other rows and the git hooks of every worktree need |
95
+ | `.pre-commit-config.yaml`, `scripts/` | `.venv/bin/pre-commit run --all-files` |
96
+ | Docs | the pre-commit row and `make docs-check` (it checks links and anchors), plus figures and claims checked by hand against their source: the check proves a document changed, not that it is true |
97
+
98
+ The ESP-IDF build, with the image pinned in `docs/stage0-findings.md`. A separate build directory
99
+ leaves the user's own `build/` and `sdkconfig` alone (`tools/*/build*/` is ignored by git); for
100
+ `tools/cryptobench`'s variant without accelerators, add
101
+ `-D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.defaults.nohw"` and use `build-pr-nohw`:
102
+
103
+ ```sh
104
+ docker run --rm -v "$PWD":/project -w /project/tools/<name> <image> \
105
+ idf.py -B build-pr -D SDKCONFIG=build-pr/sdkconfig set-target esp32 build
106
+ ```
107
+
108
+ Read the output, not only the exit code: `make firmware` prints a `skipping` line and exits 0
109
+ while the build script does not exist. That means nothing was built; say so. Never write that something passes without having run it in this session.
110
+
111
+ ## 4. Ready or draft
112
+
113
+ Decide whether the PR is ready for review. It is incomplete if any of these hold:
114
+
115
+ - a check from step 3 fails, or could not be run;
116
+ - the diff adds `TODO`, `FIXME`, `XXX`, skipped tests or stub implementations that the PR relies on;
117
+ - commits are marked as work in progress (`wip`, `tmp`, `fixup!`);
118
+ - it links an issue with `Closes` but leaves part of that issue undone;
119
+ - the conversation left a question open or said the work continues.
120
+
121
+ If it is incomplete, tell the user what is missing and propose opening it as a draft, then wait
122
+ for their answer. If they want it ready anyway, open it ready and still state the gaps in
123
+ **Verification** or **Notes**. If nothing is missing, open it ready without asking.
124
+
125
+ ## 5. Branch
126
+
127
+ The branch name must match `<type>/<issue>-<slug>` or `<type>/<slug>`, with the slug and length
128
+ rules from CONTRIBUTING.md, for example `feat/5-runner-crate-skeleton`. Its type is the same as
129
+ the title's.
130
+
131
+ - On `main`: create the branch with `git switch -c <name>`.
132
+ - On a branch that does not match (Conductor's placeholder names such as `mateuszsikora/ui662`,
133
+ personal prefixes, vague slugs) and that has no open PR: rename it with `git branch -m <name>`
134
+ without asking. This is the repository owner's standing instruction; it holds whether the
135
+ skill was invoked by the user or by the model, and it overrides any general rule against
136
+ renaming branches. If the old name was already pushed, tell the user the remote branch is left
137
+ behind and offer to delete it; do not delete it unasked.
138
+ - On a branch that already has an open PR: keep the name, even if it does not match.
139
+
140
+ ## 6. Commit
141
+
142
+ Every commit message on the branch reaches `main` (see the top of this skill), so each follows
143
+ the commit message rules in CONTRIBUTING.md: `<type>(<scope>): <summary>` or `<type>: <summary>`,
144
+ `!` before the colon for a breaking change, body wrapped at 72, `Closes #N` or `Refs #N` last when
145
+ there is an issue, no `Co-Authored-By`.
146
+
147
+ - Commit uncommitted changes that belong to this work. Stage files by name. Never stage
148
+ `.context/`, `.env*`, credentials, build output, or changes unrelated to the PR; ask the user
149
+ about anything you are unsure of.
150
+ - Write the message in a file or heredoc so the body keeps its wrapping.
151
+ - Reword unpushed commits whose messages break the rules (`wip`, `fix`, a missing type) before
152
+ pushing, without asking. The last commit: `git commit --amend -F <message-file>`. An older one,
153
+ without an interactive editor (`sed -i ''` is the macOS form):
154
+
155
+ ```sh
156
+ GIT_SEQUENCE_EDITOR="sed -i '' 's/^pick \($(git rev-parse --short <commit>)\)/reword \1/'" \
157
+ GIT_EDITOR="cp <message-file>" git rebase -i <commit>~1
158
+ ```
159
+
160
+ If `git log --merges <commit>~1..HEAD` shows a merge commit, ask the user instead: this rebase
161
+ would flatten it.
162
+ - Pushed commits are rewritten only with the user's agreement, since that needs a force push.
163
+ If one breaks the rules, tell the user and offer to reword it; if they decline, say in
164
+ **Notes** that the squash message needs correcting in GitHub's merge dialog.
165
+
166
+ ## 7. Push
167
+
168
+ ```sh
169
+ git push -u origin <branch>
170
+ ```
171
+
172
+ Never force-push without the user's agreement (then `--force-with-lease`); never push to `main`.
173
+
174
+ ## 8. Write the title and description
175
+
176
+ **Title.** `<type>(<scope>): <summary>`, types and scopes from CONTRIBUTING.md, or
177
+ `<type>: <summary>` when no scope fits (do not invent a catch-all scope); `!` before the colon
178
+ for a breaking change; the summary in the imperative, starting lowercase; at most 72 characters
179
+ in all; no issue number, no trailing period. It says what changes for the project. For a
180
+ one-commit branch the title must equal the commit subject, because the commit subject is what
181
+ lands on `main`.
182
+
183
+ | Avoid | Prefer |
184
+ |---|---|
185
+ | `feat: runner crate` | `feat(runner): add the crate with a console-only link` |
186
+ | `chore: update Makefile` | `fix: refuse a Python older than 3.11 before creating the venv` |
187
+ | `fix(harness): fixes #12` | `fix(harness): keep the UART tap from dropping a frame's last byte` |
188
+ | `docs: stage 0` | `docs(tools): record what stage 0 found running ESP-IDF images` |
189
+ | `Pin esp32sim` | `build(runner): pin esp32sim at the merge of the chip-revision fix` |
190
+
191
+ **Description.** Fill in
192
+ [`.github/pull_request_template.md`](../../../.github/pull_request_template.md):
193
+
194
+ 1. One or two paragraphs: what changes and why, outcome first. Then `Closes #N` (the PR finishes
195
+ the issue) or `Refs #N` (it is a step towards it), on its own line; nothing if there is no issue.
196
+ 2. `## Changes`: what a reviewer needs to know, grouped by meaning. Name files only where the
197
+ reviewer needs to find something; do not list every file.
198
+ 3. `## Decisions`: each non-obvious choice in bold, then the alternative rejected and why.
199
+ 4. `## Documentation`: tick the boxes of the template that hold, and name the documents the
200
+ change updates, or say why it needs none. Run `make docs-check` for the first box; never
201
+ tick it unrun.
202
+ 5. `## Verification`: the commands from step 3 and what they showed, with numbers where there
203
+ are numbers. Say what was not verified and why.
204
+ 6. `## Notes`: deliberately out of scope (with issue numbers), follow-ups, anything that deserves
205
+ a closer look. For a draft, what is missing before it is ready goes first.
206
+ 7. Delete empty sections and all template comments. No signature or attribution line at the end.
207
+
208
+ Style, as in the existing PRs (#2, #42, #43 are good examples of the description; their titles
209
+ and the `Co-Authored-By` lines in their commits predate these conventions):
210
+
211
+ - Specific and checkable: SHAs, versions, counts, measured figures. 7-character short SHAs in
212
+ prose; full SHAs where a machine reads them.
213
+ - `#N` for issues and PRs here, `mikroverk/esp32sim#N` upstream.
214
+ - Plain words. No "comprehensive", "robust", "seamless", "enhance", no emoji, no summary of the
215
+ summary.
216
+ - No hard wrapping: GitHub renders single line breaks in descriptions.
217
+ - Scale it to the change: a one-line fix gets a paragraph and a Verification line, not five
218
+ sections.
219
+
220
+ Before creating the PR, check the draft against this list:
221
+
222
+ - [ ] Title has a type (and a scope, if one fits) from CONTRIBUTING.md, its type matches the
223
+ branch (unless the branch had an open PR and was kept), and it would read well as a line
224
+ in `git log` on `main`.
225
+ - [ ] For a one-commit branch, the title equals the commit subject.
226
+ - [ ] Every commit message on the branch follows the rules, or the user knows which does not.
227
+ - [ ] A reader who has not seen the conversation understands why the change exists.
228
+ - [ ] Every claim in Verification was run in this session.
229
+ - [ ] `make docs-check` passes, and Documentation names the documents this changes.
230
+ - [ ] The issue link is correct and uses `Closes` only if the PR finishes the issue.
231
+ - [ ] No attribution lines in the description or the commits.
232
+ - [ ] Everything is in English.
233
+
234
+ ## 9. Create or update
235
+
236
+ Write the title and the description to files (in `.context/` if it exists, else temporary
237
+ files): a title with backticks, `$` or an apostrophe survives `"$(cat <file>)"` but not a quoted
238
+ literal. Then:
239
+
240
+ ```sh
241
+ gh pr create --repo mateuszsikora/esp32-testing-library --base main --head <branch> \
242
+ --title "$(cat <title-file>)" --body-file <body-file> [--draft] \
243
+ --label <label> [--label <label> ...]
244
+ ```
245
+
246
+ Labels follow from the type, the scope and the paths touched:
247
+
248
+ | Type, scope or paths | Label |
249
+ |---|---|
250
+ | `harness` (`esp32tl/`, `tests/`) | `area:harness` |
251
+ | `runner` (`runner/`) | `area:runner` |
252
+ | `firmware` (`firmware/`) | `area:firmware` |
253
+ | `Makefile`, `pyproject.toml`, `.pre-commit-config.yaml`, `scripts/`, `.github/workflows/` | `area:ci` |
254
+ | type `feat` | `enhancement` |
255
+ | type `fix` | `bug` |
256
+ | type `docs` | `documentation` |
257
+ | work in or for esp32sim / pytest-embedded upstream | `upstream` |
258
+
259
+ A PR that matches no row gets no label. Use only labels that exist (`gh label list`); do not
260
+ create labels.
261
+
262
+ For an existing PR, `gh pr edit <N> --title "$(cat <title-file>)" --body-file <body-file>`
263
+ (`--add-label` for labels). Older `gh` versions (seen on 2.69) fail there with "Projects
264
+ (classic) is being deprecated" before editing anything; then suggest upgrading `gh` and use the
265
+ REST API meanwhile:
266
+
267
+ ```sh
268
+ gh api -X PATCH repos/mateuszsikora/esp32-testing-library/pulls/<N> \
269
+ -f title="$(cat <title-file>)" -F body=@<body-file>
270
+ gh api -X POST repos/mateuszsikora/esp32-testing-library/issues/<N>/labels -f 'labels[]=<label>'
271
+ ```
272
+
273
+ ## 10. Report
274
+
275
+ Tell the user, in their language: the PR URL, whether it is a draft and why, the branch name (and
276
+ that it was renamed, if it was), the title, the linked issue (or that none fit), the labels, and
277
+ what was and was not verified. If the work was done on a different branch than the one checked
278
+ out, check out the PR's branch so Conductor shows it.
@@ -0,0 +1,55 @@
1
+ ---
2
+ paths:
3
+ - "esp32tl/**"
4
+ - "runner/**"
5
+ - "firmware/**"
6
+ - "tools/**"
7
+ - "scripts/**"
8
+ - ".github/workflows/**"
9
+ - "tests/conftest.py"
10
+ - "Makefile"
11
+ - "pyproject.toml"
12
+ - ".pre-commit-config.yaml"
13
+ ---
14
+
15
+ # Documentation contract
16
+
17
+ A behaviour change lands its documentation in the same change; removing behaviour removes its
18
+ documentation. This restates the table in `AGENTS.md`, which Codex reads too and which wins where
19
+ the two differ. How to write each document: `docs/guides/documentation.md`.
20
+
21
+ - `esp32tl/pytest_plugin.py`, `esp32tl/interfaces/` → `docs/features/pytest-plugin-*.md`
22
+ - `esp32tl/backends/` → `docs/features/esp32sim-backend-*.md`
23
+ - `esp32tl/cli.py`, `esp32tl/__init__.py` → `docs/features/cli-user.md`
24
+ - `runner/src/` (not the protocol files) → `docs/features/runner-*.md`
25
+ - `runner/Cargo.toml` → `docs/features/runner-technical.md`
26
+ - `esp32tl/link/`, `runner/src/protocol.rs`, `runner/src/socket_board.rs` → `docs/protocol.md`
27
+ - `firmware/` → `docs/features/validation-firmware-*.md`
28
+ - `esp32tl/boards/` → `docs/features/board-profiles-*.md`
29
+ - `esp32tl/recording.py` → `docs/recording-format.md`
30
+ - `esp32tl/sources/replay.py` → `docs/features/replay-*.md`
31
+ - `esp32tl/tap.py`, `esp32tl/report.py` → `docs/features/run-report-*.md`
32
+ - `esp32tl/units.py`, `esp32tl/sources/model/` → `docs/features/models-*.md`
33
+ - `esp32tl/flash.py` → `docs/features/flash-contents-*.md`
34
+ - `esp32tl/build.py` → `docs/features/builds-*.md`
35
+ - `esp32tl/bluetooth/` → `docs/features/bluetooth-peer-*.md`
36
+ - any other `esp32tl/` path → a new `docs/features/<feature>-*.md` and a row in the ownership map
37
+ - `.github/workflows/` → `docs/cicd.md`
38
+ - `Makefile`, `.pre-commit-config.yaml`, `scripts/fetch-rom-elf`, `scripts/venv-tool`,
39
+ `runner/rust-toolchain.toml` → `docs/guides/development.md`
40
+ - `pyproject.toml` → development guide, testing guide, or the plugin or CLI doc, by section
41
+ - `tests/conftest.py` → `docs/guides/testing.md`
42
+ - `scripts/check-docs.py`, `scripts/decisions-index.py` → `AGENTS.md` and/or
43
+ `docs/guides/documentation.md`; a change to the rules also changes the table in
44
+ `docs/features/README.md`, which the check compares with the script
45
+ - `tools/` → Reproducing in `docs/stage0-findings.md`
46
+ - `scripts/generate-gnss-recordings.py` → `docs/features/validation-firmware-*.md`
47
+ - `scripts/check-determinism.py` → `docs/guides/testing.md`
48
+ - `scripts/compare-backends.py` → `docs/features/serial-backend-*.md`
49
+ - a rejected alternative or postponed scope → `docs/decisions/<domain>.md`, then
50
+ `python3 scripts/decisions-index.py`
51
+ - a domain rule that a test enforces → `docs/invariants.md`
52
+
53
+ Test files and version-only bumps need nothing.
54
+
55
+ Verify before finishing: `make docs-check`
@@ -0,0 +1,55 @@
1
+ name: Restore firmware
2
+ description: Restore every checked firmware shard under its exact producer key.
3
+ inputs:
4
+ key:
5
+ description: Common firmware cache key published by the build matrix.
6
+ required: true
7
+ runs:
8
+ using: composite
9
+ steps:
10
+ - uses: actions/cache/restore@v6
11
+ with:
12
+ path: build/ci/firmware-idf-1.tar
13
+ key: ${{ inputs.key }}-idf-1
14
+ fail-on-cache-miss: true
15
+ - uses: actions/cache/restore@v6
16
+ with:
17
+ path: build/ci/firmware-idf-2.tar
18
+ key: ${{ inputs.key }}-idf-2
19
+ fail-on-cache-miss: true
20
+ - uses: actions/cache/restore@v6
21
+ with:
22
+ path: build/ci/firmware-idf-3.tar
23
+ key: ${{ inputs.key }}-idf-3
24
+ fail-on-cache-miss: true
25
+ - uses: actions/cache/restore@v6
26
+ with:
27
+ path: build/ci/firmware-idf-4.tar
28
+ key: ${{ inputs.key }}-idf-4
29
+ fail-on-cache-miss: true
30
+ - uses: actions/cache/restore@v6
31
+ with:
32
+ path: build/ci/firmware-examples-1.tar
33
+ key: ${{ inputs.key }}-examples-1
34
+ fail-on-cache-miss: true
35
+ - uses: actions/cache/restore@v6
36
+ with:
37
+ path: build/ci/firmware-examples-2.tar
38
+ key: ${{ inputs.key }}-examples-2
39
+ fail-on-cache-miss: true
40
+ - uses: actions/cache/restore@v6
41
+ with:
42
+ path: build/ci/firmware-examples-3.tar
43
+ key: ${{ inputs.key }}-examples-3
44
+ fail-on-cache-miss: true
45
+ - uses: actions/cache/restore@v6
46
+ with:
47
+ path: build/ci/firmware-platformio.tar
48
+ key: ${{ inputs.key }}-platformio
49
+ fail-on-cache-miss: true
50
+ - name: Unpack all firmware shards
51
+ shell: bash
52
+ run: |
53
+ for group in idf-1 idf-2 idf-3 idf-4 examples-1 examples-2 examples-3 platformio; do
54
+ tar -xf "build/ci/firmware-$group.tar"
55
+ done
@@ -0,0 +1,43 @@
1
+ <!--
2
+ Title: <type>(<scope>): <imperative summary>, scope optional, at most 72 characters, no period.
3
+ With several commits it becomes the squash commit subject on main; with one commit, that
4
+ commit's subject does, so keep the two equal. See CONTRIBUTING.md.
5
+ Delete any section below that would be empty.
6
+ -->
7
+
8
+ <!-- One or two paragraphs: what this changes and why. Outcome first, not a file list. -->
9
+
10
+ <!-- Closes #N if this finishes the issue, Refs #N if it is a step towards it; delete if there is no issue. -->
11
+ Closes #
12
+
13
+ ## Changes
14
+
15
+ -
16
+
17
+ ## Decisions
18
+
19
+ <!-- Choices a reviewer might question, each with the alternative you rejected and why. -->
20
+
21
+ -
22
+
23
+ ## Documentation
24
+
25
+ <!-- AGENTS.md, "Documentation contract": a behaviour change lands its documentation here. Tick
26
+ what holds; name the documents this changes, or say why none needed to. -->
27
+
28
+ - [ ] `make docs-check` passes on this branch, after the latest merge of the base branch
29
+ - [ ] The documents this changes say what is now true:
30
+ - [ ] Removed behaviour is removed from the documentation too
31
+ - [ ] No behaviour changes, so no documentation:
32
+
33
+ ## Verification
34
+
35
+ <!-- What you ran and what it showed: commands and results, not "tested locally". -->
36
+
37
+ -
38
+
39
+ ## Notes
40
+
41
+ <!-- Deliberately out of scope, follow-ups, things worth a closer look. -->
42
+
43
+ -
@@ -0,0 +1,102 @@
1
+ #!/usr/bin/env python3
2
+ """Update release metadata or recognize an exact, increasing version-only git diff."""
3
+
4
+ import argparse
5
+ import os
6
+ import re
7
+ import subprocess
8
+ import tomllib
9
+ from pathlib import Path
10
+
11
+ FILES = ("pyproject.toml", "runner/Cargo.toml", "runner/Cargo.lock")
12
+ VERSION = r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)"
13
+
14
+
15
+ def number(value: str) -> tuple[int, ...]:
16
+ if not re.fullmatch(VERSION, value):
17
+ raise ValueError("version must be MAJOR.MINOR.PATCH without a v prefix or leading zeros")
18
+ return tuple(map(int, value.split(".")))
19
+
20
+
21
+ def versions(files: dict[str, str]) -> str:
22
+ project, cargo, lock = (tomllib.loads(files[name]) for name in FILES)
23
+ runner = [p["version"] for p in lock["package"] if p["name"] == "esp32tl-runner"]
24
+ version = project["project"]["version"]
25
+ if runner != [version] or cargo["package"]["version"] != version:
26
+ raise ValueError("Python, runner and lockfile versions must match")
27
+ number(version)
28
+ return str(version)
29
+
30
+
31
+ def bumped(files: dict[str, str], version: str) -> dict[str, str]:
32
+ if number(version) <= number(versions(files)):
33
+ raise ValueError("new version must be greater than the current version")
34
+ result = {}
35
+ for name, section in zip(FILES, ("project", "package", None), strict=True):
36
+ if section:
37
+ pattern = rf'(^\[{section}\]\n(?:(?!^\[).)*?^version = ")[^"\n]+(")'
38
+ else:
39
+ pattern = r'(^name = "esp32tl-runner"\nversion = ")[^"\n]+(")'
40
+ updated, count = re.subn(
41
+ pattern, lambda m: m[1] + version + m[2], files[name], flags=re.M | re.S
42
+ )
43
+ if count != 1:
44
+ raise ValueError(f"expected exactly one release version in {name}")
45
+ result[name] = updated
46
+ if versions(result) != version:
47
+ raise ValueError("updated metadata does not match the requested version")
48
+ return result
49
+
50
+
51
+ def git(*args: str) -> str:
52
+ return subprocess.check_output(["git", *args]).decode("utf-8")
53
+
54
+
55
+ def classify(base: str, head: str) -> str | None:
56
+ # Compare full trees, not labels, titles, commit messages or only a list of paths.
57
+ if set(git("diff", "--name-only", base, head).splitlines()) != set(FILES):
58
+ return None
59
+ for name in FILES:
60
+ before = git("ls-tree", base, "--", name).split()
61
+ after = git("ls-tree", head, "--", name).split()
62
+ if before[:2] != ["100644", "blob"] or after[:2] != before[:2]:
63
+ return None
64
+ old = {name: git("show", f"{base}:{name}") for name in FILES}
65
+ new = {name: git("show", f"{head}:{name}") for name in FILES}
66
+ try:
67
+ version = versions(new)
68
+ return version if bumped(old, version) == new else None
69
+ except (ValueError, KeyError, TypeError):
70
+ return None
71
+
72
+
73
+ def main() -> None:
74
+ parser = argparse.ArgumentParser(description=__doc__)
75
+ commands = parser.add_subparsers(dest="command", required=True)
76
+ bump = commands.add_parser("bump")
77
+ bump.add_argument("version")
78
+ check = commands.add_parser("classify")
79
+ check.add_argument("base")
80
+ check.add_argument("head", nargs="?", default="HEAD")
81
+ args = parser.parse_args()
82
+ if args.command == "bump":
83
+ # Validate all three files before writing any of them.
84
+ files = {name: Path(name).read_bytes().decode("utf-8") for name in FILES}
85
+ try:
86
+ updated = bumped(files, args.version)
87
+ except (ValueError, KeyError, TypeError) as error:
88
+ parser.error(str(error))
89
+ for name, content in updated.items():
90
+ Path(name).write_text(content)
91
+ print(f"Updated Python, runner and lockfile to {args.version}")
92
+ else:
93
+ version = classify(args.base, args.head)
94
+ output = f"version_only={str(version is not None).lower()}\nversion={version or ''}\n"
95
+ print(output, end="")
96
+ if path := os.environ.get("GITHUB_OUTPUT"):
97
+ with Path(path).open("a") as stream:
98
+ stream.write(output)
99
+
100
+
101
+ if __name__ == "__main__":
102
+ main()
@@ -0,0 +1,121 @@
1
+ #!/usr/bin/env python3
2
+ """Run two existing pytest shards concurrently, failing if either fails."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import os
7
+ import re
8
+ import signal
9
+ import subprocess
10
+ import sys
11
+ import tempfile
12
+ import time
13
+ from contextlib import ExitStack, suppress
14
+ from pathlib import Path
15
+
16
+
17
+ def stop_groups(processes: list[subprocess.Popen[bytes]]) -> None:
18
+ groups = set()
19
+ for process in processes:
20
+ # A reaped leader can still have descendants in its process group.
21
+ process.poll()
22
+ try:
23
+ os.killpg(process.pid, signal.SIGTERM)
24
+ except ProcessLookupError:
25
+ continue
26
+ except PermissionError:
27
+ # A leader can become a non-signalable zombie between poll and killpg
28
+ # on macOS. Track the group until it disappears or needs escalation.
29
+ pass
30
+ groups.add(process.pid)
31
+
32
+ deadline = time.monotonic() + 5
33
+ while groups and time.monotonic() < deadline:
34
+ for process in processes:
35
+ process.poll() # Reap leaders so their zombies do not keep groups alive.
36
+ for group in groups.copy():
37
+ try:
38
+ os.killpg(group, 0)
39
+ except ProcessLookupError:
40
+ groups.remove(group)
41
+ except PermissionError:
42
+ # Still present, but not signalable (e.g. a dying group on macOS).
43
+ # Keep tracking it; only ESRCH proves the group disappeared.
44
+ pass
45
+ if groups:
46
+ time.sleep(0.05)
47
+ for group in groups:
48
+ with suppress(ProcessLookupError):
49
+ os.killpg(group, signal.SIGKILL)
50
+ for process in processes:
51
+ process.wait()
52
+
53
+
54
+ def run_pair(shards: list[str], arguments: list[str]) -> int:
55
+ processes: list[subprocess.Popen[bytes]] = []
56
+ with (
57
+ tempfile.TemporaryDirectory(prefix="e32-pair-", dir="/tmp") as temporary,
58
+ ExitStack() as stack,
59
+ ):
60
+ root = Path(temporary)
61
+ logs = []
62
+ try:
63
+ for index, shard in enumerate(shards):
64
+ directory = root / str(index)
65
+ directory.mkdir()
66
+ log = directory / "pytest.log"
67
+ logs.append(log)
68
+ output = stack.enter_context(log.open("wb"))
69
+ command = [
70
+ sys.executable,
71
+ "-m",
72
+ "pytest",
73
+ f"--shard={shard}",
74
+ f"--basetemp={directory / 'tests'}",
75
+ "-o",
76
+ f"cache_dir={directory / 'cache'}",
77
+ *arguments,
78
+ ]
79
+ print(f"Starting shard {shard}", flush=True)
80
+ processes.append(
81
+ subprocess.Popen(
82
+ command,
83
+ stdout=output,
84
+ stderr=subprocess.STDOUT,
85
+ env={**os.environ, "TMPDIR": str(directory)},
86
+ start_new_session=True,
87
+ )
88
+ )
89
+ codes = [process.wait() for process in processes]
90
+ finally:
91
+ # Each pytest owns a process group, including its pytester/runner children.
92
+ # On cancellation do not leave them running after the temporary files disappear.
93
+ stop_groups(processes)
94
+ for shard, log in zip(shards, logs, strict=False):
95
+ print(f"\n--- shard {shard} ---", flush=True)
96
+ print(log.read_text(errors="replace"), end="", flush=True)
97
+ for shard, code in zip(shards, codes, strict=True):
98
+ print(f"shard {shard}: exit {code}", flush=True)
99
+ return 0 if all(code == 0 for code in codes) else 1
100
+
101
+
102
+ def main() -> int:
103
+ if len(sys.argv) < 3 or any(not re.fullmatch(r"[1-4]/4", s) for s in sys.argv[1:3]):
104
+ print("usage: test-pair.py K/4 J/4 [pytest arguments...]", file=sys.stderr)
105
+ return 2
106
+ if sys.argv[1] == sys.argv[2]:
107
+ print("test-pair.py: the shards must be different", file=sys.stderr)
108
+ return 2
109
+
110
+ def interrupted(signum: int, frame: object) -> None:
111
+ raise KeyboardInterrupt
112
+
113
+ signal.signal(signal.SIGTERM, interrupted)
114
+ try:
115
+ return run_pair(sys.argv[1:3], sys.argv[3:])
116
+ except KeyboardInterrupt:
117
+ return 130
118
+
119
+
120
+ if __name__ == "__main__":
121
+ sys.exit(main())