Two new debug commands:
- 'X' (reset): ESP.restart() for clean reboot
- 'Z' (bootloader): sets RTC_CNTL_FORCE_DOWNLOAD_BOOT and restarts,
putting the ESP32-S3 directly into download mode for esptool
Workflow: screenshot.py z → esptool write_flash (no BOOT+RST)
Also adds reset/bootloader subcommands to screenshot.py.
Implements gui_list_files_fn callback to list SD card contents
as JSON via the serial debug protocol. Replaces the stub that
returned "use_log_command".
Refactors IMULogger to a general sensor data logger with tagged CSV format:
ms,type,d0,d1,...,d8
Types: A=accel, G=gyro, M=mag, S=step, W=wrist_tilt, P=GPS, T=touch
Each sensor pushes its own tagged sample independently instead of
the old combined IMU-only row format. GPS logged at 1Hz when active,
step/tilt events logged on occurrence, touch logged on press.
Adds Data Logger switch to the Settings screen with live sample
count and duration display.
Reorders includes so IMULogger.h is available to sensor callbacks.
The LXMF beacon path was gated on both lxmf_identity_configured AND
beacon_crypto_configured. The latter is only set when legacy collector
keys are provisioned via EEPROM — unrelated to LXMF. Removing the
gate allows the LXMF announce + telemetry path to work standalone.
Verified: watch LXMF announce received by Sideband as "RNode GPS
Tracker" via T-Beam Supreme LoRa gateway.
Also adds lxmf_id and bcn_crypto fields to metrics output.
Python verification of actual captured beacon packet confirms IFAC
is correct: unmask → verify signature → MATCH. The firmware crypto
implementation (IfacAuth.h) produces identical output to Reticulum.
T-Beam Supreme receiver detects RF energy (-74 dBm) but doesn't
decode a valid LoRa packet — the airtime counter shows activity but
no traffic is counted. Likely cause: near-field RF saturation (watch
and T-Beam are cm apart on the same Pi USB hub). The SX1262 receiver
may be overloaded at this close range.
Also: added beacon packet dump command 'B', extended crypto test
with live key verification, added T-Beam Supreme to device_init
signature bypass for development.
Firmware crypto test (debug command 'C') validates IfacAuth.h
against test vectors generated by scripts/test_ifac.py from
Reticulum's Python implementation:
pk: Ed25519 keypair from seed PASS
sig: Ed25519 detached signature PASS
hkdf: HKDF-SHA256 mask generation PASS
ifac: Full IFAC packet wrapping PASS
The IFAC crypto implementation matches Reticulum exactly.
The beacon reception failure is NOT a crypto bug — likely
an IFAC key provisioning issue (NVS storage mismatch) or
a beacon packet format issue before IFAC is applied.
Run: ./scripts/screenshot.py crypto
Generate vectors: python3 scripts/test_ifac.py
Also: guarded profiling variables for non-T-Watch builds
so T-Beam Supreme and other targets compile cleanly.
Watch no longer enters deep sleep after beacon TX when on external
power (charging or charged). This keeps the display, USB serial,
and debug tools active during development. On battery only, the
sleep/wake beacon cycle operates normally for power conservation.
Added beacon_gate and hw_ready to metrics output for debugging
beacon activation: gate 1=host active, 2=startup delay, 3=radio
offline, 4=no GPS fix, 5=interval wait, 6=beacon sent.
Verified: radio comes online with "RADIO" mode indicator and
amber "---" LoRa complication when provisioned with GPS fix.
Beacon mode activates after 15s no-host timeout.
Root cause found via loop profiling: two functions called every loop
iteration on unprovisioned devices consumed 950ms:
1. beacon_update() called startRadio() every loop when GPS had fix
but device wasn't provisioned (hw_ready=false). startRadio() does
full radio init with SPI commands and delays (~600ms). Fix: gate
beacon_update() on hw_ready.
2. stopRadio() called LoRa->end() (SPI sleep + SPI.end()) every loop
in the !hw_ready path (~99ms). Fix: only call when radio_online
is true (stop once, not repeatedly).
Result: loop time 950ms → 0.3ms (3200x improvement).
Also added:
- Main loop profiling (radio/serial/display/pmu/gps/bt/imu timing)
- Build timestamp in metrics command for version verification
- Visible-tile-only label updates (GPS float formatting skipped
when GPS screen not shown)
- Reverted to hwcdc USB mode (TinyUSB adds ~900ms/loop overhead)
- USB MSC SD card code preserved but inactive (needs TinyUSB)
SharedSPI.h: FreeRTOS mutex protecting the shared SPI bus (pins
33/34/35) used by LoRa (SX1262), SD card, and future NFC.
sx126x.cpp: All 6 SPI transaction blocks wrapped with
shared_spi_mutex acquire/release. LoRa uses portMAX_DELAY
(always gets access, just delayed by SD if needed).
USBSD.h: USB MSC SD card access uses shared_spi_mutex with
200ms timeout. Deferred init (3s after boot) for SPI bus
readiness. Metrics: sd_ready, sd_reads, sd_fails counters.
IMULogger.h, Gui.h: SD card writes wrapped in shared_spi_mutex.
Status: SD card correctly reports 29.7GB via USB MSC. Reads
work intermittently (~50% success). Root cause: main loop
takes ~700ms per iteration, causing mutex timeout for MSC
callbacks. Needs loop time investigation to achieve reliable
USB mass storage.
The CO5300 display uses a separate SPI3 bus — not affected.
Streams BHI260AP accelerometer (50Hz), gyroscope (50Hz), and
magnetometer (25Hz) as timestamped CSV to SD card. Ring buffer
in PSRAM (512 samples) flushed to SD from the main loop.
Remote debug command 'L' toggles logging. Python tool:
./scripts/screenshot.py log
CSV format: ms,ax,ay,az,gx,gy,gz,mx,my,mz (raw int16 units)
Measured throughput: ~43Hz actual sample rate.
Also fixed: BHI260AP init no longer gated on hw_ready (radio
provisioning) — IMU sensors should work regardless of radio state.
Foundation for compass calibration (PCA on magnetometer data),
gesture recognition training, and activity classification.
Wrist tilt gesture (sensor ID 67): waking the display by raising
the wrist toward you, with a light haptic click. Replaces the need
to touch the screen or press a button for the most common interaction.
Step counter (sensor ID 52): always-on pedometer displayed below
the complications on the watch face. Shows count once walking starts.
Both sensors configured after the deferred BHI260AP firmware upload
(~5s after boot). IMU events processed in the main loop via
bhi260->update(). Wrist tilt triggers display_unblank() directly.
Also added BoschSensorDataHelper.hpp for typed sensor data parsing
and imu_step_count/imu_wrist_tilt globals for cross-module access.
GPS screen: coordinates shown in teal when HDOP<10 (good fix),
grey when poor. Speed suppressed when HDOP>=10 (meaningless
noise from position drift). HDOP text color-coded: green (<2),
teal (<5), amber (<10), red (>=10).
Watch face GPS complication: satellite count color reflects fix
quality — teal (HDOP<5), amber (HDOP<15), grey (poor).
Addresses phantom speed readings during high-HDOP conditions
where position noise causes false velocity reports from the
GPS module's Kalman filter.
GPS screen: centered title and coordinate text to clear the
display's rounded corners. Previously left-aligned text was
clipped at the top-left corner radius.
Screenshot command: advance LVGL tick by LV_DEF_REFR_PERIOD+1
before calling lv_timer_handler() to ensure the refresh timer
fires. Previously the 1ms tick advance wasn't enough to trigger
a render cycle, resulting in black screenshots.
Watch face: replaced Steps complication with battery voltage and
charge state (green when charging/full, red when <15%, white
otherwise). Shows actual voltage (e.g., 4.17V).
Radio status screen: added BATTERY row (voltage + percentage)
and TEMPERATURE row (ESP32-S3 internal temp via PMU sensor).
Status bar continues to show percentage + charging indicator.
Scroll throw friction set to 2% (momentum carries into snap naturally).
Disabled elastic overscroll at tile boundaries.
gui_update_data() skipped during scroll animations to free CPU for
rendering. Added gui_is_scrolling() detection.
Loop timing metrics added: loop_us (interval between gui_update calls),
loop_max_us (worst case). Metrics show 84ms/frame during scroll
(37ms SPI flush + 44ms LVGL render). Release-to-snap latency is
~2 frames (~168ms).
SPI chunk size remains at 16384 pixels (32768 bytes) — larger chunks
cause display failure (DMA/PSRAM bandwidth limits on ESP32-S3).
Async DMA and larger chunks investigated but not viable with current
SPI driver constraints.
Switched from full-frame to partial rendering — only dirty
rectangles are rendered and flushed. Static watch face flushes
in ~750us vs ~18ms (24x faster). PSRAM usage drops from 824KB
to 197KB for draw buffers.
Remote debug protocol over serial (prefix "RWS" + command byte):
S — Screenshot (wakes display, forces full redraw, captures)
T — Touch injection (x, y, duration)
N — Navigate to tile by column/row
M — Frame metrics (JSON: flush/render times, memory)
I — Invalidate (force full redraw)
Python tool (scripts/screenshot.py) supports all commands:
screenshot, metrics, touch, swipe, navigate, invalidate
Screenshot now works correctly with partial rendering by
keeping the capture flag active across all flush strips and
forcing a full invalidation before capture.
Frame timing instrumentation added to flush callback and
render loop for performance profiling.
Switched all SPI operations from spi_device_polling_transmit (CPU
busy-wait) to spi_device_transmit (DMA with FreeRTOS yield). The
CPU blocks on a semaphore instead of spinning, allowing ISRs to
run during the ~18ms frame transfer.
Removed per-frame 411KB screenshot buffer copy — now only copies
when a screenshot is actually requested via serial trigger.
Shortened tileview scroll snap animation from default ~300ms to
150ms for snappier transitions with fewer intermediate frames.
Async DMA (queue_trans with deferred flush_ready) was investigated
but spi_device_queue_trans conflicts with spi_device_transmit on
the same device — needs further investigation with a fully queued
pipeline (no mixed blocking/queued calls).
Both custom fonts (96px time, 28px date/complications/sub-screens)
now render correctly using C++ namespace isolation to avoid symbol
collisions when included in the same translation unit.
Switched to LV_DISPLAY_RENDER_MODE_FULL with two 412KB PSRAM
frame buffers for tear-free scrolling. Combined with
LV_COLOR_FORMAT_RGB565_SWAPPED to eliminate byte-swap overhead
in the flush callback entirely.
Custom 96px font was not rendering because lv_font_conv defaults
to compressed bitmap format (bitmap_format=1) which requires
LV_USE_FONT_COMPRESSED. Regenerated with --no-compress.
Eliminated scroll tearing by switching from partial-strip rendering
to full-frame double buffering (LV_DISPLAY_RENDER_MODE_FULL).
Each buffer is 412KB in PSRAM (824KB total). Removes the need for
a separate byte-swap buffer — using LV_COLOR_FORMAT_RGB565_SWAPPED
so LVGL renders directly in the display's native byte order.
Also: hidden tileview scrollbar, enabled PSRAM in build flags.
LVGL 9.5.0 integration replacing direct framebuffer rendering.
Watch face with time, date, status bar (mode/battery), and three
complications (LoRa/GPS/Steps). Tileview swipe navigation between
five screens: watch face, radio status, GPS, messages, settings.
Haptic feedback on screen transitions via DRV2605.
Radio status screen shows frequency, LoRa params, RSSI bar gauge,
channel utilization, BLE state, and packet counts. GPS screen shows
coordinates, fix quality, altitude/speed, and beacon status.
Serial screenshot tool (scripts/screenshot.py) captures display
contents over USB CDC by sending trigger bytes and receiving the
shadow framebuffer as raw RGB565.
Build changes:
- FlashSize=16M in FQBN (bootloader embeds flash size, defaults 4MB)
- PSRAM=enabled for LVGL draw buffers and screenshot shadow buffer
- Custom 8MB app partition (partition_twatch.csv) for 16MB flash
- flash-twatch_ultra-full make target for full bootloader+partition+app flash
Architecture notes in code:
- display_init() must run BEFORE xl9555_init() (display power gate
defaults high at power-on, reordering causes black screen)
- LVGL draw buffers use separate swap buffer for RGB565 byte-order
conversion to avoid corrupting LVGL's internal buffer state
- Touch input registered via function pointer to decouple Gui.h from
touch library include order
