Record T-Deck radio2 hardware timing and regression coverage

Add receive-only same-image display, SPI, modem/IQ-cache and scoped-priority experiments with checkpointed collectors. Keep rejected clock-phase correction and elevated-priority experiments out of production.

Publish sanitized timing data, Full Companion/Bluetooth/USB checks and redraw measurements with their limits. Wire the new behavioral checks into CI.
This commit is contained in:
mikecarper committed 2026-10-18 23:20:50 -07:00
1 parent a782cc8413
commit e8d1e537e4
16 files changed
+18129 -1

No files matched your search

+1 -1
View File
@@ -611,7 +611,7 @@ jobs:
run: >-
python3 -B -m unittest -v
test_sx1262_profile_switch test_sx1262_batched_modulation test_sx1262_protocol_batching
test_sx1262_modem_cache
test_sx1262_modem_cache test_esp32_retune_priority test_tdeck_spi_clock_timing
test_radio_chirp_math
- name: Verify radio lab collectors and compiled experiment contracts
+2
View File
@@ -24,6 +24,8 @@ Completed validation reports, experiments, and test guides are collected here. O
- [Shared radio/radio2 chirp timing and preamble warnings](radio_chirp_math_validation.md)
- [Automatic dwell policy: 4.6 chirps on both profiles](radio_dwell_policy_validation.md)
- [SX1262 profile-switch validation](radio_profile_switch_validation.md)
- [T-Deck radio2 scheduling during display redraw](tdeck_radio2_display.md)
- [T-Deck retune command, priority and SPI experiments](tdeck_radio2_retune_experiments.md)
- [Dual-profile receive validation](radio_profiles_validation.md)
- [Radio receive calibration and recovery](radio_receive_calibration.md)
- [Separated radios, normal XIAO RX gain, and unchanged-modulation timing](separated_radio_modulation_cache_validation.md)
+98
View File
@@ -0,0 +1,98 @@
<!-- meshcore-hosted-doc-link:start -->
<p class="meshcore-hosted-doc-link"><a href="https://mikecarper.github.io/MeshCore/test-results/tdeck_radio2_display/">View this page on MeshCore Docs</a>.</p>
<!-- meshcore-hosted-doc-link:end -->
# T-Deck radio2 scheduling during display redraw
Measured on 18 October 2026 (America/Los_Angeles), using one ESP32-S3 T-Deck
with 16 MiB flash and 8 MiB PSRAM. The receive-only harness uses the production
`CustomSX1262Wrapper`, profile scheduler and `ST7789LCDDisplay`. It never sends
radio packets or starts WiFi/Bluetooth. Source base: `22cdb7014`, with the
changes and application readback hash identified in the
[machine-readable results](tdeck_radio2_display_results.json).
## Change
T-Deck renders into a 153,600-byte RGB565 canvas allocated explicitly in PSRAM.
It transfers at most 960 pixels per TFT transaction (384 microseconds of wire
time at 40 MHz). Each transfer ends and releases chip select before servicing
the radio. CPU rasterization also offers bounded cooperative checkpoints.
The callback runs only the radio driver, without recursively entering the mesh
dispatcher or UI. Pending-packet, active-reception and transmit guards remain.
The T-Deck radio also uses the existing buffered 8 MHz SPI HAL. The TFT and radio
retain their shared HSPI peripheral and separate chip selects. Display wake
restores the backlight without repeating controller initialization. Other
boards keep their existing display path. If PSRAM allocation fails, the driver
warns and falls back to direct rendering.
## Same-image measurements
The two profiles were 909.5 MHz / SF7 / BW62.5 and 910.5 MHz / SF8 / BW500,
both CR5 with explicit 32-symbol preambles. These are measurement controls,
not a packet-delivery or preamble recommendation.
Each stress case ran three times for five seconds, requesting 20 redraws per
second. Rendering could take longer than the requested frame interval; actual
frame counts and elapsed times are retained in the results. Values below use
all samples across the three trials, with worst observed maxima.
| Display path | Radio SPI | Mean retune | Maximum retune | Maximum gap between radio service calls |
| --- | --- | ---: | ---: | ---: |
| Static screen | Bytewise, 2 MHz | 497 us | 525 us | 584 us |
| Original direct redraw | Bytewise, 2 MHz | 610 us | 629 us | 76,089 us |
| PSRAM canvas and bounded strips | Bytewise, 2 MHz | 581 us | 668 us | 1,343 us |
| PSRAM canvas and bounded strips | Buffered, 8 MHz | 468 us | 581 us | 1,237 us |
At a normal requested refresh rate of one frame per second (two four-second
trials per case), the original 2 MHz path's maximum service gap was 73,383 us;
the new 8 MHz path's was 1,251 us. Reducing refresh frequency alone does not
remove the individual blocking redraw.
Retune samples bracket the production retune hooks. They are separate from
display frame duration and the gap between radio service calls. Histogram
percentiles in the JSON are bucket upper bounds, not exact percentiles.
All 30 trials completed 7,025 profile switches with zero reported switch
failures, failed retunes, BUSY timeouts or chip errors. Every final RX-mode and
modulation-cache check passed. The minimum remaining loop stack was 3,340
bytes in this harness. No packets were decoded, so these measurements do not
establish packet delivery under redraw, loaded-channel behavior, Bluetooth/
WiFi interference, or long-term reliability.
## Reproduction and checks
Include `tools/hil/tdeck_display_switch.ini` in `platformio.local.ini`, build
`tdeck_display_switch`, and flash the exact T-Deck. The board needs a
ROM-compatible DIO boot header; the first QIO-header attempt failed before the
application started. The supplied harness recipe selects DIO.
Run the collector with `--fps 20 --seconds 5 --repeats 3`, then with
`--fps 1 --seconds 4 --repeats 2`. Only one tool may own the selected serial
port, and PlatformIO commands must run sequentially.
Sixteen focused native display/R8/radio tests passed. They cover pixel parity,
clipping, partial updates, strip bounds, released SPI before callbacks,
callback recursion protection, PSRAM failure, mode toggling and sleep/wake.
The new display regression is included in CI.
## Full Companion smoke check
The optimized canonical Full Companion image
`v1.18.0.1-tdeck-radio2-fast-22cdb701` compiled and passed its unchanged RAM
gate (230,680 internal bytes available; 164,896 required). It was installed
on the same board. USB ASCII commands and Binary Companion device queries
worked; Bluetooth reported on. Device queries retained 350 contacts and 40
channels. A Bluetooth client connection was not tested.
With the screen held on, a temporary receive-only secondary accumulated 759
switches with zero switch errors during a short runtime check. Its maximum
successful active-pair retune was 1,013 us and the guarded budget was 1,115 us.
One additional primary packet was received during that interval. This is a
smoke check rather than a controlled packet-delivery trial. Returning to
single-profile RX power saving raised the lifetime `max` diagnostic to 4,510 us;
that teardown is outside the active pair's measured switching budget.
The board was left running Full Companion with Bluetooth on, radio2 off and
its original `button-pairing` USB display mode. Seven hosted-document tests
also passed after adding this report.
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,321 @@
<!-- meshcore-hosted-doc-link:start -->
<p class="meshcore-hosted-doc-link"><a href="https://mikecarper.github.io/MeshCore/test-results/tdeck_radio2_retune_experiments/">View this page on MeshCore Docs</a>.</p>
<!-- meshcore-hosted-doc-link:end -->
# T-Deck retune command, priority and SPI experiments
Measured on 18 October 2026 (America/Los_Angeles) on one ESP32-S3 T-Deck with
16 MiB flash and 8 MiB PSRAM. This follows the
[display redraw scheduling measurements](tdeck_radio2_display.md).
The receive-only harness uses the production radio wrapper, profile scheduler
and display driver. It does not start Bluetooth or WiFi or send radio packets.
The [sanitized measurements](tdeck_radio2_retune_experiments.json) retain each
result once, firmware image hashes, counters, sample counts and timing summaries;
serial-port identifiers and raw console transcripts are omitted.
For this tested board, the selected setting is 8,888,888 Hz with the confirmed
modem and IQ caches enabled, normal owner priority, and the original SPI clock
phase programming. This was the highest bulk-transfer clock that passed these
checks. It does not establish a board or transceiver physical maximum. The
canonical Full Companion build and runtime smoke checks are recorded below.
## Measurement method
The primary profile was 909.5 MHz / SF7 / BW62.5 / CR5 with a 32-symbol
preamble. The secondary was 910.5 MHz / SF8 / BW500 / CR5, using a 32-symbol
preamble for the main and load comparisons and 40 symbols for the IQ comparison.
These controlled settings are not a packet-delivery or preamble recommendation.
All 42 controlled trials used the same 394,304-byte application, SHA-256
`9afce4f59227382dfe383b6b53ac52001644b05f8636c8f4c4f3ed6e12937668`,
built from base `22cdb7014` with the experimental changes applied. Each case ran
three times for five seconds with either a static screen or requested 20 Hz
buffered redraws. Actual frame counts are retained because rendering can take
longer than the requested interval.
Retune timings bracket the radio wrapper's production retune hooks. Radio
service gaps, display frame durations and receive-window deadline lateness are
separate measurements. Table means combine both retune directions and all three
trials, weighted by sample count; maxima are the worst observed. The source
means were recorded to three decimal places. JSON percentile fields are
histogram bucket upper bounds, not exact percentiles.
Command counters count the instrumented RadioLib HAL transfers, transferred
bytes, packet-type queries and acknowledged cache skips. They describe actual
execution of the selected policy rather than an estimated command saving.
## Confirmed modem query cache
The cache omits the repeated packet-type query only while a previously
confirmed LoRa modem remains valid. Lifecycle invalidation and the existing
receive and packet-ownership guards remain part of the production path.
| Policy at 8 MHz | Static mean retune | Static maximum | Buffered mean retune | Buffered maximum |
| --- | ---: | ---: | ---: | ---: |
| Query on each hop | 428.810 us | 450 us | 486.632 us | 595 us |
| Reuse confirmed modem | 400.021 us | 423 us | 459.761 us | 575 us |
| Query on each hop, scoped priority 3 | 439.244 us | 460 us | 495.471 us | 605 us |
Across the cache-enabled main cases, 1,844 hops recorded 1,844 skipped modem
queries and zero actual modem queries. The corresponding uncached baseline
recorded 1,844 modem queries. Scoped priority alone did not improve these quiet
harness timings.
## Scoped priority under a competing task
The single existing radio/UI owner normally ran at priority 1 on core 1. The
experiment temporarily raised only the retune call to priority 3, then restored
priority 1. It did not create a second task that could manipulate radio state.
The competing task ran on the same core at priority 1, performing a bounded
250-microsecond CPU burst every two RTOS ticks.
Both policies enabled the confirmed-modem cache. The load cases recorded
25,269 competing-task bursts. Every result confirmed the selected actual
retune priority and restoration of the original owner priority.
| Priority during retune | Static mean / maximum | Buffered mean / maximum | Static maximum service gap | Buffered maximum service gap |
| --- | ---: | ---: | ---: | ---: |
| 1 | 429.704 / 665 us | 594.379 / 825 us | 730 us | 1,494 us |
| 3, then restore 1 | 405.178 / 492 us | 527.755 / 832 us | 738 us | 1,519 us |
Scoped priority reduced mean retune time with this particular competitor, but
did not improve the worst complete radio-service gap. This synthetic task does
not establish behavior with a connected Bluetooth client, network traffic or
the other services in Full Companion.
## IQ workaround reuse when packet parameters change
Using a 40-symbol secondary preamble makes the packet tuple change between the
two profiles. The comparison tests reuse of the already applied normal-IQ
workaround while retaining the packet-parameter writes required for that change.
Both cases used the confirmed-modem cache and normal owner priority.
| IQ workaround cache | Static mean / maximum | Buffered mean / maximum |
| --- | ---: | ---: |
| Off | 511.358 / 533 us | 584.149 / 708 us |
| On | 430.664 / 457 us | 491.475 / 600 us |
All 12 IQ trials passed their runtime checks. The enabled cases recorded 1,843
IQ workaround skips across 1,843 hops. This is timing and state evidence from a
quiet receiver, rather than a packet-delivery comparison.
## SPI sweep and transfer-path comparisons
The fresh-boot sweep and bytewise diagnostic used a separate 395,408-byte
application, SHA-256
`d0124aac39a949f8a1cc292cb039f64ac61351d3fd3ca248137f14b4fb06ac90`.
Every independent clock attempt began with a device reboot. Each inspection
performed 100 paired reads of packet type and the LoRa sync word, with standby
and recovery at 8 MHz. Static and buffered timing trials followed only after
the preceding checks passed. Clock order alternated between repeats.
The frequency column is calculated from the SPI peripheral's configured clock
divider, captured during the radio HAL transfer. It is not an oscilloscope
measurement of the clock signal.
| Requested MHz | Divider-derived MHz | Complete passing attempts | Incorrect modem reads per 100, across three inspections |
| --- | ---: | ---: | --- |
| 8 | 8.000000 | 3/3 | 0, 0, 0 |
| 9 | 8.888888 | 3/3 | 0, 0, 0 |
| 10 | 10.000000 | 0/3 | 6, 7, 7 |
| 11 | 10.000000 | 0/3 | 5, 5, 6 |
| 12 | 11.428571 | 0/3 | 20, 20, 28 |
| 13 | 11.428571 | 0/3 | 22, 20, 20 |
| 14 | 13.333333 | 0/3 | 59, 49, 67 |
| 15 | 13.333333 | 0/3 | 58, 54, 55 |
| 16 | 16.000000 | 0/3 | 64, 68, 64 |
These inspections recorded no sync-word mismatch or explicit SPI read error;
the failing check was an incorrect modem value. The sweep's highest passing
divider-derived frequency was 8.888888 MHz for this bulk-transfer implementation.
This observation must not be treated as the radio's physical SPI limit.
A separate bytewise diagnostic read all 100 modem values correctly at both
10 MHz and 16 MHz, with no sync-word mismatch or reported read error. Its
16 MHz bulk comparison returned 29 correct values and 71 incorrect values;
returning to bulk 8 MHz read all 100 correctly. The different transfer paths
therefore prevent interpreting the bulk failures as a transceiver clock limit.
## Clock-register experiment and longer read checks
The final diagnostic and comparison image was 396,560 bytes, SHA-256
`6e830f93dd3bb632e73e47878e8bbe61795a0389fa1ba75aab3c2a1ff9e14a85`.
With the original phase programming, 10,000 paired modem/sync-word reads passed
at both 8 MHz and 8.888888 MHz, with zero incorrect modem values, sync-word
mismatches or reported read errors. A 10 MHz check returned 58 incorrect modem
values in 1,000 pairs.
Inspection found differences between some N/pre-divider/phase fields and an
experimental reconstruction of the clock register. Changing those phase fields
did not improve the link: at 8.888888 MHz it introduced 587 incorrect modem
values in 10,000 pairs; at 10 MHz it returned 64 incorrect values in 1,000 pairs,
compared with 58 using the original programming. The experiment also failed at
higher tested clocks. It was rejected for production and remains confined to
the HIL helpers under `tools/hil`.
These observations neither explain every transfer-path difference nor establish
a causal driver defect. The reported frequencies remain divider-derived values;
clock waveforms and phase lengths were not measured with an oscilloscope.
## Final comparison with exact clock settings
All 24 final trials used that same final image, with exact clock settings enabled
and the rejected phase-field correction disabled. Each policy ran twice for five
seconds in both display modes. A nominal 9 MHz request in the earlier sweep
produced an 8,888,888 Hz divider; the final setting requests that exact frequency,
avoiding the rounded-frequency divider search. The timing comparison below is
within this final image rather than across different instrumentation builds.
| Secondary preamble | Clock setting | Caches | Static mean / maximum retune | Buffered mean / maximum retune |
| --- | ---: | --- | ---: | ---: |
| 32 | 8 MHz | Neither | 426.751 / 457 us | 518.300 / 626 us |
| 32 | 8 MHz | Modem | 404.635 / 438 us | 493.754 / 610 us |
| 32 | 8.888888 MHz | Modem | 402.134 / 436 us | 491.574 / 608 us |
| 40 | 8 MHz | Neither | 562.482 / 605 us | 652.882 / 777 us |
| 40 | 8 MHz | Modem and IQ | 437.898 / 472 us | 528.139 / 648 us |
| 40 | 8.888888 MHz | Modem and IQ | 435.327 / 471 us | 526.319 / 653 us |
The additional clock increase saved about 2–3 microseconds in mean retune time
for these cached paths. Avoiding redundant commands supplied the larger saving.
The cache-enabled final trials recorded 4,912 modem-query skips; the IQ-enabled
cases recorded 2,457 IQ workaround skips.
Across the cached 8.888888 MHz final cases with secondary preambles 32 and 40,
the best observed individual retune was 378 us and the worst was 653 us.
The separate Full Companion smoke check below reached 1,224 us under its
application workload; those measurements are not interchangeable.
The selected T-Deck configuration uses `MC_SX1262_SPI_HZ=8888888`,
`MC_SX1262_FAST_MODEM_CACHE=1` and `MC_SX1262_FAST_IQ_CACHE=1`. Scoped priority
stays off because it did not improve the maximum complete radio-service gap.
The clock-register correction stays off because its hardware comparison was
worse. This selection is limited to the tested board and workload.
## Full-screen redraw duration
| Renderer and radio policy | Frames | Mean redraw | Minimum | Maximum |
| --- | ---: | ---: | ---: | ---: |
| Original direct redraw, bytewise 2 MHz | 204 | 73.603 ms | 72.298 ms | 75.131 ms |
| Final buffered redraw, 8.888888 MHz, preamble 32 | 176 | 57.035 ms | 56.123 ms | 57.839 ms |
| Final buffered redraw, 8.888888 MHz, preamble 40 | 176 | 57.161 ms | 56.085 ms | 57.964 ms |
A typical redraw therefore fell from about 73.6 to 57.1 ms: roughly 16.5 ms
saved, or 22% less time. The worst observed redraw fell from 75.1 to 58.0 ms.
These durations include the cooperative radio service performed during rendering.
The original result combines three five-second trials from the first display
HIL image; each final row combines two five-second trials from the final
comparison image. They are observations across different images and combined
policies. Most of the saving comes from the PSRAM canvas path; this comparison
does not isolate the benefit of increasing the radio clock above 8 MHz.
## Checks, limits and remaining follow-up
The 42 controlled trials completed 12,920 profile switches and 1,801 display
frames, with zero reported switch failures, failed retunes, BUSY timeouts or
chip errors. All final RX-mode, modulation-cache and priority-restoration
checks passed. The minimum remaining owner-task stack was 3,288 bytes.
The 24 final exact-clock trials also passed every runtime check, completing
7,367 switches and 1,054 frames with zero reported switch failures, failed
retunes, BUSY timeouts or chip errors. All final RX-mode, cache and priority
checks passed. Their minimum remaining owner stack was 3,224 bytes.
No packets were decoded in those trials. They do not establish reception under
redraw, channel-load behavior, Bluetooth/WiFi coexistence or long-term reliability.
The SPI sweep failures are retained separately from the passing 42-case control
matrix, and were not followed by dependent timing trials on the failed link.
All seven hosted-document link tests passed after adding this report.
Twenty-three focused native regression tests also passed.
The final HIL source, including the isolated clock experiment helpers, compiled.
## Reproduction
Build and install the receive-only HIL using the
[display report's build instructions](tdeck_radio2_display.md#reproduction-and-checks).
The experiment controls change RAM only and the harness has no radio transmit
path. On its USB console, reproduce the final buffered, cached comparison with:
```text
exactclock 1
clockfix 0
inspect 9 1 10000
trial 2 9 1 1 0 0 40 5 20 1
```
The trial selects buffered display, nominal 9 MHz, modem and IQ caches on,
normal owner priority, no synthetic load, secondary preamble 40, five seconds
and requested 20 Hz redraws; the last number is the result sequence. Check
`actual_spi_hz` for 8,888,888, `exact_clock` for true and
`clock_timing_corrected` for false, alongside the error and cache counters.
`actual_spi_hz` is derived from the configured divider during the transfer;
it is not an oscilloscope measurement.
For repeated 8 MHz control cases, the collector accepts a port placeholder:
```text
python tools/hil/tdeck_retune_experiments.py <port> --suite main --spi 8 --seconds 5 --repeats 3 --fps 20 --output retune-main-8mhz.json
```
`tools/hil/tdeck_spi_sweep.py` explicitly reboots before every independent clock
attempt. Reboot resets the RAM-only exact-clock flag to false. Its original
clock matrix and the final manual exact-clock comparison therefore use
different clock-setting policies and must be interpreted separately.
## Full Companion follow-up
The canonical Full Companion
`v1.18.0.1-tdeck-radio2-tuned-22cdb701` compiled with the selected 8,888,888 Hz
radio SPI setting, both caches enabled, and normal owner priority. Its unchanged
RAM gate reported 230,680 internal bytes available, 164,896 required and a
197,912-byte largest region. These are linked capacity checks rather than
free heap after boot. The application body size check was 2,261,101 bytes;
the packaged application was 2,261,784 bytes, SHA-256
`9251694050ad0acdf4699cbedfabc11fe0597d28e57156f1e30d2b80df5ac9a3`.
All 31 capability verification checks passed.
The application was flashed into app0 while retaining saved device state.
Five intentional reboots returned the expected firmware, Bluetooth on and
radio2 off. USB Binary Companion device queries reported protocol 14,
350 contacts, 40 channels and manufacturer `LilyGo T-Deck`.
In the first 45-second runtime check, the screen was held on and a temporary
RX-only secondary used a 40-symbol preamble. The node completed 2,450 switches
with zero switch errors. At least six primary packets arrived while scanning
(`RX=6` advanced to `RX=12`). The longest observed active-pair retune was
1,224 us, with a provisional guarded budget of 1,347 us. The timing
recommendation window had not finished, so this remains a runtime smoke check.
A second runtime check also retained zero switch errors. Its lifetime `max`
field already contained 4,518 us before that active test, following the earlier
return to single-profile operation. That value is not attributed to an
active-pair retune. The first run's results remain in its log; the second run's
JSON replaced the earlier runtime JSON, so the sanitized report identifies
these sources separately.
Windows completed a fresh PIN pairing, and a subsequent connection confirmed
`ENCRYPTION_AND_AUTHENTICATION`. A requested 30-second, 10 Hz DEVICE_INFO
exercise returned 69 successful queries and then timed out; it recorded no
notification-queue overflow. It did not complete the intended 300-query workload
and is not a passing sustained BLE test. That earlier run overlapped
administrative settings writes.
A controlled retry configured the screen and secondary before starting BLE,
kept USB open without configuration changes during traffic, and performed
cleanup after traffic finished. It completed 30.060 seconds with 208 successful
DEVICE_INFO queries, achieving 6.886 queries/second against the requested 10 Hz.
Reply latency was 118.109 ms minimum, 145.063 ms mean, 239.963 ms p95 and
300.103 ms maximum. There were 213 notifications, including five unrelated
notifications, and no queue overflow or traffic disconnect. The authenticated
connection was still alive immediately before normal cleanup. APP_START was
not required. This passes the sustained-duration check while documenting the
lower achieved query rate; it does not establish the cause of the earlier timeout.
During that retry, radio switches advanced from 6,494 to 8,402 with zero errors,
and four primary packets arrived (`RX=125` to `RX=129`). The provisional guarded
switch budget was 1,281 us. The lifetime 4,527 us `max` was already present
before the retry and is not attributed to an active-pair retune.
The documented cleanup returned radio2 to off and the USB display mode to
`button-pairing`, and Bluetooth was on.
@@ -0,0 +1,52 @@
#pragma once
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
// Optional, same-owner scheduling experiment. This does not create a radio
// task or make the wrapper thread-safe. Pair begin/end in the existing radio
// owner's RX-to-RX retune hooks, including failed and deferred operations.
// The default request of zero preserves the owner's existing priority.
class ESP32RetunePriority {
UBaseType_t _requested = 0;
UBaseType_t _saved = 0;
UBaseType_t _depth = 0;
TaskHandle_t _owner = nullptr;
bool _boosted = false;
public:
ESP32RetunePriority() = default;
ESP32RetunePriority(const ESP32RetunePriority&) = delete;
ESP32RetunePriority& operator=(const ESP32RetunePriority&) = delete;
// A changed request applies to the next outer scope. It never replaces the
// original priority retained for an operation that is already in progress.
bool setPriority(UBaseType_t priority) {
if (priority >= configMAX_PRIORITIES) return false;
_requested = priority;
return true;
}
UBaseType_t requestedPriority() const { return _requested; }
bool isActive() const { return _boosted; }
void begin(bool continuousRx) {
if (_depth++ != 0) return;
if (!continuousRx || _requested == 0) return;
_saved = uxTaskPriorityGet(nullptr);
if (_saved >= _requested) return; // Never lower a higher-priority owner.
_owner = xTaskGetCurrentTaskHandle();
_boosted = true;
vTaskPrioritySet(_owner, _requested);
}
void end() {
if (_depth == 0 || --_depth != 0 || !_boosted) return;
// Clear our state before restoring: lowering priority may immediately
// schedule another task. Keep the saved owner/priority across that switch.
const TaskHandle_t owner = _owner;
const UBaseType_t saved = _saved;
_owner = nullptr;
_boosted = false;
vTaskPrioritySet(owner, saved);
}
};
+107
View File
@@ -0,0 +1,107 @@
"""Exercise the actual optional retune scope with a deterministic RTOS stub."""
from pathlib import Path
import os
import shutil
import subprocess
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
class ESP32RetunePriorityTests(unittest.TestCase):
def test_disabled_rx_gate_nested_restore_and_failed_operation_cleanup(self):
compiler = os.environ.get("CXX") or shutil.which("g++") or shutil.which("clang++")
if not compiler:
self.skipTest("a native C++ compiler is required")
with tempfile.TemporaryDirectory(prefix="esp32-retune-priority-") as directory:
work = Path(directory)
(work / "freertos").mkdir()
(work / "freertos/FreeRTOS.h").write_text(
"#pragma once\nusing UBaseType_t = unsigned;\n"
"struct FakeTask { UBaseType_t priority; };\n"
"using TaskHandle_t = FakeTask*;\n"
"#define configMAX_PRIORITIES 25\n", encoding="ascii")
(work / "freertos/task.h").write_text(
"#pragma once\n#include <freertos/FreeRTOS.h>\n"
"UBaseType_t uxTaskPriorityGet(TaskHandle_t);\n"
"TaskHandle_t xTaskGetCurrentTaskHandle();\n"
"void vTaskPrioritySet(TaskHandle_t, UBaseType_t);\n", encoding="ascii")
source = work / "main.cpp"
source.write_text(r'''
#include <cassert>
#include <helpers/radiolib/ESP32RetunePriority.h>
FakeTask task{1};
unsigned queries = 0, writes = 0;
UBaseType_t uxTaskPriorityGet(TaskHandle_t owner) {
++queries;
assert(owner == nullptr || owner == &task);
return task.priority;
}
TaskHandle_t xTaskGetCurrentTaskHandle() { return &task; }
void vTaskPrioritySet(TaskHandle_t owner, UBaseType_t priority) {
assert(owner == &task && priority < configMAX_PRIORITIES);
++writes;
owner->priority = priority;
}
int main() {
ESP32RetunePriority scope;
assert(scope.requestedPriority() == 0 && !scope.isActive());
scope.begin(true); scope.end(); scope.end();
assert(task.priority == 1 && queries == 0 && writes == 0);
assert(scope.setPriority(3));
scope.begin(false); scope.end();
assert(task.priority == 1 && queries == 0 && writes == 0);
scope.begin(true);
assert(task.priority == 3 && scope.isActive() && writes == 1);
scope.begin(true); scope.begin(false);
assert(task.priority == 3 && queries == 1 && writes == 1);
scope.end(); scope.end();
assert(task.priority == 3 && scope.isActive() && writes == 1);
scope.end();
assert(task.priority == 1 && !scope.isActive() && writes == 2);
// Hook cleanup is unconditional: both a deferred guard and a failed radio
// operation use the same end() and must return the original priority.
for (bool operationSucceeded : {false, true}) {
(void)operationSucceeded;
scope.begin(true);
assert(task.priority == 3);
scope.end();
assert(task.priority == 1 && !scope.isActive());
}
task.priority = 7;
unsigned beforeWrites = writes;
scope.begin(true); scope.end();
assert(task.priority == 7 && writes == beforeWrites && !scope.isActive());
task.priority = 1;
scope.begin(true);
assert(task.priority == 3);
assert(scope.setPriority(0));
assert(!scope.setPriority(configMAX_PRIORITIES));
assert(scope.requestedPriority() == 0);
scope.end();
assert(task.priority == 1 && !scope.isActive());
beforeWrites = writes;
scope.begin(true); scope.end();
assert(task.priority == 1 && writes == beforeWrites);
scope.end();
assert(task.priority == 1 && writes == beforeWrites);
}
'''.replace("#include <cassert>", "#include <cassert>\n#include <initializer_list>"), encoding="ascii")
binary = work / "retune-priority.exe"
result = subprocess.run(
[compiler, "-std=c++17", "-Wall", "-Wextra", "-Werror",
"-I", str(work), "-I", str(ROOT / "src"), str(source), "-o", str(binary)],
capture_output=True, text=True, timeout=60)
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
result = subprocess.run([str(binary)], capture_output=True, text=True, timeout=10)
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
if __name__ == "__main__":
unittest.main()
+68
View File
@@ -0,0 +1,68 @@
"""Check the HIL-only ESP32-S3 radio clock phase experiment under C++11."""
from pathlib import Path
import os
import subprocess
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
class TDeckSpiClockTimingTests(unittest.TestCase):
def test_all_dividers_preserve_frequency_and_correct_only_phase_fields(self):
fixture = r'''
#include <cassert>
#include <cstdint>
#include <initializer_list>
#include "TDeckSpiClockTiming.h"
int main() {
for (uint32_t pre = 0; pre < 16; ++pre) {
for (uint32_t n = 0; n < 64; ++n) {
for (uint32_t h = 0; h < 64; ++h) {
// Vary L independently too. Include reserved bits so a phase repair
// cannot silently modify frequency, source selection or other fields.
const uint32_t l = (h * 19 + 7) & 63;
const uint32_t original = 0x12400000U | (pre << 18) | (n << 12) | (h << 6) | l;
const uint32_t corrected = TDeckSpiClockTiming::corrected(original);
assert((corrected & ~0x0fffU) == (original & ~0x0fffU));
if (n == 0) assert(corrected == original);
else {
assert((corrected & 63) == n);
assert(((corrected >> 6) & 63) == (n + 1) / 2 - 1);
assert(TDeckSpiClockTiming::corrected(corrected) == corrected);
}
// The undivided source-clock mode must remain completely untouched.
const uint32_t sourceClock = original | (1U << 31);
assert(TDeckSpiClockTiming::corrected(sourceClock) == sourceClock);
}
}
}
// 8 MHz and 10 MHz can use period=2 plus a pre-divider. Their original
// H=0,L=1 is already correct, so this correction is not a general speed fix.
for (uint32_t pre : {4U, 3U, 2U}) {
const uint32_t raw = (pre << 18) | (1U << 12) | 1U;
assert(TDeckSpiClockTiming::corrected(raw) == raw);
}
// At 80 MHz source, /5 is 16 MHz but has 2 high and 3 low source ticks:
// 25 ns/37.5 ns. /6 with no pre-divider has symmetric 37.5 ns phases.
const uint32_t divide5 = TDeckSpiClockTiming::corrected((4U << 12) | 2U);
const uint32_t divide6 = TDeckSpiClockTiming::corrected((5U << 12) | 3U);
assert(((divide5 >> 6) & 63) + 1 == 2 && (divide5 & 63) == 4);
assert(((divide6 >> 6) & 63) + 1 == 3 && (divide6 & 63) == 5);
}
'''
with tempfile.TemporaryDirectory() as directory:
cpp = Path(directory) / "clock.cpp"
binary = Path(directory) / ("clock.exe" if os.name == "nt" else "clock")
cpp.write_text(fixture, encoding="ascii")
built = subprocess.run([os.environ.get("CXX", "g++"), "-std=c++11",
"-Wall", "-Wextra", "-I", str(ROOT / "tools/hil"), str(cpp), "-o", str(binary)],
capture_output=True, text=True)
self.assertEqual(built.returncode, 0, built.stderr)
ran = subprocess.run([str(binary)], capture_output=True, text=True)
self.assertEqual(ran.returncode, 0, ran.stderr)
if __name__ == "__main__":
unittest.main()
+89
View File
@@ -0,0 +1,89 @@
#pragma once
#include <helpers/radiolib/ESP32BufferedRadioHal.h>
#include "TDeckSpiClockTiming.h"
#if defined(CONFIG_IDF_TARGET_ESP32S3) && CONFIG_IDF_TARGET_ESP32S3
#include <esp_arduino_version.h>
#if ESP_ARDUINO_VERSION == ESP_ARDUINO_VERSION_VAL(2, 0, 17)
#include <soc/spi_struct.h>
#define MESH_TDECK_CLOCK_TIMING_SUPPORTED 1
#endif
#endif
// Experimental HIL-only divider comparison; hardware tests rejected this
// correction for production because it increased SPI read errors.
// The T-Deck radio and display both use SPIClass(HSPI), which is GPSPI3 on
// ESP32-S3. This helper must not be used with an FSPI radio bus. Correction is
// opt-in and limited to the pinned Arduino core whose divider was inspected.
class TDeckRadioHal : public ESP32BufferedRadioHal {
bool _correct_clock_timing = false;
bool _transaction_open = false;
bool _restore_clock = false;
uint32_t _original_clock = 0;
uint32_t _corrected_clock = 0;
public:
explicit TDeckRadioHal(SPIClass& bus, uint32_t hz = MC_SX1262_SPI_HZ)
: ESP32BufferedRadioHal(bus, hz) {}
static constexpr bool supportsClockTimingCorrection() {
#ifdef MESH_TDECK_CLOCK_TIMING_SUPPORTED
return true;
#else
return false;
#endif
}
// Change policy only between transactions. Return false if enabling is
// unsupported or a transaction is already open; retain the previous policy.
bool setClockTimingCorrection(bool enabled) {
if (_transaction_open || (enabled && !supportsClockTimingCorrection())) return false;
_correct_clock_timing = enabled;
return true;
}
bool isClockTimingCorrectionActive() const { return _correct_clock_timing; }
// Last transaction's raw values remain available after it ends. They are
// zero on unsupported cores, where this class retains the ordinary HAL.
uint32_t getOriginalClockTiming() const { return _original_clock; }
uint32_t getCorrectedClockTiming() const { return _corrected_clock; }
void spiBeginTransaction() override {
ArduinoHal::spiBeginTransaction();
_transaction_open = true;
_restore_clock = false;
#ifdef MESH_TDECK_CLOCK_TIMING_SUPPORTED
_original_clock = GPSPI3.clock.val;
_corrected_clock = _correct_clock_timing
? TDeckSpiClockTiming::corrected(_original_clock) : _original_clock;
if (_corrected_clock != _original_clock) {
// The base call already owns both SPI locks. Calling setClockDivider()
// or spiSetClockDiv() here would try to acquire a held mutex again.
GPSPI3.clock.val = _corrected_clock;
GPSPI3.cmd.update = 1;
while (GPSPI3.cmd.update) {}
_restore_clock = true;
}
#endif
}
void spiEndTransaction() override {
#ifdef MESH_TDECK_CLOCK_TIMING_SUPPORTED
if (_restore_clock) {
// Module has released radio CS. Restore the exact original divider while
// still owning the bus, before the TFT's independent SPIClass can use it.
GPSPI3.clock.val = _original_clock;
GPSPI3.cmd.update = 1;
while (GPSPI3.cmd.update) {}
}
#endif
_restore_clock = false;
_transaction_open = false;
ArduinoHal::spiEndTransaction();
}
};
// Correct phase fields do not make every nominal clock valid for the slave:
// 80 MHz / 5 gives 16 MHz with 25 ns high and 37.5 ns low, whereas / 6 gives
// 13.333 MHz with 37.5 ns in each phase. Check the SX1262 minimum phase times
// independently; do not select 16 MHz for production based on frequency alone.
+19
View File
@@ -0,0 +1,19 @@
#pragma once
#include <stdint.h>
// HIL-only ESP32-S3 SPI2/3 clock register experiment. Keep it independent of
// the peripheral so every N/pre combination can be checked on the host.
struct TDeckSpiClockTiming {
static constexpr uint32_t ClockEqualsSource = uint32_t(1) << 31;
static constexpr uint32_t PhaseMask = 0x0fff;
static uint32_t corrected(uint32_t original) {
const uint32_t n = (original >> 12) & 0x3f;
// Source-clock mode has no divided phases. N=0 likewise cannot represent
// both a high and a low phase; leave it untouched rather than underflow H.
if ((original & ClockEqualsSource) || n == 0) return original;
const uint32_t high = (n + 1) / 2 - 1;
return (original & ~PhaseMask) | n | (high << 6);
}
};
+544
View File
@@ -0,0 +1,544 @@
// Receive-only, RAM-only, same-image A/B harness for the production T-Deck
// display and production radio2 scheduler. There is deliberately no TX path.
#include <Arduino.h>
#include <SPI.h>
#include <stdarg.h>
#include <atomic>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
#include <helpers/radiolib/CustomSX1262Wrapper.h>
#include <helpers/radiolib/ESP32BufferedRadioHal.h>
#include "TDeckRadioHal.h"
#include <helpers/radiolib/ESP32RetunePriority.h>
#include <helpers/ui/ST7789LCDDisplay.h>
namespace {
// Exact min/mean/max plus bounded histogram percentiles. The percentile field
// is the upper edge of a bucket, not an interpolated/exact percentile.
const uint32_t timingEdges[] = {20, 50, 100, 200, 500, 750, 1000, 1500,
2000, 3000, 5000, 7500, 10000, 20000, 40000, 80000, 160000, UINT32_MAX};
struct Timing {
uint32_t n = 0, lo = UINT32_MAX, hi = 0;
uint64_t sum = 0;
uint32_t buckets[sizeof(timingEdges) / sizeof(timingEdges[0])] = {};
void add(uint32_t us) {
++n;
if (us < lo) lo = us;
if (us > hi) hi = us;
sum += us;
for (unsigned i = 0; i < sizeof(buckets) / sizeof(buckets[0]); ++i) {
if (us <= timingEdges[i]) { ++buckets[i]; break; }
}
}
uint32_t percentileUpper(unsigned percent) const {
if (!n) return 0;
const uint32_t target = (uint64_t(n) * percent + 99) / 100;
uint32_t cumulative = 0;
for (unsigned i = 0; i < sizeof(buckets) / sizeof(buckets[0]); ++i) {
cumulative += buckets[i];
if (cumulative >= target) return timingEdges[i];
}
return hi;
}
};
class BenchBoard : public mesh::MainBoard {
public:
uint16_t getBattMilliVolts() override { return 0; }
const char* getManufacturerName() const override { return "T-Deck display timing HIL"; }
void reboot() override { ESP.restart(); }
uint8_t getStartupReason() const override { return 0; }
} board;
// Default construction matches production's HSPI selection. The display has
// its own SPIClass(HSPI) handle and the same physical SCLK/MOSI pins.
SPIClass radioSpi;
class BenchHal : public TDeckRadioHal {
public:
bool bulkTransfer = false;
uint32_t transfers = 0, bytes = 0, modemQueries = 0, actualHz = 0;
explicit BenchHal(SPIClass& bus) : TDeckRadioHal(bus, 2000000) {}
void spiTransfer(uint8_t* out, size_t len, uint8_t* in) override {
++transfers; bytes += len;
actualHz = spiClockDivToFrequency(spi->getClockDivider());
if (len && out[0] == RADIOLIB_SX126X_CMD_GET_PACKET_TYPE) ++modemQueries;
if (bulkTransfer) ESP32BufferedRadioHal::spiTransfer(out, len, in);
else ArduinoHal::spiTransfer(out, len, in);
}
} radioHal(radioSpi);
CustomSX1262 chip = new Module(&radioHal, P_LORA_NSS, P_LORA_DIO_1,
P_LORA_RESET, P_LORA_BUSY);
class BenchWrapper : public CustomSX1262Wrapper {
uint32_t retuneStarted = 0, visitStarted = 0, dueAfterUs = 0;
uint8_t retuneFrom = 0;
public:
ESP32RetunePriority retunePriority;
using CustomSX1262Wrapper::CustomSX1262Wrapper;
bool measuring = false;
Timing retune[2], visit[2], late[2];
uint32_t successfulHops = 0, failedRetunes = 0;
unsigned actualRetunePriority = 0;
void resetMeasurements() {
for (unsigned i = 0; i < 2; ++i) { retune[i] = {}; visit[i] = {}; late[i] = {}; }
successfulHops = failedRetunes = 0;
actualRetunePriority = 0;
}
bool floorCalibrationPending() const { return _nf_refresh_requested; }
uint32_t nominalVisitUs(uint8_t profile) const {
return _profiles.listenUs(profile, profilePreamble(_profiles.slowerProfile()));
}
protected:
void beginProfileRetune(bool continuousRx) override {
retuneStarted = micros();
retunePriority.begin(continuousRx);
if (unsigned(uxTaskPriorityGet(nullptr)) > actualRetunePriority)
actualRetunePriority = uxTaskPriorityGet(nullptr);
retuneFrom = _active_profile;
visitStarted = _profile_visit_stamp;
dueAfterUs = nominalVisitUs(retuneFrom);
// Match serviceProfileScan's temporary noise-floor sample extension.
// A packet can legitimately extend an RX visit further; report received
// packets alongside lateness so that a busy-channel run is identifiable.
if (_nf_refresh_requested && profileFloorEstimator(retuneFrom).ready(uint32_t(millis()))
&& dueAfterUs < NoiseFloorSettleMillis * 1000UL)
dueAfterUs = NoiseFloorSettleMillis * 1000UL;
CustomSX1262Wrapper::beginProfileRetune(continuousRx);
}
void endProfileRetune(bool success) override {
CustomSX1262Wrapper::endProfileRetune(success);
retunePriority.end();
const uint32_t done = micros();
if (!measuring) return;
if (!success) { ++failedRetunes; return; }
if (retuneFrom == _active_profile) return;
++successfulHops;
retune[_active_profile].add(done - retuneStarted);
const uint32_t dwell = retuneStarted - visitStarted;
visit[retuneFrom].add(dwell);
late[retuneFrom].add(dwell > dueAfterUs ? dwell - dueAfterUs : 0);
}
} driver(chip, board);
ST7789LCDDisplay display;
bool ready = false, measuringService = false;
uint32_t lastServiceUs = 0, receivePackets = 0;
Timing serviceGap, serviceDuration, frameDuration;
char savedResult[6144] = {};
unsigned savedSequence = 0;
size_t resultUsed = 0;
std::atomic<bool> stressEnabled{false};
std::atomic<uint32_t> stressRounds{0};
bool stressTaskReady = false;
unsigned setupStage = 0;
int setupApplyResult = -1;
bool exactSpiClock = false;
uint32_t clockSettingHz = 8000000;
void configureRadioClock(unsigned spiMHz) {
clockSettingHz = spiMHz * 1000000UL;
if (exactSpiClock)
clockSettingHz = spiClockDivToFrequency(spiFrequencyToClockDiv(clockSettingHz));
radioHal.spiSettings = SPISettings(clockSettingHz, MSBFIRST, SPI_MODE0);
}
// A bounded, same-core priority-1 CPU competitor. It never accesses the radio,
// display, or SPI and sleeps between 250-us bursts. Report it separately from
// the unloaded measurements; it is not a simulation of Bluetooth's stack.
void stressTask(void*) {
for (;;) {
if (stressEnabled.load(std::memory_order_relaxed)) {
const uint32_t started = micros();
while (uint32_t(micros() - started) < 250) {}
stressRounds.fetch_add(1, std::memory_order_relaxed);
}
vTaskDelay(pdMS_TO_TICKS(2));
}
}
bool appendResult(const char* format, ...) {
if (resultUsed >= sizeof(savedResult)) return false;
va_list args;
va_start(args, format);
const int count = vsnprintf(savedResult + resultUsed, sizeof(savedResult) - resultUsed,
format, args);
va_end(args);
if (count < 0 || size_t(count) >= sizeof(savedResult) - resultUsed) {
resultUsed = sizeof(savedResult);
return false;
}
resultUsed += count;
return true;
}
void appendTiming(const char* name, const Timing& timing) {
appendResult("\"%s\":{\"n\":%u,\"min_us\":%u,\"mean_us\":%.3f,\"max_us\":%u,"
"\"p95_upper_us\":%u,\"p99_upper_us\":%u}", name, timing.n,
timing.n ? timing.lo : 0, timing.n ? double(timing.sum) / timing.n : 0,
timing.hi, timing.percentileUpper(95), timing.percentileUpper(99));
}
bool waitBusy() {
const uint32_t started = micros();
while (chip.isChipBusy()) {
if (uint32_t(micros() - started) > 20000) return false;
}
return true;
}
void serviceRadio() {
const uint32_t started = micros();
if (measuringService) {
if (lastServiceUs) serviceGap.add(started - lastServiceUs);
lastServiceUs = started;
}
// Keep the complete production scheduling/calibration/receive guards. The
// display callback is called only after its SPI transaction has ended.
driver.loop();
uint8_t packet[256];
const int received = driver.recvRaw(packet, sizeof(packet));
if (received > 0) {
++receivePackets;
driver.onReceiveProcessed();
}
if (measuringService) serviceDuration.add(micros() - started);
}
// Repeatable representative full UI redraw. Content and geometry are exactly
// the same for direct and buffered paths. Only the counter/bar change after
// the initial frame. Both paths redraw the full screen; the optimized path
// permits radio service between short, completed display transactions.
void drawFrame(unsigned mode, uint32_t frame) {
const uint32_t started = micros();
display.startFrame(UIColor::window_bkg);
display.setColor(UIColor::title_bkg);
display.fillRect(0, 0, display.width(), 28);
display.setColor(UIColor::title_txt);
display.setTextSize(2);
display.setCursor(10, 6);
display.print("T-Deck radio2 HIL");
display.setTextSize(1);
display.setColor(UIColor::primary_txt);
display.setCursor(12, 46);
display.print("Receive-only production profile scheduler");
display.setCursor(12, 68);
display.print("Primary: 909.5 MHz SF7 / BW62.5");
display.setCursor(12, 88);
display.print("Radio2: 910.5 MHz SF8 / BW500");
display.setColor(UIColor::corp_blue);
display.drawRect(12, 116, display.width() - 24, 28);
display.fillRect(16, 120, (frame % 20) * (display.width() - 32) / 20, 20);
char text[72];
snprintf(text, sizeof(text), "Frame %06lu render %s", (unsigned long)frame,
mode == 1 ? "direct" : "buffered");
display.setColor(UIColor::primary_txt);
display.setCursor(12, 168);
display.print(text);
display.setCursor(12, 200);
display.print("Native USB commands; no autonomous TX");
display.endFrame();
if (measuringService) frameDuration.add(micros() - started);
}
bool setProfiles(unsigned secondaryPreamble = 32) {
setupStage = 1; setupApplyResult = -1;
mesh::RadioProfileConfig secondary;
secondary.mode = mesh::RadioProfileMode::Off;
driver.profiles()->setSecondary(secondary, true);
for (unsigned i = 0; i < 4; ++i) { serviceRadio(); if (!waitBusy()) return false; }
mesh::RadioProfileParams primary;
primary.freq = 909.5f; primary.bw = 62.5f; primary.sf = 7;
primary.cr = 5; primary.preamble = 32;
setupStage = 2;
setupApplyResult = int(driver.trySetPrimaryParams(primary, true));
if (setupApplyResult != int(mesh::RadioParamApplyResult::APPLIED))
return false;
setupStage = 3;
secondary.params.freq = 910.5f; secondary.params.bw = 500;
secondary.params.sf = 8; secondary.params.cr = 5;
secondary.params.preamble = secondaryPreamble;
secondary.mode = mesh::RadioProfileMode::Rx;
driver.profiles()->setSecondary(secondary, true);
const uint32_t started = millis();
while (uint32_t(millis() - started) < 300) {
serviceRadio();
delay(0);
}
setupStage = 4;
return driver.profiles()->switchTestReady() && driver.isInRecvMode() && waitBusy();
}
void printInfo() {
Serial.printf("{\"bench\":\"tdeck-display-radio2-v2\",\"ready\":%s,"
"\"autonomous_tx\":false,\"psram_bytes\":%u,\"free_psram_bytes\":%u,"
"\"free_heap_bytes\":%u,\"buffered\":%s,\"width\":%d,\"height\":%d,"
"\"stress_task_ready\":%s,\"loop_priority\":%u,\"core\":%u,"
"\"clock_fix_supported\":%s,"
"\"command\":\"trial <display:0,1,2> <MHz:8..16> <modemcache:0,1> "
"<iqcache:0,1> <priority:0,3> <load:0,1> <preamble:32,40> "
"<seconds:1..10> <fps:1..30> <seq>\"}\n",
ready ? "true" : "false", ESP.getPsramSize(), ESP.getFreePsram(),
ESP.getFreeHeap(), display.isBufferedRendering() ? "true" : "false",
display.width(), display.height(), stressTaskReady ? "true" : "false",
unsigned(uxTaskPriorityGet(nullptr)), unsigned(xPortGetCoreID()),
TDeckRadioHal::supportsClockTimingCorrection() ? "true" : "false");
}
// Read-only link diagnostic, outside timed trials. Put the chip in standby
// at the known 8 MHz clock before changing the transfer policy; recover at
// 8 MHz afterwards. No identity/settings writes or RF transmission.
void inspectSpi(unsigned spiMHz, unsigned bulk, unsigned count = 100) {
radioHal.spiSettings = SPISettings(8000000, MSBFIRST, SPI_MODE0);
radioHal.bulkTransfer = true;
const int16_t standby = chip.standby();
uint8_t reference[2] = {};
const int16_t referenceRc = chip.readRegister(0x0740, reference, 2);
configureRadioClock(spiMHz);
radioHal.bulkTransfer = bulk;
unsigned correct = 0, bad = 0, firstBad = 0, syncBad = 0, readErrors = 0;
int firstReadError = 0;
for (unsigned i = 0; i < count; ++i) {
uint8_t modem = 0xff, sync[2] = {};
const int16_t modemRc = chip.getMod()->SPIreadStream(
RADIOLIB_SX126X_CMD_GET_PACKET_TYPE, &modem, 1);
const int16_t syncRc = chip.readRegister(0x0740, sync, 2);
if (modemRc != RADIOLIB_ERR_NONE || syncRc != RADIOLIB_ERR_NONE) {
if (!readErrors) firstReadError = modemRc ? modemRc : syncRc;
++readErrors;
}
if (modemRc == RADIOLIB_ERR_NONE && modem == RADIOLIB_SX126X_PACKET_TYPE_LORA) ++correct;
else { if (!bad) firstBad = modem; ++bad; }
if (syncRc != RADIOLIB_ERR_NONE || memcmp(sync, reference, sizeof(sync))) ++syncBad;
}
const uint32_t actualHz = radioHal.actualHz;
const uint32_t originalClock = radioHal.getOriginalClockTiming();
const uint32_t correctedClock = radioHal.getCorrectedClockTiming();
radioHal.spiSettings = SPISettings(8000000, MSBFIRST, SPI_MODE0);
radioHal.bulkTransfer = true;
const unsigned recoveryModem = chip.getPacketType();
const unsigned errors = chip.getDeviceErrors();
const int16_t resumed = chip.startReceive();
Serial.printf("{\"spi_inspection\":true,\"spi_mhz\":%u,\"bulk\":%s,"
"\"actual_spi_hz\":%u,\"read_pairs\":%u,\"exact_clock\":%s,"
"\"clock_setting_hz\":%u,\"clock_timing_corrected\":%s,"
"\"spi_clock_original\":%u,\"spi_clock_corrected\":%u,"
"\"standby_result\":%d,\"reference_result\":%d,"
"\"reference_sync\":[%u,%u],\"correct_modem_reads\":%u,"
"\"bad_modem_reads\":%u,\"first_bad_modem\":%u,"
"\"bad_sync_reads\":%u,\"read_errors\":%u,\"first_read_error\":%d,"
"\"recovery_modem\":%u,\"chip_errors_at_8mhz\":%u,"
"\"rx_resume_at_8mhz\":%d}\n", spiMHz, bulk ? "true" : "false",
actualHz, count, exactSpiClock ? "true" : "false", clockSettingHz,
radioHal.isClockTimingCorrectionActive() ? "true" : "false",
originalClock, correctedClock,
standby, referenceRc, reference[0], reference[1], correct,
bad, firstBad, syncBad, readErrors, firstReadError, recoveryModem, errors, resumed);
}
void run(unsigned mode, unsigned spiMHz, unsigned bulk, unsigned seconds,
unsigned fps, unsigned sequence, unsigned modemCache = 0,
unsigned iqCache = 0, unsigned priority = 0, unsigned load = 0,
unsigned secondaryPreamble = 32) {
if (!ready || !waitBusy()) { Serial.println("{\"error\":\"radio not ready\"}"); return; }
measuringService = driver.measuring = false;
radioHal.bulkTransfer = bulk;
configureRadioClock(spiMHz);
chip.hilUseFsOnRetune = true;
chip.hilSkipUnchangedPacket = true;
chip.hilSkipConfirmedModemQuery = modemCache;
chip.hilSkipUnchangedIq = iqCache;
driver.retunePriority.setPriority(priority);
display.setBufferedRendering(mode == 2);
display.setRenderYieldCallback(mode == 2 ? serviceRadio : nullptr);
if (mode == 2 && !display.isBufferedRendering()) {
Serial.println("{\"error\":\"display buffer unavailable\"}"); return;
}
if (!setProfiles(secondaryPreamble)) {
Serial.printf("{\"error\":\"profile setup failed\",\"setup_stage\":%u,"
"\"primary_apply_result\":%d,\"switch_failures\":%u,"
"\"spi_mhz\":%u,\"actual_spi_hz\":%u,\"chip_errors\":%u,"
"\"rx_mode\":%d}\n", setupStage, setupApplyResult,
driver.profiles()->switch_failures, spiMHz, radioHal.actualHz,
chip.getDeviceErrors(), sx126xReceiveMode(&chip));
return;
}
// Prime the frame buffer before measuring. Both redraw paths start from
// an already visible frame; no-display leaves that static screen in place.
if (mode) drawFrame(mode, 0);
if (!waitBusy()) { Serial.println("{\"error\":\"warmup busy timeout\"}"); return; }
const uint16_t chipErrorsBefore = chip.getDeviceErrors();
const uint32_t switchesBefore = driver.profiles()->switches;
const uint32_t failuresBefore = driver.profiles()->switch_failures;
const uint32_t optimizedBefore = chip.getOptimizedProfileSwitches();
const uint32_t modemSkipsBefore = chip.hilModemQuerySkips;
const uint32_t iqSkipsBefore = chip.hilIqWorkaroundSkips;
const uint32_t transfersBefore = radioHal.transfers, bytesBefore = radioHal.bytes;
const uint32_t modemQueriesBefore = radioHal.modemQueries;
const uint32_t stressBefore = stressRounds.load(std::memory_order_relaxed);
const unsigned originalPriority = uxTaskPriorityGet(nullptr);
stressEnabled.store(load != 0, std::memory_order_relaxed);
driver.resetMeasurements();
serviceGap = {}; serviceDuration = {}; frameDuration = {};
receivePackets = lastServiceUs = 0;
measuringService = driver.measuring = true;
const uint32_t started = micros();
uint32_t nextFrame = started, frames = 0;
const uint32_t intervalUs = 1000000UL / fps;
while (uint32_t(micros() - started) < seconds * 1000000UL) {
serviceRadio();
const uint32_t now = micros();
if (mode && int32_t(now - nextFrame) >= 0) {
drawFrame(mode, ++frames);
// Do not pile up overdue frames and starve the rest of the application.
nextFrame = now + intervalUs;
}
delay(0);
}
const uint32_t elapsedUs = micros() - started;
stressEnabled.store(false, std::memory_order_relaxed);
measuringService = driver.measuring = false;
display.setRenderYieldCallback(nullptr);
const bool idle = waitBusy();
const uint16_t chipErrorsAfter = chip.getDeviceErrors();
const int receiveMode = sx126xReceiveMode(&chip);
const unsigned active = driver.receiveProfile();
const auto& expected = driver.profiles()->params(active);
const bool cacheCorrect = chip.spreadingFactor == expected.sf
&& chip.bandwidthKhz == expected.bw && chip.codingRate == expected.cr - 4;
resultUsed = 0;
savedSequence = sequence;
savedResult[0] = 0;
appendResult("{\"result\":%u,\"bench\":\"tdeck-display-radio2-v2\",\"display_mode\":%u,"
"\"spi_mhz\":%u,\"bulk\":%s,\"seconds\":%u,\"requested_fps\":%u,"
"\"elapsed_us\":%u,\"frames\":%u,\"switches\":%u,\"switch_failures\":%u,"
"\"hook_hops\":%u,\"failed_retunes\":%u,\"optimized_rx_resumes\":%u,"
"\"received_packets\":%u,\"chip_errors_before\":%u,\"chip_errors_after\":%u,"
"\"busy_timeout\":%s,\"rx_mode\":%d,\"cache_correct\":%s,"
"\"floor_calibration_pending\":%s,\"nominal_visit_us\":[%u,%u],",
sequence, mode, spiMHz, bulk ? "true" : "false", seconds, fps,
elapsedUs, frames, driver.profiles()->switches - switchesBefore,
driver.profiles()->switch_failures - failuresBefore, driver.successfulHops,
driver.failedRetunes, chip.getOptimizedProfileSwitches() - optimizedBefore,
receivePackets, chipErrorsBefore, chipErrorsAfter, idle ? "false" : "true",
receiveMode, cacheCorrect ? "true" : "false",
driver.floorCalibrationPending() ? "true" : "false",
driver.nominalVisitUs(0), driver.nominalVisitUs(1));
appendResult("\"modem_cache\":%s,\"iq_cache\":%s,\"retune_priority\":%u,"
"\"synthetic_load\":%s,\"secondary_preamble\":%u,"
"\"modem_query_skips\":%u,\"iq_workaround_skips\":%u,\"actual_spi_hz\":%u,"
"\"spi_transfers\":%u,\"spi_bytes\":%u,\"modem_queries\":%u,"
"\"stress_rounds\":%u,\"original_priority\":%u,\"final_priority\":%u,"
"\"actual_retune_priority\":%u,\"core\":%u,\"exact_clock\":%s,"
"\"clock_setting_hz\":%u,\"clock_timing_corrected\":%s,"
"\"spi_clock_original\":%u,\"spi_clock_corrected\":%u,",
modemCache ? "true" : "false", iqCache ? "true" : "false", priority,
load ? "true" : "false", secondaryPreamble,
chip.hilModemQuerySkips - modemSkipsBefore,
chip.hilIqWorkaroundSkips - iqSkipsBefore,
radioHal.actualHz,
radioHal.transfers - transfersBefore, radioHal.bytes - bytesBefore,
radioHal.modemQueries - modemQueriesBefore,
stressRounds.load(std::memory_order_relaxed) - stressBefore,
originalPriority, unsigned(uxTaskPriorityGet(nullptr)),
driver.actualRetunePriority, unsigned(xPortGetCoreID()),
exactSpiClock ? "true" : "false", clockSettingHz,
radioHal.isClockTimingCorrectionActive() ? "true" : "false",
radioHal.getOriginalClockTiming(), radioHal.getCorrectedClockTiming());
appendTiming("service_gap", serviceGap); appendResult(",");
appendTiming("service_duration", serviceDuration); appendResult(",");
appendTiming("frame", frameDuration); appendResult(",\"directions\":[");
for (unsigned i = 0; i < 2; ++i) {
if (i) appendResult(",");
appendResult("{\"profile\":%u,", i);
appendTiming("retune_to", driver.retune[i]); appendResult(",");
appendTiming("visit_before_departure", driver.visit[i]); appendResult(",");
appendTiming("deadline_lateness", driver.late[i]); appendResult("}");
}
// ESP-IDF reports the high-water mark in bytes. This includes synchronous
// nesting of the display's stack strip buffer and radio-service callback.
appendResult("],\"free_heap_bytes\":%u,\"free_psram_bytes\":%u,"
"\"loop_stack_min_free_bytes\":%u}",
ESP.getFreeHeap(), ESP.getFreePsram(),
unsigned(uxTaskGetStackHighWaterMark(nullptr)));
if (resultUsed >= sizeof(savedResult)) {
savedSequence = 0;
Serial.println("{\"error\":\"result overflow\"}");
} else Serial.println(savedResult);
}
} // namespace
void setup() {
Serial.setTxBufferSize(8192);
Serial.setTxTimeoutMs(250);
Serial.begin(115200);
// Shared peripheral rail, TFT and SD deselected before touching the bus.
pinMode(PIN_PERF_POWERON, OUTPUT); digitalWrite(PIN_PERF_POWERON, HIGH);
pinMode(PIN_TFT_CS, OUTPUT); digitalWrite(PIN_TFT_CS, HIGH);
pinMode(39, OUTPUT); digitalWrite(39, HIGH);
pinMode(P_LORA_NSS, OUTPUT); digitalWrite(P_LORA_NSS, HIGH);
delay(100);
ready = chip.std_init(&radioSpi);
if (ready) {
driver.begin();
ready = driver.setRxPowerSaving(false, 65625, 60000);
}
const bool displayReady = display.begin();
display.setBufferedRendering(false);
ready = ready && displayReady && waitBusy();
stressTaskReady = xTaskCreatePinnedToCore(stressTask, "hilCpuLoad", 2048,
nullptr, 1, nullptr, xPortGetCoreID()) == pdPASS;
printInfo();
}
void loop() {
static char line[112];
static size_t used = 0;
while (Serial.available()) {
const char c = Serial.read();
if (c == '\r' || c == '\n') {
if (!used) continue;
line[used] = 0; used = 0;
unsigned mode, spiMHz, bulk, seconds, fps, sequence;
unsigned modemCache, iqCache, priority, load, preamble, count;
char trailing;
if (!strcmp(line, "info")) printInfo();
else if (!strcmp(line, "reboot")) ESP.restart();
else if (sscanf(line, "clockfix %u %c", &bulk, &trailing) == 1 && bulk <= 1) {
const bool supported = radioHal.setClockTimingCorrection(bulk);
Serial.printf("{\"clock_fix\":%s,\"supported\":%s}\n",
radioHal.isClockTimingCorrectionActive() ? "true" : "false",
supported ? "true" : "false");
}
else if (sscanf(line, "exactclock %u %c", &bulk, &trailing) == 1 && bulk <= 1) {
exactSpiClock = bulk;
Serial.printf("{\"exact_spi_clock\":%s}\n", exactSpiClock ? "true" : "false");
} else if (sscanf(line, "inspect %u %u %u %c", &spiMHz, &bulk, &count, &trailing) == 3
&& spiMHz >= 8 && spiMHz <= 16 && bulk <= 1 && count >= 1 && count <= 10000) {
inspectSpi(spiMHz, bulk, count);
}
else if (sscanf(line, "inspect %u %u %c", &spiMHz, &bulk, &trailing) == 2
&& spiMHz >= 8 && spiMHz <= 16 && bulk <= 1) {
inspectSpi(spiMHz, bulk);
}
else if (sscanf(line, "result %u %c", &sequence, &trailing) == 1) {
if (sequence == savedSequence && savedSequence) Serial.println(savedResult);
else Serial.println("{\"error\":\"result not retained\"}");
} else if (sscanf(line, "trial %u %u %u %u %u %u %u %u %u %u %c",
&mode, &spiMHz, &modemCache, &iqCache, &priority, &load,
&preamble, &seconds, &fps, &sequence, &trailing) == 10
&& mode <= 2 && spiMHz >= 8 && spiMHz <= 16
&& modemCache <= 1 && iqCache <= 1 && (priority == 0 || priority == 3)
&& load <= 1 && (!load || stressTaskReady)
&& (preamble == 32 || preamble == 40)
&& seconds >= 1 && seconds <= 10 && fps >= 1 && fps <= 30 && sequence) {
run(mode, spiMHz, 1, seconds, fps, sequence, modemCache, iqCache,
priority, load, preamble);
} else if (sscanf(line, "run %u %u %u %u %u %u %c", &mode, &spiMHz, &bulk,
&seconds, &fps, &sequence, &trailing) == 6
&& mode <= 2 && (spiMHz == 2 || spiMHz == 8) && bulk <= 1
&& seconds >= 1 && seconds <= 10 && fps >= 1 && fps <= 30 && sequence) {
run(mode, spiMHz, bulk, seconds, fps, sequence);
} else Serial.println("{\"error\":\"invalid command; use info\"}");
} else if (used + 1 < sizeof(line)) line[used++] = c;
}
if (ready) serviceRadio();
delay(0);
}
+57
View File
@@ -0,0 +1,57 @@
; Receive-only T-Deck display/radio scheduler A/B harness.
; Include this file in platformio.local.ini's extra_configs, then build
; tdeck_display_switch. No identity, persisted settings, network, or TX.
[env:tdeck_display_switch]
extends = arduino_base
platform = platformio/espressif32@6.11.0
board = t-deck
board_build.flash_mode = dio
upload_speed = 115200
lib_deps =
SPI
Wire
https://github.com/jgromes/RadioLib.git#2325a38a89dd0f0e402c19f67fe910111da1e246
rweather/Crypto @ ^0.4.0
adafruit/RTClib @ ^2.1.3
adafruit/Adafruit ST7735 and ST7789 Library @ ^1.11.0
extra_scripts =
pre:scripts/esp32_wifi_scan_fix.py
post:scripts/check_firmware_ram.py
build_flags =
${arduino_base.build_flags}
-D ESP32_PLATFORM
-D LILYGO_TDECK
-D BOARD_HAS_PSRAM=1
-D CORE_DEBUG_LEVEL=1
-D ARDUINO_USB_MODE=1
-D ARDUINO_USB_CDC_ON_BOOT=1
-D USE_SX1262
-D MC_SX1262_HIL=1
-D LORA_TX_POWER=0
-D SX126X_DIO2_AS_RF_SWITCH=false
-D SX126X_CURRENT_LIMIT=140
-D SX126X_RX_BOOSTED_GAIN=1
-D SX126X_DIO3_TCXO_VOLTAGE=1.8f
-D P_LORA_DIO_1=45
-D P_LORA_NSS=9
-D P_LORA_RESET=17
-D P_LORA_BUSY=13
-D P_LORA_SCLK=40
-D P_LORA_MISO=38
-D P_LORA_MOSI=41
-D PIN_PERF_POWERON=10
-D PIN_TFT_RST=-1
-D PIN_TFT_VDD_CTL=-1
-D PIN_TFT_LEDA_CTL=42
-D PIN_TFT_CS=12
-D PIN_TFT_DC=11
-D PIN_TFT_SCL=40
-D PIN_TFT_SDA=41
build_src_filter =
+<helpers/radiolib/RadioLibWrappers.cpp>
+<helpers/UsbLogging.cpp>
+<helpers/ui/DisplayDriver.cpp>
+<helpers/ui/DisplayPowerSettings.cpp>
+<helpers/ui/DisplayRotationSettings.cpp>
+<helpers/ui/ST7789LCDDisplay.cpp>
+<../tools/hil/tdeck_display_switch.cpp>
+146
View File
@@ -0,0 +1,146 @@
#!/usr/bin/env python3
"""Collect receive-only T-Deck display/radio scheduler A/B measurements.
Flash env:tdeck_display_switch first. This tool does not build, erase, flash,
reset, or transmit radio packets. Example:
python tools/hil/tdeck_display_switch.py COM10 --seconds 5 --repeats 3 \
--output tdeck-display-results.json
Modes: 0 static screen; 1 original direct redraw; 2 buffered strips with radio
service callbacks. SPI policies: original bytewise 2 MHz and buffered 8 MHz.
--full-spi-matrix adds the two intermediate policies to separate those effects.
Exact min/mean/max and coarse p95/p99 bucket upper bounds come from firmware.
"""
import argparse
import datetime as dt
import json
from pathlib import Path
import time
import serial
from profile_switch import open_session
def arguments():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("port")
parser.add_argument("--seconds", type=int, choices=range(1, 11), default=5)
parser.add_argument("--fps", type=int, choices=range(1, 31), default=20)
parser.add_argument("--repeats", type=int, default=3)
parser.add_argument("--full-spi-matrix", action="store_true")
parser.add_argument("--output", type=Path, required=True)
return parser.parse_args()
class Bench:
def __init__(self, port):
self.device = serial.Serial()
self.device.port = port
self.device.baudrate = 115200
self.device.timeout = 0.2
self.device.write_timeout = 2
# Reuse the native-USB DTR policy and no-reset bridge opener used by
# the other production-wrapper HIL tools.
open_session(self.device)
self.raw_lines = []
def close(self):
self.device.close()
def send(self, command):
self.device.write((command + "\n").encode("ascii"))
self.device.flush()
def receive(self, predicate, timeout):
deadline = time.monotonic() + timeout
pending = bytearray()
while time.monotonic() < deadline:
pending.extend(self.device.readline())
if len(pending) > 16384:
raise RuntimeError("Firmware response exceeded bounded line capture")
if not pending.endswith(b"\n"):
continue # A serial read timeout can split one logical line.
raw = pending.decode("utf-8", errors="replace").strip()
pending.clear()
if not raw:
continue
self.raw_lines.append(raw)
try:
value = json.loads(raw)
except json.JSONDecodeError:
continue
if "error" in value:
raise RuntimeError(f"Firmware rejected command: {value['error']}")
if predicate(value):
return value
raise TimeoutError("Timed out waiting for firmware JSON")
def main():
args = arguments()
if not 1 <= args.repeats <= 100:
raise SystemExit("--repeats must be between 1 and 100")
if args.output.exists():
raise SystemExit(f"Refusing to overwrite existing report: {args.output}")
report = {
"recorded_utc": dt.datetime.now(dt.timezone.utc).isoformat(),
"port": args.port,
"seconds_per_run": args.seconds,
"requested_fps": args.fps,
"repeats": args.repeats,
"receive_only": True,
"results": [],
}
bench = Bench(args.port)
try:
# Flush any partial input command, then request a fresh self-description.
bench.send("")
bench.send("info")
info = bench.receive(lambda value: value.get("bench") in (
"tdeck-display-radio2-v1", "tdeck-display-radio2-v2")
and "ready" in value, 5)
report["firmware"] = info
if not info["ready"]:
raise RuntimeError("Firmware is present but hardware initialization failed")
policies = [(2, 0), (8, 1)]
if args.full_spi_matrix:
policies = [(2, 0), (8, 0), (2, 1), (8, 1)]
sequence = 1
for repeat in range(args.repeats):
# Rotate display order between repeats to reduce run-order bias.
modes = [0, 1, 2]
modes = modes[repeat % 3:] + modes[:repeat % 3]
for mhz, bulk in policies:
for mode in modes:
command = (f"run {mode} {mhz} {bulk} {args.seconds} "
f"{args.fps} {sequence}")
print(f"{command} (repeat {repeat + 1})", flush=True)
bench.send(command)
try:
result = bench.receive(lambda value: value.get("result") == sequence,
args.seconds + 6)
except TimeoutError:
# Native USB may lose an output line while the stored
# firmware result remains available without rerunning.
bench.send(f"result {sequence}")
result = bench.receive(lambda value: value.get("result") == sequence, 4)
result["repeat"] = repeat + 1
report["results"].append(result)
print(" switches={switches}, frame max={frame[max_us]} us, "
"service gap max={service_gap[max_us]} us, chip errors="
"{chip_errors_after}".format(**result), flush=True)
sequence += 1
except BaseException as exc:
report["collection_error"] = str(exc)
raise
finally:
report["raw_lines"] = bench.raw_lines
bench.close()
args.output.parent.mkdir(parents=True, exist_ok=True)
args.output.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
print(f"Saved {len(report['results'])} runs to {args.output}", flush=True)
if __name__ == "__main__":
main()
+213
View File
@@ -0,0 +1,213 @@
#!/usr/bin/env python3
"""Collect controlled T-Deck retune experiments using the receive-only v2 HIL.
The main suite separates 16 MHz SPI, confirmed-modem caching and scoped retune
priority. The load suite compares priority under a bounded same-core CPU load;
the iq suite compares the IQ workaround cache with a 40-symbol secondary
preamble. Every policy runs with a static screen and buffered redraws.
This tool does not build, flash, reset or transmit packets. Example:
python tools/hil/tdeck_retune_experiments.py COM10 --suite main \
--seconds 5 --repeats 3 --fps 20 --output tdeck-retune-main.json
"""
import argparse
import datetime as dt
import json
import os
from pathlib import Path
import sys
from tdeck_display_switch import Bench
def arguments():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("port")
parser.add_argument("--suite", choices=("main", "load", "iq"), default="main")
parser.add_argument("--spi", nargs="+", type=int, choices=(8, 16), default=[8, 16],
help="SPI MHz policies to include (default: 8 16)")
parser.add_argument("--seconds", type=int, choices=range(1, 11), default=5)
parser.add_argument("--fps", type=int, choices=range(1, 31), default=20)
parser.add_argument("--repeats", type=int, choices=range(1, 101), default=3)
parser.add_argument("--output", type=Path, required=True)
return parser.parse_args()
def cases(suite):
# name, MHz, modem cache, IQ cache, scoped priority, synthetic load, preamble
policies = {
"main": [
("8MHz baseline", 8, 0, 0, 0, 0, 32),
("16MHz only", 16, 0, 0, 0, 0, 32),
("8MHz modem cache", 8, 1, 0, 0, 0, 32),
("8MHz priority 3", 8, 0, 0, 3, 0, 32),
("16MHz modem cache", 16, 1, 0, 0, 0, 32),
("16MHz modem cache priority 3", 16, 1, 0, 3, 0, 32),
],
"load": [
("loaded modem cache priority baseline", 8, 1, 0, 0, 1, 32),
("loaded modem cache priority 3", 8, 1, 0, 3, 1, 32),
],
"iq": [
("40-symbol IQ cache off", 8, 1, 0, 0, 0, 40),
("40-symbol IQ cache on", 8, 1, 1, 0, 0, 40),
],
}[suite]
return [dict(name=name, display_mode=mode, spi_mhz=mhz,
modem_cache=bool(modem), iq_cache=bool(iq),
retune_priority=priority, synthetic_load=bool(load),
secondary_preamble=preamble)
for name, mhz, modem, iq, priority, load, preamble in policies
for mode in (0, 2)]
def command(case, seconds, fps, sequence):
return (f"trial {case['display_mode']} {case['spi_mhz']} "
f"{int(case['modem_cache'])} {int(case['iq_cache'])} "
f"{case['retune_priority']} {int(case['synthetic_load'])} "
f"{case['secondary_preamble']} {seconds} {fps} {sequence}")
def validate(result, case, firmware, sequence, seconds, fps):
failures = []
expected = {key: value for key, value in case.items() if key != "name"}
expected.update(result=sequence, bench=firmware["bench"], bulk=True,
seconds=seconds, requested_fps=fps, busy_timeout=False,
rx_mode=1, cache_correct=True, chip_errors_before=0,
chip_errors_after=0, switch_failures=0, failed_retunes=0,
actual_retune_priority=max(firmware["loop_priority"], case["retune_priority"]))
if "core" in firmware:
expected["core"] = firmware["core"]
for key, wanted in expected.items():
if (key not in result or result[key] != wanted
or (isinstance(wanted, bool) and not isinstance(result[key], bool))):
failures.append(f"{key}: expected {wanted!r}, got {result.get(key)!r}")
for key in ("original_priority", "final_priority"):
if result.get(key) != firmware.get("loop_priority"):
failures.append(f"{key}: expected owner priority {firmware.get('loop_priority')!r}, "
f"got {result.get(key)!r}")
if result.get("original_priority") != result.get("final_priority"):
failures.append("owner priority was not restored")
positive = ["switches", "hook_hops", "optimized_rx_resumes", "spi_transfers", "spi_bytes",
"loop_stack_min_free_bytes"]
if case["display_mode"]:
positive.append("frames")
if case["synthetic_load"]:
positive.append("stress_rounds")
if case["modem_cache"]:
positive.append("modem_query_skips")
if case["iq_cache"]:
positive.append("iq_workaround_skips")
for key in positive:
value = result.get(key)
if not isinstance(value, (int, float)) or isinstance(value, bool) or value <= 0:
failures.append(f"{key}: expected a positive measurement, got {value!r}")
for key in ("service_gap", "service_duration"):
timing = result.get(key)
if not isinstance(timing, dict) or not timing.get("n", 0):
failures.append(f"{key}: missing timing samples")
elif not isinstance(timing.get("max_us"), (int, float)):
failures.append(f"{key}: missing maximum duration")
return failures
def persist(path, report, bench):
report["updated_utc"] = dt.datetime.now(dt.timezone.utc).isoformat()
report["raw_lines"] = list(bench.raw_lines) if bench else []
report["passed"] = sum(trial.get("passed") is True for trial in report["trials"])
report["failed"] = len(report["trials"]) - report["passed"]
# A complete previous checkpoint survives interruption while writing.
temporary = path.with_name(path.name + ".tmp")
temporary.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
os.replace(temporary, path)
def collect(args):
if args.output.exists():
raise SystemExit(f"Refusing to overwrite existing report: {args.output}")
args.output.parent.mkdir(parents=True, exist_ok=True)
plan = [case for case in cases(args.suite) if case["spi_mhz"] in args.spi]
if not plan:
raise SystemExit("No trial cases match the requested suite and SPI clocks")
report = dict(recorded_utc=dt.datetime.now(dt.timezone.utc).isoformat(),
suite=args.suite, port=args.port, seconds_per_run=args.seconds,
requested_fps=args.fps, repeats=args.repeats, receive_only=True,
requested_spis=list(args.spi),
priority_scope="retune only", planned_trials=len(plan)*args.repeats,
cases=plan, trials=[], results=[])
bench = None
persist(args.output, report, bench)
try:
bench = Bench(args.port)
bench.send("")
bench.send("info")
firmware = bench.receive(lambda value: isinstance(value.get("bench"), str)
and value["bench"].startswith("tdeck-display-radio2-")
and "ready" in value, 5)
report["firmware"] = firmware
if not firmware.get("ready") or not firmware.get("command", "").startswith("trial "):
raise RuntimeError("A ready T-Deck retune-experiment firmware is required")
if args.suite == "load" and not firmware.get("stress_task_ready"):
raise RuntimeError("The same-core synthetic-load task is unavailable")
if not isinstance(firmware.get("loop_priority"), int):
raise RuntimeError("Firmware did not report its original owner priority")
persist(args.output, report, bench)
sequence = 1
for repeat in range(args.repeats):
# Rotate policy order, then reverse alternate rounds to reduce
# systematic ordering effects without changing the controlled cases.
offset = (repeat * 2) % len(plan)
ordered = plan[offset:] + plan[:offset]
if repeat % 2:
ordered = list(reversed(ordered))
for case in ordered:
text = command(case, args.seconds, args.fps, sequence)
trial = dict(sequence=sequence, repeat=repeat+1, case=case,
command=text, passed=False, validation_errors=[])
print(f"[{repeat+1}/{args.repeats}] {case['name']} "
f"display={case['display_mode']}: {text}", flush=True)
try:
bench.send(text)
try:
result = bench.receive(lambda value: value.get("result") == sequence,
args.seconds + 6)
except TimeoutError:
trial["retried_retained_result"] = True
bench.send(f"result {sequence}")
result = bench.receive(lambda value: value.get("result") == sequence, 4)
trial["result"] = result
trial["validation_errors"] = validate(
result, case, firmware, sequence, args.seconds, args.fps)
trial["passed"] = not trial["validation_errors"]
report["results"].append(dict(result, repeat=repeat+1,
case_name=case["name"],
passed=trial["passed"]))
except Exception as exc:
# A rejected or lost trial does not discard successful
# earlier measurements or prevent independent later cases.
trial["collection_error"] = f"{type(exc).__name__}: {exc}"
report["trials"].append(trial)
persist(args.output, report, bench)
if trial["passed"]:
print(" PASS: switches={switches}, service gap max={service_gap[max_us]} us, "
"SPI transfers={spi_transfers}, modem skips={modem_query_skips}, "
"IQ skips={iq_workaround_skips}".format(**trial["result"]), flush=True)
else:
print(" FAIL: " + (trial.get("collection_error")
or "; ".join(trial["validation_errors"])), flush=True)
sequence += 1
except BaseException as exc:
report["collection_error"] = f"{type(exc).__name__}: {exc}"
raise
finally:
persist(args.output, report, bench)
if bench:
bench.close()
print(f"Saved {len(report['trials'])}/{report['planned_trials']} trials: "
f"{report['passed']} passed, {report['failed']} failed; {args.output}", flush=True)
return 1 if report["failed"] else 0
if __name__ == "__main__":
sys.exit(collect(arguments()))
+243
View File
@@ -0,0 +1,243 @@
#!/usr/bin/env python3
"""Sweep T-Deck radio SPI clocks with a fresh HIL reboot for each attempt.
WARNING: This collector explicitly REBOOTS the connected T-Deck before every
clock attempt. It does not erase or flash the device, save settings, or transmit
radio packets. Install the receive-only SPI-inspection HIL firmware first.
An 8 MHz baseline anchor is included even when --mhz omits it. Clock order
alternates ascending/descending between repeats. Each fresh boot runs 100 paired
modem/sync-word reads, then static-screen scheduling, then buffered redraws only
if the preceding checks passed. Requested and measured SPI clocks are retained;
ESP32 divider rounding can make different requests produce the same clock.
"""
import argparse
import datetime as dt
import json
import os
from pathlib import Path
import sys
import time
from tdeck_display_switch import Bench
from tdeck_retune_experiments import command, validate
def arguments():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("port")
parser.add_argument("--mhz", nargs="+", type=int, choices=range(8, 17),
default=list(range(8, 17)))
parser.add_argument("--repeats", type=int, choices=range(1, 101), default=3)
parser.add_argument("--seconds", type=int, choices=range(1, 11), default=3)
parser.add_argument("--fps", type=int, choices=range(1, 31), default=20)
parser.add_argument("--output", type=Path, required=True)
return parser.parse_args()
def capture(attempt, bench):
if bench:
attempt["raw_lines"].extend(bench.raw_lines)
bench.raw_lines.clear()
def checkpoint(path, report, attempt=None, bench=None):
if attempt is not None:
capture(attempt, bench)
report["updated_utc"] = dt.datetime.now(dt.timezone.utc).isoformat()
report["passed_attempts"] = sum(a.get("passed") is True for a in report["attempts"])
report["failed_attempts"] = sum(a.get("complete") and not a.get("passed")
for a in report["attempts"])
temporary = path.with_name(path.name + ".tmp")
temporary.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
os.replace(temporary, path)
def open_verified(port, attempt, phase):
"""Bounded reconnect; every failed open is closed before retrying."""
errors = []
for number in range(8):
bench = None
try:
bench = Bench(port)
bench.send("")
bench.send("info")
info = bench.receive(lambda value: isinstance(value.get("bench"), str)
and value["bench"].startswith("tdeck-display-radio2-")
and "ready" in value, 3)
if not info.get("ready") or not info.get("command", "").startswith("trial "):
raise RuntimeError("Ready T-Deck retune HIL firmware is required")
if not isinstance(info.get("loop_priority"), int):
raise RuntimeError("HIL did not report its owner priority")
attempt.setdefault("connection_attempts", []).append(
dict(phase=phase, attempt=number+1, passed=True))
capture(attempt, bench)
return bench, info
except Exception as exc:
error = f"{type(exc).__name__}: {exc}"
errors.append(error)
attempt.setdefault("connection_attempts", []).append(
dict(phase=phase, attempt=number+1, passed=False, error=error))
if bench:
capture(attempt, bench)
bench.close()
if number < 7:
time.sleep(0.5)
raise RuntimeError(f"Unable to connect during {phase} after 8 attempts: {errors[-1]}")
def inspection_errors(result, mhz):
expected = dict(spi_inspection=True, spi_mhz=mhz, bulk=True,
standby_result=0, reference_result=0,
correct_modem_reads=100, bad_modem_reads=0,
bad_sync_reads=0, read_errors=0, recovery_modem=1,
chip_errors_at_8mhz=0, rx_resume_at_8mhz=0)
errors = [f"{key}: expected {wanted!r}, got {result.get(key)!r}"
for key, wanted in expected.items()
if key not in result or result[key] != wanted]
actual = result.get("actual_spi_hz")
if not isinstance(actual, (int, float)) or isinstance(actual, bool) or actual <= 0:
errors.append(f"actual_spi_hz: expected measured clock, got {actual!r}")
if mhz == 8 and actual != 8000000:
errors.append(f"8 MHz baseline measured an unexpected clock: {actual!r}")
return errors
def run_trial(bench, attempt, firmware, mhz, mode, sequence, args):
case = dict(name=f"{mhz}MHz SPI sweep", display_mode=mode, spi_mhz=mhz,
modem_cache=True, iq_cache=False, retune_priority=0,
synthetic_load=False, secondary_preamble=32)
text = command(case, args.seconds, args.fps, sequence)
step = dict(kind="static" if mode == 0 else "buffered", command=text,
sequence=sequence, passed=False)
attempt["steps"].append(step)
try:
bench.send(text)
try:
result = bench.receive(lambda value: value.get("result") == sequence,
args.seconds + 6)
except TimeoutError:
step["retried_retained_result"] = True
bench.send(f"result {sequence}")
result = bench.receive(lambda value: value.get("result") == sequence, 4)
step["result"] = result
step["validation_errors"] = validate(
result, case, firmware, sequence, args.seconds, args.fps)
actual = result.get("actual_spi_hz")
if actual != attempt["inspection"].get("actual_spi_hz"):
step["validation_errors"].append(
f"actual_spi_hz changed from inspection: {actual!r}")
step["passed"] = not step["validation_errors"]
except Exception as exc:
step["collection_error"] = f"{type(exc).__name__}: {exc}"
checkpoint(args.output, args.report, attempt, bench)
return step["passed"]
def summarize(report):
report["baseline_anchor_passed"] = any(
a.get("passed") and a["spi_mhz"] == 8 for a in report["attempts"])
report["clock_summary"] = []
passing_hz = []
for mhz in report["clock_plan_mhz"]:
attempts = [a for a in report["attempts"] if a["spi_mhz"] == mhz]
actual = sorted({a["inspection"]["actual_spi_hz"] for a in attempts
if isinstance(a.get("inspection", {}).get("actual_spi_hz"), (int, float))})
passed = sum(a.get("passed") is True for a in attempts)
report["clock_summary"].append(dict(spi_mhz=mhz, actual_spi_hz=actual,
attempts=len(attempts), passed=passed))
# Require every independent repetition, not one lucky successful boot.
if len(attempts) == report["repeats"] and passed == len(attempts):
passing_hz.extend(actual)
report["maximum_passing_actual_spi_hz"] = (
max(passing_hz) if passing_hz and report["baseline_anchor_passed"] else None)
def collect(args):
if args.output.exists():
raise SystemExit(f"Refusing to overwrite existing report: {args.output}")
args.output.parent.mkdir(parents=True, exist_ok=True)
clocks = sorted(set(args.mhz) | {8})
report = dict(recorded_utc=dt.datetime.now(dt.timezone.utc).isoformat(),
port=args.port, requested_mhz=args.mhz, clock_plan_mhz=clocks,
repeats=args.repeats, seconds_per_trial=args.seconds,
requested_fps=args.fps, receive_only=True, reboots_device=True,
fresh_boot_per_clock_attempt=True, attempts=[])
args.report = report
checkpoint(args.output, report)
sequence = 1
try:
for repeat in range(args.repeats):
order = clocks if repeat % 2 == 0 else list(reversed(clocks))
for mhz in order:
attempt = dict(repeat=repeat+1, spi_mhz=mhz, baseline_anchor=mhz == 8,
steps=[], raw_lines=[], passed=False, complete=False)
report["attempts"].append(attempt)
bench = None
checkpoint(args.output, report)
print(f"[{repeat+1}/{args.repeats}] {mhz} MHz: rebooting HIL", flush=True)
try:
bench, info = open_verified(args.port, attempt, "before reboot")
attempt["pre_reboot_firmware"] = info
bench.send("reboot")
attempt["reboot_sent"] = True
capture(attempt, bench)
bench.close()
bench = None
checkpoint(args.output, report)
time.sleep(1.5)
bench, firmware = open_verified(args.port, attempt, "after reboot")
attempt["firmware"] = firmware
checkpoint(args.output, report, attempt, bench)
text = f"inspect {mhz} 1"
bench.send(text)
inspection = bench.receive(lambda value: value.get("spi_inspection") is True
and value.get("spi_mhz") == mhz, 6)
attempt["inspection"] = inspection
errors = inspection_errors(inspection, mhz)
attempt["steps"].append(dict(kind="inspection", command=text,
passed=not errors, validation_errors=errors))
checkpoint(args.output, report, attempt, bench)
if errors:
attempt["steps"].append(dict(kind="static", skipped=True,
reason="SPI inspection failed"))
attempt["steps"].append(dict(kind="buffered", skipped=True,
reason="SPI inspection failed"))
else:
static_ok = run_trial(bench, attempt, firmware, mhz, 0, sequence, args)
sequence += 1
if static_ok:
attempt["passed"] = run_trial(
bench, attempt, firmware, mhz, 2, sequence, args)
sequence += 1
else:
attempt["steps"].append(dict(kind="buffered", skipped=True,
reason="Static profile trial failed"))
except Exception as exc:
attempt["collection_error"] = f"{type(exc).__name__}: {exc}"
finally:
capture(attempt, bench)
if bench:
bench.close()
attempt["complete"] = True
summarize(report)
checkpoint(args.output, report)
actual = attempt.get("inspection", {}).get("actual_spi_hz", "unavailable")
print(f" {'PASS' if attempt['passed'] else 'FAIL'}: actual SPI {actual} Hz; "
f"checkpoint saved", flush=True)
except BaseException as exc:
report["collection_error"] = f"{type(exc).__name__}: {exc}"
raise
finally:
summarize(report)
checkpoint(args.output, report)
print(f"Saved {len(report['attempts'])} clock attempts: "
f"{report['passed_attempts']} passed, {report['failed_attempts']} failed; "
f"maximum passing measured clock={report['maximum_passing_actual_spi_hz']} Hz; "
f"{args.output}", flush=True)
return 1 if report["failed_attempts"] or not report["baseline_anchor_passed"] else 0
if __name__ == "__main__":
sys.exit(collect(arguments()))