From 15b474172a922a1c80769e75af1b15fb27f4061e Mon Sep 17 00:00:00 2001 From: lewisxhe Date: Wed, 21 Jan 2026 17:33:50 +0800 Subject: [PATCH 01/16] Added compatibility with LilyGo T-Deck-Pro V1.1 --- src/detect/ScanI2C.h | 3 +- src/detect/ScanI2CTwoWire.cpp | 27 +++- src/graphics/EInkDisplay2.cpp | 3 + src/main.cpp | 4 + .../extra_variants/t_deck_pro/variant.cpp | 116 +++++++++++++++++- .../esp32s3/t-deck-pro-v1_1/pins_arduino.h | 19 +++ .../esp32s3/t-deck-pro-v1_1/platformio.ini | 41 +++++++ variants/esp32s3/t-deck-pro-v1_1/variant.h | 106 ++++++++++++++++ 8 files changed, 312 insertions(+), 7 deletions(-) create mode 100644 variants/esp32s3/t-deck-pro-v1_1/pins_arduino.h create mode 100644 variants/esp32s3/t-deck-pro-v1_1/platformio.ini create mode 100644 variants/esp32s3/t-deck-pro-v1_1/variant.h diff --git a/src/detect/ScanI2C.h b/src/detect/ScanI2C.h index dffcd8fb6..7b6fdc7a2 100644 --- a/src/detect/ScanI2C.h +++ b/src/detect/ScanI2C.h @@ -88,7 +88,8 @@ class ScanI2C BH1750, DA217, CHSC6X, - CST226SE + CST226SE, + CST3530, } DeviceType; // typedef uint8_t DeviceAddress; diff --git a/src/detect/ScanI2CTwoWire.cpp b/src/detect/ScanI2CTwoWire.cpp index c6ef34846..cb20a85c7 100644 --- a/src/detect/ScanI2CTwoWire.cpp +++ b/src/detect/ScanI2CTwoWire.cpp @@ -508,8 +508,33 @@ void ScanI2CTwoWire::scanPort(I2CPort port, uint8_t *address, uint8_t asize) SCAN_SIMPLE_CASE(DFROBOT_RAIN_ADDR, DFROBOT_RAIN, "DFRobot Rain Gauge", (uint8_t)addr.address); SCAN_SIMPLE_CASE(LTR390UV_ADDR, LTR390UV, "LTR390UV", (uint8_t)addr.address); SCAN_SIMPLE_CASE(PCT2075_ADDR, PCT2075, "PCT2075", (uint8_t)addr.address); + case CST328_ADDR: - // Do we have the CST328 or the CST226SE + // Do we have the CST328 or the CST226SE,CST3530 + { + // T-Deck pro V1.1 new touch panel use CST3530 + int retry = 5; + while(retry--) { + uint8_t buffer[7]; + uint8_t r_cmd[] = {0x0d0,0x03,0x00,0x00}; + i2cBus->beginTransmission(addr.address); + i2cBus->write(r_cmd, sizeof(r_cmd)); + if(i2cBus->endTransmission() == 0){ + i2cBus->requestFrom((int)addr.address,7); + i2cBus->readBytes(buffer,7); + if(buffer[2] == 0xCA && buffer[3] == 0xCA){ + logFoundDevice("CST3530", (uint8_t)addr.address); + type = CST3530; + break; + } + } + uint8_t cmd1[] = {0xD0,0x00,0x04,0x00}; + i2cBus->beginTransmission(addr.address); + i2cBus->write(cmd1, sizeof(cmd1)); + i2cBus->endTransmission(); + delay(50); + } + } registerValue = getRegisterValue(ScanI2CTwoWire::RegisterLocation(addr, 0xAB), 1); if (registerValue == 0xA9) { type = CST226SE; diff --git a/src/graphics/EInkDisplay2.cpp b/src/graphics/EInkDisplay2.cpp index 1678da793..6f53a56b9 100644 --- a/src/graphics/EInkDisplay2.cpp +++ b/src/graphics/EInkDisplay2.cpp @@ -104,8 +104,11 @@ bool EInkDisplay::forceDisplay(uint32_t msecLimit) // End the update process - virtual method, overriden in derived class void EInkDisplay::endUpdate() { +#ifndef EINK_NOT_HIBERNATE // Power off display hardware, then deep-sleep (Except Wireless Paper V1.1, no deep-sleep) adafruitDisplay->hibernate(); +#endif + } // Write the buffer to the display memory diff --git a/src/main.cpp b/src/main.cpp index c1096a240..d28dbb809 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -413,6 +413,10 @@ void setup() digitalWrite(SDCARD_CS, HIGH); pinMode(PIN_EINK_CS, OUTPUT); digitalWrite(PIN_EINK_CS, HIGH); + pinMode(PIN_EINK_RES, OUTPUT); + digitalWrite(PIN_EINK_RES, HIGH); + pinMode(CST328_PIN_RST, OUTPUT); + digitalWrite(CST328_PIN_RST, HIGH); #elif defined(T_LORA_PAGER) pinMode(LORA_CS, OUTPUT); digitalWrite(LORA_CS, HIGH); diff --git a/src/platform/extra_variants/t_deck_pro/variant.cpp b/src/platform/extra_variants/t_deck_pro/variant.cpp index eae9335ce..77fba53b9 100644 --- a/src/platform/extra_variants/t_deck_pro/variant.cpp +++ b/src/platform/extra_variants/t_deck_pro/variant.cpp @@ -8,20 +8,126 @@ CSE_CST328 tsPanel = CSE_CST328(EINK_WIDTH, EINK_HEIGHT, &Wire, CST328_PIN_RST, CST328_PIN_INT); +static bool is_cst3530 = false; +volatile bool touch_isr = false; +#define CST3530_ADDR 0x1A + +bool read_cst3530_touch(int16_t *x, int16_t *y) { + uint8_t buffer[9] = {0}; + uint8_t r_cmd[] = {0xD0, 0x07, 0x00, 0x00}; + uint8_t clear_cmd[] = {0xD0, 0x00, 0x02, 0xAB}; + + Wire.beginTransmission(CST3530_ADDR); + Wire.write(r_cmd, sizeof(r_cmd)); + if (Wire.endTransmission() != 0) { + LOG_DEBUG("CST3530 I2C send addr failed"); + return false; + } + + int read_len = Wire.requestFrom((int)CST3530_ADDR, sizeof(buffer)); + if (read_len != sizeof(buffer)) { + LOG_DEBUG("CST3530 read len error: %d (expect 9)", read_len); + return false; + } + int actual_read = Wire.readBytes(buffer, sizeof(buffer)); + if (actual_read != sizeof(buffer)) { + LOG_DEBUG("CST3530 read bytes error: %d (expect 9)", actual_read); + return false; + } + + uint8_t report_typ = buffer[2]; + if (report_typ != 0xFF) { + return false; + } + + uint8_t touch_points = buffer[3] & 0x0F; + if (touch_points == 0 || touch_points > 1) { + LOG_DEBUG("CST3530 touch points invalid: %d", touch_points); + return false; + } + + *x = buffer[4] + ((uint16_t)(buffer[7] & 0x0F) << 8); + *y = buffer[5] + ((uint16_t)(buffer[7] & 0xF0) << 4); + + // LOG_DEBUG("CST3530 touch: num:%d x=%d,y=%d", touch_points, *x, *y); + + Wire.beginTransmission(CST3530_ADDR); + Wire.write(clear_cmd, sizeof(clear_cmd)); + if (Wire.endTransmission() != 0) { + LOG_DEBUG("CST3530 clear cmd failed"); + } + + return true; +} + bool readTouch(int16_t *x, int16_t *y) { - if (tsPanel.getTouches()) { - *x = tsPanel.getPoint(0).x; - *y = tsPanel.getPoint(0).y; - return true; + + if(is_cst3530){ + if(touch_isr){ + touch_isr = false; + return read_cst3530_touch(x, y); + } + return false; + }else{ + if (tsPanel.getTouches()) { + *x = tsPanel.getPoint(0).x; + *y = tsPanel.getPoint(0).y; + return true; + } } return false; } + +static void touchInterruptHandler(){ + touch_isr = true; +} + // T-Deck Pro specific init void lateInitVariant() { - tsPanel.begin(); + // Reset touch + pinMode(CST328_PIN_RST, OUTPUT); + digitalWrite(CST328_PIN_RST, HIGH); + delay(20); + digitalWrite(CST328_PIN_RST, LOW); + delay(80); + digitalWrite(CST328_PIN_RST, HIGH); + delay(20); + + int retry = 5; + uint8_t buffer[7]; + uint8_t r_cmd[] = {0x0d0,0x03,0x00,0x00}; + + // Probe touch chip + while(retry--) { + Wire.beginTransmission(CST3530_ADDR); + Wire.write(r_cmd, sizeof(r_cmd)); + if(Wire.endTransmission() == 0){ + Wire.requestFrom((int)CST3530_ADDR,7); + Wire.readBytes(buffer,7); + if(buffer[2] == 0xCA && buffer[3] == 0xCA){ + LOG_DEBUG("CST3530 detected"); + is_cst3530 = true; + + // The CST3530 will automatically enter sleep mode; + // polling should not be used, but rather an interrupt method should be employed. + pinMode(CST328_PIN_INT, INPUT); + attachInterrupt(digitalPinToInterrupt(CST328_PIN_INT), touchInterruptHandler, FALLING); + + break; + }else{ + LOG_DEBUG("CST3530 not response ~!"); + } + } + uint8_t cmd1[] = {0xD0,0x00,0x04,0x00}; + Wire.beginTransmission(CST3530_ADDR); + Wire.write(cmd1, sizeof(cmd1)); + Wire.endTransmission(); + delay(50); + } + touchScreenImpl1 = new TouchScreenImpl1(EINK_WIDTH, EINK_HEIGHT, readTouch); touchScreenImpl1->init(); } diff --git a/variants/esp32s3/t-deck-pro-v1_1/pins_arduino.h b/variants/esp32s3/t-deck-pro-v1_1/pins_arduino.h new file mode 100644 index 000000000..af0ba80b3 --- /dev/null +++ b/variants/esp32s3/t-deck-pro-v1_1/pins_arduino.h @@ -0,0 +1,19 @@ +#ifndef Pins_Arduino_h +#define Pins_Arduino_h + +#include + +#define USB_VID 0x303a +#define USB_PID 0x1001 + +// used for keyboard, touch controller, beam sensor, and gyroscope +static const uint8_t SDA = 13; +static const uint8_t SCL = 14; + +// Default SPI will be mapped to Radio +static const uint8_t SS = 3; +static const uint8_t MOSI = 33; +static const uint8_t MISO = 47; +static const uint8_t SCK = 36; + +#endif /* Pins_Arduino_h */ diff --git a/variants/esp32s3/t-deck-pro-v1_1/platformio.ini b/variants/esp32s3/t-deck-pro-v1_1/platformio.ini new file mode 100644 index 000000000..b76522934 --- /dev/null +++ b/variants/esp32s3/t-deck-pro-v1_1/platformio.ini @@ -0,0 +1,41 @@ +[env:t-deck-pro-v1_1] +custom_meshtastic_hw_model = 102 +custom_meshtastic_hw_model_slug = T_DECK_PRO +custom_meshtastic_architecture = esp32-s3 +custom_meshtastic_actively_supported = true +custom_meshtastic_support_level = 1 +custom_meshtastic_display_name = LILYGO T-Deck Pro +custom_meshtastic_images = tdeck_pro.svg +custom_meshtastic_tags = LilyGo +custom_meshtastic_requires_dfu = true +custom_meshtastic_partition_scheme = 16MB + +extends = esp32s3_base +board = t-deck-pro +board_check = true +upload_protocol = esptool + +build_flags = + ${esp32s3_base.build_flags} -I variants/esp32s3/t-deck-pro-v1_1 + -D T_DECK_PRO + -D USE_EINK + -D EINK_DISPLAY_MODEL=GxEPD2_310_GDEQ031T10 + -D EINK_WIDTH=240 + -D EINK_HEIGHT=320 + ;-D USE_EINK_DYNAMICDISPLAY ; Enable Dynamic EInk + -D EINK_LIMIT_FASTREFRESH=10 ; How many consecutive fast-refreshes are permitted + -D EINK_LIMIT_GHOSTING_PX=2000 ; (Optional) How much image ghosting is tolerated + -D EINK_NOT_HIBERNATE ; Disable hibernate to avoid issues with elink + +lib_deps = + ${esp32s3_base.lib_deps} + # renovate: datasource=custom.pio depName=GxEPD2 packageName=zinggjm/library/GxEPD2 + zinggjm/GxEPD2@1.6.5 + # renovate: datasource=git-refs depName=CSE_Touch packageName=https://github.com/CIRCUITSTATE/CSE_Touch gitBranch=main + https://github.com/CIRCUITSTATE/CSE_Touch/archive/b44f23b6f870b848f1fbe453c190879bc6cfaafa.zip + # renovate: datasource=github-tags depName=CSE_CST328 packageName=CIRCUITSTATE/CSE_CST328 + https://github.com/CIRCUITSTATE/CSE_CST328/archive/refs/tags/v0.0.4.zip + # renovate: datasource=git-refs depName=BQ27220 packageName=https://github.com/mverch67/BQ27220 gitBranch=main + https://github.com/mverch67/BQ27220/archive/07d92be846abd8a0258a50c23198dac0858b22ed.zip + # renovate: datasource=custom.pio depName=Adafruit DRV2605 packageName=adafruit/library/Adafruit DRV2605 Library + adafruit/Adafruit DRV2605 Library@1.2.4 diff --git a/variants/esp32s3/t-deck-pro-v1_1/variant.h b/variants/esp32s3/t-deck-pro-v1_1/variant.h new file mode 100644 index 000000000..8584fd8a1 --- /dev/null +++ b/variants/esp32s3/t-deck-pro-v1_1/variant.h @@ -0,0 +1,106 @@ +// Display (E-Ink) +#define PIN_EINK_CS 34 +#define PIN_EINK_BUSY 37 +#define PIN_EINK_DC 35 +#define PIN_EINK_RES 16 +#define PIN_EINK_SCLK 36 +#define PIN_EINK_MOSI 47 +#define TFT_BL 45 // option , default not backlight + +#define I2C_SDA SDA +#define I2C_SCL SCL + +// CST328 touch screen (implementation in src/platform/extra_variants/t_deck_pro/variant.cpp) +#define HAS_TOUCHSCREEN 1 +#define CST328_PIN_INT 12 +#define CST328_PIN_RST 38 + +#define USE_POWERSAVE +#define SLEEP_TIME 120 + +// GNNS +#define HAS_GPS 1 +#define GPS_BAUDRATE 38400 +#define PIN_GPS_EN 39 +#define GPS_EN_ACTIVE 1 +#define GPS_RX_PIN 44 +#define GPS_TX_PIN 43 +#define PIN_GPS_PPS 1 + +#define BUTTON_PIN 0 + +// vibration motor +#define HAS_DRV2605 +#define PIN_DRV_EN 2 + +// Have SPI interface SD card slot +#define HAS_SDCARD +#define SDCARD_USE_SPI1 +#define SPI_MOSI (33) +#define SPI_SCK (36) +#define SPI_MISO (47) +#define SPI_CS (48) +#define SDCARD_CS SPI_CS +#define SD_SPI_FREQUENCY 75000000U + +// TCA8418 keyboard +#define KB_BL_PIN 42 +#define CANNED_MESSAGE_MODULE_ENABLE 1 + +// microphone PCM5102A +#define PCM5102A_SCK 47 +#define PCM5102A_DIN 17 +#define PCM5102A_LRCK 18 + +// LTR_553ALS light sensor +#define HAS_LTR553ALS + +// gyroscope BHI260AP +// #define BOARD_1V8_EN 38 //Deck-Pro remove 1.8v en pin +#define HAS_BHI260AP + +// battery charger BQ25896 +#define HAS_PPM 1 +#define XPOWERS_CHIP_BQ25896 + +// battery quality management BQ27220 +#define HAS_BQ27220 1 +#define BQ27220_I2C_SDA SDA +#define BQ27220_I2C_SCL SCL +#define BQ27220_DESIGN_CAPACITY 1400 + +// LoRa +#define USE_SX1262 +#define USE_SX1268 + +#define LORA_EN 46 // LoRa enable pin +#define LORA_SCK 36 +#define LORA_MISO 47 +#define LORA_MOSI 33 +#define LORA_CS 3 + +#define LORA_DIO0 -1 // a No connect on the SX1262 module +#define LORA_RESET 4 +#define LORA_DIO1 5 // SX1262 IRQ +#define LORA_DIO2 6 // SX1262 BUSY +#define LORA_DIO3 // Not connected on PCB, but internally on the TTGO SX1262, if DIO3 is high the TXCO is enabled + +#define SX126X_CS LORA_CS // FIXME - we really should define LORA_CS instead +#define SX126X_DIO1 LORA_DIO1 +#define SX126X_BUSY LORA_DIO2 +#define SX126X_RESET LORA_RESET +// Not really an E22 but TTGO seems to be trying to clone that +#define SX126X_DIO2_AS_RF_SWITCH +#define SX126X_DIO3_TCXO_VOLTAGE 2.4 +// Internally the TTGO module hooks the SX1262-DIO2 in to control the TX/RX switch (which is the default for the sx1262interface +// code) + +#define MODEM_POWER_EN 41 +#define MODEM_PWRKEY 40 +#define MODEM_RST 9 +#define MODEM_RI 7 +#define MODEM_DTR 8 +#define MODEM_RX 10 +#define MODEM_TX 11 + +#define HAS_PHYSICAL_KEYBOARD 1 \ No newline at end of file From edf660ccb399cb6d9d4490af6d7737bcf5013271 Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Thu, 16 Apr 2026 07:48:19 -0500 Subject: [PATCH 02/16] Update variants/esp32s3/t-deck-pro-v1_1/variant.h Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- variants/esp32s3/t-deck-pro-v1_1/variant.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variants/esp32s3/t-deck-pro-v1_1/variant.h b/variants/esp32s3/t-deck-pro-v1_1/variant.h index 8584fd8a1..af761d64d 100644 --- a/variants/esp32s3/t-deck-pro-v1_1/variant.h +++ b/variants/esp32s3/t-deck-pro-v1_1/variant.h @@ -18,7 +18,7 @@ #define USE_POWERSAVE #define SLEEP_TIME 120 -// GNNS +// GNSS #define HAS_GPS 1 #define GPS_BAUDRATE 38400 #define PIN_GPS_EN 39 From 5cae9e0183b1f84ad9502c28eb175219decee7b4 Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Thu, 16 Apr 2026 07:48:35 -0500 Subject: [PATCH 03/16] Update src/platform/extra_variants/t_deck_pro/variant.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/platform/extra_variants/t_deck_pro/variant.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platform/extra_variants/t_deck_pro/variant.cpp b/src/platform/extra_variants/t_deck_pro/variant.cpp index 77fba53b9..ff8e34ebd 100644 --- a/src/platform/extra_variants/t_deck_pro/variant.cpp +++ b/src/platform/extra_variants/t_deck_pro/variant.cpp @@ -80,7 +80,7 @@ bool readTouch(int16_t *x, int16_t *y) } -static void touchInterruptHandler(){ +static void IRAM_ATTR touchInterruptHandler(){ touch_isr = true; } From 7d957f8c7ba87905e1a7c25b652809642155cf6c Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Thu, 16 Apr 2026 07:48:50 -0500 Subject: [PATCH 04/16] Update variants/esp32s3/t-deck-pro-v1_1/platformio.ini Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- variants/esp32s3/t-deck-pro-v1_1/platformio.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variants/esp32s3/t-deck-pro-v1_1/platformio.ini b/variants/esp32s3/t-deck-pro-v1_1/platformio.ini index b76522934..1a9b20f76 100644 --- a/variants/esp32s3/t-deck-pro-v1_1/platformio.ini +++ b/variants/esp32s3/t-deck-pro-v1_1/platformio.ini @@ -30,7 +30,7 @@ build_flags = lib_deps = ${esp32s3_base.lib_deps} # renovate: datasource=custom.pio depName=GxEPD2 packageName=zinggjm/library/GxEPD2 - zinggjm/GxEPD2@1.6.5 + zinggjm/GxEPD2@1.6.8 # renovate: datasource=git-refs depName=CSE_Touch packageName=https://github.com/CIRCUITSTATE/CSE_Touch gitBranch=main https://github.com/CIRCUITSTATE/CSE_Touch/archive/b44f23b6f870b848f1fbe453c190879bc6cfaafa.zip # renovate: datasource=github-tags depName=CSE_CST328 packageName=CIRCUITSTATE/CSE_CST328 From d5af07e4584cef54c28a5247830b426931b43dc8 Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Thu, 16 Apr 2026 07:49:08 -0500 Subject: [PATCH 05/16] Update src/main.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/main.cpp | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/main.cpp b/src/main.cpp index 6b714f1cf..937df88cb 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -374,8 +374,10 @@ void setup() digitalWrite(SDCARD_CS, HIGH); pinMode(PIN_EINK_CS, OUTPUT); digitalWrite(PIN_EINK_CS, HIGH); +#if PIN_EINK_RES >= 0 pinMode(PIN_EINK_RES, OUTPUT); digitalWrite(PIN_EINK_RES, HIGH); +#endif pinMode(CST328_PIN_RST, OUTPUT); digitalWrite(CST328_PIN_RST, HIGH); #elif defined(T_LORA_PAGER) From 79e7ed30f1f7b44da205bb1e37e5ff0202318a00 Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Thu, 16 Apr 2026 07:49:34 -0500 Subject: [PATCH 06/16] Update src/graphics/EInkDisplay2.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/graphics/EInkDisplay2.cpp | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/graphics/EInkDisplay2.cpp b/src/graphics/EInkDisplay2.cpp index 96321f9c4..28b956bb1 100644 --- a/src/graphics/EInkDisplay2.cpp +++ b/src/graphics/EInkDisplay2.cpp @@ -105,10 +105,12 @@ bool EInkDisplay::forceDisplay(uint32_t msecLimit) void EInkDisplay::endUpdate() { #ifndef EINK_NOT_HIBERNATE - // Power off display hardware, then deep-sleep (Except Wireless Paper V1.1, no deep-sleep) + // By default, power off the E-Ink display hardware and enter hibernate(). + // Boards/panels that define EINK_NOT_HIBERNATE intentionally skip this step. + // Skipping hibernate() can help avoid panel-specific wake/refresh or ghosting issues, + // but it typically trades lower power savings for that compatibility. adafruitDisplay->hibernate(); #endif - } // Write the buffer to the display memory From 2c8dec2fbdaea2860851841a0fbd38eb129da13c Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Fri, 17 Apr 2026 19:48:07 -0500 Subject: [PATCH 07/16] Update meshtastic/device-ui digest to 56e1da4 (#10195) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- platformio.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platformio.ini b/platformio.ini index 3cd0cc9d0..4d66cf538 100644 --- a/platformio.ini +++ b/platformio.ini @@ -126,7 +126,7 @@ lib_deps = [device-ui_base] lib_deps = # renovate: datasource=git-refs depName=meshtastic/device-ui packageName=https://github.com/meshtastic/device-ui gitBranch=master - https://github.com/meshtastic/device-ui/archive/5305670b68eb5b92d14e62b5b536969ca4bb441f.zip + https://github.com/meshtastic/device-ui/archive/56e1da4e7d30abcd746a2092a30e422f8cf5fc2b.zip ; Common libs for environmental measurements in telemetry module [environmental_base] From d31d0f85fe789649e292478ea426ea29e2744b19 Mon Sep 17 00:00:00 2001 From: lewisxhe Date: Wed, 21 Jan 2026 17:33:50 +0800 Subject: [PATCH 08/16] Added compatibility with LilyGo T-Deck-Pro V1.1 --- src/detect/ScanI2C.h | 3 +- src/detect/ScanI2CTwoWire.cpp | 26 +++- src/graphics/EInkDisplay2.cpp | 3 + src/main.cpp | 60 +++++++++ .../extra_variants/t_deck_pro/variant.cpp | 116 +++++++++++++++++- .../esp32s3/t-deck-pro-v1_1/pins_arduino.h | 19 +++ .../esp32s3/t-deck-pro-v1_1/platformio.ini | 41 +++++++ variants/esp32s3/t-deck-pro-v1_1/variant.h | 106 ++++++++++++++++ 8 files changed, 367 insertions(+), 7 deletions(-) create mode 100644 variants/esp32s3/t-deck-pro-v1_1/pins_arduino.h create mode 100644 variants/esp32s3/t-deck-pro-v1_1/platformio.ini create mode 100644 variants/esp32s3/t-deck-pro-v1_1/variant.h diff --git a/src/detect/ScanI2C.h b/src/detect/ScanI2C.h index cc83a8d7b..5eb9217cc 100644 --- a/src/detect/ScanI2C.h +++ b/src/detect/ScanI2C.h @@ -94,7 +94,8 @@ class ScanI2C SFA30, CW2015, SCD30, - ADS1115 + ADS1115, + CST3530, } DeviceType; // typedef uint8_t DeviceAddress; diff --git a/src/detect/ScanI2CTwoWire.cpp b/src/detect/ScanI2CTwoWire.cpp index 2e00c11ce..e992fb276 100644 --- a/src/detect/ScanI2CTwoWire.cpp +++ b/src/detect/ScanI2CTwoWire.cpp @@ -585,7 +585,31 @@ void ScanI2CTwoWire::scanPort(I2CPort port, uint8_t *address, uint8_t asize) SCAN_SIMPLE_CASE(PCT2075_ADDR, PCT2075, "PCT2075", (uint8_t)addr.address); SCAN_SIMPLE_CASE(SCD30_ADDR, SCD30, "SCD30", (uint8_t)addr.address); case CST328_ADDR: - // Do we have the CST328 or the CST226SE + // Do we have the CST328 or the CST226SE,CST3530 + { + // T-Deck pro V1.1 new touch panel use CST3530 + int retry = 5; + while (retry--) { + uint8_t buffer[7]; + uint8_t r_cmd[] = {0x0d0, 0x03, 0x00, 0x00}; + i2cBus->beginTransmission(addr.address); + i2cBus->write(r_cmd, sizeof(r_cmd)); + if (i2cBus->endTransmission() == 0) { + i2cBus->requestFrom((int)addr.address, 7); + i2cBus->readBytes(buffer, 7); + if (buffer[2] == 0xCA && buffer[3] == 0xCA) { + logFoundDevice("CST3530", (uint8_t)addr.address); + type = CST3530; + break; + } + } + uint8_t cmd1[] = {0xD0, 0x00, 0x04, 0x00}; + i2cBus->beginTransmission(addr.address); + i2cBus->write(cmd1, sizeof(cmd1)); + i2cBus->endTransmission(); + delay(50); + } + } registerValue = getRegisterValue(ScanI2CTwoWire::RegisterLocation(addr, 0xAB), 1); if (registerValue == 0xA9) { type = CST226SE; diff --git a/src/graphics/EInkDisplay2.cpp b/src/graphics/EInkDisplay2.cpp index 704487bc8..96321f9c4 100644 --- a/src/graphics/EInkDisplay2.cpp +++ b/src/graphics/EInkDisplay2.cpp @@ -104,8 +104,11 @@ bool EInkDisplay::forceDisplay(uint32_t msecLimit) // End the update process - virtual method, overridden in derived class void EInkDisplay::endUpdate() { +#ifndef EINK_NOT_HIBERNATE // Power off display hardware, then deep-sleep (Except Wireless Paper V1.1, no deep-sleep) adafruitDisplay->hibernate(); +#endif + } // Write the buffer to the display memory diff --git a/src/main.cpp b/src/main.cpp index 6f78c0b96..cc7d25ed9 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -343,6 +343,66 @@ void setup() digitalWrite(BLE_LED, LED_STATE_OFF); #endif +#if defined(T_DECK) + // GPIO10 manages all peripheral power supplies + // Turn on peripheral power immediately after MUC starts. + // If some boards are turned on late, ESP32 will reset due to low voltage. + // ESP32-C3(Keyboard) , MAX98357A(Audio Power Amplifier) , + // TF Card , Display backlight(AW9364DNR) , AN48841B(Trackball) , ES7210(Decoder) + pinMode(KB_POWERON, OUTPUT); + digitalWrite(KB_POWERON, HIGH); + // T-Deck has all three SPI peripherals (TFT, SD, LoRa) attached to the same SPI bus + // We need to initialize all CS pins in advance otherwise there will be SPI communication issues + // e.g. when detecting the SD card + pinMode(LORA_CS, OUTPUT); + digitalWrite(LORA_CS, HIGH); + pinMode(SDCARD_CS, OUTPUT); + digitalWrite(SDCARD_CS, HIGH); + pinMode(TFT_CS, OUTPUT); + digitalWrite(TFT_CS, HIGH); + delay(100); +#elif defined(T_DECK_PRO) + pinMode(LORA_EN, OUTPUT); + digitalWrite(LORA_EN, HIGH); + pinMode(LORA_CS, OUTPUT); + digitalWrite(LORA_CS, HIGH); + pinMode(SDCARD_CS, OUTPUT); + digitalWrite(SDCARD_CS, HIGH); + pinMode(PIN_EINK_CS, OUTPUT); + digitalWrite(PIN_EINK_CS, HIGH); + pinMode(PIN_EINK_RES, OUTPUT); + digitalWrite(PIN_EINK_RES, HIGH); + pinMode(CST328_PIN_RST, OUTPUT); + digitalWrite(CST328_PIN_RST, HIGH); +#elif defined(T_LORA_PAGER) + pinMode(LORA_CS, OUTPUT); + digitalWrite(LORA_CS, HIGH); + pinMode(SDCARD_CS, OUTPUT); + digitalWrite(SDCARD_CS, HIGH); + pinMode(TFT_CS, OUTPUT); + digitalWrite(TFT_CS, HIGH); + pinMode(KB_INT, INPUT_PULLUP); + // io expander + io.begin(Wire, XL9555_SLAVE_ADDRESS0, SDA, SCL); + io.pinMode(EXPANDS_DRV_EN, OUTPUT); + io.digitalWrite(EXPANDS_DRV_EN, HIGH); + io.pinMode(EXPANDS_AMP_EN, OUTPUT); + io.digitalWrite(EXPANDS_AMP_EN, LOW); + io.pinMode(EXPANDS_LORA_EN, OUTPUT); + io.digitalWrite(EXPANDS_LORA_EN, HIGH); + io.pinMode(EXPANDS_GPS_EN, OUTPUT); + io.digitalWrite(EXPANDS_GPS_EN, HIGH); + io.pinMode(EXPANDS_KB_EN, OUTPUT); + io.digitalWrite(EXPANDS_KB_EN, HIGH); + io.pinMode(EXPANDS_SD_EN, OUTPUT); + io.digitalWrite(EXPANDS_SD_EN, HIGH); + io.pinMode(EXPANDS_GPIO_EN, OUTPUT); + io.digitalWrite(EXPANDS_GPIO_EN, HIGH); + io.pinMode(EXPANDS_SD_PULLEN, INPUT); +#elif defined(HACKADAY_COMMUNICATOR) + pinMode(KB_INT, INPUT); +#endif + concurrency::hasBeenSetup = true; #if HAS_SCREEN meshtastic_Config_DisplayConfig_OledType screen_model = diff --git a/src/platform/extra_variants/t_deck_pro/variant.cpp b/src/platform/extra_variants/t_deck_pro/variant.cpp index eae9335ce..77fba53b9 100644 --- a/src/platform/extra_variants/t_deck_pro/variant.cpp +++ b/src/platform/extra_variants/t_deck_pro/variant.cpp @@ -8,20 +8,126 @@ CSE_CST328 tsPanel = CSE_CST328(EINK_WIDTH, EINK_HEIGHT, &Wire, CST328_PIN_RST, CST328_PIN_INT); +static bool is_cst3530 = false; +volatile bool touch_isr = false; +#define CST3530_ADDR 0x1A + +bool read_cst3530_touch(int16_t *x, int16_t *y) { + uint8_t buffer[9] = {0}; + uint8_t r_cmd[] = {0xD0, 0x07, 0x00, 0x00}; + uint8_t clear_cmd[] = {0xD0, 0x00, 0x02, 0xAB}; + + Wire.beginTransmission(CST3530_ADDR); + Wire.write(r_cmd, sizeof(r_cmd)); + if (Wire.endTransmission() != 0) { + LOG_DEBUG("CST3530 I2C send addr failed"); + return false; + } + + int read_len = Wire.requestFrom((int)CST3530_ADDR, sizeof(buffer)); + if (read_len != sizeof(buffer)) { + LOG_DEBUG("CST3530 read len error: %d (expect 9)", read_len); + return false; + } + int actual_read = Wire.readBytes(buffer, sizeof(buffer)); + if (actual_read != sizeof(buffer)) { + LOG_DEBUG("CST3530 read bytes error: %d (expect 9)", actual_read); + return false; + } + + uint8_t report_typ = buffer[2]; + if (report_typ != 0xFF) { + return false; + } + + uint8_t touch_points = buffer[3] & 0x0F; + if (touch_points == 0 || touch_points > 1) { + LOG_DEBUG("CST3530 touch points invalid: %d", touch_points); + return false; + } + + *x = buffer[4] + ((uint16_t)(buffer[7] & 0x0F) << 8); + *y = buffer[5] + ((uint16_t)(buffer[7] & 0xF0) << 4); + + // LOG_DEBUG("CST3530 touch: num:%d x=%d,y=%d", touch_points, *x, *y); + + Wire.beginTransmission(CST3530_ADDR); + Wire.write(clear_cmd, sizeof(clear_cmd)); + if (Wire.endTransmission() != 0) { + LOG_DEBUG("CST3530 clear cmd failed"); + } + + return true; +} + bool readTouch(int16_t *x, int16_t *y) { - if (tsPanel.getTouches()) { - *x = tsPanel.getPoint(0).x; - *y = tsPanel.getPoint(0).y; - return true; + + if(is_cst3530){ + if(touch_isr){ + touch_isr = false; + return read_cst3530_touch(x, y); + } + return false; + }else{ + if (tsPanel.getTouches()) { + *x = tsPanel.getPoint(0).x; + *y = tsPanel.getPoint(0).y; + return true; + } } return false; } + +static void touchInterruptHandler(){ + touch_isr = true; +} + // T-Deck Pro specific init void lateInitVariant() { - tsPanel.begin(); + // Reset touch + pinMode(CST328_PIN_RST, OUTPUT); + digitalWrite(CST328_PIN_RST, HIGH); + delay(20); + digitalWrite(CST328_PIN_RST, LOW); + delay(80); + digitalWrite(CST328_PIN_RST, HIGH); + delay(20); + + int retry = 5; + uint8_t buffer[7]; + uint8_t r_cmd[] = {0x0d0,0x03,0x00,0x00}; + + // Probe touch chip + while(retry--) { + Wire.beginTransmission(CST3530_ADDR); + Wire.write(r_cmd, sizeof(r_cmd)); + if(Wire.endTransmission() == 0){ + Wire.requestFrom((int)CST3530_ADDR,7); + Wire.readBytes(buffer,7); + if(buffer[2] == 0xCA && buffer[3] == 0xCA){ + LOG_DEBUG("CST3530 detected"); + is_cst3530 = true; + + // The CST3530 will automatically enter sleep mode; + // polling should not be used, but rather an interrupt method should be employed. + pinMode(CST328_PIN_INT, INPUT); + attachInterrupt(digitalPinToInterrupt(CST328_PIN_INT), touchInterruptHandler, FALLING); + + break; + }else{ + LOG_DEBUG("CST3530 not response ~!"); + } + } + uint8_t cmd1[] = {0xD0,0x00,0x04,0x00}; + Wire.beginTransmission(CST3530_ADDR); + Wire.write(cmd1, sizeof(cmd1)); + Wire.endTransmission(); + delay(50); + } + touchScreenImpl1 = new TouchScreenImpl1(EINK_WIDTH, EINK_HEIGHT, readTouch); touchScreenImpl1->init(); } diff --git a/variants/esp32s3/t-deck-pro-v1_1/pins_arduino.h b/variants/esp32s3/t-deck-pro-v1_1/pins_arduino.h new file mode 100644 index 000000000..af0ba80b3 --- /dev/null +++ b/variants/esp32s3/t-deck-pro-v1_1/pins_arduino.h @@ -0,0 +1,19 @@ +#ifndef Pins_Arduino_h +#define Pins_Arduino_h + +#include + +#define USB_VID 0x303a +#define USB_PID 0x1001 + +// used for keyboard, touch controller, beam sensor, and gyroscope +static const uint8_t SDA = 13; +static const uint8_t SCL = 14; + +// Default SPI will be mapped to Radio +static const uint8_t SS = 3; +static const uint8_t MOSI = 33; +static const uint8_t MISO = 47; +static const uint8_t SCK = 36; + +#endif /* Pins_Arduino_h */ diff --git a/variants/esp32s3/t-deck-pro-v1_1/platformio.ini b/variants/esp32s3/t-deck-pro-v1_1/platformio.ini new file mode 100644 index 000000000..b76522934 --- /dev/null +++ b/variants/esp32s3/t-deck-pro-v1_1/platformio.ini @@ -0,0 +1,41 @@ +[env:t-deck-pro-v1_1] +custom_meshtastic_hw_model = 102 +custom_meshtastic_hw_model_slug = T_DECK_PRO +custom_meshtastic_architecture = esp32-s3 +custom_meshtastic_actively_supported = true +custom_meshtastic_support_level = 1 +custom_meshtastic_display_name = LILYGO T-Deck Pro +custom_meshtastic_images = tdeck_pro.svg +custom_meshtastic_tags = LilyGo +custom_meshtastic_requires_dfu = true +custom_meshtastic_partition_scheme = 16MB + +extends = esp32s3_base +board = t-deck-pro +board_check = true +upload_protocol = esptool + +build_flags = + ${esp32s3_base.build_flags} -I variants/esp32s3/t-deck-pro-v1_1 + -D T_DECK_PRO + -D USE_EINK + -D EINK_DISPLAY_MODEL=GxEPD2_310_GDEQ031T10 + -D EINK_WIDTH=240 + -D EINK_HEIGHT=320 + ;-D USE_EINK_DYNAMICDISPLAY ; Enable Dynamic EInk + -D EINK_LIMIT_FASTREFRESH=10 ; How many consecutive fast-refreshes are permitted + -D EINK_LIMIT_GHOSTING_PX=2000 ; (Optional) How much image ghosting is tolerated + -D EINK_NOT_HIBERNATE ; Disable hibernate to avoid issues with elink + +lib_deps = + ${esp32s3_base.lib_deps} + # renovate: datasource=custom.pio depName=GxEPD2 packageName=zinggjm/library/GxEPD2 + zinggjm/GxEPD2@1.6.5 + # renovate: datasource=git-refs depName=CSE_Touch packageName=https://github.com/CIRCUITSTATE/CSE_Touch gitBranch=main + https://github.com/CIRCUITSTATE/CSE_Touch/archive/b44f23b6f870b848f1fbe453c190879bc6cfaafa.zip + # renovate: datasource=github-tags depName=CSE_CST328 packageName=CIRCUITSTATE/CSE_CST328 + https://github.com/CIRCUITSTATE/CSE_CST328/archive/refs/tags/v0.0.4.zip + # renovate: datasource=git-refs depName=BQ27220 packageName=https://github.com/mverch67/BQ27220 gitBranch=main + https://github.com/mverch67/BQ27220/archive/07d92be846abd8a0258a50c23198dac0858b22ed.zip + # renovate: datasource=custom.pio depName=Adafruit DRV2605 packageName=adafruit/library/Adafruit DRV2605 Library + adafruit/Adafruit DRV2605 Library@1.2.4 diff --git a/variants/esp32s3/t-deck-pro-v1_1/variant.h b/variants/esp32s3/t-deck-pro-v1_1/variant.h new file mode 100644 index 000000000..8584fd8a1 --- /dev/null +++ b/variants/esp32s3/t-deck-pro-v1_1/variant.h @@ -0,0 +1,106 @@ +// Display (E-Ink) +#define PIN_EINK_CS 34 +#define PIN_EINK_BUSY 37 +#define PIN_EINK_DC 35 +#define PIN_EINK_RES 16 +#define PIN_EINK_SCLK 36 +#define PIN_EINK_MOSI 47 +#define TFT_BL 45 // option , default not backlight + +#define I2C_SDA SDA +#define I2C_SCL SCL + +// CST328 touch screen (implementation in src/platform/extra_variants/t_deck_pro/variant.cpp) +#define HAS_TOUCHSCREEN 1 +#define CST328_PIN_INT 12 +#define CST328_PIN_RST 38 + +#define USE_POWERSAVE +#define SLEEP_TIME 120 + +// GNNS +#define HAS_GPS 1 +#define GPS_BAUDRATE 38400 +#define PIN_GPS_EN 39 +#define GPS_EN_ACTIVE 1 +#define GPS_RX_PIN 44 +#define GPS_TX_PIN 43 +#define PIN_GPS_PPS 1 + +#define BUTTON_PIN 0 + +// vibration motor +#define HAS_DRV2605 +#define PIN_DRV_EN 2 + +// Have SPI interface SD card slot +#define HAS_SDCARD +#define SDCARD_USE_SPI1 +#define SPI_MOSI (33) +#define SPI_SCK (36) +#define SPI_MISO (47) +#define SPI_CS (48) +#define SDCARD_CS SPI_CS +#define SD_SPI_FREQUENCY 75000000U + +// TCA8418 keyboard +#define KB_BL_PIN 42 +#define CANNED_MESSAGE_MODULE_ENABLE 1 + +// microphone PCM5102A +#define PCM5102A_SCK 47 +#define PCM5102A_DIN 17 +#define PCM5102A_LRCK 18 + +// LTR_553ALS light sensor +#define HAS_LTR553ALS + +// gyroscope BHI260AP +// #define BOARD_1V8_EN 38 //Deck-Pro remove 1.8v en pin +#define HAS_BHI260AP + +// battery charger BQ25896 +#define HAS_PPM 1 +#define XPOWERS_CHIP_BQ25896 + +// battery quality management BQ27220 +#define HAS_BQ27220 1 +#define BQ27220_I2C_SDA SDA +#define BQ27220_I2C_SCL SCL +#define BQ27220_DESIGN_CAPACITY 1400 + +// LoRa +#define USE_SX1262 +#define USE_SX1268 + +#define LORA_EN 46 // LoRa enable pin +#define LORA_SCK 36 +#define LORA_MISO 47 +#define LORA_MOSI 33 +#define LORA_CS 3 + +#define LORA_DIO0 -1 // a No connect on the SX1262 module +#define LORA_RESET 4 +#define LORA_DIO1 5 // SX1262 IRQ +#define LORA_DIO2 6 // SX1262 BUSY +#define LORA_DIO3 // Not connected on PCB, but internally on the TTGO SX1262, if DIO3 is high the TXCO is enabled + +#define SX126X_CS LORA_CS // FIXME - we really should define LORA_CS instead +#define SX126X_DIO1 LORA_DIO1 +#define SX126X_BUSY LORA_DIO2 +#define SX126X_RESET LORA_RESET +// Not really an E22 but TTGO seems to be trying to clone that +#define SX126X_DIO2_AS_RF_SWITCH +#define SX126X_DIO3_TCXO_VOLTAGE 2.4 +// Internally the TTGO module hooks the SX1262-DIO2 in to control the TX/RX switch (which is the default for the sx1262interface +// code) + +#define MODEM_POWER_EN 41 +#define MODEM_PWRKEY 40 +#define MODEM_RST 9 +#define MODEM_RI 7 +#define MODEM_DTR 8 +#define MODEM_RX 10 +#define MODEM_TX 11 + +#define HAS_PHYSICAL_KEYBOARD 1 \ No newline at end of file From d0cd8ec366402e260df6761220eeb71bacea5d91 Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Thu, 16 Apr 2026 07:48:19 -0500 Subject: [PATCH 09/16] Update variants/esp32s3/t-deck-pro-v1_1/variant.h Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- variants/esp32s3/t-deck-pro-v1_1/variant.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variants/esp32s3/t-deck-pro-v1_1/variant.h b/variants/esp32s3/t-deck-pro-v1_1/variant.h index 8584fd8a1..af761d64d 100644 --- a/variants/esp32s3/t-deck-pro-v1_1/variant.h +++ b/variants/esp32s3/t-deck-pro-v1_1/variant.h @@ -18,7 +18,7 @@ #define USE_POWERSAVE #define SLEEP_TIME 120 -// GNNS +// GNSS #define HAS_GPS 1 #define GPS_BAUDRATE 38400 #define PIN_GPS_EN 39 From 2beebea453a0e6e7cc82cad6769eb528ff0792fa Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Thu, 16 Apr 2026 07:48:35 -0500 Subject: [PATCH 10/16] Update src/platform/extra_variants/t_deck_pro/variant.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/platform/extra_variants/t_deck_pro/variant.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platform/extra_variants/t_deck_pro/variant.cpp b/src/platform/extra_variants/t_deck_pro/variant.cpp index 77fba53b9..ff8e34ebd 100644 --- a/src/platform/extra_variants/t_deck_pro/variant.cpp +++ b/src/platform/extra_variants/t_deck_pro/variant.cpp @@ -80,7 +80,7 @@ bool readTouch(int16_t *x, int16_t *y) } -static void touchInterruptHandler(){ +static void IRAM_ATTR touchInterruptHandler(){ touch_isr = true; } From 84bb90943721bb399ee41e798aaa5f277e8fb5f8 Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Thu, 16 Apr 2026 07:48:50 -0500 Subject: [PATCH 11/16] Update variants/esp32s3/t-deck-pro-v1_1/platformio.ini Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- variants/esp32s3/t-deck-pro-v1_1/platformio.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variants/esp32s3/t-deck-pro-v1_1/platformio.ini b/variants/esp32s3/t-deck-pro-v1_1/platformio.ini index b76522934..1a9b20f76 100644 --- a/variants/esp32s3/t-deck-pro-v1_1/platformio.ini +++ b/variants/esp32s3/t-deck-pro-v1_1/platformio.ini @@ -30,7 +30,7 @@ build_flags = lib_deps = ${esp32s3_base.lib_deps} # renovate: datasource=custom.pio depName=GxEPD2 packageName=zinggjm/library/GxEPD2 - zinggjm/GxEPD2@1.6.5 + zinggjm/GxEPD2@1.6.8 # renovate: datasource=git-refs depName=CSE_Touch packageName=https://github.com/CIRCUITSTATE/CSE_Touch gitBranch=main https://github.com/CIRCUITSTATE/CSE_Touch/archive/b44f23b6f870b848f1fbe453c190879bc6cfaafa.zip # renovate: datasource=github-tags depName=CSE_CST328 packageName=CIRCUITSTATE/CSE_CST328 From 9e26cc3795365251b2d4dbc32c46a1a9cbe964fb Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Thu, 16 Apr 2026 07:49:08 -0500 Subject: [PATCH 12/16] Update src/main.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/main.cpp | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/main.cpp b/src/main.cpp index cc7d25ed9..76b9bb13a 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -370,8 +370,10 @@ void setup() digitalWrite(SDCARD_CS, HIGH); pinMode(PIN_EINK_CS, OUTPUT); digitalWrite(PIN_EINK_CS, HIGH); +#if PIN_EINK_RES >= 0 pinMode(PIN_EINK_RES, OUTPUT); digitalWrite(PIN_EINK_RES, HIGH); +#endif pinMode(CST328_PIN_RST, OUTPUT); digitalWrite(CST328_PIN_RST, HIGH); #elif defined(T_LORA_PAGER) From a277108c842fe4f97a1ed09938d295f6c777934c Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Thu, 16 Apr 2026 07:49:34 -0500 Subject: [PATCH 13/16] Update src/graphics/EInkDisplay2.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/graphics/EInkDisplay2.cpp | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/graphics/EInkDisplay2.cpp b/src/graphics/EInkDisplay2.cpp index 96321f9c4..28b956bb1 100644 --- a/src/graphics/EInkDisplay2.cpp +++ b/src/graphics/EInkDisplay2.cpp @@ -105,10 +105,12 @@ bool EInkDisplay::forceDisplay(uint32_t msecLimit) void EInkDisplay::endUpdate() { #ifndef EINK_NOT_HIBERNATE - // Power off display hardware, then deep-sleep (Except Wireless Paper V1.1, no deep-sleep) + // By default, power off the E-Ink display hardware and enter hibernate(). + // Boards/panels that define EINK_NOT_HIBERNATE intentionally skip this step. + // Skipping hibernate() can help avoid panel-specific wake/refresh or ghosting issues, + // but it typically trades lower power savings for that compatibility. adafruitDisplay->hibernate(); #endif - } // Write the buffer to the display memory From e589de2d6e86cede7890acc468d9e1693190695f Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Sat, 18 Apr 2026 11:12:05 -0500 Subject: [PATCH 14/16] Tronk --- .../extra_variants/t_deck_pro/variant.cpp | 45 ++++++++++--------- variants/esp32s3/t-deck-pro-v1_1/variant.h | 2 +- 2 files changed, 24 insertions(+), 23 deletions(-) diff --git a/src/platform/extra_variants/t_deck_pro/variant.cpp b/src/platform/extra_variants/t_deck_pro/variant.cpp index ff8e34ebd..2915ff363 100644 --- a/src/platform/extra_variants/t_deck_pro/variant.cpp +++ b/src/platform/extra_variants/t_deck_pro/variant.cpp @@ -10,13 +10,14 @@ CSE_CST328 tsPanel = CSE_CST328(EINK_WIDTH, EINK_HEIGHT, &Wire, CST328_PIN_RST, static bool is_cst3530 = false; volatile bool touch_isr = false; -#define CST3530_ADDR 0x1A +#define CST3530_ADDR 0x1A -bool read_cst3530_touch(int16_t *x, int16_t *y) { +bool read_cst3530_touch(int16_t *x, int16_t *y) +{ uint8_t buffer[9] = {0}; uint8_t r_cmd[] = {0xD0, 0x07, 0x00, 0x00}; - uint8_t clear_cmd[] = {0xD0, 0x00, 0x02, 0xAB}; - + uint8_t clear_cmd[] = {0xD0, 0x00, 0x02, 0xAB}; + Wire.beginTransmission(CST3530_ADDR); Wire.write(r_cmd, sizeof(r_cmd)); if (Wire.endTransmission() != 0) { @@ -41,13 +42,13 @@ bool read_cst3530_touch(int16_t *x, int16_t *y) { } uint8_t touch_points = buffer[3] & 0x0F; - if (touch_points == 0 || touch_points > 1) { + if (touch_points == 0 || touch_points > 1) { LOG_DEBUG("CST3530 touch points invalid: %d", touch_points); return false; } - *x = buffer[4] + ((uint16_t)(buffer[7] & 0x0F) << 8); - *y = buffer[5] + ((uint16_t)(buffer[7] & 0xF0) << 4); + *x = buffer[4] + ((uint16_t)(buffer[7] & 0x0F) << 8); + *y = buffer[5] + ((uint16_t)(buffer[7] & 0xF0) << 4); // LOG_DEBUG("CST3530 touch: num:%d x=%d,y=%d", touch_points, *x, *y); @@ -63,13 +64,13 @@ bool read_cst3530_touch(int16_t *x, int16_t *y) { bool readTouch(int16_t *x, int16_t *y) { - if(is_cst3530){ - if(touch_isr){ + if (is_cst3530) { + if (touch_isr) { touch_isr = false; return read_cst3530_touch(x, y); } return false; - }else{ + } else { if (tsPanel.getTouches()) { *x = tsPanel.getPoint(0).x; *y = tsPanel.getPoint(0).y; @@ -79,8 +80,8 @@ bool readTouch(int16_t *x, int16_t *y) return false; } - -static void IRAM_ATTR touchInterruptHandler(){ +static void IRAM_ATTR touchInterruptHandler() +{ touch_isr = true; } @@ -98,30 +99,30 @@ void lateInitVariant() int retry = 5; uint8_t buffer[7]; - uint8_t r_cmd[] = {0x0d0,0x03,0x00,0x00}; + uint8_t r_cmd[] = {0x0d0, 0x03, 0x00, 0x00}; // Probe touch chip - while(retry--) { + while (retry--) { Wire.beginTransmission(CST3530_ADDR); Wire.write(r_cmd, sizeof(r_cmd)); - if(Wire.endTransmission() == 0){ - Wire.requestFrom((int)CST3530_ADDR,7); - Wire.readBytes(buffer,7); - if(buffer[2] == 0xCA && buffer[3] == 0xCA){ + if (Wire.endTransmission() == 0) { + Wire.requestFrom((int)CST3530_ADDR, 7); + Wire.readBytes(buffer, 7); + if (buffer[2] == 0xCA && buffer[3] == 0xCA) { LOG_DEBUG("CST3530 detected"); is_cst3530 = true; - // The CST3530 will automatically enter sleep mode; - // polling should not be used, but rather an interrupt method should be employed. + // The CST3530 will automatically enter sleep mode; + // polling should not be used, but rather an interrupt method should be employed. pinMode(CST328_PIN_INT, INPUT); attachInterrupt(digitalPinToInterrupt(CST328_PIN_INT), touchInterruptHandler, FALLING); break; - }else{ + } else { LOG_DEBUG("CST3530 not response ~!"); } } - uint8_t cmd1[] = {0xD0,0x00,0x04,0x00}; + uint8_t cmd1[] = {0xD0, 0x00, 0x04, 0x00}; Wire.beginTransmission(CST3530_ADDR); Wire.write(cmd1, sizeof(cmd1)); Wire.endTransmission(); diff --git a/variants/esp32s3/t-deck-pro-v1_1/variant.h b/variants/esp32s3/t-deck-pro-v1_1/variant.h index af761d64d..d7accfe82 100644 --- a/variants/esp32s3/t-deck-pro-v1_1/variant.h +++ b/variants/esp32s3/t-deck-pro-v1_1/variant.h @@ -5,7 +5,7 @@ #define PIN_EINK_RES 16 #define PIN_EINK_SCLK 36 #define PIN_EINK_MOSI 47 -#define TFT_BL 45 // option , default not backlight +#define TFT_BL 45 // option , default not backlight #define I2C_SDA SDA #define I2C_SCL SCL From 6b15571e1407e53f6fe371ca611029f83d524693 Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Sat, 18 Apr 2026 08:17:44 -0500 Subject: [PATCH 15/16] Add MCP server for interacting with meshtastic devices and testing framework / TUI (#10194) * Start of MCP server and test suite * Add MCP server for interacting with meshtastic devices and testing framework / TUI * Update mcp-server/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix mcp-server review feedback from thread Agent-Logs-Url: https://github.com/meshtastic/firmware/sessions/91dc128a-ed50-4d07-8bb2-3dc6623a05f7 Co-authored-by: thebentern <9000580+thebentern@users.noreply.github.com> * Enhance StreamAPI and PhoneAPI for improved log record handling and concurrency control * Semgrep fixes * Trunk and semgrep fixes * optimize pio streaming tee file writes Agent-Logs-Url: https://github.com/meshtastic/firmware/sessions/04e26c6b-6a2b-45be-bbeb-79ae4d0be633 Co-authored-by: thebentern <9000580+thebentern@users.noreply.github.com> * chore: remove redundant log handle assignment Agent-Logs-Url: https://github.com/meshtastic/firmware/sessions/04e26c6b-6a2b-45be-bbeb-79ae4d0be633 Co-authored-by: thebentern <9000580+thebentern@users.noreply.github.com> * Consolidate type imports and remove placeholder test files * Add tests for config persistence and more exchange messages * Refactor position test to validate on-demand request/reply behavior * Remove position request/reply test and update README for telemetry behavior * Fix transmit history file to get removed on factory reset --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> --- .claude/commands/README.md | 49 + .claude/commands/diagnose.md | 55 + .claude/commands/repro.md | 65 + .claude/commands/test.md | 42 + .github/copilot-instructions.md | 160 ++ .github/prompts/mcp-diagnose.prompt.md | 57 + .github/prompts/mcp-repro.prompt.md | 67 + .github/prompts/mcp-test.prompt.md | 51 + .gitignore | 2 + .mcp.json | 11 + .trunk/configs/.bandit | 28 +- AGENTS.md | 113 ++ mcp-server/.gitignore | 26 + mcp-server/README.md | 270 +++ mcp-server/pyproject.toml | 39 + mcp-server/run-tests.sh | 236 +++ mcp-server/src/meshtastic_mcp/__init__.py | 3 + mcp-server/src/meshtastic_mcp/__main__.py | 11 + mcp-server/src/meshtastic_mcp/admin.py | 377 ++++ mcp-server/src/meshtastic_mcp/boards.py | 159 ++ mcp-server/src/meshtastic_mcp/cli/__init__.py | 6 + .../src/meshtastic_mcp/cli/_flashlog.py | 73 + mcp-server/src/meshtastic_mcp/cli/_fwlog.py | 96 + mcp-server/src/meshtastic_mcp/cli/_history.py | 127 ++ .../src/meshtastic_mcp/cli/_reproducer.py | 214 ++ mcp-server/src/meshtastic_mcp/cli/test_tui.py | 1782 +++++++++++++++++ mcp-server/src/meshtastic_mcp/config.py | 137 ++ mcp-server/src/meshtastic_mcp/connection.py | 84 + mcp-server/src/meshtastic_mcp/devices.py | 75 + mcp-server/src/meshtastic_mcp/flash.py | 447 +++++ mcp-server/src/meshtastic_mcp/hw_tools.py | 243 +++ mcp-server/src/meshtastic_mcp/info.py | 103 + mcp-server/src/meshtastic_mcp/pio.py | 295 +++ mcp-server/src/meshtastic_mcp/registry.py | 98 + .../src/meshtastic_mcp/serial_session.py | 216 ++ mcp-server/src/meshtastic_mcp/server.py | 590 ++++++ mcp-server/src/meshtastic_mcp/userprefs.py | 532 +++++ mcp-server/tests/README.md | 116 ++ mcp-server/tests/__init__.py | 0 mcp-server/tests/_port_discovery.py | 118 ++ mcp-server/tests/admin/__init__.py | 0 .../tests/admin/test_channel_url_roundtrip.py | 57 + .../tests/admin/test_config_roundtrip.py | 106 + .../tests/admin/test_owner_survives_reboot.py | 59 + mcp-server/tests/conftest.py | 1041 ++++++++++ mcp-server/tests/fleet/__init__.py | 0 .../fleet/test_psk_seed_isolates_runs.py | 43 + mcp-server/tests/mesh/__init__.py | 0 mcp-server/tests/mesh/_receive.py | 220 ++ mcp-server/tests/mesh/test_bidirectional.py | 83 + .../tests/mesh/test_broadcast_delivers.py | 45 + mcp-server/tests/mesh/test_direct_with_ack.py | 105 + mcp-server/tests/mesh/test_mesh_formation.py | 39 + mcp-server/tests/mesh/test_traceroute.py | 147 ++ mcp-server/tests/monitor/__init__.py | 0 .../tests/monitor/test_boot_log_no_panic.py | 63 + mcp-server/tests/provisioning/__init__.py | 0 .../provisioning/test_admin_key_baked.py | 83 + .../test_bake_region_modem_slot.py | 60 + .../test_unset_region_blocks_tx.py | 108 + .../test_userprefs_survive_factory_reset.py | 90 + mcp-server/tests/telemetry/__init__.py | 0 .../test_device_telemetry_broadcast.py | 77 + .../telemetry/test_telemetry_request_reply.py | 187 ++ mcp-server/tests/test_00_bake.py | 291 +++ mcp-server/tests/tool_coverage.py | 145 ++ mcp-server/tests/unit/__init__.py | 0 mcp-server/tests/unit/test_boards.py | 72 + mcp-server/tests/unit/test_pio_wrapper.py | 61 + mcp-server/tests/unit/test_testing_profile.py | 120 ++ mcp-server/tests/unit/test_userprefs_parse.py | 115 ++ src/mesh/NodeDB.cpp | 7 + src/mesh/PhoneAPI.cpp | 20 +- src/mesh/StreamAPI.cpp | 45 +- src/mesh/StreamAPI.h | 24 + src/mesh/TransmitHistory.cpp | 21 + src/mesh/TransmitHistory.h | 7 + 77 files changed, 10701 insertions(+), 13 deletions(-) create mode 100644 .claude/commands/README.md create mode 100644 .claude/commands/diagnose.md create mode 100644 .claude/commands/repro.md create mode 100644 .claude/commands/test.md create mode 100644 .github/prompts/mcp-diagnose.prompt.md create mode 100644 .github/prompts/mcp-repro.prompt.md create mode 100644 .github/prompts/mcp-test.prompt.md create mode 100644 .mcp.json create mode 100644 AGENTS.md create mode 100644 mcp-server/.gitignore create mode 100644 mcp-server/README.md create mode 100644 mcp-server/pyproject.toml create mode 100755 mcp-server/run-tests.sh create mode 100644 mcp-server/src/meshtastic_mcp/__init__.py create mode 100644 mcp-server/src/meshtastic_mcp/__main__.py create mode 100644 mcp-server/src/meshtastic_mcp/admin.py create mode 100644 mcp-server/src/meshtastic_mcp/boards.py create mode 100644 mcp-server/src/meshtastic_mcp/cli/__init__.py create mode 100644 mcp-server/src/meshtastic_mcp/cli/_flashlog.py create mode 100644 mcp-server/src/meshtastic_mcp/cli/_fwlog.py create mode 100644 mcp-server/src/meshtastic_mcp/cli/_history.py create mode 100644 mcp-server/src/meshtastic_mcp/cli/_reproducer.py create mode 100644 mcp-server/src/meshtastic_mcp/cli/test_tui.py create mode 100644 mcp-server/src/meshtastic_mcp/config.py create mode 100644 mcp-server/src/meshtastic_mcp/connection.py create mode 100644 mcp-server/src/meshtastic_mcp/devices.py create mode 100644 mcp-server/src/meshtastic_mcp/flash.py create mode 100644 mcp-server/src/meshtastic_mcp/hw_tools.py create mode 100644 mcp-server/src/meshtastic_mcp/info.py create mode 100644 mcp-server/src/meshtastic_mcp/pio.py create mode 100644 mcp-server/src/meshtastic_mcp/registry.py create mode 100644 mcp-server/src/meshtastic_mcp/serial_session.py create mode 100644 mcp-server/src/meshtastic_mcp/server.py create mode 100644 mcp-server/src/meshtastic_mcp/userprefs.py create mode 100644 mcp-server/tests/README.md create mode 100644 mcp-server/tests/__init__.py create mode 100644 mcp-server/tests/_port_discovery.py create mode 100644 mcp-server/tests/admin/__init__.py create mode 100644 mcp-server/tests/admin/test_channel_url_roundtrip.py create mode 100644 mcp-server/tests/admin/test_config_roundtrip.py create mode 100644 mcp-server/tests/admin/test_owner_survives_reboot.py create mode 100644 mcp-server/tests/conftest.py create mode 100644 mcp-server/tests/fleet/__init__.py create mode 100644 mcp-server/tests/fleet/test_psk_seed_isolates_runs.py create mode 100644 mcp-server/tests/mesh/__init__.py create mode 100644 mcp-server/tests/mesh/_receive.py create mode 100644 mcp-server/tests/mesh/test_bidirectional.py create mode 100644 mcp-server/tests/mesh/test_broadcast_delivers.py create mode 100644 mcp-server/tests/mesh/test_direct_with_ack.py create mode 100644 mcp-server/tests/mesh/test_mesh_formation.py create mode 100644 mcp-server/tests/mesh/test_traceroute.py create mode 100644 mcp-server/tests/monitor/__init__.py create mode 100644 mcp-server/tests/monitor/test_boot_log_no_panic.py create mode 100644 mcp-server/tests/provisioning/__init__.py create mode 100644 mcp-server/tests/provisioning/test_admin_key_baked.py create mode 100644 mcp-server/tests/provisioning/test_bake_region_modem_slot.py create mode 100644 mcp-server/tests/provisioning/test_unset_region_blocks_tx.py create mode 100644 mcp-server/tests/provisioning/test_userprefs_survive_factory_reset.py create mode 100644 mcp-server/tests/telemetry/__init__.py create mode 100644 mcp-server/tests/telemetry/test_device_telemetry_broadcast.py create mode 100644 mcp-server/tests/telemetry/test_telemetry_request_reply.py create mode 100644 mcp-server/tests/test_00_bake.py create mode 100644 mcp-server/tests/tool_coverage.py create mode 100644 mcp-server/tests/unit/__init__.py create mode 100644 mcp-server/tests/unit/test_boards.py create mode 100644 mcp-server/tests/unit/test_pio_wrapper.py create mode 100644 mcp-server/tests/unit/test_testing_profile.py create mode 100644 mcp-server/tests/unit/test_userprefs_parse.py diff --git a/.claude/commands/README.md b/.claude/commands/README.md new file mode 100644 index 000000000..3767dac98 --- /dev/null +++ b/.claude/commands/README.md @@ -0,0 +1,49 @@ +# Claude Code slash commands for the mcp-server test suite + +Three AI-assisted workflows wrapping `mcp-server/run-tests.sh` and the meshtastic MCP tools. Each one has a twin in `.github/prompts/` for Copilot users. + +| Slash command | What it does | Copilot equivalent | +| --------------------- | ------------------------------------------------------------------------- | ---------------------------------------- | +| `/test [args]` | Runs the test suite (auto-detects hardware) and interprets failures | `.github/prompts/mcp-test.prompt.md` | +| `/diagnose [role]` | Read-only device health report via the meshtastic MCP tools | `.github/prompts/mcp-diagnose.prompt.md` | +| `/repro [n=5]` | Re-runs one test N times, diffs firmware logs between passes and failures | `.github/prompts/mcp-repro.prompt.md` | + +## Why two surfaces + +The Claude Code commands and Copilot prompts cover the same three workflows but each speaks its host's idiom: + +- **Claude Code** (`/test`) uses `$ARGUMENTS` for pass-through, has direct access to Bash + all MCP tools registered in the user's settings, and runs in the terminal context. +- **Copilot** (`/mcp-test`) runs in VS Code's agent mode; it has terminal + MCP access too but typically asks the operator to confirm inputs interactively. + +A contributor using either IDE gets equivalent assistance. Keep the two in sync when behavior changes — the diff of intent should be minimal. + +## House rules + +- **No destructive writes without explicit operator approval.** Skills that could reflash, factory-reset, or reboot a device must describe the action and stop — the operator authorizes. +- **Interpret failures, don't just echo them.** The skill body should pull firmware log lines from `mcp-server/tests/report.html` (the `Meshtastic debug` section, attached by `tests/conftest.py::pytest_runtest_makereport`) and classify the failure. +- **Keep MCP tool calls sequential per port.** SerialInterface holds an exclusive port lock; two parallel tool calls on the same port deadlock. +- **Never speculate about root cause.** If the evidence doesn't support a classification, say "unknown" and list what you'd need to disambiguate. + +## Adding a new command + +1. Write the Claude Code version at `.claude/commands/.md` with YAML frontmatter: + + ```yaml + --- + description: one-line purpose (used for auto-invocation by the model) + argument-hint: [optional-hint] + --- + ``` + +2. Write the Copilot equivalent at `.github/prompts/mcp-.prompt.md` with: + + ```yaml + --- + mode: agent + description: ... + --- + ``` + +3. Add the row to the table above. Cross-link in both bodies. + +4. Smoke-test on Claude Code first (`/` should appear in autocomplete), then in VS Code Copilot (`/mcp-` in Chat). diff --git a/.claude/commands/diagnose.md b/.claude/commands/diagnose.md new file mode 100644 index 000000000..45aa937a5 --- /dev/null +++ b/.claude/commands/diagnose.md @@ -0,0 +1,55 @@ +--- +description: Produce a device health report using the meshtastic MCP tools (device_info, list_nodes, get_config, short serial log capture) +argument-hint: [role=all|nrf52|esp32s3|] +--- + +# `/diagnose` — device health report + +Call the meshtastic MCP tool bundle and format a structured health report for one or all detected devices. Zero guesswork for the operator. + +## What to do + +1. **Enumerate hardware.** Call `mcp__meshtastic__list_devices(include_unknown=True)`. For each entry where `likely_meshtastic=True`, capture `port`, `vid`, `pid`, `description`. + +2. **Filter by `$ARGUMENTS`**: + - No args, `all` → every likely-meshtastic device. + - `nrf52` → only devices with `vid == 0x239a`. + - `esp32s3` → only devices with `vid == 0x303a` or `vid == 0x10c4`. + - A `/dev/cu.*` path → only that one port. + - Anything else → treat as a substring match against the `port` string. + +3. **For each selected device, in sequence (NOT parallel — SerialInterface holds an exclusive port lock):** + - `mcp__meshtastic__device_info(port=

)` — captures `my_node_num`, `long_name`, `short_name`, `firmware_version`, `hw_model`, `region`, `num_nodes`, `primary_channel`. + - `mcp__meshtastic__list_nodes(port=

)` — count of peers, which ones have `publicKey` set, SNR/RSSI distribution. + - `mcp__meshtastic__get_config(section="lora", port=

)` — region, preset, channel_num, tx_power, hop_limit. + - Optionally, if the device seems unhappy (fails to connect, `num_nodes==1` when ≥2 are plugged in, missing firmware*version), open a short firmware log window: `mcp__meshtastic__serial_open(port=

, env=)`, wait 3s, `serial_read(session_id=, max_lines=100)`, `serial_close(session_id=)`. The env should be inferred from the VID map in `mcp-server/run-tests.sh` (nrf52 → rak4631, esp32s3 → heltec-v3) unless `MESHTASTIC_MCP_ENV*` is set. + +4. **Render per-device report** as: + + ```text + [nrf52 @ /dev/cu.usbmodem1101] fw=2.7.23.bce2825, hw=RAK4631 + owner : Meshtastic 40eb / 40eb + region/band : US, channel 88, LONG_FAST + tx_power : 30 dBm, hop_limit=3 + peers : 1 (esp32s3 0x433c2428, pubkey ✓, SNR 6.0 / RSSI -24 dBm) + primary ch : McpTest + firmware : no panics in last 3s; NodeInfoModule emitted 2 broadcasts + ``` + + Keep it scannable. If a field is missing or abnormal (no pubkey for a known peer, region=UNSET, num_nodes inconsistent with the hub), flag it inline with a short `⚠︎ `. + +5. **Cross-device correlation** (only when >1 device is inspected): + - Do both sides see each other in `nodesByNum`? If one does and the other doesn't, that's asymmetric NodeInfo — flag it. + - Do the LoRa configs match? (region, channel_num, modem_preset should all agree; mismatch = no mesh) + - Do the primary channel NAMES match? Mismatch = different PSK = no decode. + +6. **Suggest next actions only for specific, recognisable failure modes**: + - Stale PKI pubkey one-way → "run `/test tests/mesh/test_direct_with_ack.py` — the retry + nodeinfo-ping heals this in the test path." + - Region mismatch → "re-bake one side via `./mcp-server/run-tests.sh --force-bake`." + - Device unreachable → point at touch_1200bps + the CP2102-wedged-driver note in run-tests.sh. + +## What NOT to do + +- No writes. No `set_config`, no `reboot`, no `factory_reset`. This is a read-only diagnostic skill — if the operator wants to change state, they'll ask explicitly. +- No `flash` / `erase_and_flash`. Those are separate escalations. +- No holding SerialInterface across tool calls — open, query, close; next device. The port lock is exclusive. diff --git a/.claude/commands/repro.md b/.claude/commands/repro.md new file mode 100644 index 000000000..52dcf222b --- /dev/null +++ b/.claude/commands/repro.md @@ -0,0 +1,65 @@ +--- +description: Re-run a specific test N times in isolation to triage flakes, diff firmware logs between passes and failures +argument-hint: [count=5] +--- + +# `/repro` — flakiness triage for one test + +Re-run a single pytest node ID N times in isolation, track pass rate, and surface what's _different_ in the firmware logs between the passing attempts and the failing ones. Turns "it's flaky, I guess" into "it fails when X, passes when Y." + +## What to do + +1. **Parse `$ARGUMENTS`**: first token is the pytest node id (e.g. `tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip[nrf52->esp32s3]`); second token is an integer count (default `5`, cap at `20`). If the first token doesn't look like a test path (no `::` and no `tests/` prefix), treat the whole `$ARGUMENTS` as a `-k` filter instead. + +2. **Sanity-check the hub first** (so we're not measuring "nothing plugged in" N times): call `mcp__meshtastic__list_devices`. If the test name contains `nrf52` or `esp32s3` and the matching VID isn't present, stop and report — re-running won't help. + +3. **Loop N times**. For each iteration: + + ```bash + ./mcp-server/run-tests.sh --tb=short -p no:cacheprovider + ``` + + Capture: exit code, duration, and (on failure) the `Meshtastic debug` firmware log section from `mcp-server/tests/report.html`. `-p no:cacheprovider` suppresses pytest's `.pytest_cache` writes so iterations don't influence each other. + +4. **Track a small structured tally**: + + ```text + attempt 1: PASS (42s) + attempt 2: FAIL (128s) ← firmware log 200-line tail captured + attempt 3: PASS (39s) + attempt 4: FAIL (121s) + attempt 5: PASS (41s) + -------------------------------------- + pass rate: 3/5 (60%) | mean duration: 74s + ``` + +5. **On mixed outcomes**: diff the firmware log tails between a representative passing attempt and a representative failing attempt. Focus on: + - Error-level lines only present in failures (`PKI_UNKNOWN_PUBKEY`, `Alloc an err=`, `Skip send`, `No suitable channel`) + - Timing around the assertion event — did a broadcast go out, was there an ACK, did NAK fire? + - Device state fields that changed (nodesByNum entries, region/preset, channel_num) + + Surface the top 3 differences as a "passes when / fails when" table. Don't dump full logs — pull specific lines with uptime timestamps. + +6. **Classify the flake** into one of: + - **LoRa airtime collision** → pass rate improves with fewer concurrent transmitters; propose a `time.sleep` gap or retry bump in the test body. + - **PKI key staleness** → fails on first attempt, passes after self-heal; existing retry loop in `test_direct_with_ack.py` handles this. + - **NodeInfo cooldown** → `Skip send NodeInfo since we sent it <600s ago` in fail-only logs; needs `broadcast_nodeinfo_ping()` warmup. + - **Hardware-specific** (one direction fails, other passes; one device's firmware is older; driver wedged) → specific recovery pointer. + - **Genuinely unknown** → say so; don't invent a root cause. + +7. **Report back** with: + - Pass rate and mean duration. + - Classification + evidence (the specific log lines that support it). + - A suggested next step (re-run with specific args, open `/diagnose`, edit a specific test file, nothing). + +## Examples + +- `/repro tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip[esp32s3->nrf52] 10` — runs 10 times, diffs firmware logs. +- `/repro broadcast_delivers` — no `::`, no `tests/`, so interpreted as `-k broadcast_delivers`; runs every matching test the default 5 times. +- `/repro tests/telemetry/test_device_telemetry_broadcast.py 3` — shorter run for a slow test. + +## Constraints + +- Don't exceed `count=20` per invocation — airtime and USB wear add up. If the user asks for 50, negotiate down. +- Don't rebuild firmware as part of triage; flakes that only reproduce under different firmware belong in a separate session. +- If the FIRST attempt fails AND the rest all pass, that's a classic "state leak from a prior test" → say so and suggest running with `--force-bake` or starting from a clean state rather than chasing the first failure. diff --git a/.claude/commands/test.md b/.claude/commands/test.md new file mode 100644 index 000000000..986ee1f31 --- /dev/null +++ b/.claude/commands/test.md @@ -0,0 +1,42 @@ +--- +description: Run the mcp-server test suite (auto-detects devices) and interpret the results +argument-hint: [pytest-args] +--- + +# `/test` — mcp-server test runner with interpretation + +Run `mcp-server/run-tests.sh` and make sense of the output so the operator doesn't have to. + +## What to do + +1. **Invoke the wrapper.** From the firmware repo root, run: + + ```bash + ./mcp-server/run-tests.sh $ARGUMENTS + ``` + + The wrapper auto-detects connected Meshtastic devices, maps each to its PlatformIO env, exports the required `MESHTASTIC_MCP_ENV_*` env vars, and invokes pytest. If the user passed no arguments, the wrapper supplies a sensible default set (`tests/ --html=tests/report.html --self-contained-html --junitxml=tests/junit.xml -v --tb=short`). A `--report-log=tests/reportlog.jsonl` arg is always appended (unless the operator passed their own). `--assume-baked` is deliberately NOT in the defaults — `test_00_bake.py` has its own skip-if-already-baked check and runs the ~8 s verification by default. Operators can opt into the fast path with `--assume-baked`, or force a reflash with `--force-bake`. + +2. **Read the pre-flight header.** First ~6 lines print the detected hub (role → port → env). If that line reads `detected hub : (none)`, the wrapper will narrow to `tests/unit` only — say so explicitly in your summary so the operator knows hardware tiers were skipped. + +3. **On pass**: one-line summary of the form `N passed, M skipped in `. Don't enumerate the 52 test names — the user can read those. Do mention if any test was SKIPPED for a NON-placeholder reason (e.g. "role not present on hub" is worth flagging). + +4. **On failure**: for every FAILED test, open `mcp-server/tests/report.html` and extract the `Meshtastic debug` section for that test. pytest-html embeds the firmware log stream + device state dump there; the 200-line firmware log tail is usually enough to explain the failure. Summarise: which test, one-line assertion message, the firmware log lines that matter (things like `PKI_UNKNOWN_PUBKEY`, `Skip send NodeInfo`, `Error=`, `Guru Meditation`, `assertion failed`). + +5. **Classify the failure** as one of: + - **Transient/flake**: LoRa collision, timing-sensitive assertion, first-attempt NAK + successful retry pattern. Propose `/repro ` to confirm. + - **Environmental**: device unreachable, port busy, CP2102 driver wedged. Suggest the specific recovery (replug USB, `touch_1200bps`, check `git status userPrefs.jsonc`). + - **Regression**: same assertion fails repeatedly, firmware log shows a new/unusual error. Surface the diff between expected and observed, identify the module likely responsible. + +6. **Never run destructive recovery automatically.** If a failure looks like it needs a reflash, factory*reset, or USB replug, \_describe what to do* — don't execute. The operator decides. + +## Arguments handling + +- No args → wrapper's defaults (full suite). +- `$ARGUMENTS` passed verbatim to the wrapper, which passes them to pytest. +- Common operator invocations: `/test tests/mesh`, `/test tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip`, `/test --force-bake`, `/test -k telemetry`. + +## Side-effects to mention in summary + +- The session fixture snapshots `userPrefs.jsonc` at session start and restores at teardown (plus on `atexit`). After a clean run, `git status userPrefs.jsonc` should be empty. If the wrapper's pre-flight printed a warning about a stale sidecar, call that out — means a prior session crashed. +- `mcp-server/tests/report.html` and `junit.xml` are regenerated on every run; the HTML is self-contained (shareable). diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 24e11bd4d..d12244229 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -429,6 +429,8 @@ Most workflows can be triggered manually via `workflow_dispatch` for testing. ## Testing +### Native unit tests (C++) + Unit tests in `test/` directory with 12 test suites: - `test_crypto/` - Cryptography @@ -446,6 +448,164 @@ Run with: `pio test -e native` Simulation testing: `bin/test-simulator.sh` +### Hardware-in-the-loop tests (`mcp-server/tests/`) + +Separate pytest suite that exercises real USB-connected Meshtastic devices. See the **MCP Server & Hardware Test Harness** section below for invocation, tier layout, and agent usage rules. + +## MCP Server & Hardware Test Harness + +The `mcp-server/` directory houses a firmware-aware [MCP](https://modelcontextprotocol.io/) server plus a pytest-based integration suite. AI agents that speak MCP get a well-defined tool surface for flashing, configuring, and inspecting physical Meshtastic devices — use it instead of hand-rolling `pio` or `meshtastic --port` calls where possible. `mcp-server/README.md` is the operator-facing setup doc; this section is the agent-facing usage contract. + +The repo registers the server via `.mcp.json` at the repo root — Claude Code picks it up automatically once `mcp-server/.venv/` is built (`cd mcp-server && python3 -m venv .venv && .venv/bin/pip install -e '.[test]'`). + +### When to use which surface + +| Goal | Tool | +| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| Find a connected device | `mcp__meshtastic__list_devices` | +| Read a live node's config/state | `mcp__meshtastic__device_info`, `list_nodes`, `get_config` | +| Mutate a device (owner, region, channels, reboot) | `set_owner`, `set_config`, `set_channel_url`, `reboot`, `shutdown`, `factory_reset` — all require `confirm=True` | +| Flash firmware to a variant | `pio_flash` (any arch) or `erase_and_flash` (ESP32 factory install) | +| Stream serial logs while debugging | `serial_open` → `serial_read` loop → `serial_close` | +| Administer `userPrefs.jsonc` build-time constants | `userprefs_get`, `userprefs_set`, `userprefs_reset`, `userprefs_manifest` | +| Run the regression suite | `./mcp-server/run-tests.sh` (or `/test` slash command) | +| Diagnose a specific device | `/diagnose [role]` slash command (read-only) | +| Triage a flaky test | `/repro [count]` slash command | + +**One MCP call per port at a time.** `SerialInterface` holds an exclusive OS-level lock on the serial port for its lifetime. If a `serial_*` session is open on `/dev/cu.usbmodem101`, calling `device_info` on the same port will fail fast pointing at the active session. Sequence calls: open → read/mutate → close, then next device. Never parallelize tool calls on the same port. + +### MCP tool surface (~32 tools) + +Grouped by purpose. Full argument shapes in `mcp-server/README.md`; a few high-value signatures are called out here. + +- **Discovery & metadata**: `list_devices`, `list_boards`, `get_board` +- **Build & flash**: `build`, `clean`, `pio_flash`, `erase_and_flash` (ESP32 only), `update_flash` (ESP32 OTA), `touch_1200bps` +- **Serial sessions** (long-running, 10k-line ring buffer): `serial_open`, `serial_read`, `serial_list`, `serial_close` +- **Device reads**: `device_info`, `list_nodes` +- **Device writes** (all require `confirm=True`): `set_owner`, `get_config`, `set_config`, `get_channel_url`, `set_channel_url`, `send_text`, `reboot`, `shutdown`, `factory_reset`, `set_debug_log_api` +- **userPrefs admin** (build-time constants, not runtime config): `userprefs_get`, `userprefs_set`, `userprefs_reset`, `userprefs_manifest`, `userprefs_testing_profile` +- **Vendor escape hatches**: `esptool_chip_info`, `esptool_erase_flash`, `esptool_raw`, `nrfutil_dfu`, `nrfutil_raw`, `picotool_info`, `picotool_load`, `picotool_raw` + +`confirm=True` is a tool-level gate on top of whatever permission prompt your MCP host shows. **Don't bypass it** by asking the host to auto-approve — it exists specifically because MCP hosts sometimes remember "always allow this tool" and that's dangerous for `factory_reset` and `erase_and_flash`. + +### Hardware test suite (`mcp-server/run-tests.sh`) + +The wrapper auto-detects connected devices (VID → role map: `0x239A` → `nrf52`, `0x303A`/`0x10C4` → `esp32s3`), maps each role to a PlatformIO env (`nrf52` → `rak4631`, `esp32s3` → `heltec-v3`, overridable via `MESHTASTIC_MCP_ENV_`), then invokes pytest. Zero pre-flight config needed from the operator. + +Suite tiers (collected + run in this order via `pytest_collection_modifyitems`): + +1. `tests/unit/` — pure Python (boards parse, pio wrapper, userPrefs parse, testing profile). No hardware. +2. `tests/test_00_bake.py` — flashes each detected device with current `userPrefs.jsonc` merged with the session's test profile. Has its own skip-if-already-baked check comparing region + primary channel to the session profile; skips cheaply on warm devices. +3. `tests/mesh/` — multi-device mesh: bidirectional send, broadcast delivery, direct-with-ACK, mesh formation within 60s. Parametrized `[nrf52->esp32s3]` and `[esp32s3->nrf52]`. +4. `tests/telemetry/` — `DEVICE_METRICS_APP` broadcast timing. +5. `tests/monitor/` — boot-log panic check. +6. `tests/fleet/` — PSK seed session isolation. +7. `tests/admin/` — channel URL roundtrip, owner persistence across reboot. +8. `tests/provisioning/` — region + modem + slot bake, admin key presence, `UNSET` region blocks TX, userPrefs survive factory reset. + +Invocation patterns: + +```bash +./mcp-server/run-tests.sh # full suite (auto-bake-if-needed) +./mcp-server/run-tests.sh --force-bake # reflash before testing +./mcp-server/run-tests.sh --assume-baked # skip bake (caller vouches for device state) +./mcp-server/run-tests.sh tests/mesh # one tier +./mcp-server/run-tests.sh tests/mesh/test_direct_with_ack.py # one file +./mcp-server/run-tests.sh -k telemetry # name filter +``` + +**No hardware detected?** The wrapper auto-narrows to `tests/unit/` only and prints `detected hub : (none)` in the pre-flight header. Agents interpreting the output should call this out explicitly — a 52-test green run without hardware is qualitatively different from a 12-unit-test green run. + +**Artifacts every run produces:** + +- `mcp-server/tests/report.html` — self-contained pytest-html. Each test gets a `Meshtastic debug` section with the tail of firmware log + device state dump. **Open this first** on failures; it's the canonical evidence source. +- `mcp-server/tests/junit.xml` — CI-parseable. +- `mcp-server/tests/reportlog.jsonl` — pytest-reportlog stream (`$report_type` keyed JSONL). Consumed by the live TUI. +- `mcp-server/tests/fwlog.jsonl` — firmware log mirror from the `meshtastic.log.line` pubsub topic. Populated by the `_firmware_log_stream` autouse session fixture. + +### Live TUI (`meshtastic-mcp-test-tui`) + +A Textual-based live view that wraps `run-tests.sh`. Tails reportlog for per-test state, streams firmware logs, polls device state at startup + post-run (gated out of the active run because `hub_devices` holds exclusive port locks). Key bindings: + +| Key | Action | +| --- | ------------------------------------------------------------------------------------------------------------ | +| `r` | re-run focused test (leaf → that node id; internal node → directory or `-k`) | +| `f` | filter tree by substring | +| `d` | failure detail modal (pulls `longrepr` + captured stdout from the reportlog) | +| `g` | export reproducer bundle (tar.gz with README, test_report.json, time-filtered fwlog, devices.json, env.json) | +| `l` | toggle firmware log pane | +| `x` | tool coverage modal | +| `c` | cross-run history sparkline | +| `q` | quit (SIGINT → SIGTERM → SIGKILL escalation, 5-s windows each) | + +Launch: + +```bash +cd mcp-server +.venv/bin/meshtastic-mcp-test-tui # full suite +.venv/bin/meshtastic-mcp-test-tui tests/mesh # args pass through to pytest +``` + +The plain CLI stays primary; the TUI is for operators who want a live dashboard. Both consume the same `run-tests.sh`. + +### Slash commands (Claude Code + Copilot) + +Three AI-assisted workflows wrap the test harness. Claude Code operators get `/test`, `/diagnose`, `/repro`; Copilot operators get `/mcp-test`, `/mcp-diagnose`, `/mcp-repro`. Bodies: + +- `.claude/commands/{test,diagnose,repro}.md` +- `.github/prompts/mcp-{test,diagnose,repro}.prompt.md` + +`.claude/commands/README.md` is the index. + +House rules for agents running these prompts: + +- **Interpret failures, don't just echo them.** Pull firmware log tails from `report.html` and classify each failure as transient / environmental / regression. Use the exact format in `.claude/commands/test.md`. +- **No destructive writes without operator approval.** Any skill that could reflash, factory-reset, or reboot a device must describe the action and stop. The operator authorizes. +- **Sequential MCP calls per port.** See above. +- **"Unknown" is a valid classification.** If evidence doesn't support a root cause, say so and list what would disambiguate. Do not invent. + +### Key fixtures (test authors + agents debugging) + +`mcp-server/tests/conftest.py` provides: + +- **`_session_userprefs`** (autouse session) — snapshots `userPrefs.jsonc` at session start, merges the session test profile via `userprefs.merge_active(test_profile)`, restores at teardown. Four layers of safety: pytest teardown + `atexit` + sidecar file (`userPrefs.jsonc.mcp-session-bak`) + startup self-heal in `run-tests.sh`. **Do not edit `userPrefs.jsonc` from inside a test.** +- **`_firmware_log_stream`** (autouse session) — subscribes to `meshtastic.log.line` pubsub on every connected `SerialInterface` and mirrors lines to `tests/fwlog.jsonl`. Drives the TUI firmware-log pane. +- **`_debug_log_buffer`** (autouse per-test) — captures last 200 firmware log lines + device state for attachment to the pytest-html `Meshtastic debug` section on failure. +- **`hub_devices`** (session) — `dict[role, SerialInterface]` with session-long exclusive port locks. Reason the TUI's device poller is gated to startup + post-run only. +- **`baked_mesh`** — parametrized mesh-pair fixture; depends on `test_00_bake`. `pytest_generate_tests` in `conftest.py` auto-generates `[nrf52->esp32s3]` and `[esp32s3->nrf52]` variants. +- **`test_profile`** — session-scoped dict: region, primary channel, admin key, PSK seed. Derived from `MESHTASTIC_MCP_SEED` (defaults to `mcp--`). + +### Firmware integration points tied to the test harness + +Two firmware changes exist specifically so the test harness works reliably. **Keep these in mind when touching related code.** + +- **`src/mesh/StreamAPI.cpp` + `StreamAPI.h`** — `emitLogRecord` uses a dedicated `fromRadioScratchLog` + `txBufLog` pair and a `concurrency::Lock streamLock`. Before this fix, `debug_log_api_enabled=true` would tear `FromRadio` protobufs on the serial transport because `emitTxBuffer` and `emitLogRecord` shared a single scratch buffer. The conftest enables the log stream session-wide; without this fix the device would corrupt its own FromRadio replies mid-session. +- **`src/mesh/PhoneAPI.cpp`** — `ToRadio` `Heartbeat(nonce=1)` triggers `nodeInfoModule->sendOurNodeInfo(NODENUM_BROADCAST, true, 0, true)` for serial clients, mirroring the pre-existing behavior for TCP/UDP clients in `PacketAPI.cpp`. The mesh tests rely on this to force a NodeInfo broadcast right after connect so the peer discovers them before the test's first assertion. + +If you're modifying `StreamAPI`, `PhoneAPI`, `NodeInfoModule`, or `userPrefs` flow, run `./mcp-server/run-tests.sh` at minimum before asking for review. + +### Recovery playbooks + +| Symptom | First check | Fix | +| ---------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `userPrefs.jsonc` dirty after test run | `git status --porcelain userPrefs.jsonc` | If non-empty, re-run `./mcp-server/run-tests.sh` once — the pre-flight self-heal restores from sidecar. If still dirty, `git checkout userPrefs.jsonc`. | +| Port busy / wedged CP2102 on macOS | `lsof /dev/cu.usbserial-0001` | Kill the holder. USB replug if the kernel still reports busy. Often a stale `pio device monitor` or zombie `meshtastic_mcp` process. | +| nRF52 appears unresponsive | `list_devices` shows VID `0x239A` but `device_info` times out | `touch_1200bps(port=...)` drops it into the DFU bootloader → `pio_flash` re-installs. | +| Multiple MCP server processes | `ps aux \| grep meshtastic_mcp` shows >1 | Kill all but the one your MCP host spawned. Zombies hold ports and break tests. | +| Mesh formation fails, one side sees peer but other doesn't | `/diagnose` (or `list_nodes` on both sides) | Asymmetric NodeInfo. `test_direct_with_ack` has a heal path; `/repro` it a few times. If persistent, both devices' clocks may be out of sync with their NodeInfo cooldown. | +| "role not present on hub" in skip reasons | `list_devices` | Expected if a device is unplugged. Reconnect before re-running the tier. | +| Tests fail only on first attempt then pass on rerun | — | State leak from a prior session. Run with `--force-bake` to reset to a known state. | + +### Never do these without asking + +- `factory_reset` — wipes node identity; regenerates PKI keypair. Mesh peers will reject old DMs until re-exchange. Legitimate only when the operator explicitly wants it. +- `erase_and_flash` — full chip erase; destroys all on-device state. +- `esptool_erase_flash` / `esptool_raw` write/erase — bypasses pio's safety chain. +- `set_config` on `lora.region` — changes regulatory domain; requires physical-location context the operator has and the agent doesn't. +- `reboot` / `shutdown` mid-test — breaks fixture invariants. +- `push -f`, `rebase -i`, `reset --hard`, or any history-rewriting git operation. +- Clicking computer-use tools on web links in Mail/Messages/PDFs — open URLs via the claude-in-chrome MCP so the extension's link-safety checks apply. + ## Resources - [Documentation](https://meshtastic.org/docs/) diff --git a/.github/prompts/mcp-diagnose.prompt.md b/.github/prompts/mcp-diagnose.prompt.md new file mode 100644 index 000000000..c86826030 --- /dev/null +++ b/.github/prompts/mcp-diagnose.prompt.md @@ -0,0 +1,57 @@ +--- +mode: agent +description: Device health report via the meshtastic MCP tools (Copilot equivalent of the Claude Code /diagnose slash command) +--- + +# `/mcp-diagnose` — device health report + +Equivalent of `.claude/commands/diagnose.md`. Use when the operator asks to "check the devices", "what's the mesh looking like", "is nrf52 alive", etc. + +This prompt assumes the meshtastic MCP server is registered with your VS Code Copilot agent. If it isn't, fall back to running `./mcp-server/run-tests.sh tests/unit` plus a short `device_info` script via the terminal. + +## What to do + +1. **Enumerate hardware** via the `list_devices` MCP tool (with `include_unknown=True`). For each entry where `likely_meshtastic=True`, capture `port`, `vid`, `pid`, `description`. + +2. **Apply the operator's filter** (if any): + - No filter → every likely-meshtastic device. + - `nrf52` → `vid == 0x239a` + - `esp32s3` → `vid == 0x303a` or `vid == 0x10c4` + - A `/dev/cu.*` path → only that port. + - Anything else → substring match on port. + +3. **For each selected device, in sequence (don't parallelize — SerialInterface holds an exclusive port lock):** + - `device_info(port=

)` → `my_node_num`, `long_name`, `short_name`, `firmware_version`, `hw_model`, `region`, `num_nodes`, `primary_channel` + - `list_nodes(port=

)` → peer count, which peers have `publicKey`, SNR/RSSI distribution + - `get_config(section="lora", port=

)` → region, preset, channel_num, tx_power, hop_limit + - If anything looks off (can't connect, `num_nodes` wrong, missing `firmware_version`), open a short firmware-log window: `serial_open(port=

, env=)`, wait 3 seconds, `serial_read(session_id, max_lines=100)`, `serial_close(session_id)`. Infer env from VID (0x239a → `rak4631`, 0x303a/0x10c4 → `heltec-v3`) unless an `MESHTASTIC_MCP_ENV_` env var overrides it. + +4. **Render per-device report** as a compact block: + + ```text + [nrf52 @ /dev/cu.usbmodem1101] fw=2.7.23.bce2825, hw=RAK4631 + owner : Meshtastic 40eb / 40eb + region/band : US, channel 88, LONG_FAST + tx_power : 30 dBm, hop_limit=3 + peers : 1 (esp32s3 0x433c2428, pubkey ✓, SNR 6.0 / RSSI -24 dBm) + primary ch : McpTest + firmware : no panics in last 3s + ``` + + Flag abnormalities inline with `⚠︎ ` — missing pubkey on a known peer, region UNSET, mismatched channel name, etc. + +5. **Cross-device correlation** (when >1 device selected): + - Do both see each other in `nodesByNum`? + - Do `region`, `channel_num`, `modem_preset` match across devices? + - Do the primary channel names match? (Different name → different PSK → no decode.) + +6. **Suggest next steps only for recognizable failure modes**, never speculatively: + - Stale PKI one-way → "`/mcp-test tests/mesh/test_direct_with_ack.py` — the test's retry+nodeinfo-ping heals this." + - Region mismatch → "re-bake one side via `./mcp-server/run-tests.sh --force-bake`." + - Device unreachable → refer operator to the touch_1200bps + CP2102-wedged-driver notes in `run-tests.sh`. + +## Hard constraints + +- **Read-only.** No `set_config`, no `reboot`, no `factory_reset`, no `flash`. If the operator wants mutation, they'll escalate explicitly. +- **Open/query/close per device.** Never hold multiple SerialInterfaces to the same port. The port lock is exclusive. +- **Don't infer env beyond the VID map** — if the operator has an unusual board, ask them which env to use rather than guessing. diff --git a/.github/prompts/mcp-repro.prompt.md b/.github/prompts/mcp-repro.prompt.md new file mode 100644 index 000000000..be2963c33 --- /dev/null +++ b/.github/prompts/mcp-repro.prompt.md @@ -0,0 +1,67 @@ +--- +mode: agent +description: Re-run a specific test N times to triage flakes; diff firmware logs between passes and failures (Copilot equivalent of the Claude Code /repro slash command) +--- + +# `/mcp-repro` — flakiness triage for one test + +Equivalent of `.claude/commands/repro.md`. Use when the operator says "that one test is flaky — dig in", "repro the direct_with_ack failure", "why does X sometimes fail?". + +## What to do + +1. **Parse the operator's input** into two pieces: + - **Test identifier** — either a pytest node id (has `::` or starts with `tests/`) or a `-k`-style filter (plain substring like `direct_with_ack`). + - **Count** — integer, default `5`, cap at `20`. If the operator asks for 50, negotiate down and explain (airtime + USB wear). + +2. **Sanity-check the hub** via the `list_devices` MCP tool. If the test name references `nrf52` or `esp32s3` and the matching VID isn't present, stop and report — re-running won't help. + +3. **Loop** N times. Each iteration: + + ```bash + ./mcp-server/run-tests.sh --tb=short -p no:cacheprovider + ``` + + `-p no:cacheprovider` keeps pytest from caching anything between iterations. Capture: exit code, duration, and (on failure) the `Meshtastic debug` firmware-log section from `mcp-server/tests/report.html`. + +4. **Tally** results as you go: + + ```text + attempt 1: PASS (42s) + attempt 2: FAIL (128s) ← fw log captured + attempt 3: PASS (39s) + attempt 4: FAIL (121s) + attempt 5: PASS (41s) + -------------------------------------------------- + pass rate: 3/5 (60%) | mean duration: 74s + ``` + +5. **On mixed outcomes, diff the firmware logs** between one representative pass and one representative fail. Focus on: + - Error-level lines present only in failures (`PKI_UNKNOWN_PUBKEY`, `Alloc an err=`, `Skip send`, `No suitable channel`, `NAK`) + - Timing around the assertion point (broadcast sent? ACK received? retry fired?) + - Device-state fields that changed between attempts + + Surface the top 3 differences as a compact "passes when / fails when" table with uptime timestamps. Don't dump full logs. + +6. **Classify** the flake into one of: + - **LoRa airtime collision** — pass rate improves with fewer concurrent transmitters. Suggest a `time.sleep` gap or retry bump in the test body. + - **PKI key staleness** — first attempt fails, subsequent ones pass; existing retry-loop pattern in `test_direct_with_ack.py` is the fix. + - **NodeInfo cooldown** — `Skip send NodeInfo since we sent it <600s ago` in fail-only logs; needs a `broadcast_nodeinfo_ping()` warmup. + - **Hardware-specific** — one direction consistently fails, firmware versions differ, CP2102 driver wedged, etc. + - **Unknown** — say so. Don't invent a root cause. + +7. **Report back** with: + - Pass rate + mean duration. + - Classification + the specific log evidence for it. + - A concrete next step (tighter assertion, more retries, open `/mcp-diagnose`, file a bug, nothing). + +## Examples + +- `tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip[esp32s3->nrf52] 10` — 10 runs of that parametrized case. +- `broadcast_delivers` — no `::`, no `tests/`; treat as `-k broadcast_delivers`; runs every match 5 times. +- `tests/telemetry/test_device_telemetry_broadcast.py 3` — shorter count for a slow test. + +## Notes + +- If the FIRST attempt fails and the rest pass, that's a state-leak signature — suggest starting from `--force-bake` or a clean device state rather than chasing the first-failure firmware logs. +- If ALL N fail, this isn't a flake — it's a regression. Say so, stop iterating, escalate to `/mcp-test` for full-suite context. +- Don't rebuild firmware during triage. Flakes that only reproduce under different firmware belong in a separate session with a plan. diff --git a/.github/prompts/mcp-test.prompt.md b/.github/prompts/mcp-test.prompt.md new file mode 100644 index 000000000..092ad3d85 --- /dev/null +++ b/.github/prompts/mcp-test.prompt.md @@ -0,0 +1,51 @@ +--- +mode: agent +description: Run the mcp-server test suite and interpret results (Copilot equivalent of the Claude Code /test slash command) +--- + +# `/mcp-test` — mcp-server test runner with interpretation + +Equivalent of the Claude Code `/test` slash command in `.claude/commands/test.md`. Use this when the operator asks you to "run the tests", "check the mcp test suite", "run the mesh tests", etc. + +## What to do + +1. **Invoke the wrapper** from the firmware repo root: + + ```bash + ./mcp-server/run-tests.sh [pytest-args] + ``` + + If the operator specified a subset (e.g. "just the mesh tests"), pass it through as `tests/mesh` or a pytest `-k filter`. If they said nothing, use the wrapper's defaults (full suite with pytest-html report). + + The wrapper auto-detects connected Meshtastic devices, maps each to its PlatformIO env, exports the required env vars, and invokes pytest. Zero pre-flight config needed from the operator. + +2. **Read the pre-flight header** (first few lines of wrapper output). The `detected hub :` line lists role → port → env mappings. If it reads `(none)`, the wrapper narrowed to `tests/unit` only — call that out explicitly so the operator knows hardware tiers were skipped. + +3. **On pass**: one-line summary like `N passed, M skipped in `. Don't enumerate test names. DO mention any non-placeholder SKIPs (things like "role not present on hub") because they indicate missing hardware or setup issues. + +4. **On failure**: open `mcp-server/tests/report.html` (pytest-html output, self-contained) and extract the `Meshtastic debug` section for each failed test. That section includes a firmware log stream (last 200 lines) and device state dump. For each failure, summarise: + - test name + - one-line assertion message + - the specific firmware log lines that explain why (look for `PKI_UNKNOWN_PUBKEY`, `Skip send NodeInfo`, `Error=`, `Guru Meditation`, `assertion failed`, `No suitable channel`) + +5. **Classify each failure** as one of: + - **Transient flake** — LoRa collision, first-attempt NAK with self-heal pattern, timing-sensitive assertion. Suggest `/mcp-repro ` to confirm. + - **Environmental** — device unreachable, port busy, CP2102 driver wedged on macOS. Suggest specific recovery (USB replug, `touch_1200bps`, `git status userPrefs.jsonc`). + - **Regression** — same assertion fails repeatedly on re-runs, firmware log shows novel errors. Identify the firmware module likely responsible. + +6. **Do NOT run destructive recovery automatically**. If a failure looks like it needs a reflash, factory*reset, or replug — \_describe the steps* and let the operator decide. Never burn airtime or flash cycles without approval. + +## Arguments convention + +Operators generally invoke this prompt either with no arguments (full suite) or with a specific subset. Examples: + +- `tests/mesh` — one tier +- `tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip` — one test +- `--force-bake` — reflash devices first +- `-k telemetry` — name-filter + +## Side-effects to confirm in your summary + +- `userPrefs.jsonc` should be clean after a successful run. The session fixture in `mcp-server/tests/conftest.py` (`_session_userprefs`) snapshots and restores. Check `git status --porcelain userPrefs.jsonc` and report if it's non-empty. +- `mcp-server/tests/report.html` and `junit.xml` regenerate on every run. +- The wrapper prints a warning if a `.mcp-session-bak` sidecar was left over from a crashed prior session and auto-restores from it — mention that if it happened. diff --git a/.gitignore b/.gitignore index 43cee78db..f1eb9d852 100644 --- a/.gitignore +++ b/.gitignore @@ -54,3 +54,5 @@ CMakeLists.txt # PYTHONPATH used by the Nix shell .python3 +.claude/scheduled_tasks.lock +userPrefs.jsonc.mcp-session-bak diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 000000000..c5cf2e55e --- /dev/null +++ b/.mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "meshtastic": { + "command": "./mcp-server/.venv/bin/python", + "args": ["-m", "meshtastic_mcp"], + "env": { + "MESHTASTIC_FIRMWARE_ROOT": "." + } + } + } +} diff --git a/.trunk/configs/.bandit b/.trunk/configs/.bandit index d286ded89..c70e7743b 100644 --- a/.trunk/configs/.bandit +++ b/.trunk/configs/.bandit @@ -1,2 +1,28 @@ [bandit] -skips = B101 \ No newline at end of file +# Rule IDs: https://bandit.readthedocs.io/en/latest/plugins/index.html +# +# B101 assert_used +# pytest assertions + internal invariants; required for pytest. +# B110 try_except_pass +# best-effort cleanup paths (atexit handlers, pubsub unsubscribe, +# session-end file close, socket shutdown). Logging inside the +# except block would be worse than the silent pass — teardown is +# already at end-of-session and the surrounding caller has context. +# B112 try_except_continue +# defensive loops over flaky sources (pubsub handlers, device +# re-enumeration polls). One failed iteration shouldn't abort the loop. +# B404 import_subprocess +# mcp-server wraps PlatformIO, esptool, nrfutil, picotool, and the +# pytest test-runner — subprocess is a load-bearing import here, not +# a smell. The "consider possible security implications" advisory is +# redundant given the file-level review already applied. +# B603 subprocess_without_shell_equals_true +# all subprocess calls use a static argv list; `shell=False` is the +# default and we never string-interpolate user input into the command. +# B606 start_process_with_no_shell +# same invariant as B603 — running a binary via argv list (not +# `shell=True`) is the safe pattern bandit is asking for. +# +# Higher-severity checks (B102 exec_used, B301 pickle, B307 eval, +# B602 shell=True, etc.) remain enabled. +skips = B101,B110,B112,B404,B603,B606 \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..cd043c087 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,113 @@ +# Agent instructions + +This repository is the [Meshtastic](https://meshtastic.org) firmware — a C++17 embedded codebase targeting ESP32 / nRF52 / RP2040 / STM32WL / Linux-Portduino LoRa mesh radios — plus a Python MCP server in `mcp-server/` that AI agents use to flash, configure, and test connected devices. + +## Primary instruction file + +**Read `.github/copilot-instructions.md` first.** That file is the canonical agent-facing document for this repo. It covers project layout, coding conventions (naming, module framework, Observer pattern, thread safety), the build system, CI/CD, the native C++ test suite, and — most importantly for automation work — the **MCP Server & Hardware Test Harness** section. Read it top-to-bottom before starting any non-trivial change. + +This file (`AGENTS.md`) is a short pointer + quick reference for agents that don't read `.github/copilot-instructions.md` by default. + +## Quick command reference + +| Action | Command | +| -------------------------------- | ----------------------------------------------------------------------------------- | +| Build a firmware variant | `pio run -e ` (e.g. `pio run -e rak4631`, `pio run -e heltec-v3`) | +| Clean + rebuild | `pio run -e -t clean && pio run -e ` | +| Flash a device | `pio run -e -t upload --upload-port ` (or use the `pio_flash` MCP tool) | +| Run firmware unit tests (native) | `pio test -e native` | +| Run MCP hardware tests | `./mcp-server/run-tests.sh` | +| Live TUI test runner | `mcp-server/.venv/bin/meshtastic-mcp-test-tui` | +| Format before commit | `trunk fmt` | +| Regenerate protobuf bindings | `bin/regen-protos.sh` | +| Generate CI matrix | `./bin/generate_ci_matrix.py all [--level pr]` | + +## MCP server (device + test automation) + +The `mcp-server/` package exposes ~32 MCP tools for device discovery, building, flashing, serial monitoring, and live-node administration. Tools are grouped as: + +- **Discovery**: `list_devices`, `list_boards`, `get_board` +- **Build & flash**: `build`, `clean`, `pio_flash`, `erase_and_flash` (ESP32 factory), `update_flash` (ESP32 OTA), `touch_1200bps` +- **Serial sessions**: `serial_open`, `serial_read`, `serial_list`, `serial_close` +- **Device reads**: `device_info`, `list_nodes` +- **Device writes** (require `confirm=True`): `set_owner`, `get_config`, `set_config`, `get_channel_url`, `set_channel_url`, `send_text`, `reboot`, `shutdown`, `factory_reset`, `set_debug_log_api` +- **userPrefs admin**: `userprefs_get`, `userprefs_set`, `userprefs_reset`, `userprefs_manifest`, `userprefs_testing_profile` +- **Vendor escape hatches**: `esptool_*`, `nrfutil_*`, `picotool_*` + +Setup: `cd mcp-server && python3 -m venv .venv && .venv/bin/pip install -e '.[test]'`. The repo registers the server via `.mcp.json` — Claude Code picks it up automatically. + +See `mcp-server/README.md` for argument shapes and the **MCP Server & Hardware Test Harness** section of `.github/copilot-instructions.md` for agent usage rules (tool surface, fixture contract, firmware integration points, recovery playbooks). + +## Slash commands (AI-assisted workflows) + +Three test-and-diagnose workflows exist as slash commands: + +- **`/test` (Claude Code) / `/mcp-test` (Copilot)** — run the hardware test suite and interpret failures +- **`/diagnose` / `/mcp-diagnose`** — read-only device health report +- **`/repro` / `/mcp-repro`** — flakiness triage: re-run one test N times, diff firmware logs between passes and failures + +Bodies live in `.claude/commands/` and `.github/prompts/` respectively. `.claude/commands/README.md` is the index. + +## House rules + +- **No destructive device operations without operator approval.** `factory_reset`, `erase_and_flash`, `reboot`, `shutdown`, history-rewriting git ops — describe the action and stop. Operator authorizes. +- **One MCP call per serial port at a time.** The port lock is exclusive; concurrent calls deadlock. Sequence: open → read/mutate → close, then next device. +- **`userPrefs.jsonc` is session state during tests.** The `_session_userprefs` fixture snapshots + restores it; never edit it from inside a test. +- **Don't speculate about firmware root causes.** When evidence doesn't support a classification, say "unknown" and list what would disambiguate. +- **Run `trunk fmt` before proposing a commit.** The `trunk_check` CI gate will reject unformatted code. +- **`confirm=True` on destructive MCP tools is a real gate, not a formality.** Don't bypass it via auto-approve settings. + +## Typical agent workflows + +### Flashing a device + +1. `list_devices` → find the port + likely VID +2. `list_boards` → confirm the env, or use the known default for the hardware +3. `pio_flash(env=..., port=..., confirm=True)` for any arch, or `erase_and_flash(env=..., port=..., confirm=True)` for an ESP32 factory install + +### Inspecting live node state + +1. `device_info(port=...)` — short summary (node num, firmware version, region, peer count) +2. `list_nodes(port=...)` — full peer table (SNR, RSSI, pubkey presence, last_heard) +3. `get_config(section="lora", port=...)` — LoRa settings for cross-device comparison + +Sequence these; don't parallelize on the same port. + +### Testing a firmware change + +1. Build locally: `pio run -e ` +2. Flash the test device: `pio_flash(env=..., port=..., confirm=True)` +3. Run the suite: `./mcp-server/run-tests.sh tests/` or `/test tests/` +4. On failure, open `mcp-server/tests/report.html` → `Meshtastic debug` section for the firmware log tail + device state dump +5. Iterate + +### Debugging a flaky test + +1. `/repro [count]` — re-runs the test N times, diffs firmware logs between passes and failures +2. If the first attempt always fails and the rest pass, that's a state-leak pattern → suggest `--force-bake` or a clean device state, don't chase the first failure +3. If all N fail, this isn't a flake — it's a regression. Stop iterating and escalate to `/test` for full-suite context. + +## Where to look + +| Path | What's there | +| --------------------------------- | ---------------------------------------------------------------------------------------------------- | +| `src/` | Firmware C++ source (`mesh/`, `modules/`, `platform/`, `graphics/`, `gps/`, `motion/`, `mqtt/`, …) | +| `src/mesh/` | Core: NodeDB, Router, Channels, CryptoEngine, radio interfaces, StreamAPI, PhoneAPI | +| `src/modules/` | Feature modules; `Telemetry/Sensor/` has 50+ I2C sensor drivers | +| `variants/` | 200+ hardware variant definitions (`variant.h` + `platformio.ini` per board) | +| `protobufs/` | `.proto` definitions; regenerate with `bin/regen-protos.sh` | +| `test/` | Firmware unit tests (12 suites; `pio test -e native`) | +| `mcp-server/` | Python MCP server + pytest hardware integration tests | +| `mcp-server/tests/` | Tiered pytest suite: `unit/`, `mesh/`, `telemetry/`, `monitor/`, `fleet/`, `admin/`, `provisioning/` | +| `.claude/commands/` | Claude Code slash command bodies | +| `.github/prompts/` | Copilot prompt bodies (mirrors of the Claude Code ones) | +| `.github/copilot-instructions.md` | **Primary agent instructions — read this** | +| `.github/workflows/` | CI pipelines | +| `.mcp.json` | MCP server registration for Claude Code | + +## Recovery one-liners + +- **`userPrefs.jsonc` dirty after a test run?** Re-run `./mcp-server/run-tests.sh` once (pre-flight self-heals from the sidecar). If still dirty: `git checkout userPrefs.jsonc`. +- **nRF52 not responding?** `mcp__meshtastic__touch_1200bps(port=...)` drops it into the DFU bootloader, then `pio_flash` re-installs. +- **Port busy?** `lsof ` to find the holder. Usually a stale `pio device monitor` or zombie `meshtastic_mcp` process. Kill it. +- **Multiple MCP servers running?** `ps aux | grep meshtastic_mcp` — zombies hold ports. Kill all but the one your host spawned. diff --git a/mcp-server/.gitignore b/mcp-server/.gitignore new file mode 100644 index 000000000..f5180bc71 --- /dev/null +++ b/mcp-server/.gitignore @@ -0,0 +1,26 @@ +.venv/ +__pycache__/ +*.py[cod] +*.egg-info/ +.pytest_cache/ +.mypy_cache/ +dist/ +build/ + +# Test harness artifacts +tests/report.html +tests/junit.xml +tests/reportlog.jsonl +tests/fwlog.jsonl +# Subprocess-output tee from pio/esptool/nrfutil/picotool (live flash +# progress for the TUI; also a post-run diagnostic for plain CLI runs). +tests/flash.log +tests/tool_coverage.json +tests/.coverage +htmlcov/ +# Persistent run counter for meshtastic-mcp-test-tui header. +tests/.tui-runs +# Cross-run history (TUI duration sparkline). +tests/.history/ +# Reproducer bundles (TUI `x` export on failed tests). +tests/reproducers/ diff --git a/mcp-server/README.md b/mcp-server/README.md new file mode 100644 index 000000000..7d5fc551a --- /dev/null +++ b/mcp-server/README.md @@ -0,0 +1,270 @@ +# Meshtastic MCP Server + +An [MCP](https://modelcontextprotocol.io) server for working with the Meshtastic firmware repo and connected devices. Lets Claude Code / Claude Desktop: + +- Discover USB-connected Meshtastic devices +- Enumerate PlatformIO board variants (166+) with Meshtastic metadata +- Build, clean, flash, erase-and-flash (factory), and OTA-update firmware +- Read serial logs via `pio device monitor` (with board-specific exception decoders) +- Trigger 1200bps touch-reset for bootloader entry (nRF52, ESP32-S3, RP2040) +- Query and administer a running node via the [`meshtastic` Python API](https://github.com/meshtastic/python): owner name, config (LocalConfig + ModuleConfig), channels, messaging, reboot/shutdown/factory-reset +- Call `esptool`, `nrfutil`, `picotool` directly when PlatformIO doesn't cover the operation + +## Design principle + +**PlatformIO first.** Its `pio run -t upload` knows the correct protocol, offsets, and post-build chain for every variant in `variants/`. Direct vendor-tool wrappers (`esptool_*`, `nrfutil_*`, `picotool_*`) exist as escape hatches for operations pio doesn't cover (blank-chip erase, DFU `.zip` packages, BOOTSEL-mode inspection). + +## Prerequisites + +- Python ≥ 3.11 +- [PlatformIO Core](https://platformio.org/install/cli) — `pio` on `$PATH` or at `~/.platformio/penv/bin/pio` +- The Meshtastic firmware repo checked out somewhere (set via `MESHTASTIC_FIRMWARE_ROOT`) +- Optional: `esptool`, `nrfutil`, `picotool` on `$PATH` (or under the firmware venv at `.venv/bin/`) if you want to use the direct-tool wrappers + +## Install + +```bash +cd /mcp-server +python3 -m venv .venv +.venv/bin/pip install -e . +``` + +Verify: + +```bash +MESHTASTIC_FIRMWARE_ROOT= .venv/bin/python -m meshtastic_mcp +``` + +The server blocks on stdin (that's correct — it speaks MCP over stdio). Ctrl-C to exit. + +## Register with Claude Code + +Edit `~/.claude/settings.json` (global) or `/.claude/settings.local.json` (project-only): + +```json +{ + "mcpServers": { + "meshtastic": { + "command": "/mcp-server/.venv/bin/python", + "args": ["-m", "meshtastic_mcp"], + "env": { + "MESHTASTIC_FIRMWARE_ROOT": "" + } + } + } +} +``` + +Replace `` with the absolute path, e.g. `/Users/you/GitHub/firmware`. Restart Claude Code after editing. + +## Register with Claude Desktop + +Same `mcpServers` block, but in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). + +## Tools (38) + +### Discovery & metadata + +| Tool | What it does | +| -------------- | ------------------------------------------------------------------------------------------ | +| `list_devices` | USB/serial port listing, flags likely-Meshtastic candidates | +| `list_boards` | PlatformIO envs with `custom_meshtastic_*` metadata; filters by arch/supported/query/level | +| `get_board` | Full env dict incl. raw pio config | + +### Build & flash + +| Tool | What it does | +| ----------------- | -------------------------------------------------------------------- | +| `build` | `pio run -e ` (+ mtjson target) | +| `clean` | `pio run -e -t clean` | +| `pio_flash` | `pio run -e -t upload --upload-port ` — any architecture | +| `erase_and_flash` | ESP32 full factory flash via `bin/device-install.sh` | +| `update_flash` | ESP32 OTA app-partition update via `bin/device-update.sh` | +| `touch_1200bps` | 1200-baud open/close to trigger USB CDC bootloader entry | + +### Serial log sessions + +Backed by long-running `pio device monitor` subprocesses with a 10k-line ring buffer per session and board-specific filters (`esp32_exception_decoder` auto-selected when you pass `env=`). + +| Tool | What it does | +| -------------- | ------------------------------------------------------------------ | +| `serial_open` | Start a monitor session; returns `session_id` | +| `serial_read` | Cursor-based pull; reports `dropped` if lines aged out of the ring | +| `serial_list` | All active sessions | +| `serial_close` | Terminate a session | + +### Device reads + +| Tool | What it does | +| ------------- | --------------------------------------------------------------------------- | +| `device_info` | my_node_num, long/short name, firmware version, region, channel, node count | +| `list_nodes` | Full node database with position, SNR, RSSI, last_heard, battery | + +_The tool tables below document 38 currently registered MCP server tools._ + +### Device writes + +| Tool | What it does | +| ------------------- | -------------------------------------------------------------------------- | +| `set_owner` | Long name + optional short name (≤4 chars) | +| `get_config` | One section or all (LocalConfig + ModuleConfig) | +| `set_config` | Dot-path field write: `lora.region`=`"US"`, `device.role`=`"ROUTER"`, etc. | +| `get_channel_url` | Primary-only or include_all=admin URL | +| `set_channel_url` | Import channels from a Meshtastic URL | +| `set_debug_log_api` | Enable or disable debug logging for the Meshtastic Python API client | +| `send_text` | Broadcast or direct text message | +| `reboot` | `localNode.reboot(secs)` — requires `confirm=True` | +| `shutdown` | `localNode.shutdown(secs)` — requires `confirm=True` | +| `factory_reset` | `localNode.factoryReset(full?)` — requires `confirm=True` | + +### Direct hardware tools (escape hatches) + +| Tool | What it does | +| --------------------- | --------------------------------------------------------- | +| `esptool_chip_info` | Read chip, MAC, crystal, flash size | +| `esptool_erase_flash` | Full-chip erase (destructive) | +| `esptool_raw` | Pass-through; confirm=True required for write/erase/merge | +| `nrfutil_dfu` | DFU-flash a `.zip` package | +| `nrfutil_raw` | Pass-through | +| `picotool_info` | Read Pico BOOTSEL-mode info | +| `picotool_load` | Load a UF2 | +| `picotool_raw` | Pass-through | + +## Safety + +- **All destructive flash/admin tools require `confirm=True`** as a tool-level gate, on top of any permission prompt from Claude. +- **Serial port is exclusive.** If a `serial_*` session is active on a port, `device_info`/admin tools on the same port will fail fast with a pointer at the active `session_id`. Close the session first. +- **Flash confirmation by architecture**: `erase_and_flash` / `update_flash` error if the env's architecture isn't ESP32 — use `pio_flash` for nRF52/RP2040/STM32. + +## Environment variables + +| Var | Default | Purpose | +| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- | +| `MESHTASTIC_FIRMWARE_ROOT` | walks up from cwd for `platformio.ini` | Pin the firmware repo | +| `MESHTASTIC_PIO_BIN` | `~/.platformio/penv/bin/pio` → `$PATH` `pio` → `platformio` | Override `pio` location | +| `MESHTASTIC_ESPTOOL_BIN` | `/.venv/bin/esptool` → `$PATH` | Override esptool | +| `MESHTASTIC_NRFUTIL_BIN` | `$PATH` | Override nrfutil | +| `MESHTASTIC_PICOTOOL_BIN` | `$PATH` | Override picotool | +| `MESHTASTIC_MCP_SEED` | `mcp--` | PSK seed for test-harness session (CI override) | +| `MESHTASTIC_MCP_FLASH_LOG` | `/tests/flash.log` | Tee target for pio/esptool/nrfutil subprocess output (TUI tails it) | + +## Hardware Test Suite + +`mcp-server/tests/` holds a pytest-based integration suite that exercises +real USB-connected Meshtastic devices against the MCP server surface. Separate +from the native C++ unit tests in the firmware repo's top-level `test/` +directory — this one validates the device-facing behavior end-to-end. + +### Invocation + +```bash +./mcp-server/run-tests.sh # full suite (auto-detect + auto-bake-if-needed) +./mcp-server/run-tests.sh --force-bake # reflash devices before testing +./mcp-server/run-tests.sh --assume-baked # skip the bake step (caller vouches for state) +./mcp-server/run-tests.sh tests/mesh # one tier +./mcp-server/run-tests.sh tests/mesh/test_traceroute.py # one file +./mcp-server/run-tests.sh -k telemetry # pytest name filter +``` + +The wrapper auto-detects connected devices (VID `0x239A` → `nrf52` → env +`rak4631`; `0x303A` or `0x10C4` → `esp32s3` → env `heltec-v3`), exports +`MESHTASTIC_MCP_ENV_` env vars, and invokes pytest. Overrides via +per-role env vars: `MESHTASTIC_MCP_ENV_NRF52=heltec-mesh-node-t114 ./run-tests.sh`. + +No hardware connected? The wrapper narrows to `tests/unit/` only and says so +in the pre-flight header. + +### Tiers (run in this order) + +- **`bake`** (`tests/test_00_bake.py`) — flashes both hub roles with the + session's test profile. Has a skip-if-already-baked check (region + channel + match); `--force-bake` overrides. +- **`unit`** — pure Python, no hardware. boards / PIO wrapper / + userPrefs-parse / testing-profile fixtures. +- **`mesh`** — 2-device mesh: formation, broadcast delivery, direct+ACK, + traceroute, bidirectional. Parametrized over both directions. +- **`telemetry`** — periodic telemetry broadcast + on-demand request/reply + (`TELEMETRY_APP` with `wantResponse=True`). +- **`monitor`** — boot log has no panic markers within 60 s of reboot. +- **`fleet`** — PSK-seed isolation: two labs with different seeds never + overlap. +- **`admin`** — owner persistence across reboot, channel URL round-trip, + `lora.hop_limit` persistence. +- **`provisioning`** — region/channel baking, userPrefs survive + `factory_reset(full=False)`. + +### Artifacts (regenerated every run, under `tests/`) + +- `report.html` — self-contained pytest-html report. Each test gets a + **Meshtastic debug** section attached on failure with a 200-line firmware + log tail + device-state dump. Open this first on failures. +- `junit.xml` — CI-parseable. +- `reportlog.jsonl` — `pytest-reportlog` event stream; consumed by the TUI. +- `fwlog.jsonl` — firmware log mirror (`meshtastic.log.line` pubsub → JSONL). +- `flash.log` — tee of all pio / esptool / nrfutil / picotool subprocess + output during the run (driven by `MESHTASTIC_MCP_FLASH_LOG`). + +### Live TUI + +```bash +.venv/bin/meshtastic-mcp-test-tui +.venv/bin/meshtastic-mcp-test-tui tests/mesh # pytest args pass through +``` + +Textual-based wrapper over `run-tests.sh` with a live test tree, tier +counters, pytest output pane, firmware-log pane, and a device-status strip. +Key bindings: `r` re-run focused, `f` filter, `d` failure detail, `g` open +`report.html`, `x` export reproducer bundle, `l` cycle fw-log filter, `q` +quit (SIGINT → SIGTERM → SIGKILL escalation). + +### Slash commands + +Three AI-assisted workflows are wired up for Claude Code operators +(`.claude/commands/`) and Copilot operators (`.github/prompts/`): +`/test` (run + interpret), `/diagnose` (read-only health report), `/repro` +(flake triage, N-times re-run with log diff). + +### House rules (for human + agent contributors) + +- Session-scoped fixtures in `tests/conftest.py` snapshot + restore + `userPrefs.jsonc`; **never edit `userPrefs.jsonc` from inside a test**. + Use the `test_profile` / `no_region_profile` fixtures for ephemeral + overrides. +- `SerialInterface` holds an **exclusive port lock**; sequence calls + open → mutate → close, then next device. No parallel calls to the + same port. +- Directed PKI-encrypted sends need **bilateral NodeInfo warmup** — + both sides must hold the other's current pubkey. See + `tests/mesh/_receive.py::nudge_nodeinfo_port` and the three directed- + send tests (`test_direct_with_ack`, `test_traceroute`, + `test_telemetry_request_reply`) for the canonical pattern. + +## Layout + +```text +mcp-server/ +├── pyproject.toml +├── README.md +└── src/meshtastic_mcp/ + ├── __main__.py # entry: python -m meshtastic_mcp + ├── server.py # FastMCP app + @app.tool() registrations (thin) + ├── config.py # firmware_root, pio_bin, esptool_bin, etc. + ├── pio.py # subprocess wrapper (timeouts, JSON, tail_lines) + ├── devices.py # list_devices (findPorts + comports) + ├── boards.py # list_boards / get_board (pio project config parse + cache) + ├── flash.py # build, clean, flash, erase_and_flash, update_flash, touch_1200bps + ├── serial_session.py # SerialSession + reader thread + ring buffer + ├── registry.py # session registry + per-port locks + ├── connection.py # connect(port) ctx mgr — SerialInterface + port lock + ├── info.py # device_info, list_nodes + ├── admin.py # set_owner, get/set_config, channels, send_text, reboot/shutdown/factory_reset + └── hw_tools.py # esptool / nrfutil / picotool wrappers +``` + +## Troubleshooting + +- **"Could not locate Meshtastic firmware root"** — set `MESHTASTIC_FIRMWARE_ROOT`. +- **"Could not find `pio`"** — install PlatformIO or set `MESHTASTIC_PIO_BIN`. +- **"Port is held by serial session ..."** — call `serial_close(session_id)` or `serial_list` to find it. +- **`factory.bin` not found after build** — the env may not be ESP32; only ESP32 envs produce a `.factory.bin`. +- **`touch_1200bps` reported `new_port: null`** — the device may not have 1200bps-reset stdio, or the bootloader re-uses the same port name. Check `list_devices` manually. diff --git a/mcp-server/pyproject.toml b/mcp-server/pyproject.toml new file mode 100644 index 000000000..d73bf795f --- /dev/null +++ b/mcp-server/pyproject.toml @@ -0,0 +1,39 @@ +[project] +name = "meshtastic-mcp" +version = "0.1.0" +description = "MCP server for Meshtastic firmware development: device discovery, PlatformIO tooling, flashing, serial monitoring, and device administration via the meshtastic Python API." +readme = "README.md" +requires-python = ">=3.11" +license = { text = "GPL-3.0-only" } +authors = [{ name = "thebentern" }] +dependencies = ["mcp>=1.2", "pyserial>=3.5", "meshtastic>=2.7.8"] + +[project.optional-dependencies] +dev = ["pytest>=7"] +test = [ + "pytest>=8", + "pytest-html>=4", + "pytest-reportlog>=0.4", + "pytest-timeout>=2.3", + "coverage[toml]>=7", + "pyyaml>=6", + # textual is required by the `meshtastic-mcp-test-tui` script (see + # `src/meshtastic_mcp/cli/test_tui.py`). Bundled into `test` rather than a + # separate `[tui]` extra because v1 expects test operators are the only + # consumers; revisit if install cost pushes back. + "textual>=0.50", +] + +[project.scripts] +meshtastic-mcp = "meshtastic_mcp.__main__:main" +# Live TUI wrapping run-tests.sh — shells out to the same script the plain +# CLI uses, tails pytest-reportlog for per-test state, and polls the device +# list at startup + post-run (port lock forces it to stay idle during the run). +meshtastic-mcp-test-tui = "meshtastic_mcp.cli.test_tui:main" + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[tool.hatch.build.targets.wheel] +packages = ["src/meshtastic_mcp"] diff --git a/mcp-server/run-tests.sh b/mcp-server/run-tests.sh new file mode 100755 index 000000000..292e6e3a2 --- /dev/null +++ b/mcp-server/run-tests.sh @@ -0,0 +1,236 @@ +#!/usr/bin/env bash +# mcp-server hardware test runner. +# +# Auto-detects connected Meshtastic devices, maps each to its PlatformIO env +# via the same role table the pytest fixtures use, exports the right +# MESHTASTIC_MCP_ENV_* env vars, and invokes pytest. +# +# Usage: +# ./run-tests.sh # full suite, default pytest args +# ./run-tests.sh tests/mesh # subset (any pytest args pass through) +# ./run-tests.sh --force-bake # override one default with another +# MESHTASTIC_MCP_ENV_NRF52=foo ./run-tests.sh # override env per role +# MESHTASTIC_MCP_SEED=ci-run-42 ./run-tests.sh # override PSK seed +# +# If zero supported devices are detected, only the unit tier runs. +# +# Also restores `userPrefs.jsonc` from the session-backup sidecar if a prior +# run exited abnormally (belt to conftest.py's atexit suspenders). + +set -euo pipefail + +# cd to the script's directory so relative paths resolve consistently no +# matter where the user invoked from. +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +cd "$SCRIPT_DIR" + +VENV_PY="$SCRIPT_DIR/.venv/bin/python" +if [[ ! -x $VENV_PY ]]; then + echo "error: $VENV_PY not found or not executable." >&2 + echo " Bootstrap the venv first:" >&2 + echo " cd $SCRIPT_DIR && python3 -m venv .venv && .venv/bin/pip install -e '.[test]'" >&2 + exit 2 +fi + +# Resolve firmware root the same way conftest.py does (this script sits in +# mcp-server/, firmware repo root is one level up). +FIRMWARE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +USERPREFS_PATH="$FIRMWARE_ROOT/userPrefs.jsonc" +USERPREFS_SIDECAR="$USERPREFS_PATH.mcp-session-bak" + +# ---------- Pre-flight: recover stale userPrefs.jsonc from prior crash ---- +# If conftest.py's atexit hook didn't fire (SIGKILL, kernel panic, OS +# restart), the sidecar is the ground truth. Self-heal before running so we +# don't bake the previous run's dirty state into this run's firmware. +if [[ -f $USERPREFS_SIDECAR ]]; then + echo "[pre-flight] found $USERPREFS_SIDECAR from a prior abnormal exit;" >&2 + echo " restoring userPrefs.jsonc before starting." >&2 + cp "$USERPREFS_SIDECAR" "$USERPREFS_PATH" + rm -f "$USERPREFS_SIDECAR" +fi + +# If userPrefs.jsonc has uncommitted changes BEFORE the run starts, that's +# worth warning about — tests will snapshot this dirty state and restore to +# it at the end, which may not be what the operator wants. +if command -v git >/dev/null 2>&1; then + cd "$FIRMWARE_ROOT" + # Capture the git status into a local first — SC2312 flags command + # substitution inside `[[ -n ... ]]` because the exit code of `git + # status` is masked. A two-step assignment makes the failure path + # explicit (non-git, missing file) and keeps the bracket test clean. + _git_status_porcelain="$(git status --porcelain userPrefs.jsonc 2>/dev/null || true)" + if [[ -n $_git_status_porcelain ]]; then + echo "[pre-flight] warning: userPrefs.jsonc has uncommitted changes." >&2 + echo " Tests will snapshot THIS state and restore to it" >&2 + echo " at teardown. If that's not intended, run:" >&2 + echo " git checkout userPrefs.jsonc" >&2 + echo " and re-invoke." >&2 + fi + cd "$SCRIPT_DIR" +fi + +# ---------- Seed default -------------------------------------------------- +# Per-machine default so repeated runs from the same operator land on the +# same PSK (makes --assume-baked valid across invocations). Operator can +# override with an explicit env var if they want isolation (e.g. CI). +if [[ -z ${MESHTASTIC_MCP_SEED-} ]]; then + WHO="$(whoami 2>/dev/null || echo anon)" + HOST="$(hostname -s 2>/dev/null || echo host)" + export MESHTASTIC_MCP_SEED="mcp-${WHO}-${HOST}" +fi + +# ---------- Flash progress log -------------------------------------------- +# pio.py / hw_tools.py tee subprocess output (pio run -t upload, esptool, +# nrfutil, picotool) to this file line-by-line as it arrives when this env +# var is set. The TUI tails it so the operator sees live flash progress +# instead of 3 minutes of silence during `test_00_bake.py`. Plain CLI users +# also benefit — the log is a post-run diagnostic even without the TUI. +# Truncate at session start so each run gets a clean log. +export MESHTASTIC_MCP_FLASH_LOG="$SCRIPT_DIR/tests/flash.log" +: >"$MESHTASTIC_MCP_FLASH_LOG" + +# ---------- Detect connected hardware ------------------------------------- +# In-process call to the same Python API the test fixtures use, so the +# script never drifts from what pytest sees. Returns a JSON object +# {role: port, ...}. +ROLES_JSON="$( + "$VENV_PY" - <<'PY' +import json +import sys + +sys.path.insert(0, "src") +from meshtastic_mcp import devices + +# Role → canonical VID map. Kept in sync with +# `tests/conftest.py::hub_profile` defaults; if that changes, this must too. +ROLE_BY_VID = { + 0x239A: "nrf52", # Adafruit / RAK nRF52 native USB (app + DFU) + 0x303A: "esp32s3", # Espressif native USB (ESP32-S3) + 0x10C4: "esp32s3", # CP2102 USB-UART (common on Heltec/LilyGO ESP32 boards) +} + +out: dict[str, str] = {} +for dev in devices.list_devices(include_unknown=True): + vid_raw = dev.get("vid") or "" + try: + if isinstance(vid_raw, str) and vid_raw.startswith("0x"): + vid = int(vid_raw, 16) + else: + vid = int(vid_raw) + except (TypeError, ValueError): + continue + role = ROLE_BY_VID.get(vid) + # First port wins per role — matches hub_devices fixture semantics. + if role and role not in out: + out[role] = dev["port"] + +json.dump(out, sys.stdout) +PY +)" + +# ---------- Map role → pio env -------------------------------------------- +# Honor MESHTASTIC_MCP_ENV_ operator overrides; fall back to the +# same defaults hardcoded in tests/conftest.py::_DEFAULT_ROLE_ENVS. +resolve_env() { + local role="$1" + local default="$2" + local upper + upper="$(echo "$role" | tr '[:lower:]' '[:upper:]')" + local var="MESHTASTIC_MCP_ENV_${upper}" + eval "local override=\${$var:-}" + if [[ -n $override ]]; then + echo "$override" + else + echo "$default" + fi +} + +NRF52_PORT="$(echo "$ROLES_JSON" | "$VENV_PY" -c 'import json,sys; print(json.loads(sys.stdin.read()).get("nrf52", ""))')" +ESP32S3_PORT="$(echo "$ROLES_JSON" | "$VENV_PY" -c 'import json,sys; print(json.loads(sys.stdin.read()).get("esp32s3", ""))')" + +DETECTED="" +if [[ -n $NRF52_PORT ]]; then + NRF52_ENV="$(resolve_env nrf52 rak4631)" + export MESHTASTIC_MCP_ENV_NRF52="$NRF52_ENV" + DETECTED="${DETECTED} nrf52 @ ${NRF52_PORT} -> env=${NRF52_ENV}\n" +fi +if [[ -n $ESP32S3_PORT ]]; then + ESP32S3_ENV="$(resolve_env esp32s3 heltec-v3)" + export MESHTASTIC_MCP_ENV_ESP32S3="$ESP32S3_ENV" + DETECTED="${DETECTED} esp32s3 @ ${ESP32S3_PORT} -> env=${ESP32S3_ENV}\n" +fi + +# ---------- Pre-flight summary -------------------------------------------- +# Surface what pytest is about to do with respect to the bake phase: the +# operator should see "will verify + bake if needed" by default, so a +# 3-minute flash appearing mid-run isn't a surprise. Detection of the +# explicit overrides is best-effort — we just scan $@ for the known flags. +_bake_mode="auto (verify + bake if needed)" +for _arg in "$@"; do + case "$_arg" in + --assume-baked) _bake_mode="skip (--assume-baked)" ;; + --force-bake) _bake_mode="force (--force-bake)" ;; + *) ;; # any other arg: pass-through; bake mode unchanged + esac +done + +echo "mcp-server test runner" +echo " firmware root : $FIRMWARE_ROOT" +echo " seed : $MESHTASTIC_MCP_SEED" +echo " bake : $_bake_mode" +if [[ -n $DETECTED ]]; then + echo " detected hub :" + printf "%b" "$DETECTED" +else + echo " detected hub : (none)" +fi +echo + +# ---------- Invoke pytest ------------------------------------------------- +# If no devices detected, only the unit tier would produce meaningful +# PASS/FAIL — every hardware test would SKIP with "role not present". We +# narrow to tests/unit explicitly so the summary reads as "no hardware, +# unit suite only" instead of "big skip count looks suspicious". +if [[ -z $DETECTED && $# -eq 0 ]]; then + echo "[pre-flight] no supported devices detected; running unit tier only." + echo + exec "$VENV_PY" -m pytest tests/unit -v --report-log=tests/reportlog.jsonl +fi + +# Default pytest args when the user passed none. Power users can invoke +# `./run-tests.sh tests/mesh -v --tb=long` and skip all of these defaults. +# +# NOTE: `--assume-baked` is DELIBERATELY omitted here. `tests/test_00_bake.py` +# has an internal skip-if-already-baked check (`_bake_role`: query device_info, +# compare region + primary_channel to the session profile, skip on match). +# So the fast path is ~8-10 s of verification overhead when the devices are +# already baked — negligible next to the 2-6 min suite runtime. Letting +# test_00_bake.py run means a fresh device, a re-seeded session, or a post- +# factory-reset device gets flashed automatically instead of silently +# skipping half the hardware tests with "not baked with session profile" +# errors. Power users who know their hardware is current and want to shave +# those seconds can pass `--assume-baked` explicitly. +if [[ $# -eq 0 ]]; then + set -- tests/ \ + --html=tests/report.html --self-contained-html \ + --junitxml=tests/junit.xml \ + -v --tb=short +fi + +# Always emit `tests/reportlog.jsonl` (unless the operator explicitly passed +# their own `--report-log=...`). Consumers — notably the +# `meshtastic-mcp-test-tui` TUI — tail the reportlog for live per-test state. +# Appending here means power-user invocations like `./run-tests.sh tests/mesh` +# also produce it, not just the all-defaults invocation. +_has_report_log=0 +for _arg in "$@"; do + case "$_arg" in + --report-log | --report-log=*) _has_report_log=1 ;; + *) ;; # any other arg: no-op; loop continues + esac +done +if [[ $_has_report_log -eq 0 ]]; then + set -- "$@" --report-log=tests/reportlog.jsonl +fi + +exec "$VENV_PY" -m pytest "$@" diff --git a/mcp-server/src/meshtastic_mcp/__init__.py b/mcp-server/src/meshtastic_mcp/__init__.py new file mode 100644 index 000000000..bd696afe0 --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/__init__.py @@ -0,0 +1,3 @@ +"""Meshtastic MCP server — device discovery, PlatformIO tooling, and device admin.""" + +__version__ = "0.1.0" diff --git a/mcp-server/src/meshtastic_mcp/__main__.py b/mcp-server/src/meshtastic_mcp/__main__.py new file mode 100644 index 000000000..4ed67db38 --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/__main__.py @@ -0,0 +1,11 @@ +"""Entry point for `python -m meshtastic_mcp`.""" + +from meshtastic_mcp.server import app + + +def main() -> None: + app.run() + + +if __name__ == "__main__": + main() diff --git a/mcp-server/src/meshtastic_mcp/admin.py b/mcp-server/src/meshtastic_mcp/admin.py new file mode 100644 index 000000000..6da92d860 --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/admin.py @@ -0,0 +1,377 @@ +"""Device administration: owner, config, channels, messaging, admin actions. + +All operations use the same `connect()` context manager so port selection, +port-busy detection, and cleanup are handled uniformly. + +Config writes use a dot-path: the first segment names a section (e.g. +`"lora"` in LocalConfig or `"mqtt"` in LocalModuleConfig), remaining segments +walk protobuf fields. Enum fields accept their string names (`"US"` for +`lora.region`) so callers don't need to know the numeric values. +""" + +from __future__ import annotations + +from typing import Any + +from google.protobuf import descriptor as pb_descriptor +from google.protobuf import json_format +from meshtastic.protobuf import localonly_pb2 + +from .connection import connect + + +class AdminError(RuntimeError): + pass + + +LOCAL_CONFIG_SECTIONS = {f.name for f in localonly_pb2.LocalConfig.DESCRIPTOR.fields} +MODULE_CONFIG_SECTIONS = { + f.name for f in localonly_pb2.LocalModuleConfig.DESCRIPTOR.fields +} + + +def _require_confirm(confirm: bool, operation: str) -> None: + if not confirm: + raise AdminError(f"{operation} is destructive and requires confirm=True.") + + +def _message_to_dict(msg: Any) -> dict[str, Any]: + # `including_default_value_fields` was renamed to + # `always_print_fields_with_no_presence` in protobuf 5.26+. Pick whichever + # kwarg the installed version accepts so we work against both. + kwargs: dict[str, Any] = {"preserving_proto_field_name": True} + import inspect + + sig = inspect.signature(json_format.MessageToDict) + if "always_print_fields_with_no_presence" in sig.parameters: + kwargs["always_print_fields_with_no_presence"] = False + elif "including_default_value_fields" in sig.parameters: + kwargs["including_default_value_fields"] = False + return json_format.MessageToDict(msg, **kwargs) + + +# ---------- owner ---------------------------------------------------------- + + +def set_owner( + long_name: str, + short_name: str | None = None, + port: str | None = None, +) -> dict[str, Any]: + if short_name is not None and len(short_name) > 4: + raise AdminError("short_name must be 4 characters or fewer") + with connect(port=port) as iface: + iface.localNode.setOwner(long_name=long_name, short_name=short_name) + return { + "ok": True, + "long_name": long_name, + "short_name": short_name, + } + + +# ---------- config reads --------------------------------------------------- + + +def _section_container(node, section: str) -> tuple[Any, str]: + """Return (container_message, parent_name) for a section name. + + Parent is 'localConfig' or 'moduleConfig' so callers know where to call + writeConfig() after mutating. + """ + if section in LOCAL_CONFIG_SECTIONS: + return getattr(node.localConfig, section), "localConfig" + if section in MODULE_CONFIG_SECTIONS: + return getattr(node.moduleConfig, section), "moduleConfig" + raise AdminError( + f"Unknown config section: {section!r}. " + f"Valid sections: {sorted(LOCAL_CONFIG_SECTIONS | MODULE_CONFIG_SECTIONS)}" + ) + + +def get_config(section: str | None = None, port: str | None = None) -> dict[str, Any]: + """Read one or all config sections. + + `section` may be any name in LocalConfig (device, lora, position, power, + network, display, bluetooth, security) or LocalModuleConfig (mqtt, serial, + telemetry, ...). Omit `section` or pass `"all"` for everything. + """ + with connect(port=port) as iface: + node = iface.localNode + if section in (None, "all"): + lc = _message_to_dict(node.localConfig) + mc = _message_to_dict(node.moduleConfig) + return { + "config": { + "localConfig": lc, + "moduleConfig": mc, + } + } + container, _parent = _section_container(node, section) + return {"config": {section: _message_to_dict(container)}} + + +# ---------- config writes -------------------------------------------------- + + +def _coerce_enum(field: pb_descriptor.FieldDescriptor, value: Any) -> int: + """Accept an enum value as either its int or its string name.""" + enum_type = field.enum_type + if isinstance(value, bool): + raise AdminError(f"{field.name}: expected enum {enum_type.name}, got bool") + if isinstance(value, int): + if enum_type.values_by_number.get(value) is None: + raise AdminError( + f"{field.name}: {value} is not a valid {enum_type.name} value" + ) + return value + if isinstance(value, str): + upper = value.upper() + ev = enum_type.values_by_name.get(upper) + if ev is None: + valid = sorted(enum_type.values_by_name.keys()) + raise AdminError( + f"{field.name}: {value!r} is not a valid {enum_type.name}. " + f"Valid: {valid}" + ) + return ev.number + raise AdminError( + f"{field.name}: expected enum {enum_type.name}, got {type(value).__name__}" + ) + + +def _coerce_scalar(field: pb_descriptor.FieldDescriptor, value: Any) -> Any: + t = field.type + FT = pb_descriptor.FieldDescriptor + if t == FT.TYPE_ENUM: + return _coerce_enum(field, value) + if t == FT.TYPE_BOOL: + if isinstance(value, bool): + return value + if isinstance(value, str): + return value.strip().lower() in ("true", "yes", "1", "on") + if isinstance(value, int): + return bool(value) + if t in ( + FT.TYPE_INT32, + FT.TYPE_INT64, + FT.TYPE_UINT32, + FT.TYPE_UINT64, + FT.TYPE_SINT32, + FT.TYPE_SINT64, + FT.TYPE_FIXED32, + FT.TYPE_FIXED64, + ): + return int(value) + if t in (FT.TYPE_FLOAT, FT.TYPE_DOUBLE): + return float(value) + if t == FT.TYPE_STRING: + return str(value) + if t == FT.TYPE_BYTES: + if isinstance(value, (bytes, bytearray)): + return bytes(value) + return str(value).encode("utf-8") + raise AdminError( + f"{field.name}: unsupported field type {t}. Use raw protobuf for this field." + ) + + +def _walk_to_field( + root_msg: Any, path_segments: list[str] +) -> tuple[Any, pb_descriptor.FieldDescriptor]: + """Walk `root_msg` by field names until the leaf; return (parent_msg, leaf_field_descriptor).""" + msg = root_msg + for i, name in enumerate(path_segments): + desc = msg.DESCRIPTOR + field = desc.fields_by_name.get(name) + if field is None: + trail = ".".join(path_segments[:i] or [""]) + valid = [f.name for f in desc.fields] + raise AdminError(f"No field {name!r} in {trail}. Valid: {valid}") + is_last = i == len(path_segments) - 1 + if is_last: + return msg, field + if field.type != pb_descriptor.FieldDescriptor.TYPE_MESSAGE: + raise AdminError( + f"{'.'.join(path_segments[:i+1])} is a scalar; cannot descend into it" + ) + msg = getattr(msg, name) + # path_segments was empty + raise AdminError("Empty config path") + + +def set_config(path: str, value: Any, port: str | None = None) -> dict[str, Any]: + """Set a single config field by dot-path and write it to the device. + + Examples: + set_config("lora.region", "US") + set_config("lora.modem_preset", "LONG_FAST") + set_config("device.role", "ROUTER") + set_config("mqtt.enabled", True) + set_config("mqtt.address", "mqtt.example.com") + + """ + segments = [s for s in path.split(".") if s] + if not segments: + raise AdminError("path cannot be empty") + section = segments[0] + + with connect(port=port) as iface: + node = iface.localNode + container, parent_name = _section_container(node, section) + + # Treat the section as the root; the rest of the path walks into it. + leaf_parent, field = _walk_to_field(container, segments[1:] or []) + # Use `is_repeated` (modern upb protobuf API) rather than the + # deprecated `label == LABEL_REPEATED` check — the C-extension + # FieldDescriptor in protobuf >= 5.x doesn't expose `.label` at + # all, and `is_repeated` is the supported replacement that works + # across both the pure-python and upb backends. + if field.is_repeated: + raise AdminError( + f"{path!r} is a repeated field; v1 only supports scalar sets. " + "Use the raw meshtastic CLI for now." + ) + old_raw = getattr(leaf_parent, field.name) + coerced = _coerce_scalar(field, value) + try: + setattr(leaf_parent, field.name, coerced) + except (TypeError, ValueError) as exc: + raise AdminError(f"{path}: {exc}") from exc + + node.writeConfig(section) + + # Stringify enums for the response (so the caller can see the change in + # the same vocabulary they used to set it). + if field.type == pb_descriptor.FieldDescriptor.TYPE_ENUM: + try: + old_display = field.enum_type.values_by_number[old_raw].name + new_display = field.enum_type.values_by_number[coerced].name + except Exception: + old_display, new_display = old_raw, coerced + else: + old_display, new_display = old_raw, coerced + + return { + "ok": True, + "path": path, + "section": section, + "parent": parent_name, + "old_value": old_display, + "new_value": new_display, + } + + +# ---------- channels ------------------------------------------------------- + + +def get_channel_url( + include_all: bool = False, port: str | None = None +) -> dict[str, Any]: + with connect(port=port) as iface: + url = iface.localNode.getURL(includeAll=include_all) + return {"url": url} + + +def set_channel_url(url: str, port: str | None = None) -> dict[str, Any]: + with connect(port=port) as iface: + # setURL replaces the channel set from the URL's contents. It does not + # return a count; we infer by counting non-DISABLED channels after. + iface.localNode.setURL(url) + channels = iface.localNode.channels or [] + active = sum(1 for c in channels if getattr(c, "role", 0) != 0) + return {"ok": True, "channels_imported": active} + + +# ---------- messaging ------------------------------------------------------ + + +def send_text( + text: str, + to: str | int | None = None, + channel_index: int = 0, + want_ack: bool = False, + port: str | None = None, +) -> dict[str, Any]: + destination = to if to is not None else "^all" + with connect(port=port) as iface: + packet = iface.sendText( + text, + destinationId=destination, + wantAck=want_ack, + channelIndex=channel_index, + ) + packet_id = getattr(packet, "id", None) + return {"ok": True, "packet_id": packet_id, "destination": destination} + + +# ---------- diagnostics ---------------------------------------------------- + + +def set_debug_log_api(enabled: bool, port: str | None = None) -> dict[str, Any]: + """Toggle `config.security.debug_log_api_enabled` on the local node. + + When enabled, firmware emits log lines as protobuf `LogRecord` messages + over the StreamAPI instead of raw text. meshtastic-python surfaces them + on pubsub topic `meshtastic.log.line`, which flows through the SAME + SerialInterface our tests already hold open — no `pio device monitor` + needed, no port-contention with admin/info calls. + + Firmware gate: `src/SerialConsole.cpp` (`usingProtobufs && + config.security.debug_log_api_enabled`). Setting persists in NVS; it + survives reboot. `factory_reset(full=False)` clears it unless it's + re-applied after reset. + + Previously-documented concurrency hazard (emitLogRecord sharing the + main packet-emission buffers) has been fixed — see `StreamAPI.h` + where the log path now owns dedicated `fromRadioScratchLog` / + `txBufLog` buffers, and `StreamAPI::emitTxBuffer` + + `StreamAPI::emitLogRecord` both serialize their `stream->write` + calls via `streamLock`. Leaving the flag on under traffic is safe. + """ + with connect(port=port) as iface: + sec = iface.localNode.localConfig.security + sec.debug_log_api_enabled = bool(enabled) + iface.localNode.writeConfig("security") + return {"ok": True, "debug_log_api_enabled": bool(enabled)} + + +# ---------- admin actions -------------------------------------------------- + + +def reboot( + port: str | None = None, confirm: bool = False, seconds: int = 10 +) -> dict[str, Any]: + _require_confirm(confirm, "reboot") + with connect(port=port) as iface: + iface.localNode.reboot(secs=seconds) + return {"ok": True, "rebooting_in_s": seconds} + + +def shutdown( + port: str | None = None, confirm: bool = False, seconds: int = 10 +) -> dict[str, Any]: + _require_confirm(confirm, "shutdown") + with connect(port=port) as iface: + iface.localNode.shutdown(secs=seconds) + return {"ok": True, "shutting_down_in_s": seconds} + + +def factory_reset( + port: str | None = None, confirm: bool = False, full: bool = False +) -> dict[str, Any]: + """Tell the node to factory-reset its config. + + Works around a meshtastic-python 2.7.8 bug: `Node.factoryReset(full=True)` + internally does `p.factory_reset_config = True` where the field is + int32. protobuf 5.x rejects bool→int assignment as a TypeError. We build + the AdminMessage directly with int values (1=non-full, 2=full) and call + `_sendAdmin` to sidestep the SDK bug entirely. + """ + _require_confirm(confirm, "factory_reset") + from meshtastic.protobuf import admin_pb2 # type: ignore[import-untyped] + + with connect(port=port) as iface: + msg = admin_pb2.AdminMessage() + msg.factory_reset_config = 2 if full else 1 + iface.localNode._sendAdmin(msg) + return {"ok": True, "full": full} diff --git a/mcp-server/src/meshtastic_mcp/boards.py b/mcp-server/src/meshtastic_mcp/boards.py new file mode 100644 index 000000000..df5024800 --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/boards.py @@ -0,0 +1,159 @@ +"""Board / PlatformIO env enumeration. + +Parses `pio project config --json-output` — a nested list of +`[section_name, [[key, value], ...]]` pairs — into a dict keyed by env name, +extracting the `custom_meshtastic_*` metadata the firmware variants expose. + +The parsed config is cached and invalidated when `platformio.ini`'s mtime +changes, so subsequent calls don't pay the 1–2s pio startup cost. +""" + +from __future__ import annotations + +import threading +from typing import Any + +from . import config, pio + +_CACHE_LOCK = threading.Lock() +_CACHE: dict[str, Any] = {"mtime": None, "envs": None} + + +def _parse_bool(value: Any) -> bool: + if isinstance(value, bool): + return value + if isinstance(value, str): + return value.strip().lower() in ("true", "yes", "1", "on") + return bool(value) + + +def _parse_int(value: Any) -> int | None: + try: + return int(value) + except (TypeError, ValueError): + return None + + +def _parse_tags(value: Any) -> list[str]: + if value is None: + return [] + if isinstance(value, list): + return [str(v).strip() for v in value if str(v).strip()] + return [t.strip() for t in str(value).replace(",", " ").split() if t.strip()] + + +def _env_record(env_name: str, items: list[list[Any]]) -> dict[str, Any]: + """Build a normalized dict for one env section.""" + d = dict(items) + return { + "env": env_name, + "architecture": d.get("custom_meshtastic_architecture"), + "hw_model": _parse_int(d.get("custom_meshtastic_hw_model")), + "hw_model_slug": d.get("custom_meshtastic_hw_model_slug"), + "display_name": d.get("custom_meshtastic_display_name"), + "actively_supported": _parse_bool( + d.get("custom_meshtastic_actively_supported") + ), + "support_level": _parse_int(d.get("custom_meshtastic_support_level")), + "board_level": d.get("board_level"), # "pr", "extra", or None + "tags": _parse_tags(d.get("custom_meshtastic_tags")), + "images": _parse_tags(d.get("custom_meshtastic_images")), + "board": d.get("board"), + "upload_speed": _parse_int(d.get("upload_speed")), + "upload_protocol": d.get("upload_protocol"), + "monitor_speed": _parse_int(d.get("monitor_speed")), + "monitor_filters": d.get("monitor_filters") or [], + "_raw": d, # Full dict for get_board + } + + +def _load_all() -> dict[str, dict[str, Any]]: + """Parse `pio project config` into `{env_name: record}`.""" + raw = pio.run_json(["project", "config"], timeout=pio.TIMEOUT_PROJECT_CONFIG) + result: dict[str, dict[str, Any]] = {} + for section_name, items in raw: + if not isinstance(section_name, str) or not section_name.startswith("env:"): + continue + env_name = section_name.split(":", 1)[1] + result[env_name] = _env_record(env_name, items) + return result + + +def _get_cached() -> dict[str, dict[str, Any]]: + root = config.firmware_root() + platformio_ini = root / "platformio.ini" + try: + mtime = platformio_ini.stat().st_mtime + except FileNotFoundError: + mtime = None + + with _CACHE_LOCK: + if _CACHE["envs"] is not None and _CACHE["mtime"] == mtime: + return _CACHE["envs"] + envs = _load_all() + _CACHE["envs"] = envs + _CACHE["mtime"] = mtime + return envs + + +def invalidate_cache() -> None: + with _CACHE_LOCK: + _CACHE["envs"] = None + _CACHE["mtime"] = None + + +def _public_record(rec: dict[str, Any]) -> dict[str, Any]: + """Strip the `_raw` field for list outputs.""" + return {k: v for k, v in rec.items() if not k.startswith("_")} + + +def list_boards( + architecture: str | None = None, + actively_supported_only: bool = False, + query: str | None = None, + board_level: str | None = None, # "release" | "pr" | "extra" +) -> list[dict[str, Any]]: + """Enumerate PlatformIO envs with Meshtastic metadata. + + Filters are cumulative (AND). `board_level="release"` means envs with no + explicit `board_level` set (the default release targets). + """ + envs = _get_cached() + q = query.lower().strip() if query else None + + out = [] + for rec in envs.values(): + if architecture and rec.get("architecture") != architecture: + continue + if actively_supported_only and not rec.get("actively_supported"): + continue + if board_level is not None: + rec_level = rec.get("board_level") + if board_level == "release": + if rec_level not in (None, ""): + continue + elif rec_level != board_level: + continue + if q: + display = (rec.get("display_name") or "").lower() + env_name = rec.get("env", "").lower() + slug = (rec.get("hw_model_slug") or "").lower() + if q not in display and q not in env_name and q not in slug: + continue + out.append(_public_record(rec)) + + out.sort(key=lambda r: (r.get("architecture") or "", r.get("env"))) + return out + + +def get_board(env: str) -> dict[str, Any]: + """Full metadata for one env, including the raw pio config dict.""" + envs = _get_cached() + rec = envs.get(env) + if rec is None: + raise KeyError( + f"Unknown env: {env!r}. Use list_boards() to see available envs." + ) + public = _public_record(rec) + public["raw_config"] = rec["_raw"] + return public diff --git a/mcp-server/src/meshtastic_mcp/cli/__init__.py b/mcp-server/src/meshtastic_mcp/cli/__init__.py new file mode 100644 index 000000000..04729b643 --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/cli/__init__.py @@ -0,0 +1,6 @@ +"""Command-line entry points that sit alongside the MCP server. + +Modules here are loaded on-demand by `[project.scripts]` entries in +`pyproject.toml`. They are NOT imported by `meshtastic_mcp.server` or the +admin/info tool surface — the MCP server stays pure stdio JSON-RPC. +""" diff --git a/mcp-server/src/meshtastic_mcp/cli/_flashlog.py b/mcp-server/src/meshtastic_mcp/cli/_flashlog.py new file mode 100644 index 000000000..889183bb3 --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/cli/_flashlog.py @@ -0,0 +1,73 @@ +"""Flash progress log tailer for ``meshtastic-mcp-test-tui``. + +``pio.py`` / ``hw_tools.py`` tee subprocess output (``pio run -t upload``, +``esptool erase_flash``, ``nrfutil dfu``, etc.) to ``tests/flash.log`` +line-by-line as it arrives — controlled by the ``MESHTASTIC_MCP_FLASH_LOG`` +env var that ``run-tests.sh`` sets. The TUI tails that file so the operator +sees live flash progress in the pytest pane instead of 3 minutes of silence +during ``test_00_bake``. + +Separate from ``_fwlog.py`` because that one parses JSONL, this one +streams plain text lines. Same daemon-thread + EOF-backoff structure. +""" + +from __future__ import annotations + +import pathlib +import threading +import time +from typing import Callable + + +class FlashLogTailer(threading.Thread): + """Tail a plain-text log file, publish each stripped line via ``post``. + + ``post`` is invoked with a single ``str`` for every new line. Lines are + stripped of trailing newlines; empty lines after stripping are dropped. + + The file may not exist yet when this thread starts — it's truncated by + ``run-tests.sh`` at session start, but if the tailer races the shell, + we tolerate FileNotFoundError for up to ``wait_s`` seconds. + """ + + def __init__( + self, + path: pathlib.Path, + post: Callable[[str], None], + stop: threading.Event, + *, + wait_s: float = 30.0, + ) -> None: + super().__init__(daemon=True, name="flashlog-tail") + self._path = path + self._post = post + self._stop = stop + self._wait_s = wait_s + + def run(self) -> None: + deadline = time.monotonic() + self._wait_s + while not self._path.is_file(): + if self._stop.is_set() or time.monotonic() > deadline: + return + time.sleep(0.1) + try: + fh = self._path.open("r", encoding="utf-8", errors="replace") + except OSError: + return + try: + while not self._stop.is_set(): + line = fh.readline() + if not line: + time.sleep(0.05) + continue + line = line.rstrip("\r\n") + if not line: + continue + try: + self._post(line) + except Exception: + # A post failure (e.g. closed app) is terminal for this + # thread but we still want to close the file handle. + return + finally: + fh.close() diff --git a/mcp-server/src/meshtastic_mcp/cli/_fwlog.py b/mcp-server/src/meshtastic_mcp/cli/_fwlog.py new file mode 100644 index 000000000..7db20f81c --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/cli/_fwlog.py @@ -0,0 +1,96 @@ +"""Firmware log tail worker for ``meshtastic-mcp-test-tui``. + +Complements v1's reportlog-tail worker. ``tests/conftest.py`` owns a +session-scoped autouse fixture (``_firmware_log_stream``) that mirrors +every ``meshtastic.log.line`` pubsub event to ``tests/fwlog.jsonl`` — +one JSON object per line: + + {"ts": 1729100000.123, "port": "/dev/cu.usbmodem1101", "line": "..."} + +The TUI tails that file from a worker thread; each new line becomes a +:class:`FirmwareLogLine` message posted to the App. Same pattern as the +reportlog tail worker — truncate on launch, tolerate missing file for +30 s, back off at EOF. + +Kept in its own module so the (large) ``test_tui.py`` stays focused on +the Textual App shell. +""" + +from __future__ import annotations + +import json +import pathlib +import threading +import time +from typing import Any, Callable + + +class FirmwareLogTailer(threading.Thread): + """Tail ``tests/fwlog.jsonl``, publish parsed records via ``post``. + + ``post`` is the App's ``post_message`` (or any callable that accepts a + single payload arg). We pass parsed dicts rather than constructing + Textual Message objects here — keeps this module free of the + textual dependency so it's unit-testable in a bare venv. + + Parameters + ---------- + path: + Path to ``tests/fwlog.jsonl``. The file may not exist yet at + startup — pytest only creates it once the session fixture runs. + post: + Callable invoked with a dict ``{"ts", "port", "line"}`` for every + new line parsed from the file. + stop: + An event the App sets to signal shutdown. + wait_s: + How long to poll for the file's creation before giving up. Default + 30 s; pytest collection on a cold cache can be slow. + + """ + + def __init__( + self, + path: pathlib.Path, + post: Callable[[dict[str, Any]], None], + stop: threading.Event, + *, + wait_s: float = 30.0, + ) -> None: + super().__init__(daemon=True, name="fwlog-tail") + self._path = path + self._post = post + self._stop = stop + self._wait_s = wait_s + + def run(self) -> None: + deadline = time.monotonic() + self._wait_s + while not self._path.is_file(): + if self._stop.is_set() or time.monotonic() > deadline: + return + time.sleep(0.1) + try: + fh = self._path.open("r", encoding="utf-8") + except OSError: + return + try: + while not self._stop.is_set(): + line = fh.readline() + if not line: + time.sleep(0.05) + continue + line = line.strip() + if not line: + continue + try: + record = json.loads(line) + except json.JSONDecodeError: + continue + # Defensive: require the three fields we rely on. + if not isinstance(record, dict): + continue + if "line" not in record: + continue + self._post(record) + finally: + fh.close() diff --git a/mcp-server/src/meshtastic_mcp/cli/_history.py b/mcp-server/src/meshtastic_mcp/cli/_history.py new file mode 100644 index 000000000..639dcec5f --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/cli/_history.py @@ -0,0 +1,127 @@ +"""Cross-run history for ``meshtastic-mcp-test-tui``. + +Persists one JSON object per pytest run to +``mcp-server/tests/.history/runs.jsonl``. The TUI reads the last N +entries on launch to render a duration sparkline in the header — a +quick read on whether the suite is slowing down over time. + +Schema (keep small; the file can grow for months): + + {"run": 42, "ts": 1729100000.0, "duration_s": 387.2, + "passed": 52, "failed": 0, "skipped": 23, "exit_code": 0, + "seed": "mcp-user-host"} +""" + +from __future__ import annotations + +import json +import pathlib +import time +from dataclasses import asdict, dataclass +from typing import Iterable + +# Sparkline glyphs, low → high. 8 levels is the Unicode convention. +_SPARK_BLOCKS = "▁▂▃▄▅▆▇█" + + +@dataclass +class RunRecord: + run: int + ts: float + duration_s: float + passed: int + failed: int + skipped: int + exit_code: int + seed: str + + +class HistoryStore: + """Append-only JSONL store with bounded read. + + Writes are fsynced after each append (the file is tiny; fsync cost + is negligible and protects against truncation on a crash). + """ + + def __init__(self, path: pathlib.Path, *, keep_last: int = 50) -> None: + self._path = path + self._keep_last = keep_last + + def append(self, record: RunRecord) -> None: + try: + self._path.parent.mkdir(parents=True, exist_ok=True) + with self._path.open("a", encoding="utf-8") as fh: + fh.write(json.dumps(asdict(record)) + "\n") + fh.flush() + except Exception: + # Non-fatal: history is cosmetic. + pass + + def read_recent(self) -> list[RunRecord]: + """Return the last ``keep_last`` records in chronological order.""" + if not self._path.is_file(): + return [] + try: + lines = self._path.read_text(encoding="utf-8").splitlines() + except OSError: + return [] + out: list[RunRecord] = [] + # Parse tail-first so we don't waste work on a huge history. + for line in lines[-self._keep_last :]: + line = line.strip() + if not line: + continue + try: + raw = json.loads(line) + except json.JSONDecodeError: + continue + try: + out.append(RunRecord(**raw)) + except TypeError: + # Schema drift; skip the record rather than crash. + continue + return out + + def record_run( + self, + *, + run: int, + duration_s: float, + passed: int, + failed: int, + skipped: int, + exit_code: int, + seed: str, + ) -> RunRecord: + rec = RunRecord( + run=run, + ts=time.time(), + duration_s=float(duration_s), + passed=int(passed), + failed=int(failed), + skipped=int(skipped), + exit_code=int(exit_code), + seed=seed, + ) + self.append(rec) + return rec + + +def sparkline(values: Iterable[float], *, width: int = 20) -> str: + """Render a Unicode block-character sparkline from the last ``width`` values. + + Returns an empty string for empty input so the header handles + "no history yet" gracefully. + """ + buf = [v for v in values if v >= 0][-width:] + if not buf: + return "" + lo, hi = min(buf), max(buf) + if hi - lo < 1e-9: + return _SPARK_BLOCKS[len(_SPARK_BLOCKS) // 2] * len(buf) + n = len(_SPARK_BLOCKS) - 1 + out = [] + for v in buf: + idx = int(round((v - lo) / (hi - lo) * n)) + out.append(_SPARK_BLOCKS[max(0, min(n, idx))]) + return "".join(out) diff --git a/mcp-server/src/meshtastic_mcp/cli/_reproducer.py b/mcp-server/src/meshtastic_mcp/cli/_reproducer.py new file mode 100644 index 000000000..420da3c76 --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/cli/_reproducer.py @@ -0,0 +1,214 @@ +"""Reproducer bundle builder for ``meshtastic-mcp-test-tui``. + +When the operator presses ``x`` on a failed test leaf, we package the +minimum viable failure context into a tarball under +``mcp-server/tests/reproducers/``: + +:: + + repro--.tar.gz + ├── README.md human-readable overview + ├── test_report.json the failing TestReport event from reportlog + ├── fwlog.jsonl firmware log filtered to the failure window + ├── devices.json per-device device_info + lora config snapshot + └── env.json seed, run #, pytest version, platform, hostname + +Separate module so the logic can be unit-tested without Textual. The +TUI glue is thin — one key binding calls :func:`build_reproducer_bundle` +with the focused test's state and shows the path in a modal. +""" + +from __future__ import annotations + +import io +import json +import pathlib +import platform +import re +import socket +import tarfile +import time +from dataclasses import dataclass +from typing import Any, Iterable + + +@dataclass +class ReproContext: + """Everything :func:`build_reproducer_bundle` needs. Shaped to map + cleanly onto the state the TUI already tracks — no extra data + collection required at export time.""" + + nodeid: str + longrepr: str + sections: list[tuple[str, str]] + start_ts: float | None + stop_ts: float | None + seed: str + run_number: int + exit_code: int | None + fwlog_path: pathlib.Path + output_dir: pathlib.Path + extra_device_rows: list[dict[str, Any]] # [{role, port, info, ...}, ...] + + +def _short_nodeid(nodeid: str) -> str: + """Collapse a pytest nodeid into a filename-safe slug (<= 60 chars).""" + # Drop the file path prefix; keep test name + parametrization. + tail = nodeid.split("::", 1)[-1] if "::" in nodeid else nodeid + slug = re.sub(r"[^A-Za-z0-9_.\-]", "_", tail) + return slug[:60].strip("_.-") or "test" + + +def _filtered_fwlog( + fwlog_path: pathlib.Path, + start_ts: float | None, + stop_ts: float | None, + *, + pad_s: float = 5.0, +) -> bytes: + """Return fwlog.jsonl lines whose ``ts`` lies in [start-pad, stop+pad].""" + if not fwlog_path.is_file(): + return b"" + if start_ts is None or stop_ts is None: + # Without a time window, include the whole file — rare; happens + # when a test fails in setup before pytest emitted a start ts. + try: + return fwlog_path.read_bytes() + except OSError: + return b"" + lo, hi = start_ts - pad_s, stop_ts + pad_s + out = io.BytesIO() + try: + with fwlog_path.open("r", encoding="utf-8") as fh: + for line in fh: + stripped = line.strip() + if not stripped: + continue + try: + record = json.loads(stripped) + except json.JSONDecodeError: + continue + ts = record.get("ts") + if not isinstance(ts, (int, float)): + continue + if lo <= ts <= hi: + out.write(line.encode("utf-8")) + except OSError: + return b"" + return out.getvalue() + + +def _readme(ctx: ReproContext) -> str: + t = time.strftime("%Y-%m-%d %H:%M:%S %Z", time.localtime()) + return f"""# Reproducer bundle + +Exported by `meshtastic-mcp-test-tui` on {t}. + +## Failing test + +- **nodeid:** `{ctx.nodeid}` +- **seed:** `{ctx.seed}` +- **run #:** {ctx.run_number} +- **suite exit code (at export time):** {ctx.exit_code if ctx.exit_code is not None else "in progress"} + +## Files in this archive + +| File | Contents | +|---|---| +| `test_report.json` | The pytest-reportlog `TestReport` event for the failing test — includes `longrepr`, captured `sections` (stdout/stderr/log), `duration`, `location`, `keywords`. | +| `fwlog.jsonl` | Firmware log lines (from `meshtastic.log.line` pubsub) filtered to [start−5s, stop+5s] around the test's run window. Each line is `{{ts, port, line}}`. | +| `devices.json` | Per-device snapshot at export time: `device_info` + `lora` config per detected role. | +| `env.json` | Python version, platform, hostname, seed, run number. | + +## How to triage + +1. Open `test_report.json` and read `longrepr` + `sections` — most failures explain themselves there. +2. If the failure is a mesh/telemetry assertion, `fwlog.jsonl` is where the answer usually lives. Grep for `Error=`, `NAK`, `PKI_UNKNOWN_PUBKEY`, `Skip send`, `Guru Meditation`, or the uptime timestamps around the assertion event. +3. Compare `devices.json` against the expected state (e.g. `num_nodes >= 2`, `primary_channel == "McpTest"`, `region == "US"`). If fields disagree with the seed-derived USERPREFS profile, the device probably wasn't baked with this session's profile. + +## Reproducing locally + +```bash +cd mcp-server +MESHTASTIC_MCP_SEED='{ctx.seed}' .venv/bin/pytest '{ctx.nodeid}' --tb=long -v +``` +""" + + +def build_reproducer_bundle(ctx: ReproContext) -> pathlib.Path: + """Build a tarball under ``ctx.output_dir`` and return its path. + + Parent dirs are created as needed. Errors during optional sections + (devices, env) are swallowed — the bundle is still useful without + them; refusing to export because the device poller had a hiccup + would be worse than the export missing a file. + """ + ctx.output_dir.mkdir(parents=True, exist_ok=True) + ts = int(time.time()) + slug = _short_nodeid(ctx.nodeid) + archive_path = ctx.output_dir / f"repro-{ts}-{slug}.tar.gz" + + with tarfile.open(archive_path, "w:gz") as tar: + + def _add(name: str, data: bytes) -> None: + info = tarfile.TarInfo(name=name) + info.size = len(data) + info.mtime = ts + tar.addfile(info, io.BytesIO(data)) + + # README + _add("README.md", _readme(ctx).encode("utf-8")) + + # test_report.json — reconstruct from the fields the TUI stashes. + test_report = { + "nodeid": ctx.nodeid, + "outcome": "failed", + "longrepr": ctx.longrepr, + "sections": [list(s) for s in ctx.sections], + "start": ctx.start_ts, + "stop": ctx.stop_ts, + } + _add( + "test_report.json", + json.dumps(test_report, indent=2, default=str).encode("utf-8"), + ) + + # fwlog.jsonl (filtered) + _add("fwlog.jsonl", _filtered_fwlog(ctx.fwlog_path, ctx.start_ts, ctx.stop_ts)) + + # devices.json + try: + devices_payload = json.dumps( + ctx.extra_device_rows or [], indent=2, default=str + ) + except Exception: + devices_payload = "[]" + _add("devices.json", devices_payload.encode("utf-8")) + + # env.json + try: + from importlib.metadata import version as _pkg_version + + pytest_version = _pkg_version("pytest") + except Exception: + pytest_version = "unknown" + env_payload = { + "seed": ctx.seed, + "run": ctx.run_number, + "exit_code": ctx.exit_code, + "export_ts": ts, + "python": platform.python_version(), + "pytest": pytest_version, + "platform": f"{platform.system()} {platform.release()} {platform.machine()}", + "hostname": socket.gethostname(), + } + _add("env.json", json.dumps(env_payload, indent=2).encode("utf-8")) + + return archive_path + + +def iter_entries(archive_path: pathlib.Path) -> Iterable[str]: + """Yield member names — used by callers that want to confirm the bundle shape.""" + with tarfile.open(archive_path, "r:gz") as tar: + for m in tar.getmembers(): + yield m.name diff --git a/mcp-server/src/meshtastic_mcp/cli/test_tui.py b/mcp-server/src/meshtastic_mcp/cli/test_tui.py new file mode 100644 index 000000000..33201101b --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/cli/test_tui.py @@ -0,0 +1,1782 @@ +"""Textual TUI wrapping `mcp-server/run-tests.sh`. + +Launch: ``meshtastic-mcp-test-tui [pytest-args]`` + +The TUI *wraps* ``run-tests.sh``; it never replaces it. Same script, same +env-var resolution, same ``userPrefs.jsonc`` session fixture. Four data +sources drive live state: + +1. ``tests/reportlog.jsonl`` — written by ``pytest-reportlog``. Tailed in a + worker thread; each JSON line is published as a :class:`ReportLogEvent` + message. This is the authoritative source for tree population + per-test + outcome. +2. The pytest subprocess ``stdout`` + ``stderr`` streams — line-by-line, + published as :class:`PytestLine` messages and rendered verbatim in the + pytest pane. +3. ``tests/fwlog.jsonl`` — firmware log stream. Written by the + ``_firmware_log_stream`` autouse session fixture in ``conftest.py`` + (mirrors every ``meshtastic.log.line`` pubsub event), tailed by the + :class:`FirmwareLogTailer` worker, displayed in a wrap-enabled + RichLog with cycleable port filter. +4. ``devices.list_devices()`` + ``info.device_info(port)`` — polled only at + startup and again after ``RunFinished``. Device polling while pytest + holds a SerialInterface would deadlock on the exclusive port lock; the + existing ``hub_devices`` fixture is session-scoped so there is no safe + "between tests" window. The header reflects this with a "(stale)" + marker while the run is active. + +Key bindings (see :class:`TestTuiApp.BINDINGS`): + ``r`` re-run focused ``f`` filter tree ``d`` failure detail + ``g`` open report.html ``l`` cycle firmware-log port filter + ``x`` export reproducer bundle ``c`` tool-coverage panel + ``q`` / Ctrl-C graceful quit with SIGINT → SIGTERM → SIGKILL escalation + +Shipped today (v1 + v2 slice): test tree + tier counters with progress bars, +pytest tail, live firmware log with port filter, device strip with +"currently running" status column, failure-detail modal, reproducer bundle +export (filters fwlog by test's start/stop timestamps), tool-coverage +modal, cross-run history sparkline in the header, clean SIGINT +propagation. Still open (see the plan file): mesh topology mini-diagram +and airtime / channel-utilization gauges. +""" + +from __future__ import annotations + +import argparse +import json +import os +import pathlib +import signal +import subprocess +import sys +import threading +import time +from dataclasses import dataclass, field +from typing import Any, Iterator + +# --------------------------------------------------------------------------- +# Configuration constants +# --------------------------------------------------------------------------- + +# Tier names that map nodeids like "tests//..." to counter buckets. +# Order here == display order in the tier-counters table. Matches the order +# `pytest_collection_modifyitems` in `conftest.py` uses: +# bake → unit → mesh → telemetry → monitor → fleet → admin → provisioning +# so the counters table reads top-to-bottom in execution order. +# +# "bake" is the synthetic tier for `tests/test_00_bake.py` — the file sits +# at the `tests/` root rather than under a tier subdirectory, so without +# this mapping `_tier_of_nodeid` would return "other" and the bake outcomes +# would be silently dropped from both the tier table and the history +# record (which sums tier counters to compute passed/failed/skipped). +TIERS = ( + "bake", + "unit", + "mesh", + "telemetry", + "monitor", + "fleet", + "admin", + "provisioning", +) + +# Relative paths from the mcp-server root. +_REPORTLOG_RELATIVE = "tests/reportlog.jsonl" +_FWLOG_RELATIVE = "tests/fwlog.jsonl" +# pio / esptool / nrfutil / picotool tee subprocess output here when +# `MESHTASTIC_MCP_FLASH_LOG` is set (see `pio._run_capturing`). run-tests.sh +# sets that env var; the TUI also sets it for direct `_spawn_pytest` calls +# so `r`-key re-runs that skip the wrapper still get tee'd output. +_FLASHLOG_RELATIVE = "tests/flash.log" +_REPORT_HTML_RELATIVE = "tests/report.html" +_TOOL_COVERAGE_RELATIVE = "tests/tool_coverage.json" +_HISTORY_RELATIVE = "tests/.history/runs.jsonl" +_REPRODUCERS_RELATIVE = "tests/reproducers" +_RUN_TESTS_RELATIVE = "run-tests.sh" +_RUN_COUNTER_RELATIVE = "tests/.tui-runs" + +# Graceful-shutdown budgets (seconds) for the pytest subprocess when the +# user hits `q`. Matches what the existing CLI's atexit + userprefs sidecar +# self-heal expects. +_SIGINT_GRACE_S = 5.0 +_SIGTERM_GRACE_S = 5.0 + + +# --------------------------------------------------------------------------- +# Path resolution +# --------------------------------------------------------------------------- + + +def _mcp_server_root() -> pathlib.Path: + """Locate the mcp-server directory (the one containing run-tests.sh).""" + here = pathlib.Path(__file__).resolve() + # Walk up until we find pyproject.toml with a matching project name, or + # default to the three-up ancestor (src/meshtastic_mcp/cli/test_tui.py → + # .../mcp-server). The walk-up protects against unusual checkouts. + for parent in (here.parent, *here.parents): + if (parent / "pyproject.toml").is_file() and ( + parent / "run-tests.sh" + ).is_file(): + return parent + return here.parents[3] + + +# --------------------------------------------------------------------------- +# Data classes +# --------------------------------------------------------------------------- + + +@dataclass +class LeafReport: + """Per-test state drawn from reportlog events. + + Outcomes mirror pytest's: "passed" | "failed" | "skipped" | "running". + """ + + nodeid: str + tier: str + outcome: str = "pending" + duration_s: float = 0.0 + longrepr: str = "" + # Captured stdout / stderr / firmware-log sections from the test's + # `TestReport.sections` — shown in the failure-detail modal. + sections: list[tuple[str, str]] = field(default_factory=list) + # Wall-clock start/stop from the TestReport event. Used by the + # reproducer exporter (`x`) to filter `tests/fwlog.jsonl` down to + # just the lines around the failure window. + start_ts: float | None = None + stop_ts: float | None = None + + +@dataclass +class TierCounters: + tier: str + passed: int = 0 + failed: int = 0 + skipped: int = 0 + running: int = 0 + remaining: int = 0 + + +@dataclass +class DeviceRow: + role: str | None + port: str + vid: str + pid: str + description: str + # Populated from info.device_info when available; empty dict when we + # haven't queried (or when the poller is paused). + info: dict[str, Any] = field(default_factory=dict) + + +@dataclass +class State: + """Shared state owned by the App; written by workers under `lock`. + + UI code reads via Textual Message handlers which run on the UI thread + in the order workers called `post_message` — so reads don't need the + lock themselves. + """ + + lock: threading.Lock = field(default_factory=threading.Lock) + tiers: dict[str, TierCounters] = field( + default_factory=lambda: {t: TierCounters(tier=t) for t in TIERS} + ) + leaves: dict[str, LeafReport] = field(default_factory=dict) + # Ordered list of nodeids in the order they were first seen — lets us + # rebuild the tree deterministically. + nodeid_order: list[str] = field(default_factory=list) + devices: list[DeviceRow] = field(default_factory=list) + run_active: bool = False + exit_code: int | None = None + # nodeid of the currently-running test. Set on `when="setup"` + + # outcome="passed" (body about to execute); cleared on `when="call"` + # (any outcome) or on `when="setup"` + outcome="failed" (no body + # window). Drives the device-table "Status" column so the operator + # can see which test is touching a given device right now. + running_nodeid: str | None = None + # `time.monotonic()` captured when `running_nodeid` was set. Surfaced + # as live-updating elapsed-time ("RUNNING: test_bake_nrf52 (1:23)") so + # an operator staring at a ~3 min `test_00_bake` or a `mesh_formation` + # with a 60 s ceiling has concrete evidence the test isn't stuck. + running_started_at: float | None = None + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _tier_of_nodeid(nodeid: str) -> str: + """Map a pytest nodeid to its tier bucket. Unknown → 'other'. + + `tests/test_00_bake.py::...` is special-cased to the synthetic `bake` + tier — it's a top-level file (no tier subdirectory) so the generic + "second path segment" logic would miss it and route the bake outcomes + into the non-existent `other` bucket. + """ + parts = nodeid.split("/", 2) + if len(parts) >= 2 and parts[0] == "tests": + # Bake file sits at `tests/test_00_bake.py` — dedicated bucket. + if parts[1].startswith("test_00_bake"): + return "bake" + candidate = parts[1] + if candidate in TIERS: + return candidate + return "other" + + +def _file_of_nodeid(nodeid: str) -> str: + """Extract the test file name (e.g. 'test_boards.py') from a nodeid.""" + left = nodeid.split("::", 1)[0] + return left.rsplit("/", 1)[-1] + + +def _testname_of_nodeid(nodeid: str) -> str: + """Extract the 'test_foo[param]' suffix from a nodeid, or the full thing.""" + if "::" in nodeid: + return nodeid.split("::", 1)[1] + return nodeid + + +def _roles_from_nodeid(nodeid: str) -> set[str]: + """Infer which device roles a parametrized test touches. + + Patterns we recognize (from the existing ``conftest.py`` parametrization + in ``pytest_generate_tests``): + + - ``test_foo[nrf52]`` → {"nrf52"} (baked_single) + - ``test_foo[nrf52->esp32s3]`` → {"nrf52", "esp32s3"} (mesh_pair) + + Unparametrized tests (no bracket) return an empty set — the caller + should fall back to "this test involves ALL detected devices" rather + than pretending it touches none. + """ + if "[" not in nodeid or not nodeid.endswith("]"): + return set() + try: + inner = nodeid.rsplit("[", 1)[1][:-1] + except Exception: + return set() + # Split on "->" for directed mesh pairs; otherwise treat as single role. + parts = [p.strip() for p in inner.split("->")] if "->" in inner else [inner.strip()] + return {p for p in parts if p} + + +def _parse_events(path: pathlib.Path) -> Iterator[dict[str, Any]]: + """Yield parsed JSON dicts from a reportlog file, skipping malformed lines. + + Used for smoke-testing the parser against a finished file; the live + worker has its own tail loop. + """ + if not path.is_file(): + return + with path.open("r", encoding="utf-8") as fh: + for line in fh: + line = line.strip() + if not line: + continue + try: + yield json.loads(line) + except json.JSONDecodeError: + continue + + +def _load_run_number(counter_path: pathlib.Path) -> int: + """Bump + persist a monotonic run counter used in the TUI header.""" + try: + n = int(counter_path.read_text().strip()) + except Exception: + n = 0 + n += 1 + try: + counter_path.parent.mkdir(parents=True, exist_ok=True) + counter_path.write_text(str(n)) + except Exception: + # Non-fatal: the counter is cosmetic. + pass + return n + + +def _resolve_seed() -> str: + """Mirror the default-seed resolution from run-tests.sh. + + Operator can override via MESHTASTIC_MCP_SEED. Matches the + per-user/per-host default so repeated invocations land on the same PSK + (makes --assume-baked valid across invocations). + """ + if explicit := os.environ.get("MESHTASTIC_MCP_SEED"): + return explicit + try: + who = os.environ.get("USER") or os.environ.get("LOGNAME") or "anon" + except Exception: + who = "anon" + try: + import socket + + host = socket.gethostname().split(".", 1)[0] + except Exception: + host = "host" + return f"mcp-{who}-{host}" + + +def _format_duration(seconds: float) -> str: + if seconds < 60: + return f"{seconds:5.1f}s" + m, s = divmod(int(seconds), 60) + return f"{m:d}:{s:02d}" + + +# --------------------------------------------------------------------------- +# Textual imports (lazy — only when main() runs, so `_parse_events` can be +# imported by smoke tests without requiring textual installed in every env) +# --------------------------------------------------------------------------- + + +def _import_textual() -> Any: + """Return a namespace carrying every Textual class we use. + + Deferred import keeps `_parse_events` + `_tier_of_nodeid` importable + from tests / smoke scripts without pulling in the UI stack. + """ + import textual + from textual.app import App, ComposeResult + from textual.binding import Binding + from textual.containers import Horizontal, Vertical + from textual.message import Message + from textual.screen import ModalScreen + from textual.widgets import DataTable, Footer, Input, RichLog, Static, Tree + + ns = argparse.Namespace() + ns.App = App + ns.Binding = Binding + ns.ComposeResult = ComposeResult + ns.DataTable = DataTable + ns.Footer = Footer + ns.Horizontal = Horizontal + ns.Input = Input + ns.Message = Message + ns.ModalScreen = ModalScreen + ns.RichLog = RichLog + ns.Static = Static + ns.Tree = Tree + ns.Vertical = Vertical + ns.textual = textual + return ns + + +# --------------------------------------------------------------------------- +# main() — the important scaffolding lives here so that when we bail out +# before entering the Textual event loop (missing terminal, --help, etc.) +# nothing has grabbed the screen yet. +# --------------------------------------------------------------------------- + + +def main(argv: list[str] | None = None) -> int: + """Entry point for `meshtastic-mcp-test-tui`.""" + argv = list(argv if argv is not None else sys.argv[1:]) + + parser = argparse.ArgumentParser( + prog="meshtastic-mcp-test-tui", + description=( + "Live Textual TUI wrapping mcp-server/run-tests.sh. " + "Passes any unrecognized arguments through to pytest." + ), + allow_abbrev=False, + ) + parser.add_argument( + "--no-tui", + action="store_true", + help=( + "Skip the TUI and exec run-tests.sh directly. Useful as a health " + "check that the wrapper argv+env resolution is working." + ), + ) + args, pytest_args = parser.parse_known_args(argv) + + root = _mcp_server_root() + run_tests = root / _RUN_TESTS_RELATIVE + reportlog = root / _REPORTLOG_RELATIVE + fwlog = root / _FWLOG_RELATIVE + flashlog = root / _FLASHLOG_RELATIVE + counter = root / _RUN_COUNTER_RELATIVE + + if not run_tests.is_file(): + print( + f"error: could not locate {_RUN_TESTS_RELATIVE} relative to " + f"{root}. Is this the mcp-server checkout?", + file=sys.stderr, + ) + return 2 + + # Always clear stale log files before launching pytest. The TUI's tail + # workers race pytest file-creation; starting from a known-empty state + # avoids mid-line-decode confusion from the prior run. The fwlog session + # fixture also truncates on its end, and run-tests.sh truncates the + # flashlog — triple-truncate is deliberate (whichever side creates the + # file first, it starts empty). + for p in (reportlog, fwlog, flashlog): + try: + p.unlink(missing_ok=True) + except Exception: + pass + + # Compute + persist the run counter for the header (cosmetic). + run_number = _load_run_number(counter) + seed = _resolve_seed() + # Export the seed so the subprocess inherits the SAME value the TUI + # displays. run-tests.sh computes its own fallback if unset, and we'd + # end up with a header / wrapper-header mismatch if we let that happen. + os.environ.setdefault("MESHTASTIC_MCP_SEED", seed) + # Turn on subprocess-output tee'ing so `pio._run_capturing` writes each + # line of pio / esptool / nrfutil / picotool output to `tests/flash.log` + # as it arrives. The TUI tails that file and routes each line to the + # pytest pane so the operator sees live flash progress during long + # `pio run -t upload` / `esptool erase_flash` operations. run-tests.sh + # also sets this when invoked directly — `setdefault` so the wrapper's + # value wins when present. + os.environ.setdefault("MESHTASTIC_MCP_FLASH_LOG", str(flashlog)) + + # --no-tui: exec run-tests.sh directly. Useful for diagnosing wrapper + # env / argv handling without getting into Textual's alternate screen. + if args.no_tui: + cmd = [str(run_tests), *pytest_args] + os.execv(str(run_tests), cmd) # noqa: S606 — intentional + + # Textual UI import is deferred so `--help` and `--no-tui` do not pay + # the ~40 MB startup cost. + try: + tx = _import_textual() + except ImportError as exc: + print( + f"error: textual is not installed ({exc}). Install with: " + f"pip install -e '.[test]'", + file=sys.stderr, + ) + return 2 + + # Narrow-terminal warning (see plan §8 risk 2). Textual itself degrades, + # but a heads-up helps a first-time user. + term = os.environ.get("TERM", "") + if term in ("", "dumb", "screen") and not os.environ.get("TEXTUAL_NO_TERM_HINT"): + print( + f"[hint] TERM={term!r} may render poorly. Try " + f"`TERM=xterm-256color meshtastic-mcp-test-tui ...` if the layout " + f"looks broken.", + file=sys.stderr, + ) + + app = _build_app( + tx=tx, + root=root, + run_tests=run_tests, + reportlog=reportlog, + fwlog=fwlog, + flashlog=flashlog, + seed=seed, + run_number=run_number, + pytest_args=pytest_args, + ) + + # App.run() returns the subprocess exit code via `app.exit(returncode)`. + return_value = app.run() + if isinstance(return_value, int): + return return_value + return 0 + + +# --------------------------------------------------------------------------- +# Everything below is only reachable once Textual is importable. `tx` is +# the namespace returned by `_import_textual()` so we don't scatter `from +# textual import ...` across the file. +# --------------------------------------------------------------------------- + + +def _build_app( + *, + tx: Any, + root: pathlib.Path, + run_tests: pathlib.Path, + reportlog: pathlib.Path, + fwlog: pathlib.Path, + flashlog: pathlib.Path, + seed: str, + run_number: int, + pytest_args: list[str], +) -> Any: + """Assemble TestTuiApp with its Textual-dependent inner classes. + + Keeping the class definitions inside a factory means `main()` can + short-circuit (--no-tui, terminal-check, argparse error) before we + force Textual's import cost. + """ + + # Helper modules — lazy-imported here so the top-of-file import cost + # only kicks in when main() has decided to run the TUI. + from . import _flashlog as _flashlog_mod + from . import _fwlog as _fwlog_mod + from . import _history as _history_mod + from . import _reproducer as _reproducer_mod + + # ---------------- Messages ---------------- + + class ReportLogEvent(tx.Message): + def __init__(self, event: dict[str, Any]) -> None: + self.event = event + super().__init__() + + class PytestLine(tx.Message): + def __init__(self, source: str, line: str) -> None: + self.source = source # "stdout" | "stderr" + self.line = line + super().__init__() + + class FirmwareLogLine(tx.Message): + def __init__(self, record: dict[str, Any]) -> None: + # {"ts": float, "port": str | None, "line": str} + self.record = record + super().__init__() + + class FlashLogLine(tx.Message): + """Plain-text line from `tests/flash.log` — pio / esptool / nrfutil / + picotool output tee'd by `pio._run_capturing`. Routed to the pytest + pane so the operator sees live flash progress during `test_00_bake` + instead of 3 minutes of pytest-captured silence.""" + + def __init__(self, line: str) -> None: + self.line = line + super().__init__() + + class DeviceSnapshot(tx.Message): + def __init__(self, rows: list[DeviceRow]) -> None: + self.rows = rows + super().__init__() + + class RunFinished(tx.Message): + def __init__(self, returncode: int) -> None: + self.returncode = returncode + super().__init__() + + # ---------------- Workers ---------------- + + class ReportlogWorker(threading.Thread): + """Tail `reportlog.jsonl`, publish each event.""" + + def __init__(self, app: Any, path: pathlib.Path, stop: threading.Event) -> None: + super().__init__(daemon=True, name="reportlog-tail") + self._app = app + self._path = path + self._stop = stop + + def run(self) -> None: + # Wait up to 30 s for pytest to create the file (first call on + # a cold cache can be slow). + wait_deadline = time.monotonic() + 30.0 + while not self._path.is_file(): + if self._stop.is_set() or time.monotonic() > wait_deadline: + return + time.sleep(0.1) + try: + fh = self._path.open("r", encoding="utf-8") + except OSError: + return + try: + while not self._stop.is_set(): + line = fh.readline() + if not line: + time.sleep(0.05) + continue + line = line.strip() + if not line: + continue + try: + event = json.loads(line) + except json.JSONDecodeError: + continue + self._app.post_message(ReportLogEvent(event)) + finally: + fh.close() + + class SubprocessReaderWorker(threading.Thread): + """Read one stream line-by-line and publish PytestLine messages.""" + + def __init__( + self, + app: Any, + stream: Any, + source: str, + stop: threading.Event, + ) -> None: + super().__init__(daemon=True, name=f"subprocess-{source}") + self._app = app + self._stream = stream + self._source = source + self._stop = stop + + def run(self) -> None: + try: + for line in iter(self._stream.readline, ""): + if self._stop.is_set(): + break + self._app.post_message( + PytestLine(source=self._source, line=line.rstrip("\n")) + ) + except Exception: + # stream closed / subprocess died; not fatal. + pass + + class DevicePollerWorker(threading.Thread): + """Poll list_devices() + device_info() at startup and after RunFinished. + + Deliberately NOT polling during the run — `hub_devices` is a + session-scoped fixture holding SerialInterfaces across the whole + session, and device_info() would deadlock on the exclusive port + lock. Header shows "(stale)" during the gap. + """ + + def __init__(self, app: Any, state: State, stop: threading.Event) -> None: + super().__init__(daemon=True, name="device-poller") + self._app = app + self._state = state + self._stop = stop + self._trigger = threading.Event() + + def trigger(self) -> None: + self._trigger.set() + + def run(self) -> None: + # Perform one poll at startup; then wait for explicit triggers. + self._poll_once() + while not self._stop.is_set(): + if self._trigger.wait(timeout=0.5): + self._trigger.clear() + if self._stop.is_set(): + break + with self._state.lock: + active = self._state.run_active + if active: + continue + self._poll_once() + + def _poll_once(self) -> None: + try: + from meshtastic_mcp import devices as devices_mod + from meshtastic_mcp import info as info_mod + except Exception as exc: # pragma: no cover + self._app.post_message( + PytestLine( + source="stderr", line=f"[tui] device import failed: {exc!r}" + ) + ) + return + rows: list[DeviceRow] = [] + try: + raw = devices_mod.list_devices(include_unknown=True) + except Exception as exc: + self._app.post_message( + PytestLine( + source="stderr", line=f"[tui] list_devices failed: {exc!r}" + ) + ) + return + for d in raw: + vid_raw = d.get("vid") or "" + try: + vid_i = ( + int(vid_raw, 16) + if isinstance(vid_raw, str) and vid_raw.startswith("0x") + else int(vid_raw) + ) + except (TypeError, ValueError): + vid_i = 0 + role = None + if vid_i == 0x239A: + role = "nrf52" + elif vid_i in (0x303A, 0x10C4): + role = "esp32s3" + if not role and not d.get("likely_meshtastic"): + continue + row = DeviceRow( + role=role, + port=d.get("port", ""), + vid=str(vid_raw), + pid=str(d.get("pid") or ""), + description=d.get("description", "") or "", + ) + if role: + try: + row.info = info_mod.device_info(port=row.port, timeout_s=6.0) + except Exception as exc: + row.info = {"error": repr(exc)} + rows.append(row) + self._app.post_message(DeviceSnapshot(rows=rows)) + + # ---------------- Modals ---------------- + + class FailureDetailScreen(tx.ModalScreen): + """Show a failed test's longrepr + captured sections.""" + + BINDINGS = [tx.Binding("escape,q", "dismiss", "close")] + + def __init__(self, leaf: LeafReport, report_html: pathlib.Path) -> None: + self._leaf = leaf + self._report_html = report_html + super().__init__() + + def compose(self) -> Any: + yield tx.Static( + f"[bold]{self._leaf.nodeid}[/bold] " + f"outcome=[red]{self._leaf.outcome}[/red] " + f"duration={_format_duration(self._leaf.duration_s)}", + id="failure-detail-header", + ) + log = tx.RichLog( + highlight=False, markup=False, wrap=False, id="failure-detail-log" + ) + yield log + yield tx.Static( + f"[dim]Full HTML report: {self._report_html}[/dim] [esc] close", + id="failure-detail-footer", + ) + + def on_mount(self) -> None: + log = self.query_one("#failure-detail-log", tx.RichLog) + if self._leaf.longrepr: + log.write(self._leaf.longrepr) + log.write("") + for section_name, section_text in self._leaf.sections: + log.write(f"--- {section_name} ---") + log.write(section_text) + log.write("") + if not self._leaf.longrepr and not self._leaf.sections: + log.write("(no longrepr or captured sections in reportlog event)") + + def action_dismiss(self, _result: Any = None) -> None: + self.dismiss() + + class FilterInputScreen(tx.ModalScreen[str]): + """Prompt the user for a tree filter substring (empty clears).""" + + BINDINGS = [tx.Binding("escape", "cancel", "cancel")] + + def compose(self) -> Any: + yield tx.Static("filter test tree (substring, empty = clear):") + yield tx.Input(placeholder="nodeid substring", id="filter-input") + + def on_input_submitted(self, event: Any) -> None: + self.dismiss(event.value.strip()) + + def action_cancel(self) -> None: + self.dismiss(None) + + class CoverageModal(tx.ModalScreen): + """Read `tests/tool_coverage.json` (written by `tests/tool_coverage.py` + at `pytest_sessionfinish`) and render a two-column summary of which + MCP tools got exercised by the run. `(no coverage data yet)` while + the run is in flight.""" + + BINDINGS = [tx.Binding("escape,q,c", "dismiss", "close")] + + def __init__(self, coverage_path: pathlib.Path) -> None: + self._path = coverage_path + super().__init__() + + def compose(self) -> Any: + yield tx.Static("[bold]MCP tool coverage[/bold]", id="coverage-header") + yield tx.RichLog( + highlight=False, markup=True, wrap=False, id="coverage-log" + ) + yield tx.Static( + f"[dim]{self._path}[/dim] [esc] close", + id="coverage-footer", + ) + + def on_mount(self) -> None: + log = self.query_one("#coverage-log", tx.RichLog) + if not self._path.is_file(): + log.write("(no coverage data — tool_coverage.json not written yet)") + log.write("") + log.write("Coverage is emitted at pytest_sessionfinish; this") + log.write("file appears after the suite completes.") + return + try: + data = json.loads(self._path.read_text(encoding="utf-8")) + except Exception as exc: + log.write(f"[red]failed to read {self._path}:[/red] {exc!r}") + return + calls = data.get("calls") or {} + if not calls: + log.write("(tool_coverage.json present but no calls recorded)") + return + exercised = sorted( + ((n, c) for n, c in calls.items() if c > 0), key=lambda x: -x[1] + ) + unexercised = sorted(n for n, c in calls.items() if c == 0) + log.write(f"[b]{len(exercised)} / {len(calls)} MCP tools exercised[/b]") + log.write("") + log.write("[green]exercised[/green] (count):") + for name, count in exercised: + log.write(f" {count:>4} {name}") + if unexercised: + log.write("") + log.write("[dim]not exercised:[/dim]") + for name in unexercised: + log.write(f" {name}") + + def action_dismiss(self, _result: Any = None) -> None: + self.dismiss() + + class ReproducerResultModal(tx.ModalScreen): + """Show the exported reproducer tarball path with a short instruction.""" + + BINDINGS = [tx.Binding("escape,q,enter", "dismiss", "close")] + + def __init__( + self, archive_path: pathlib.Path, error: str | None = None + ) -> None: + self._archive = archive_path + self._error = error + super().__init__() + + def compose(self) -> Any: + if self._error: + yield tx.Static(f"[red]Reproducer export failed:[/red] {self._error}") + else: + yield tx.Static("[bold green]Reproducer bundle written[/bold green]") + yield tx.Static(f"[cyan]{self._archive}[/cyan]") + yield tx.Static("") + yield tx.Static( + "Contains: README.md, test_report.json, fwlog.jsonl (time-filtered)," + ) + yield tx.Static( + "devices.json, env.json. Attach to an issue / paste the path in chat." + ) + yield tx.Static("") + yield tx.Static("[dim][esc] close[/dim]") + + def action_dismiss(self, _result: Any = None) -> None: + self.dismiss() + + # ---------------- App ---------------- + + class TestTuiApp(tx.App): + CSS = """ + Screen { layout: vertical; } + #header-bar { height: 2; padding: 0 1; background: $panel; } + #tier-table { height: auto; max-height: 11; } + #body { height: 1fr; } + #tree-pane { width: 50%; border-right: solid $primary-background; } + #right-pane { width: 50%; layout: vertical; } + #pytest-pane { height: 50%; border-bottom: solid $primary-background; } + #fwlog-header { height: 1; padding: 0 1; background: $panel; } + #fwlog-pane { height: 1fr; } + Tree { height: 100%; } + RichLog { height: 100%; } + #device-table { height: auto; max-height: 6; } + """ + + TITLE = "mcp-server test runner" + + BINDINGS = [ + tx.Binding("r", "rerun_focused", "re-run focused"), + tx.Binding("f", "filter_tree", "filter"), + tx.Binding("d", "failure_detail", "failure detail"), + tx.Binding("g", "open_html_report", "open report.html"), + tx.Binding("x", "export_reproducer", "export reproducer"), + tx.Binding("c", "coverage_panel", "coverage"), + tx.Binding("l", "cycle_fwlog_filter", "fw log filter"), + tx.Binding("q,ctrl+c", "quit_app", "quit"), + ] + + def __init__(self) -> None: + super().__init__() + self._state = State() + self._root = root + self._run_tests = run_tests + self._reportlog = reportlog + self._fwlog = fwlog + self._flashlog = flashlog + self._report_html = root / _REPORT_HTML_RELATIVE + self._tool_coverage = root / _TOOL_COVERAGE_RELATIVE + self._repro_dir = root / _REPRODUCERS_RELATIVE + self._seed = seed + self._run_number = run_number + self._pytest_args = pytest_args + self._start_time = time.monotonic() + self._proc: subprocess.Popen[str] | None = None + self._stop = threading.Event() + self._reportlog_worker: ReportlogWorker | None = None + self._stdout_worker: SubprocessReaderWorker | None = None + self._stderr_worker: SubprocessReaderWorker | None = None + self._device_worker: DevicePollerWorker | None = None + self._fwlog_worker: _fwlog_mod.FirmwareLogTailer | None = None + self._flashlog_worker: _flashlog_mod.FlashLogTailer | None = None + self._tree_filter: str = "" + self._sigint_count = 0 + # Firmware-log port filter: None = all, else exact port match. + self._fwlog_filter: str | None = None + # Ordered set of distinct ports we've seen firmware log lines + # from — the `l` key cycles through these. + self._fwlog_ports: list[str] = [] + # Cross-run history. + self._history_store = _history_mod.HistoryStore( + root / _HISTORY_RELATIVE, keep_last=40 + ) + self._history_cache = self._history_store.read_recent() + + # -------- composition / mount -------- + + def compose(self) -> Any: + yield tx.Static(self._header_text(), id="header-bar") + tier_table = tx.DataTable(id="tier-table", show_cursor=False) + yield tier_table + with tx.Horizontal(id="body"): + with tx.Vertical(id="tree-pane"): + yield tx.Tree("tests", id="test-tree") + with tx.Vertical(id="right-pane"): + with tx.Vertical(id="pytest-pane"): + yield tx.RichLog( + id="pytest-log", + highlight=False, + markup=False, + wrap=False, + max_lines=5000, + ) + yield tx.Static(self._fwlog_header_text(), id="fwlog-header") + with tx.Vertical(id="fwlog-pane"): + yield tx.RichLog( + id="fwlog-log", + highlight=False, + markup=False, + # `wrap=True` so long firmware log lines (some + # hit ~200 chars — full packet hex dumps plus + # source tags) don't get truncated at the + # right edge. The right pane is ~50% of the + # terminal so even a wide terminal has a + # ~90-char cap; plain truncation dropped the + # uptime counter or packet id off the end. + wrap=True, + max_lines=5000, + ) + yield tx.DataTable(id="device-table", show_cursor=False) + yield tx.Footer() + + def _fwlog_header_text(self) -> str: + filt = self._fwlog_filter or "(all ports)" + return f"firmware log filter: [b]{filt}[/b] [l] cycle" + + def on_mount(self) -> None: + # Tier-counters table. `add_column` (singular) lets us pick + # the key explicitly — `add_columns` (plural) in textual 8.x + # returns auto-generated keys that are tedious to track + # separately, and update_cell(column_key=

)` — region, preset, channel_num, tx_power, hop_limit. - Optionally, if the device seems unhappy (fails to connect, `num_nodes==1` when ≥2 are plugged in, missing firmware*version), open a short firmware log window: `mcp__meshtastic__serial_open(port=

, env=)`, wait 3s, `serial_read(session_id=, max_lines=100)`, `serial_close(session_id=)`. The env should be inferred from the VID map in `mcp-server/run-tests.sh` (nrf52 → rak4631, esp32s3 → heltec-v3) unless `MESHTASTIC_MCP_ENV*` is set. -4. **Render per-device report** as: +4. **Hub health** (call once, not per-device): `mcp__meshtastic__uhubctl_list()` — enumerates every USB hub the host can see. Note which hubs advertise `ppps=true` and which hub hosts each Meshtastic device (cross-reference by VID). Flag it in the report if: + - No hub advertises PPPS → `tests/recovery/` can't run on this setup; hard-recovery via `uhubctl_cycle` isn't available. + - A Meshtastic device is on a non-PPPS hub → note it; operator may want to move the device to a PPPS hub to unlock auto-recovery. + - `uhubctl_list` raises `ConfigError: uhubctl not found` → just say `uhubctl not installed` in the report; don't treat as a fault. + +5. **Render per-device report** as: ```text [nrf52 @ /dev/cu.usbmodem1101] fw=2.7.23.bce2825, hw=RAK4631 @@ -33,20 +38,22 @@ Call the meshtastic MCP tool bundle and format a structured health report for on tx_power : 30 dBm, hop_limit=3 peers : 1 (esp32s3 0x433c2428, pubkey ✓, SNR 6.0 / RSSI -24 dBm) primary ch : McpTest + hub : 1-1.3 port 2 (PPPS, uhubctl-controllable) firmware : no panics in last 3s; NodeInfoModule emitted 2 broadcasts ``` - Keep it scannable. If a field is missing or abnormal (no pubkey for a known peer, region=UNSET, num_nodes inconsistent with the hub), flag it inline with a short `⚠︎ `. + Keep it scannable. If a field is missing or abnormal (no pubkey for a known peer, region=UNSET, num_nodes inconsistent with the hub, device on non-PPPS hub), flag it inline with a short `⚠︎ `. -5. **Cross-device correlation** (only when >1 device is inspected): +6. **Cross-device correlation** (only when >1 device is inspected): - Do both sides see each other in `nodesByNum`? If one does and the other doesn't, that's asymmetric NodeInfo — flag it. - Do the LoRa configs match? (region, channel_num, modem_preset should all agree; mismatch = no mesh) - Do the primary channel NAMES match? Mismatch = different PSK = no decode. -6. **Suggest next actions only for specific, recognisable failure modes**: +7. **Suggest next actions only for specific, recognisable failure modes**: - Stale PKI pubkey one-way → "run `/test tests/mesh/test_direct_with_ack.py` — the retry + nodeinfo-ping heals this in the test path." - Region mismatch → "re-bake one side via `./mcp-server/run-tests.sh --force-bake`." - - Device unreachable → point at touch_1200bps + the CP2102-wedged-driver note in run-tests.sh. + - Device unreachable, reachable via DFU → `touch_1200bps(port=...)` + `pio_flash`. If not even DFU responds AND the device is on a PPPS hub, escalate to `uhubctl_cycle(role=..., confirm=True)`. + - CP2102-wedged-driver on macOS → see the note in `run-tests.sh`. ## What NOT to do diff --git a/.claude/commands/repro.md b/.claude/commands/repro.md index 52dcf222b..c5f466ce6 100644 --- a/.claude/commands/repro.md +++ b/.claude/commands/repro.md @@ -44,7 +44,8 @@ Re-run a single pytest node ID N times in isolation, track pass rate, and surfac - **LoRa airtime collision** → pass rate improves with fewer concurrent transmitters; propose a `time.sleep` gap or retry bump in the test body. - **PKI key staleness** → fails on first attempt, passes after self-heal; existing retry loop in `test_direct_with_ack.py` handles this. - **NodeInfo cooldown** → `Skip send NodeInfo since we sent it <600s ago` in fail-only logs; needs `broadcast_nodeinfo_ping()` warmup. - - **Hardware-specific** (one direction fails, other passes; one device's firmware is older; driver wedged) → specific recovery pointer. + - **Hardware-specific** (one direction fails, other passes; one device's firmware is older; driver wedged) → specific recovery pointer. For a device that's wedged past `touch_1200bps`, the next escalation is `uhubctl_cycle(role=..., confirm=True)` to hard-power-cycle its hub port (requires `uhubctl` installed). + - **Device went dark mid-run** → fails from some attempt onward, never recovers, firmware log stops arriving. Almost always hardware: a Guru crash + frozen CDC. Hard-power-cycle via `uhubctl_cycle(role=..., confirm=True)` before the next iteration; if that also fails, escalate to replug. - **Genuinely unknown** → say so; don't invent a root cause. 7. **Report back** with: diff --git a/.claude/commands/test.md b/.claude/commands/test.md index 986ee1f31..46a753749 100644 --- a/.claude/commands/test.md +++ b/.claude/commands/test.md @@ -19,16 +19,21 @@ Run `mcp-server/run-tests.sh` and make sense of the output so the operator doesn 2. **Read the pre-flight header.** First ~6 lines print the detected hub (role → port → env). If that line reads `detected hub : (none)`, the wrapper will narrow to `tests/unit` only — say so explicitly in your summary so the operator knows hardware tiers were skipped. -3. **On pass**: one-line summary of the form `N passed, M skipped in `. Don't enumerate the 52 test names — the user can read those. Do mention if any test was SKIPPED for a NON-placeholder reason (e.g. "role not present on hub" is worth flagging). +3. **On pass**: one-line summary of the form `N passed, M skipped in `. Don't enumerate the test names — the user can read those. Do mention any SKIPPED tests and name the cause: + - `"role not present on hub"` → device unplugged; operator knows to reconnect. + - `"firmware not baked with USERPREFS_UI_TEST_LOG"` → tests/ui skipped because the macro isn't in firmware yet; suggest `--force-bake`. + - `"uhubctl not installed"` → tests/recovery + peer-offline skipped; suggest `brew install uhubctl` / `apt install uhubctl`. + - `"no PPPS-capable hubs detected"` → tests/recovery skipped because the hub doesn't support per-port power; the tier will never run on that setup. + - `"opencv-python-headless is not installed"` → tests/ui auto-deselected by run-tests.sh; suggest `pip install -e 'mcp-server/.[ui]'`. -4. **On failure**: for every FAILED test, open `mcp-server/tests/report.html` and extract the `Meshtastic debug` section for that test. pytest-html embeds the firmware log stream + device state dump there; the 200-line firmware log tail is usually enough to explain the failure. Summarise: which test, one-line assertion message, the firmware log lines that matter (things like `PKI_UNKNOWN_PUBKEY`, `Skip send NodeInfo`, `Error=`, `Guru Meditation`, `assertion failed`). +4. **On failure**: for every FAILED test, open `mcp-server/tests/report.html` and extract the `Meshtastic debug` section for that test. pytest-html embeds the firmware log stream + device state dump there; the 200-line firmware log tail is usually enough to explain the failure. Summarise: which test, one-line assertion message, the firmware log lines that matter (things like `PKI_UNKNOWN_PUBKEY`, `Skip send NodeInfo`, `Error=`, `Guru Meditation`, `assertion failed`). For UI-tier failures also glance at `mcp-server/tests/ui_captures///transcript.md` — it records each step's frame + OCR. 5. **Classify the failure** as one of: - **Transient/flake**: LoRa collision, timing-sensitive assertion, first-attempt NAK + successful retry pattern. Propose `/repro ` to confirm. - - **Environmental**: device unreachable, port busy, CP2102 driver wedged. Suggest the specific recovery (replug USB, `touch_1200bps`, check `git status userPrefs.jsonc`). + - **Environmental**: device unreachable, port busy, CP2102 driver wedged. Suggest the specific recovery in escalation order: (a) replug USB, (b) `touch_1200bps(port=...)` + `pio_flash` for nRF52 DFU, (c) `uhubctl_cycle(role="nrf52", confirm=True)` when a device is fully wedged past DFU (needs `uhubctl` installed — `baked_single`'s auto-recovery hook does this once automatically). Also check `git status userPrefs.jsonc`. - **Regression**: same assertion fails repeatedly, firmware log shows a new/unusual error. Surface the diff between expected and observed, identify the module likely responsible. -6. **Never run destructive recovery automatically.** If a failure looks like it needs a reflash, factory*reset, or USB replug, \_describe what to do* — don't execute. The operator decides. +6. **Never run destructive recovery automatically.** If a failure looks like it needs a reflash, factory*reset, `uhubctl_cycle`, or USB replug, \_describe what to do* — don't execute. The operator decides. ## Arguments handling diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d12244229..7c71a5014 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -474,7 +474,7 @@ The repo registers the server via `.mcp.json` at the repo root — Claude Code p **One MCP call per port at a time.** `SerialInterface` holds an exclusive OS-level lock on the serial port for its lifetime. If a `serial_*` session is open on `/dev/cu.usbmodem101`, calling `device_info` on the same port will fail fast pointing at the active session. Sequence calls: open → read/mutate → close, then next device. Never parallelize tool calls on the same port. -### MCP tool surface (~32 tools) +### MCP tool surface (43 tools) Grouped by purpose. Full argument shapes in `mcp-server/README.md`; a few high-value signatures are called out here. @@ -482,11 +482,13 @@ Grouped by purpose. Full argument shapes in `mcp-server/README.md`; a few high-v - **Build & flash**: `build`, `clean`, `pio_flash`, `erase_and_flash` (ESP32 only), `update_flash` (ESP32 OTA), `touch_1200bps` - **Serial sessions** (long-running, 10k-line ring buffer): `serial_open`, `serial_read`, `serial_list`, `serial_close` - **Device reads**: `device_info`, `list_nodes` -- **Device writes** (all require `confirm=True`): `set_owner`, `get_config`, `set_config`, `get_channel_url`, `set_channel_url`, `send_text`, `reboot`, `shutdown`, `factory_reset`, `set_debug_log_api` +- **Device writes**: `set_owner`, `get_config`, `set_config`, `get_channel_url`, `set_channel_url`, `send_text`, `send_input_event` (inject a button/key press via the firmware's InputBroker), `set_debug_log_api`; destructive/power-state writes require `confirm=True`: `reboot`, `shutdown`, `factory_reset` - **userPrefs admin** (build-time constants, not runtime config): `userprefs_get`, `userprefs_set`, `userprefs_reset`, `userprefs_manifest`, `userprefs_testing_profile` - **Vendor escape hatches**: `esptool_chip_info`, `esptool_erase_flash`, `esptool_raw`, `nrfutil_dfu`, `nrfutil_raw`, `picotool_info`, `picotool_load`, `picotool_raw` +- **USB power control** (via `uhubctl`, per-port PPPS toggle): `uhubctl_list` (read-only), `uhubctl_power(action='on'|'off', confirm=True)`, `uhubctl_cycle(delay_s, confirm=True)`. Target by raw `(location, port)` or by `role` (`"nrf52"`, `"esp32s3"`); role lookup checks `MESHTASTIC_UHUBCTL_LOCATION_` + `_PORT_` env vars first, falls back to VID auto-detection. +- **Observability** (UI tier + operator ad-hoc): `capture_screen(role, ocr=True)` — grabs a USB-webcam frame of the device OLED and optionally OCRs it. Requires `mcp-server[ui]` extras (`opencv-python-headless`, `easyocr`) and `MESHTASTIC_UI_CAMERA_DEVICE_` env var; falls through to a 1×1 black PNG `NullBackend` when unconfigured. -`confirm=True` is a tool-level gate on top of whatever permission prompt your MCP host shows. **Don't bypass it** by asking the host to auto-approve — it exists specifically because MCP hosts sometimes remember "always allow this tool" and that's dangerous for `factory_reset` and `erase_and_flash`. +`confirm=True` is a tool-level gate on top of whatever permission prompt your MCP host shows. **Don't bypass it** by asking the host to auto-approve — it exists specifically because MCP hosts sometimes remember "always allow this tool" and that's dangerous for `factory_reset`, `erase_and_flash`, `uhubctl_power(action='off')`, and `uhubctl_cycle`. ### Hardware test suite (`mcp-server/run-tests.sh`) @@ -494,14 +496,16 @@ The wrapper auto-detects connected devices (VID → role map: `0x239A` → `nrf5 Suite tiers (collected + run in this order via `pytest_collection_modifyitems`): -1. `tests/unit/` — pure Python (boards parse, pio wrapper, userPrefs parse, testing profile). No hardware. +1. `tests/unit/` — pure Python (boards parse, pio wrapper, userPrefs parse, testing profile, uhubctl parser). No hardware. 2. `tests/test_00_bake.py` — flashes each detected device with current `userPrefs.jsonc` merged with the session's test profile. Has its own skip-if-already-baked check comparing region + primary channel to the session profile; skips cheaply on warm devices. -3. `tests/mesh/` — multi-device mesh: bidirectional send, broadcast delivery, direct-with-ACK, mesh formation within 60s. Parametrized `[nrf52->esp32s3]` and `[esp32s3->nrf52]`. +3. `tests/mesh/` — multi-device mesh: bidirectional send, broadcast delivery, direct-with-ACK, mesh formation within 60s. Parametrized `[nrf52->esp32s3]` and `[esp32s3->nrf52]`. Includes `test_peer_offline_recovery` which uses uhubctl to physically power off one peer mid-conversation (requires uhubctl; skips without). 4. `tests/telemetry/` — `DEVICE_METRICS_APP` broadcast timing. 5. `tests/monitor/` — boot-log panic check. -6. `tests/fleet/` — PSK seed session isolation. -7. `tests/admin/` — channel URL roundtrip, owner persistence across reboot. -8. `tests/provisioning/` — region + modem + slot bake, admin key presence, `UNSET` region blocks TX, userPrefs survive factory reset. +6. `tests/recovery/` — `uhubctl` power-cycle round-trip + NVS persistence across hard reset. Requires `uhubctl` installed and a PPPS-capable hub; entire tier auto-skips otherwise. +7. `tests/ui/` — input-broker-driven screen navigation with camera + OCR evidence. +8. `tests/fleet/` — PSK seed session isolation. +9. `tests/admin/` — channel URL roundtrip, owner persistence across reboot. +10. `tests/provisioning/` — region + modem + slot bake, admin key presence, `UNSET` region blocks TX, userPrefs survive factory reset. Invocation patterns: @@ -586,15 +590,19 @@ If you're modifying `StreamAPI`, `PhoneAPI`, `NodeInfoModule`, or `userPrefs` fl ### Recovery playbooks -| Symptom | First check | Fix | -| ---------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `userPrefs.jsonc` dirty after test run | `git status --porcelain userPrefs.jsonc` | If non-empty, re-run `./mcp-server/run-tests.sh` once — the pre-flight self-heal restores from sidecar. If still dirty, `git checkout userPrefs.jsonc`. | -| Port busy / wedged CP2102 on macOS | `lsof /dev/cu.usbserial-0001` | Kill the holder. USB replug if the kernel still reports busy. Often a stale `pio device monitor` or zombie `meshtastic_mcp` process. | -| nRF52 appears unresponsive | `list_devices` shows VID `0x239A` but `device_info` times out | `touch_1200bps(port=...)` drops it into the DFU bootloader → `pio_flash` re-installs. | -| Multiple MCP server processes | `ps aux \| grep meshtastic_mcp` shows >1 | Kill all but the one your MCP host spawned. Zombies hold ports and break tests. | -| Mesh formation fails, one side sees peer but other doesn't | `/diagnose` (or `list_nodes` on both sides) | Asymmetric NodeInfo. `test_direct_with_ack` has a heal path; `/repro` it a few times. If persistent, both devices' clocks may be out of sync with their NodeInfo cooldown. | -| "role not present on hub" in skip reasons | `list_devices` | Expected if a device is unplugged. Reconnect before re-running the tier. | -| Tests fail only on first attempt then pass on rerun | — | State leak from a prior session. Run with `--force-bake` to reset to a known state. | +| Symptom | First check | Fix | +| --------------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `userPrefs.jsonc` dirty after test run | `git status --porcelain userPrefs.jsonc` | If non-empty, re-run `./mcp-server/run-tests.sh` once — the pre-flight self-heal restores from sidecar. If still dirty, `git checkout userPrefs.jsonc`. | +| Port busy / wedged CP2102 on macOS | `lsof /dev/cu.usbserial-0001` | Kill the holder. USB replug if the kernel still reports busy. Often a stale `pio device monitor` or zombie `meshtastic_mcp` process. | +| nRF52 appears unresponsive | `list_devices` shows VID `0x239A` but `device_info` times out | `touch_1200bps(port=...)` drops it into the DFU bootloader → `pio_flash` re-installs. | +| Device fully wedged (Guru Meditation, frozen CDC, no DFU) | `list_devices` shows the VID but every admin call times out | `uhubctl_cycle(role="nrf52", confirm=True)` hard-power-cycles the port via USB hub PPPS. `baked_single`'s auto-recovery hook does this once automatically if uhubctl is installed. Falls back to physical replug if no PPPS hub. | +| Multiple MCP server processes | `ps aux \| grep meshtastic_mcp` shows >1 | Kill all but the one your MCP host spawned. Zombies hold ports and break tests. | +| Mesh formation fails, one side sees peer but other doesn't | `/diagnose` (or `list_nodes` on both sides) | Asymmetric NodeInfo. `test_direct_with_ack` has a heal path; `/repro` it a few times. If persistent, both devices' clocks may be out of sync with their NodeInfo cooldown. | +| "role not present on hub" in skip reasons | `list_devices` | Expected if a device is unplugged. Reconnect before re-running the tier. | +| Entire `tests/recovery/` tier skipped | `command -v uhubctl` | Expected if `uhubctl` isn't on PATH. Install via `brew install uhubctl` (macOS) or `apt install uhubctl` (Debian/Ubuntu). Also skips if no hub advertises PPPS. | +| Entire `tests/ui/` tier skipped ("firmware not baked with USERPREFS_UI_TEST_LOG") | reportlog.jsonl for the skip reason | Re-run with `--force-bake` so the UI-log macro gets compiled into the fresh firmware. First run after the Round-3 landing always re-bakes. | +| `tests/ui/` runs but captures are all 1×1 black PNGs | `MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3` | Env var not set → `NullBackend`. Point a USB webcam at the heltec-v3 OLED and set the device index; `.venv/bin/python -c "import cv2; [print(i, cv2.VideoCapture(i).read()[0]) for i in range(5)]"` discovers it. | +| Tests fail only on first attempt then pass on rerun | — | State leak from a prior session. Run with `--force-bake` to reset to a known state. | ### Never do these without asking diff --git a/.github/prompts/mcp-diagnose.prompt.md b/.github/prompts/mcp-diagnose.prompt.md index c86826030..1049858f8 100644 --- a/.github/prompts/mcp-diagnose.prompt.md +++ b/.github/prompts/mcp-diagnose.prompt.md @@ -26,7 +26,12 @@ This prompt assumes the meshtastic MCP server is registered with your VS Code Co - `get_config(section="lora", port=

)` → region, preset, channel_num, tx_power, hop_limit - If anything looks off (can't connect, `num_nodes` wrong, missing `firmware_version`), open a short firmware-log window: `serial_open(port=

, env=)`, wait 3 seconds, `serial_read(session_id, max_lines=100)`, `serial_close(session_id)`. Infer env from VID (0x239a → `rak4631`, 0x303a/0x10c4 → `heltec-v3`) unless an `MESHTASTIC_MCP_ENV_` env var overrides it. -4. **Render per-device report** as a compact block: +4. **Hub health** (call once, not per-device): `uhubctl_list()` — enumerates every USB hub the host sees. Cross-reference each Meshtastic device's VID to find which hub + port it's on. Flag in the report if: + - No hub advertises `ppps=true` → `tests/recovery/` can't run; hard-recovery via `uhubctl_cycle` isn't available. + - A Meshtastic device is on a non-PPPS hub → note it; moving to a PPPS hub unlocks auto-recovery. + - `uhubctl_list` raises `ConfigError: uhubctl not found` → report as "uhubctl not installed"; don't treat as a device fault. + +5. **Render per-device report** as a compact block: ```text [nrf52 @ /dev/cu.usbmodem1101] fw=2.7.23.bce2825, hw=RAK4631 @@ -35,20 +40,22 @@ This prompt assumes the meshtastic MCP server is registered with your VS Code Co tx_power : 30 dBm, hop_limit=3 peers : 1 (esp32s3 0x433c2428, pubkey ✓, SNR 6.0 / RSSI -24 dBm) primary ch : McpTest + hub : 1-1.3 port 2 (PPPS, uhubctl-controllable) firmware : no panics in last 3s ``` - Flag abnormalities inline with `⚠︎ ` — missing pubkey on a known peer, region UNSET, mismatched channel name, etc. + Flag abnormalities inline with `⚠︎ ` — missing pubkey on a known peer, region UNSET, mismatched channel name, device on non-PPPS hub, etc. -5. **Cross-device correlation** (when >1 device selected): +6. **Cross-device correlation** (when >1 device selected): - Do both see each other in `nodesByNum`? - Do `region`, `channel_num`, `modem_preset` match across devices? - Do the primary channel names match? (Different name → different PSK → no decode.) -6. **Suggest next steps only for recognizable failure modes**, never speculatively: +7. **Suggest next steps only for recognizable failure modes**, never speculatively: - Stale PKI one-way → "`/mcp-test tests/mesh/test_direct_with_ack.py` — the test's retry+nodeinfo-ping heals this." - Region mismatch → "re-bake one side via `./mcp-server/run-tests.sh --force-bake`." - - Device unreachable → refer operator to the touch_1200bps + CP2102-wedged-driver notes in `run-tests.sh`. + - Device unreachable, DFU reachable → `touch_1200bps(port=...)` + `pio_flash`. If not even DFU responds and the device is on a PPPS hub, escalate to `uhubctl_cycle(role=..., confirm=True)`. + - CP2102-wedged-driver on macOS → see `run-tests.sh` notes. ## Hard constraints diff --git a/.github/prompts/mcp-repro.prompt.md b/.github/prompts/mcp-repro.prompt.md index be2963c33..3a7c5c3de 100644 --- a/.github/prompts/mcp-repro.prompt.md +++ b/.github/prompts/mcp-repro.prompt.md @@ -46,7 +46,8 @@ Equivalent of `.claude/commands/repro.md`. Use when the operator says "that one - **LoRa airtime collision** — pass rate improves with fewer concurrent transmitters. Suggest a `time.sleep` gap or retry bump in the test body. - **PKI key staleness** — first attempt fails, subsequent ones pass; existing retry-loop pattern in `test_direct_with_ack.py` is the fix. - **NodeInfo cooldown** — `Skip send NodeInfo since we sent it <600s ago` in fail-only logs; needs a `broadcast_nodeinfo_ping()` warmup. - - **Hardware-specific** — one direction consistently fails, firmware versions differ, CP2102 driver wedged, etc. + - **Hardware-specific** — one direction consistently fails, firmware versions differ, CP2102 driver wedged, etc. For a device wedged past `touch_1200bps`, recommend `uhubctl_cycle(role=..., confirm=True)` to hard-power-cycle its hub port (requires `uhubctl` installed). + - **Device went dark mid-run** — fails from some iteration onward and never recovers; firmware log stops arriving. Almost always a Guru crash with frozen CDC. Recommend `uhubctl_cycle` before the next iteration; escalate to replug if that also fails. - **Unknown** — say so. Don't invent a root cause. 7. **Report back** with: diff --git a/.github/prompts/mcp-test.prompt.md b/.github/prompts/mcp-test.prompt.md index 092ad3d85..148569e83 100644 --- a/.github/prompts/mcp-test.prompt.md +++ b/.github/prompts/mcp-test.prompt.md @@ -21,19 +21,25 @@ Equivalent of the Claude Code `/test` slash command in `.claude/commands/test.md 2. **Read the pre-flight header** (first few lines of wrapper output). The `detected hub :` line lists role → port → env mappings. If it reads `(none)`, the wrapper narrowed to `tests/unit` only — call that out explicitly so the operator knows hardware tiers were skipped. -3. **On pass**: one-line summary like `N passed, M skipped in `. Don't enumerate test names. DO mention any non-placeholder SKIPs (things like "role not present on hub") because they indicate missing hardware or setup issues. +3. **On pass**: one-line summary like `N passed, M skipped in `. Don't enumerate test names. DO mention any non-placeholder SKIPs and name the cause: + - `"role not present on hub"` → device unplugged; operator should reconnect. + - `"firmware not baked with USERPREFS_UI_TEST_LOG"` → tests/ui skipped; the UI-log compile macro isn't in the baked firmware. Suggest `--force-bake`. + - `"uhubctl not installed"` → tests/recovery + `test_peer_offline_recovery` skipped. Suggest `brew install uhubctl` / `apt install uhubctl`. + - `"no PPPS-capable hubs detected"` → tests/recovery skipped because the attached hub doesn't support per-port power switching; won't run on that setup. + - `"opencv-python-headless is not installed"` → tests/ui auto-deselected by `run-tests.sh`. Suggest `pip install -e 'mcp-server/.[ui]'`. 4. **On failure**: open `mcp-server/tests/report.html` (pytest-html output, self-contained) and extract the `Meshtastic debug` section for each failed test. That section includes a firmware log stream (last 200 lines) and device state dump. For each failure, summarise: - test name - one-line assertion message - the specific firmware log lines that explain why (look for `PKI_UNKNOWN_PUBKEY`, `Skip send NodeInfo`, `Error=`, `Guru Meditation`, `assertion failed`, `No suitable channel`) + - for UI-tier failures also check `mcp-server/tests/ui_captures///transcript.md` (per-step frame + OCR) 5. **Classify each failure** as one of: - **Transient flake** — LoRa collision, first-attempt NAK with self-heal pattern, timing-sensitive assertion. Suggest `/mcp-repro ` to confirm. - - **Environmental** — device unreachable, port busy, CP2102 driver wedged on macOS. Suggest specific recovery (USB replug, `touch_1200bps`, `git status userPrefs.jsonc`). + - **Environmental** — device unreachable, port busy, CP2102 driver wedged on macOS. Suggest recovery in escalation order: (a) replug USB, (b) `touch_1200bps` + `pio_flash` for nRF52 DFU, (c) `uhubctl_cycle(role=..., confirm=True)` for a device wedged past DFU (needs `uhubctl` installed; `baked_single` does this once automatically when available). Also check `git status userPrefs.jsonc`. - **Regression** — same assertion fails repeatedly on re-runs, firmware log shows novel errors. Identify the firmware module likely responsible. -6. **Do NOT run destructive recovery automatically**. If a failure looks like it needs a reflash, factory*reset, or replug — \_describe the steps* and let the operator decide. Never burn airtime or flash cycles without approval. +6. **Do NOT run destructive recovery automatically**. If a failure looks like it needs a reflash, factory*reset, `uhubctl_cycle`, or replug — \_describe the steps* and let the operator decide. Never burn airtime or flash cycles without approval. ## Arguments convention diff --git a/AGENTS.md b/AGENTS.md index cd043c087..b3fa1970c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,25 +89,42 @@ Sequence these; don't parallelize on the same port. ## Where to look -| Path | What's there | -| --------------------------------- | ---------------------------------------------------------------------------------------------------- | -| `src/` | Firmware C++ source (`mesh/`, `modules/`, `platform/`, `graphics/`, `gps/`, `motion/`, `mqtt/`, …) | -| `src/mesh/` | Core: NodeDB, Router, Channels, CryptoEngine, radio interfaces, StreamAPI, PhoneAPI | -| `src/modules/` | Feature modules; `Telemetry/Sensor/` has 50+ I2C sensor drivers | -| `variants/` | 200+ hardware variant definitions (`variant.h` + `platformio.ini` per board) | -| `protobufs/` | `.proto` definitions; regenerate with `bin/regen-protos.sh` | -| `test/` | Firmware unit tests (12 suites; `pio test -e native`) | -| `mcp-server/` | Python MCP server + pytest hardware integration tests | -| `mcp-server/tests/` | Tiered pytest suite: `unit/`, `mesh/`, `telemetry/`, `monitor/`, `fleet/`, `admin/`, `provisioning/` | -| `.claude/commands/` | Claude Code slash command bodies | -| `.github/prompts/` | Copilot prompt bodies (mirrors of the Claude Code ones) | -| `.github/copilot-instructions.md` | **Primary agent instructions — read this** | -| `.github/workflows/` | CI pipelines | -| `.mcp.json` | MCP server registration for Claude Code | +| Path | What's there | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `src/` | Firmware C++ source (`mesh/`, `modules/`, `platform/`, `graphics/`, `gps/`, `motion/`, `mqtt/`, …) | +| `src/mesh/` | Core: NodeDB, Router, Channels, CryptoEngine, radio interfaces, StreamAPI, PhoneAPI | +| `src/modules/` | Feature modules; `Telemetry/Sensor/` has 50+ I2C sensor drivers | +| `variants/` | 200+ hardware variant definitions (`variant.h` + `platformio.ini` per board) | +| `protobufs/` | `.proto` definitions; regenerate with `bin/regen-protos.sh` | +| `test/` | Firmware unit tests (12 suites; `pio test -e native`) | +| `mcp-server/` | Python MCP server + pytest hardware integration tests | +| `mcp-server/tests/` | Tiered pytest suite: `unit/`, `mesh/`, `telemetry/`, `monitor/`, `recovery/`, `ui/`, `fleet/`, `admin/`, `provisioning/` | +| `.claude/commands/` | Claude Code slash command bodies | +| `.github/prompts/` | Copilot prompt bodies (mirrors of the Claude Code ones) | +| `.github/copilot-instructions.md` | **Primary agent instructions — read this** | +| `.github/workflows/` | CI pipelines | +| `.mcp.json` | MCP server registration for Claude Code | ## Recovery one-liners - **`userPrefs.jsonc` dirty after a test run?** Re-run `./mcp-server/run-tests.sh` once (pre-flight self-heals from the sidecar). If still dirty: `git checkout userPrefs.jsonc`. - **nRF52 not responding?** `mcp__meshtastic__touch_1200bps(port=...)` drops it into the DFU bootloader, then `pio_flash` re-installs. +- **Device fully wedged (no DFU)?** `mcp__meshtastic__uhubctl_cycle(role="nrf52", confirm=True)` hard-power-cycles it via USB hub PPPS. Needs `uhubctl` installed (`brew install uhubctl` / `apt install uhubctl`); on Linux without udev rules, permission errors fail fast, so use `sudo uhubctl` yourself or configure udev access. - **Port busy?** `lsof ` to find the holder. Usually a stale `pio device monitor` or zombie `meshtastic_mcp` process. Kill it. - **Multiple MCP servers running?** `ps aux | grep meshtastic_mcp` — zombies hold ports. Kill all but the one your host spawned. + +## Environment variables (test harness) + +| Var | Purpose | +| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `MESHTASTIC_MCP_ENV_` | Override PlatformIO env for a role (e.g. `MESHTASTIC_MCP_ENV_NRF52=rak4631-dap`). Default map: `nrf52→rak4631`, `esp32s3→heltec-v3`. | +| `MESHTASTIC_MCP_SEED` | PSK seed for the session test profile. Defaults to `mcp--`. | +| `MESHTASTIC_MCP_FLASH_LOG` | File path to tee pio/esptool/nrfutil/picotool output. `run-tests.sh` sets this to `tests/flash.log` so the TUI can stream live flash progress. | +| `MESHTASTIC_UHUBCTL_BIN` | Absolute path to `uhubctl` binary. Default: PATH lookup. | +| `MESHTASTIC_UHUBCTL_LOCATION_` | Pin a role to a specific uhubctl hub location (e.g. `1-1.3`). Wins over VID auto-detection — use when multiple devices share a VID. | +| `MESHTASTIC_UHUBCTL_PORT_` | Pin a role to a specific hub port number. Required alongside `LOCATION_`. | +| `MESHTASTIC_UI_CAMERA_BACKEND` | Camera backend for UI tier + `capture_screen` tool: `opencv` / `ffmpeg` / `null` / `auto` (default). | +| `MESHTASTIC_UI_CAMERA_DEVICE` | Generic camera device (index or path). Used by the UI tier when no per-role var is set. | +| `MESHTASTIC_UI_CAMERA_DEVICE_` | Per-role camera pinning (e.g. `MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3=0` for the OLED-bearing heltec-v3). | +| `MESHTASTIC_UI_OCR_BACKEND` | OCR engine selection: `easyocr` / `pytesseract` / `null` / `auto` (default). | +| `MESHTASTIC_UI_TUI_CAMERA` | Set to `1` to mount the live camera-feed panel in `meshtastic-mcp-test-tui`. | diff --git a/mcp-server/.gitignore b/mcp-server/.gitignore index f5180bc71..4cc892b2a 100644 --- a/mcp-server/.gitignore +++ b/mcp-server/.gitignore @@ -24,3 +24,6 @@ tests/.tui-runs tests/.history/ # Reproducer bundles (TUI `x` export on failed tests). tests/reproducers/ +# UI-tier camera captures + per-test transcripts. Regenerated every run; +# left on disk for human review between runs. +tests/ui_captures/ diff --git a/mcp-server/README.md b/mcp-server/README.md index 7d5fc551a..7a36a6fac 100644 --- a/mcp-server/README.md +++ b/mcp-server/README.md @@ -61,7 +61,7 @@ Replace `` with the absolute path, e.g. `/Users/you/GitHub/firmwa Same `mcpServers` block, but in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). -## Tools (38) +## Tools (43) ### Discovery & metadata @@ -130,6 +130,34 @@ _The tool tables below document 38 currently registered MCP server tools._ | `picotool_load` | Load a UF2 | | `picotool_raw` | Pass-through | +### USB power control (uhubctl) + +| Tool | What it does | +| --------------- | ----------------------------------------------------------- | +| `uhubctl_list` | Enumerate USB hubs + attached-device VID/PID (read-only) | +| `uhubctl_power` | Drive a hub port `on` or `off`; `off` requires confirm=True | +| `uhubctl_cycle` | Off → wait `delay_s` → on; confirm=True required | + +Target a port by explicit `(location, port)` (raw uhubctl syntax like +`location="1-1.3", port=2`) or by `role` (`"nrf52"`, `"esp32s3"`). Role +lookup checks `MESHTASTIC_UHUBCTL_LOCATION_` + +`MESHTASTIC_UHUBCTL_PORT_` env vars first, then auto-detects via VID +against `uhubctl`'s output. + +Requires [`uhubctl`](https://github.com/mvp/uhubctl) on PATH: + +```bash +brew install uhubctl # macOS +apt install uhubctl # Debian/Ubuntu +``` + +Modern macOS + PPPS-capable hubs generally work without root. On Linux +without udev rules, or on old macOS with driver quirks, you may need +`sudo`. If uhubctl returns a permission error the MCP tool raises a +clear `UhubctlError` pointing at the +[udev-rules / sudo fallback](https://github.com/mvp/uhubctl#linux-usb-permissions) +rather than auto-`sudo`'ing mid-run. + ## Safety - **All destructive flash/admin tools require `confirm=True`** as a tool-level gate, on top of any permission prompt from Claude. @@ -182,10 +210,22 @@ in the pre-flight header. - **`unit`** — pure Python, no hardware. boards / PIO wrapper / userPrefs-parse / testing-profile fixtures. - **`mesh`** — 2-device mesh: formation, broadcast delivery, direct+ACK, - traceroute, bidirectional. Parametrized over both directions. + traceroute, bidirectional. Parametrized over both directions. Includes + `test_peer_offline_recovery` which uses uhubctl to power-cycle one peer + mid-conversation and verifies the mesh recovers (skips without uhubctl). - **`telemetry`** — periodic telemetry broadcast + on-demand request/reply (`TELEMETRY_APP` with `wantResponse=True`). - **`monitor`** — boot log has no panic markers within 60 s of reboot. +- **`recovery`** — `uhubctl` power-cycle round-trip: verifies the hub port + can be toggled off/on, the device re-enumerates with the same + `my_node_num`, and NVS-resident config (region, channel, modem preset) + survives a hard reset. Requires `uhubctl` on PATH; skips cleanly otherwise. +- **`ui`** — input-broker-driven screen navigation (`AdminMessage.send_input_event` + injection → `Screen::handleInputEvent` → frame transition). Parametrized + on the screen-bearing role (heltec-v3 OLED). Captures images via USB + webcam + OCRs them for HTML-report evidence. Requires `pip install -e '.[ui]'` + and `MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3=`; tier is auto-deselected + if `cv2` isn't importable. - **`fleet`** — PSK-seed isolation: two labs with different seeds never overlap. - **`admin`** — owner persistence across reboot, channel URL round-trip, @@ -193,6 +233,42 @@ in the pre-flight header. - **`provisioning`** — region/channel baking, userPrefs survive `factory_reset(full=False)`. +#### UI tier setup + +The `tests/ui/` tier drives the on-device OLED via the firmware's existing +`AdminMessage.send_input_event` RPC (no firmware changes required) and +verifies transitions via a macro-gated log line + camera + OCR. Summary: + +1. Install extras: `pip install -e 'mcp-server/.[ui]'` — pulls in + `opencv-python-headless`, `numpy`, `easyocr`, `Pillow`. First easyocr + run downloads ~100 MB of models to `~/.EasyOCR/`; an autouse session + fixture pre-warms the reader so per-test OCR is <100 ms after that. +2. Point a USB webcam at the heltec-v3 OLED. Discover its index: + ```bash + .venv/bin/python -c "import cv2; [print(i, cv2.VideoCapture(i).read()[0]) for i in range(5)]" + ``` +3. Export the per-role device env var: + ```bash + export MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3=0 + ``` +4. Run: + ```bash + ./run-tests.sh tests/ui -v + ``` + Captures land under `tests/ui_captures///`, one + PNG + `.ocr.txt` per `frame_capture()` call, with a per-test + `transcript.md` stepping through event → frame → OCR. The HTML report + embeds the full image strip inline (pass or fail). + +On macOS, `cv2.VideoCapture(0)` triggers the TCC Camera permission prompt +on first use. Pre-grant Terminal (or your IDE's terminal) before running. +The `OpenCVBackend` fails fast on 10 consecutive black frames so a silent +permission denial surfaces as a clear error, not an empty PNG strip. + +No camera? Set `MESHTASTIC_UI_CAMERA_BACKEND=null` (or leave the device var +unset). Tests still exercise the event-injection path and log assertions; +captures just become 1×1 black PNGs. + ### Artifacts (regenerated every run, under `tests/`) - `report.html` — self-contained pytest-html report. Each test gets a @@ -217,6 +293,14 @@ Key bindings: `r` re-run focused, `f` filter, `d` failure detail, `g` open `report.html`, `x` export reproducer bundle, `l` cycle fw-log filter, `q` quit (SIGINT → SIGTERM → SIGKILL escalation). +Set `MESHTASTIC_UI_TUI_CAMERA=1` to mount a bottom-of-screen **UI camera** +panel. Left side: the latest capture PNG rendered as Unicode half-blocks +(via `rich-pixels`, works in any terminal — no kitty/sixel required). +Right side: live transcript tail ("step 3 — frame 4/8 name=nodelist_nodes +— OCR: Nodes 2/2") so you can see every event-injection and its result +as each UI test runs. Requires the `[ui]` extras for image rendering; the +transcript alone works without them. + ### Slash commands Three AI-assisted workflows are wired up for Claude Code operators diff --git a/mcp-server/pyproject.toml b/mcp-server/pyproject.toml index d73bf795f..3241c843f 100644 --- a/mcp-server/pyproject.toml +++ b/mcp-server/pyproject.toml @@ -23,6 +23,21 @@ test = [ # consumers; revisit if install cost pushes back. "textual>=0.50", ] +# UI test tier + `capture_screen` MCP tool. Optional because the ML OCR +# model alone is ~100 MB and camera hardware is user-supplied. +# pip install -e '.[ui]' — full (OpenCV + easyocr) +# pip install -e '.[ui-min]' — image capture only, no OCR +ui = [ + "opencv-python-headless>=4.9", + "numpy>=1.26", + "easyocr>=1.7", + "Pillow>=10.0", + # Renders the latest camera capture as Unicode half-blocks in the TUI + # (MESHTASTIC_UI_TUI_CAMERA=1). Terminal-agnostic — no kitty / sixel + # dependency. Pure Python, tiny. + "rich-pixels>=3.0", +] +ui-min = ["opencv-python-headless>=4.9", "numpy>=1.26"] [project.scripts] meshtastic-mcp = "meshtastic_mcp.__main__:main" diff --git a/mcp-server/run-tests.sh b/mcp-server/run-tests.sh index 292e6e3a2..c84a8f751 100755 --- a/mcp-server/run-tests.sh +++ b/mcp-server/run-tests.sh @@ -217,6 +217,40 @@ if [[ $# -eq 0 ]]; then -v --tb=short fi +# UI tier requires opencv-python-headless (and ideally easyocr). If it's +# not installed, auto-deselect tests/ui so operators without the [ui] +# extra still get a green run. Printed in yellow; silent when cv2 is +# present. +_cv2_ok=0 +if "$VENV_PY" -c "import cv2" >/dev/null 2>&1; then + _cv2_ok=1 +fi +_running_ui=0 +for _arg in "$@"; do + case "$_arg" in + *tests/ui* | tests/) _running_ui=1 ;; + *) ;; + esac +done +if [[ $_running_ui -eq 1 && $_cv2_ok -eq 0 ]]; then + printf '\033[33m[pre-flight] tests/ui tier detected, but opencv-python-headless is not installed — deselecting.\033[0m\n' + printf ' install with: .venv/bin/pip install -e "mcp-server/.[ui]"\n' + echo + set -- "$@" --ignore=tests/ui +fi + +# Recovery tier needs `uhubctl` on PATH — it power-cycles devices via USB +# hub PPPS. The tier's conftest already skips cleanly, so this is just a +# friendly heads-up before the skip happens. `baked_single`'s auto- +# recovery hook also benefits from having uhubctl available across the +# whole suite. +if ! command -v uhubctl >/dev/null 2>&1; then + printf "\033[33m[pre-flight] uhubctl not found on PATH — recovery tier will skip, and\n" + printf " wedged-device auto-recovery is disabled.\033[0m\n" + printf " install with: brew install uhubctl (macOS) or apt install uhubctl (Debian/Ubuntu).\n" + echo +fi + # Always emit `tests/reportlog.jsonl` (unless the operator explicitly passed # their own `--report-log=...`). Consumers — notably the # `meshtastic-mcp-test-tui` TUI — tail the reportlog for live per-test state. diff --git a/mcp-server/src/meshtastic_mcp/admin.py b/mcp-server/src/meshtastic_mcp/admin.py index 6da92d860..33f3865dd 100644 --- a/mcp-server/src/meshtastic_mcp/admin.py +++ b/mcp-server/src/meshtastic_mcp/admin.py @@ -356,6 +356,46 @@ def shutdown( return {"ok": True, "shutting_down_in_s": seconds} +def send_input_event( + event_code: int | str, + kb_char: int = 0, + touch_x: int = 0, + touch_y: int = 0, + port: str | None = None, +) -> dict[str, Any]: + """Inject an InputBroker event (button press / key / gesture) into the UI. + + Wraps `AdminMessage.send_input_event` (handled in firmware at + src/modules/AdminModule.cpp::handleSendInputEvent). Local-only — no PKI + warmup needed since the admin message is addressed to `my_node_num`. + + `event_code` accepts an int, a case-insensitive name + (`"RIGHT"` / `"input_broker_right"`), or an `InputEventCode`. The + firmware-side enum lives in src/input/InputBroker.h and is mirrored in + `meshtastic_mcp.input_events`. + """ + from meshtastic.protobuf import admin_pb2 # type: ignore[import-untyped] + + from .input_events import coerce_event_code + + code = coerce_event_code(event_code) + if not 0 <= kb_char <= 255: + raise ValueError(f"kb_char out of u8 range: {kb_char}") + if not 0 <= touch_x <= 65535: + raise ValueError(f"touch_x out of u16 range: {touch_x}") + if not 0 <= touch_y <= 65535: + raise ValueError(f"touch_y out of u16 range: {touch_y}") + + with connect(port=port) as iface: + msg = admin_pb2.AdminMessage() + msg.send_input_event.event_code = code + msg.send_input_event.kb_char = kb_char + msg.send_input_event.touch_x = touch_x + msg.send_input_event.touch_y = touch_y + iface.localNode._sendAdmin(msg) + return {"ok": True, "event_code": code, "kb_char": kb_char} + + def factory_reset( port: str | None = None, confirm: bool = False, full: bool = False ) -> dict[str, Any]: diff --git a/mcp-server/src/meshtastic_mcp/camera.py b/mcp-server/src/meshtastic_mcp/camera.py new file mode 100644 index 000000000..5f1e5ede3 --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/camera.py @@ -0,0 +1,286 @@ +"""Cross-platform USB-webcam capture for UI tests + the `capture_screen` tool. + +Backends: +- `opencv` — cv2.VideoCapture (AVFoundation on macOS, V4L2 on Linux). +- `ffmpeg` — subprocess shelling out to the system `ffmpeg` binary. Slower + per frame, but zero Python deps beyond stdlib. +- `null` — no-op stub returning a 1×1 black PNG. Used when no camera is + configured; keeps code paths alive without forcing every operator to + hook up hardware. + +Environment variables (read at `get_camera()` call time): +- `MESHTASTIC_UI_CAMERA_BACKEND` — one of `opencv` / `ffmpeg` / `null` / + `auto` (default). `auto` picks opencv if `cv2` imports, else ffmpeg if + `ffmpeg --version` resolves, else null. +- `MESHTASTIC_UI_CAMERA_DEVICE` — generic default (index or path). +- `MESHTASTIC_UI_CAMERA_DEVICE_` — per-role override, e.g. + `MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3=0` for the OLED-bearing heltec-v3. + Role suffix is uppercased before lookup. + +Dependencies land in the optional `[ui]` extra; imports are lazy so clients +without `opencv-python-headless` installed can still import this module. +""" + +from __future__ import annotations + +import io +import os +import shutil +import subprocess +import sys +import time +import warnings +from pathlib import Path +from typing import Protocol + + +class CameraError(RuntimeError): + """Raised when a camera backend fails to initialize or capture.""" + + +class CameraBackend(Protocol): + name: str + + def capture(self) -> bytes: + """Return one PNG-encoded frame.""" + ... + + def close(self) -> None: ... + + +# ---------- OpenCV backend ------------------------------------------------- + + +class OpenCVBackend: + name = "opencv" + + def __init__(self, device: int | str, warmup_frames: int = 5) -> None: + try: + import cv2 # type: ignore[import-untyped] # noqa: PLC0415 + except ImportError as exc: + raise CameraError( + "opencv backend requested but `cv2` is not installed. " + "Install the mcp-server [ui] extra: pip install -e '.[ui]'" + ) from exc + + self._cv2 = cv2 + device_arg: int | str + if isinstance(device, str) and device.isdigit(): + device_arg = int(device) + else: + device_arg = device + self._cap = cv2.VideoCapture(device_arg) + if not self._cap.isOpened(): + raise CameraError( + f"cv2.VideoCapture({device_arg!r}) failed to open. " + "On macOS check TCC Camera permission; on Linux check /dev/video* and v4l2 access." + ) + + # Drop the first few frames — auto-exposure + white-balance settle. + for _ in range(warmup_frames): + self._cap.read() + # Detect a stuck black-frame camera early rather than silently + # producing all-black captures. + ok, frame = self._cap.read() + if not ok or frame is None: + self._cap.release() + raise CameraError(f"camera {device_arg!r} opened but returned no frames") + + def capture(self) -> bytes: + cv2 = self._cv2 + ok, frame = self._cap.read() + if not ok or frame is None: + raise CameraError("cv2.VideoCapture.read() returned no frame") + success, buf = cv2.imencode(".png", frame) + if not success: + raise CameraError("cv2.imencode('.png', ...) failed") + return bytes(buf) + + def close(self) -> None: + try: + self._cap.release() + except Exception: # noqa: BLE001 + pass + + +# ---------- ffmpeg subprocess backend -------------------------------------- + + +class FfmpegBackend: + name = "ffmpeg" + + def __init__(self, device: int | str) -> None: + if shutil.which("ffmpeg") is None: + raise CameraError("ffmpeg backend requested but `ffmpeg` is not on PATH") + + self._device = str(device) + # Platform-specific -f flag: + # macOS → avfoundation (index like "0") + # Linux → v4l2 (device like "/dev/video0" or "0") + if sys.platform == "darwin": + self._input_format = "avfoundation" + self._input_spec = self._device # bare index for avfoundation + else: + self._input_format = "v4l2" + self._input_spec = ( + self._device + if self._device.startswith("/dev/") + else f"/dev/video{self._device}" + ) + + def capture(self) -> bytes: + cmd = [ + "ffmpeg", + "-hide_banner", + "-loglevel", + "error", + "-f", + self._input_format, + "-i", + self._input_spec, + "-frames:v", + "1", + "-f", + "image2pipe", + "-vcodec", + "png", + "-", + ] + try: + out = subprocess.run( + cmd, capture_output=True, check=True, timeout=15 # noqa: S603 + ) + except subprocess.CalledProcessError as exc: + raise CameraError( + f"ffmpeg capture failed (rc={exc.returncode}): {exc.stderr.decode(errors='replace')[:200]}" + ) from exc + except subprocess.TimeoutExpired as exc: + raise CameraError("ffmpeg capture timed out after 15s") from exc + return out.stdout + + def close(self) -> None: + pass # stateless — each capture spawns a new process + + +# ---------- Null backend --------------------------------------------------- + + +# A tiny valid 1×1 transparent PNG so callers always get a decodable image. +_BLACK_1X1_PNG = bytes.fromhex( + "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c489" + "0000000d49444154789c6300010000000500010d0a2db40000000049454e44ae426082" +) + + +class NullBackend: + name = "null" + + def capture(self) -> bytes: + return _BLACK_1X1_PNG + + def close(self) -> None: + pass + + +# ---------- Factory -------------------------------------------------------- + + +def _resolve_device(role: str | None) -> str | None: + if role: + specific = os.environ.get(f"MESHTASTIC_UI_CAMERA_DEVICE_{role.upper()}") + if specific: + return specific + return os.environ.get("MESHTASTIC_UI_CAMERA_DEVICE") + + +def get_camera(role: str | None = None) -> CameraBackend: + """Return a CameraBackend for the given device role (e.g. `"esp32s3"`). + + Falls back to `NullBackend` if no camera is configured or the selected + backend fails to init — tests should treat captures as best-effort + evidence, not a blocker. + """ + backend = os.environ.get("MESHTASTIC_UI_CAMERA_BACKEND", "auto").lower() + device = _resolve_device(role) + + if backend in ("null", "none") or device is None: + return NullBackend() + + if backend == "auto": + # Prefer opencv if importable; fall back to ffmpeg; else null. + try: + import cv2 # type: ignore[import-untyped] # noqa: F401,PLC0415 + + backend = "opencv" + except ImportError: + backend = "ffmpeg" if shutil.which("ffmpeg") else "null" + + if backend == "opencv": + try: + return OpenCVBackend(device) + except CameraError as exc: + warnings.warn( + f"camera backend {backend!r} failed to initialize for device " + f"{device!r}: {exc}; falling back to null backend", + RuntimeWarning, + stacklevel=2, + ) + return NullBackend() + if backend == "ffmpeg": + try: + return FfmpegBackend(device) + except CameraError as exc: + warnings.warn( + f"camera backend {backend!r} failed to initialize for device " + f"{device!r}: {exc}; falling back to null backend", + RuntimeWarning, + stacklevel=2, + ) + return NullBackend() + if backend == "null": + return NullBackend() + + raise CameraError(f"unknown MESHTASTIC_UI_CAMERA_BACKEND: {backend!r}") + + +def save_capture(png_bytes: bytes, path: Path) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(png_bytes) + + +def capture_to_file(role: str | None, path: Path) -> dict[str, object]: + """One-shot: open camera, capture, write PNG, close. Returns metadata.""" + started = time.monotonic() + cam = get_camera(role) + try: + data = cam.capture() + finally: + cam.close() + save_capture(data, path) + return { + "backend": cam.name, + "path": str(path), + "bytes": len(data), + "elapsed_s": round(time.monotonic() - started, 3), + } + + +def _is_png(data: bytes) -> bool: + return data.startswith(b"\x89PNG\r\n\x1a\n") + + +# Exposed so callers can sanity-check a capture without a full PIL import. +__all__ = [ + "CameraBackend", + "CameraError", + "FfmpegBackend", + "NullBackend", + "OpenCVBackend", + "capture_to_file", + "get_camera", + "save_capture", +] + +# Keep `io` import used (pyflakes is picky) via a small guard used at import +# time to normalize stdin/stdout if a subclass ever needs it. +_ = io.BytesIO # noqa: SLF001 diff --git a/mcp-server/src/meshtastic_mcp/cli/_uicap.py b/mcp-server/src/meshtastic_mcp/cli/_uicap.py new file mode 100644 index 000000000..448459954 --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/cli/_uicap.py @@ -0,0 +1,83 @@ +"""UI-capture transcript tailer for ``meshtastic-mcp-test-tui``. + +Watches ``tests/ui_captures//`` for new transcript lines +(one per ``frame_capture()`` call from the UI tier) and posts them to +the TUI. Enabled by ``MESHTASTIC_UI_TUI_CAMERA=1``. + +Design mirrors ``_flashlog.py``: +- Daemon thread, cooperative stop via ``threading.Event``. +- Tolerates the captures directory not existing yet (UI tier hasn't run). +- Per-file seek state so we only forward genuinely-new lines. +""" + +from __future__ import annotations + +import pathlib +import threading +import time +from typing import Callable + + +class UiCaptureTailer(threading.Thread): + """Recursively watch a captures root for new `transcript.md` lines. + + Invokes ``post(test_id, line)`` for each new line, where ``test_id`` + is derived from the path — the sanitized nodeid directory name. + """ + + def __init__( + self, + root: pathlib.Path, + post: Callable[[str, str], None], + stop: threading.Event, + *, + poll_interval: float = 0.5, + ) -> None: + super().__init__(daemon=True, name="uicap-tail") + self._root = root + self._post = post + self._stop = stop + self._poll_interval = poll_interval + # path → byte offset we've already read through + self._offsets: dict[pathlib.Path, int] = {} + + def run(self) -> None: + while not self._stop.is_set(): + try: + self._scan_once() + except Exception: + # Best-effort tailer — never bring down the TUI because a + # directory vanished mid-scan. + pass + time.sleep(self._poll_interval) + + def _scan_once(self) -> None: + if not self._root.is_dir(): + return + for transcript in self._root.rglob("transcript.md"): + test_id = transcript.parent.name + offset = self._offsets.get(transcript, 0) + try: + size = transcript.stat().st_size + except OSError: + continue + if size < offset: + # File truncated / rewritten — reset and re-emit. + offset = 0 + if size == offset: + continue + try: + with transcript.open("rb") as fh: + fh.seek(offset) + chunk = fh.read(size - offset).decode("utf-8", errors="replace") + except OSError: + continue + for line in chunk.splitlines(): + line = line.rstrip() + if not line or line.startswith("#"): + continue + try: + self._post(test_id, line) + except Exception: + return + self._offsets[transcript] = size diff --git a/mcp-server/src/meshtastic_mcp/cli/test_tui.py b/mcp-server/src/meshtastic_mcp/cli/test_tui.py index 33201101b..7f3a2da36 100644 --- a/mcp-server/src/meshtastic_mcp/cli/test_tui.py +++ b/mcp-server/src/meshtastic_mcp/cli/test_tui.py @@ -518,6 +518,7 @@ def _build_app( from . import _fwlog as _fwlog_mod from . import _history as _history_mod from . import _reproducer as _reproducer_mod + from . import _uicap as _uicap_mod # ---------------- Messages ---------------- @@ -548,6 +549,16 @@ def _build_app( self.line = line super().__init__() + class UiCaptureLine(tx.Message): + """Live line from the UI-tier camera transcript — one per + `frame_capture()` call. Posted only when the camera panel is + enabled via `MESHTASTIC_UI_TUI_CAMERA=1`.""" + + def __init__(self, test_id: str, line: str) -> None: + self.test_id = test_id + self.line = line + super().__init__() + class DeviceSnapshot(tx.Message): def __init__(self, rows: list[DeviceRow]) -> None: self.rows = rows @@ -871,6 +882,10 @@ def _build_app( #pytest-pane { height: 50%; border-bottom: solid $primary-background; } #fwlog-header { height: 1; padding: 0 1; background: $panel; } #fwlog-pane { height: 1fr; } + #uicap-header { height: 1; padding: 0 1; background: $boost; } + #uicap-pane { height: 14; border-top: solid $primary-background; } + #uicap-image { width: 36; border-right: solid $primary-background; padding: 0 1; } + #uicap-log { width: 1fr; height: 14; } Tree { height: 100%; } RichLog { height: 100%; } #device-table { height: auto; max-height: 6; } @@ -912,6 +927,11 @@ def _build_app( self._device_worker: DevicePollerWorker | None = None self._fwlog_worker: _fwlog_mod.FirmwareLogTailer | None = None self._flashlog_worker: _flashlog_mod.FlashLogTailer | None = None + self._uicap_worker: _uicap_mod.UiCaptureTailer | None = None + # Env-gated; only mounts the UI-capture panel when operator asks for it. + self._ui_camera_enabled = bool( + int(os.environ.get("MESHTASTIC_UI_TUI_CAMERA", "0") or "0") + ) self._tree_filter: str = "" self._sigint_count = 0 # Firmware-log port filter: None = all, else exact port match. @@ -959,6 +979,22 @@ def _build_app( wrap=True, max_lines=5000, ) + if self._ui_camera_enabled: + yield tx.Static( + "UI camera — latest capture + transcript (MESHTASTIC_UI_TUI_CAMERA=1)", + id="uicap-header", + ) + with tx.Horizontal(id="uicap-pane"): + yield tx.Static( + "(waiting…)", id="uicap-image", markup=False + ) + yield tx.RichLog( + id="uicap-log", + highlight=False, + markup=False, + wrap=True, + max_lines=500, + ) yield tx.DataTable(id="device-table", show_cursor=False) yield tx.Footer() @@ -1023,6 +1059,21 @@ def _build_app( stop=self._stop, ) self._flashlog_worker.start() + # UI-capture transcript tailer — only runs when the camera panel + # is enabled. Watches tests/ui_captures/**/transcript.md for new + # lines as UI tests execute. + if self._ui_camera_enabled: + captures_root = self._root / "mcp-server" / "tests" / "ui_captures" + # When the TUI is launched from inside mcp-server (the usual + # case), `self._root` is already mcp-server/, so adjust: + if not captures_root.parent.name == "mcp-server": + captures_root = self._root / "tests" / "ui_captures" + self._uicap_worker = _uicap_mod.UiCaptureTailer( + root=captures_root, + post=lambda tid, line: self.post_message(UiCaptureLine(tid, line)), + stop=self._stop, + ) + self._uicap_worker.start() self._spawn_pytest(self._pytest_args) # Header tick (seed / runtime / sparkline re-renders at 1 Hz). # Also refreshes the device-status column so the per-test elapsed @@ -1217,6 +1268,84 @@ def _build_app( log = self.query_one("#pytest-log", tx.RichLog) log.write(f"[flash] {message.line}") + def on_ui_capture_line(self, message: Any) -> None: + """Route a UI-capture transcript line into the camera panel. + + Each line is already formatted by frame_capture — e.g. + `1. **initial** — frame 2/8 name=home — OCR: ...`. We write + the text into the RichLog AND try to render the corresponding + PNG on the left side (requires rich-pixels, Pillow). + """ + if not self._ui_camera_enabled: + return + try: + log_panel = self.query_one("#uicap-log", tx.RichLog) + except Exception: + return + log_panel.write(f"[{message.test_id}] {message.line}") + self._render_latest_ui_capture(message.test_id, message.line) + + def _render_latest_ui_capture(self, test_id: str, line: str) -> None: + """Find the PNG that corresponds to `line` and render it on the + left of the uicap pane. Soft-fails if rich-pixels isn't + installed or the PNG isn't found — operator still has the text + transcript on the right. + """ + try: + from PIL import Image # type: ignore[import-untyped] + from rich_pixels import Pixels # type: ignore[import-untyped] + except ImportError: + return + + # Transcript lines look like `1. **label** — ...`. Pull the leading + # integer to locate the capture file. + import re as _re + + m = _re.match(r"\s*(\d+)\.\s", line) + if not m: + return + step = int(m.group(1)) + + # Captures directory is sibling of tests/ — mirror the path the + # tailer watches. Search both likely layouts (in-mcp-server vs. + # firmware-root invocation). + candidates = [ + self._root / "tests" / "ui_captures", + self._root / "mcp-server" / "tests" / "ui_captures", + ] + captures_root = next((p for p in candidates if p.is_dir()), None) + if captures_root is None: + return + + # Drill into // — test_id is the + # sanitized nodeid the tailer already passed through. + matches = list(captures_root.rglob(f"{test_id}/{step:03d}-*.png")) + if not matches: + return + png_path = matches[-1] + + try: + img = Image.open(png_path).convert("RGB") + # Resize to fit ~32 cells wide × ~12 rows tall (half-block + # renderer gives 2× vertical resolution, so 32×24 px input + # lands at ~32×12 cells). Keep aspect ratio. + target_w = 60 + w, h = img.size + target_h = max(1, int(h * (target_w / max(1, w)))) + # Clamp: the image panel is 14 rows; half-blocks give 2 rows + # per vertical cell, so cap pixel height at ~26. + target_h = min(target_h, 26) + img = img.resize((target_w, target_h)) + pixels = Pixels.from_image(img) + except Exception: + return + + try: + image_widget = self.query_one("#uicap-image", tx.Static) + image_widget.update(pixels) + except Exception: + pass + def on_firmware_log_line(self, message: Any) -> None: rec = message.record port = rec.get("port") diff --git a/mcp-server/src/meshtastic_mcp/config.py b/mcp-server/src/meshtastic_mcp/config.py index 7ece10032..d3006a73e 100644 --- a/mcp-server/src/meshtastic_mcp/config.py +++ b/mcp-server/src/meshtastic_mcp/config.py @@ -135,3 +135,14 @@ def picotool_bin() -> Path: ("picotool",), "Install via `brew install picotool` or build from https://github.com/raspberrypi/picotool.", ) + + +def uhubctl_bin() -> Path: + return _hw_tool( + "MESHTASTIC_UHUBCTL_BIN", + ("uhubctl",), + "Install via `brew install uhubctl` (macOS) or `apt install uhubctl` " + "(Debian/Ubuntu). On Linux without the udev rules, or on older macOS " + "with certain hubs, you may need to run via `sudo`: " + "https://github.com/mvp/uhubctl#linux-usb-permissions", + ) diff --git a/mcp-server/src/meshtastic_mcp/input_events.py b/mcp-server/src/meshtastic_mcp/input_events.py new file mode 100644 index 000000000..f6b287ba3 --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/input_events.py @@ -0,0 +1,67 @@ +"""Python mirror of firmware `enum input_broker_event` (src/input/InputBroker.h). + +Used by `admin.send_input_event` + `tests/ui/` so callers can say +`InputEventCode.RIGHT` instead of hard-coding 20. Values MUST stay in sync +with the firmware enum — unit test `tests/unit/test_input_event_codes.py` +pins the mapping. +""" + +from __future__ import annotations + +from enum import IntEnum + + +class InputEventCode(IntEnum): + """Button / key / gesture events dispatched by the firmware InputBroker.""" + + NONE = 0 + SELECT = 10 + SELECT_LONG = 11 + UP_LONG = 12 + DOWN_LONG = 13 + UP = 17 + DOWN = 18 + LEFT = 19 + RIGHT = 20 + CANCEL = 24 + BACK = 27 + # Auto-incremented values in the C enum (27 + 1, +2, +3): + USER_PRESS = 28 + ALT_PRESS = 29 + ALT_LONG = 30 + SHUTDOWN = 0x9B + GPS_TOGGLE = 0x9E + SEND_PING = 0xAF + FN_F1 = 0xF1 + FN_F2 = 0xF2 + FN_F3 = 0xF3 + FN_F4 = 0xF4 + FN_F5 = 0xF5 + MATRIXKEY = 0xFE + ANYKEY = 0xFF + + +def coerce_event_code(value: int | str | InputEventCode) -> int: + """Accept an int, a case-insensitive name, or an `InputEventCode` and return + the u8 wire value. Raises ValueError on unknown names / out-of-range ints. + """ + if isinstance(value, InputEventCode): + return int(value) + if isinstance(value, int): + if not 0 <= value <= 255: + raise ValueError(f"event_code out of u8 range: {value}") + return value + if isinstance(value, str): + key = value.upper().replace("-", "_") + if key.startswith("INPUT_BROKER_"): + key = key[len("INPUT_BROKER_") :] + try: + return int(InputEventCode[key]) + except KeyError as exc: + known = ", ".join(m.name for m in InputEventCode) + raise ValueError( + f"unknown event code name {value!r}; known: {known}" + ) from exc + raise TypeError( + f"event_code must be int|str|InputEventCode, got {type(value).__name__}" + ) diff --git a/mcp-server/src/meshtastic_mcp/ocr.py b/mcp-server/src/meshtastic_mcp/ocr.py new file mode 100644 index 000000000..f40bc3cbd --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/ocr.py @@ -0,0 +1,147 @@ +"""OCR wrapper for UI tests + the `capture_screen` tool. + +Auto-selects a reader in priority order: + 1. `easyocr` (deep-learning, high quality on OLED screens — but ~100 MB + model download on first use). + 2. `pytesseract` (requires system `tesseract` binary on PATH). + 3. `null` — returns `""` with a warning. Tests fall back to log + image + evidence when OCR is unavailable. + +Override via `MESHTASTIC_UI_OCR_BACKEND=easyocr|pytesseract|null|auto` +(default `auto`). + +`ocr_text(png_bytes) -> str` is the only public entry point. The reader is +constructed lazily on first call and cached, so the easyocr cold-start cost +only hits once per process. +""" + +from __future__ import annotations + +import functools +import logging +import os +import shutil +import sys +from typing import Callable + +log = logging.getLogger(__name__) + + +def _backend_choice() -> str: + return os.environ.get("MESHTASTIC_UI_OCR_BACKEND", "auto").lower() + + +@functools.lru_cache(maxsize=1) +def _reader() -> tuple[str, Callable[[bytes], str]]: + """Return `(backend_name, callable)` for whichever OCR is available.""" + choice = _backend_choice() + + def _easyocr() -> tuple[str, Callable[[bytes], str]]: + import easyocr # type: ignore[import-untyped] # noqa: PLC0415 + import numpy as np # type: ignore[import-untyped] # noqa: PLC0415 + + reader = easyocr.Reader(["en"], gpu=False, verbose=False) + + def _run(png: bytes) -> str: + try: + import cv2 # type: ignore[import-untyped] # noqa: PLC0415 + + arr = np.frombuffer(png, dtype=np.uint8) + img = cv2.imdecode(arr, cv2.IMREAD_COLOR) + except ImportError: + # Fall back to PIL if cv2 isn't around. + from io import BytesIO # noqa: PLC0415 + + from PIL import Image # type: ignore[import-untyped] # noqa: PLC0415 + + img = np.array(Image.open(BytesIO(png)).convert("RGB")) + try: + results = reader.readtext(img, detail=0, paragraph=True) + except Exception as exc: # noqa: BLE001 + log.warning("easyocr failed: %s", exc) + return "" + return "\n".join(str(r) for r in results) + + return "easyocr", _run + + def _pytesseract() -> tuple[str, Callable[[bytes], str]]: + from io import BytesIO # noqa: PLC0415 + + import pytesseract # type: ignore[import-untyped] # noqa: PLC0415 + from PIL import Image # type: ignore[import-untyped] # noqa: PLC0415 + + if shutil.which("tesseract") is None: + raise ImportError("`tesseract` binary not on PATH") + + def _run(png: bytes) -> str: + try: + return str(pytesseract.image_to_string(Image.open(BytesIO(png)))) + except Exception as exc: # noqa: BLE001 + log.warning("pytesseract failed: %s", exc) + return "" + + return "pytesseract", _run + + def _null() -> tuple[str, Callable[[bytes], str]]: + log.warning( + "OCR backend is null; install easyocr or tesseract for text extraction" + ) + return "null", lambda _png: "" + + if choice == "easyocr": + return _easyocr() + if choice == "pytesseract": + return _pytesseract() + if choice == "null": + return _null() + if choice != "auto": + print( + f"[ocr] unknown MESHTASTIC_UI_OCR_BACKEND={choice!r}; falling back to auto", + file=sys.stderr, + ) + + # auto mode + try: + return _easyocr() + except ImportError: + pass + try: + return _pytesseract() + except ImportError: + pass + return _null() + + +def ocr_text(png_bytes: bytes) -> str: + """Run OCR on a PNG-encoded image and return the decoded text (possibly empty).""" + if not png_bytes: + return "" + _, run = _reader() + return run(png_bytes) + + +def backend_name() -> str: + """Return the currently-selected backend name, initializing if necessary.""" + name, _ = _reader() + return name + + +def warm() -> None: + """Run one dummy inference so the easyocr cold-start cost is paid upfront. + + Pytest session fixture calls this once so the first real capture doesn't + eat the model-load latency. + """ + # A 64×32 white PNG — decodes clean, no text to extract. + white_png = bytes.fromhex( + "89504e470d0a1a0a0000000d49484452000000400000002008060000007ccac28e" + "0000001c49444154785eedc1010d000000c2a0f74f6d0d370000000000000080" + "0b010000ffff030000000000000049454e44ae426082" + ) + try: + ocr_text(white_png) + except Exception as exc: # noqa: BLE001 + log.warning("ocr.warm() failed: %s", exc) + + +__all__ = ["backend_name", "ocr_text", "warm"] diff --git a/mcp-server/src/meshtastic_mcp/server.py b/mcp-server/src/meshtastic_mcp/server.py index 7cb8db65e..83aa80c45 100644 --- a/mcp-server/src/meshtastic_mcp/server.py +++ b/mcp-server/src/meshtastic_mcp/server.py @@ -1,4 +1,4 @@ -"""FastMCP server wiring — 38 tools across 7 categories. +"""FastMCP server wiring — 43 tools across 9 categories (adds uhubctl power control). Each tool handler is a thin delegation to a named module (pio.py, admin.py, etc.). Business logic does not live here. @@ -513,6 +513,152 @@ def factory_reset( return admin.factory_reset(port=port, confirm=confirm, full=full) +@app.tool() +def send_input_event( + event_code: int | str, + kb_char: int = 0, + touch_x: int = 0, + touch_y: int = 0, + port: str | None = None, +) -> dict[str, Any]: + """Inject an InputBroker event (button / key / gesture) into the device UI. + + Drives the same code path as a physical button press. Accepts a numeric + event code (0..255) or a name like `"RIGHT"`, `"SELECT"`, `"FN_F1"`. + + Common codes: SELECT=10, UP=17, DOWN=18, LEFT=19, RIGHT=20, CANCEL=24, + BACK=27, FN_F1..F5=241..245. + """ + return admin.send_input_event( + event_code=event_code, + kb_char=kb_char, + touch_x=touch_x, + touch_y=touch_y, + port=port, + ) + + +@app.tool() +def capture_screen(role: str | None = None, ocr: bool = True) -> dict[str, Any]: + """Grab a frame from the USB webcam pointed at the device screen. + + Returns PNG bytes (base64), optional OCR text, and backend metadata. + Requires the `[ui]` extras (opencv-python-headless) and a camera + configured via `MESHTASTIC_UI_CAMERA_DEVICE[_]`. Falls back to a + 1×1 black PNG from the null backend when no camera is configured. + """ + import base64 + + from . import camera as camera_mod + + cam = camera_mod.get_camera(role) + try: + png = cam.capture() + finally: + cam.close() + + result: dict[str, Any] = { + "backend": cam.name, + "bytes": len(png), + "image_base64": base64.b64encode(png).decode("ascii"), + } + if ocr: + from . import ocr as ocr_mod + + result["ocr_backend"] = ocr_mod.backend_name() + result["ocr_text"] = ocr_mod.ocr_text(png) + return result + + +# ---------- USB power control (uhubctl) ----------------------------------- + + +@app.tool() +def uhubctl_list() -> list[dict[str, Any]]: + """List every USB hub + per-port device attachment as seen by `uhubctl`. + + Read-only — no confirm required. Each hub entry includes its location + (`1-1.3`), descriptor, whether it supports Per-Port Power Switching, + and a list of populated ports with VID:PID of attached devices. + Useful for pre-flight checks before a destructive power-cycle call. + """ + from . import uhubctl as uhubctl_mod + + return uhubctl_mod.list_hubs() + + +@app.tool() +def uhubctl_power( + action: str, + location: str | None = None, + port: int | None = None, + role: str | None = None, + confirm: bool = False, +) -> dict[str, Any]: + """Power a USB hub port on or off via `uhubctl -a on|off`. + + Target the port by either (`location`, `port`) — raw uhubctl syntax, + e.g. `location="1-1.3", port=2` — OR by `role` ("nrf52", "esp32s3"). + Role lookup honors `MESHTASTIC_UHUBCTL_LOCATION_` + + `_PORT_` env vars first, falls back to VID auto-detection. + + `action="off"` requires `confirm=True` (destructive — the attached + device will immediately disappear from the OS). + """ + from . import uhubctl as uhubctl_mod + + action_lower = action.lower() + if action_lower not in {"on", "off"}: + raise ValueError(f"action must be 'on' or 'off', got {action!r}") + if action_lower == "off" and not confirm: + raise uhubctl_mod.UhubctlError( + "uhubctl_power action='off' requires confirm=True" + ) + loc, p = _resolve_uhubctl_target(location, port, role) + if action_lower == "on": + return uhubctl_mod.power_on(loc, p) + return uhubctl_mod.power_off(loc, p) + + +@app.tool() +def uhubctl_cycle( + location: str | None = None, + port: int | None = None, + role: str | None = None, + delay_s: int = 2, + confirm: bool = False, +) -> dict[str, Any]: + """Power a USB hub port off, wait `delay_s` seconds, then on. + + The typical hard-reset sequence — shorter than off+on as two RPCs + because uhubctl handles the timing in-process. Target by (location, + port) or by role (see `uhubctl_power`). Requires `confirm=True`. + """ + from . import uhubctl as uhubctl_mod + + if not confirm: + raise uhubctl_mod.UhubctlError("uhubctl_cycle requires confirm=True") + if delay_s < 0 or delay_s > 60: + raise ValueError(f"delay_s must be 0..60, got {delay_s}") + loc, p = _resolve_uhubctl_target(location, port, role) + return uhubctl_mod.cycle(loc, p, delay_s=delay_s) + + +def _resolve_uhubctl_target( + location: str | None, port: int | None, role: str | None +) -> tuple[str, int]: + """Shared arg-resolution for uhubctl_power + uhubctl_cycle.""" + from . import uhubctl as uhubctl_mod + + if role is not None: + if location is not None or port is not None: + raise ValueError("pass either `role` OR (`location` + `port`), not both") + return uhubctl_mod.resolve_target(role) + if location is None or port is None: + raise ValueError("must pass `role` or both `location` and `port`") + return (location, int(port)) + + # ---------- Direct hardware tools ----------------------------------------- diff --git a/mcp-server/src/meshtastic_mcp/uhubctl.py b/mcp-server/src/meshtastic_mcp/uhubctl.py new file mode 100644 index 000000000..e0306386b --- /dev/null +++ b/mcp-server/src/meshtastic_mcp/uhubctl.py @@ -0,0 +1,321 @@ +"""USB hub power control via `uhubctl` — hard-recovery for wedged devices + +deliberate offline-peer simulation for mesh tests. + +Why: when a Meshtastic device's serial port wedges (stuck in a boot loop, +frozen USB CDC, crashed firmware that didn't reboot), the only recovery is +a physical unplug. uhubctl toggles VBUS per-port on any hub with Per-Port +Power Switching (PPPS) support — which is most externally-powered hubs +from the last ~5 years — so the harness can power-cycle a device +programmatically. + +Architecture: +- `list_hubs()` parses `uhubctl` default output into structured records. +- `find_port_for_vid(vid)` walks the hubs to find which location+port + hosts a given USB VID. +- `resolve_target(role)` is the public entry for callers that know a role + (`nrf52`, `esp32s3`) but not a hub location: env-var pins win, VID + auto-detect falls back. +- `power_on`, `power_off`, `cycle` wrap the corresponding `uhubctl -a` + invocations, routed through `hw_tools._run` so they share tee-to-flash- + log + timeout handling with esptool / nrfutil / picotool. + +Sudo policy: **fail fast**. Modern macOS + most PPPS-capable hubs work +without root, but Linux without udev rules (or old macOS with specific +driver quirks) still needs it. We run uhubctl non-root; if stderr +matches the classic permission pattern we raise `UhubctlError` with an +install hint pointing at the uhubctl docs. Auto-wrapping with `sudo` +would prompt in the middle of test runs — bad for CI. +""" + +from __future__ import annotations + +import os +import re +from typing import Any, Sequence + +from . import config, hw_tools + +# ---------- Parser --------------------------------------------------------- + +# Hub descriptor line: +# Current status for hub 1-1.3 [2109:2817 VIA Labs, Inc. USB2.0 Hub, USB 2.10, 4 ports, ppps] +_HUB_RE = re.compile( + r"^Current status for hub (?P\S+)\s+\[(?P.+)\]\s*$" +) + +# Port line: +# " Port 2: 0103 power enable connect [239a:8029 RAKwireless ...]" +# The bracketed section is absent for empty ports. +_PORT_RE = re.compile( + r"^\s+Port\s+(?P\d+):\s+(?P\S+)\s+(?P.*?)" + r"(?:\s+\[(?P[0-9a-fA-F]{4}):(?P[0-9a-fA-F]{4})(?:\s+(?P.+))?\])?\s*$" +) + + +class UhubctlError(RuntimeError): + """Raised on uhubctl-specific failures: parse errors, permission denied, + hub-not-found, or PPPS not supported.""" + + +# ---------- Role → VID map ------------------------------------------------- + +# Mirrors the default hub_profile in `mcp-server/tests/conftest.py:335`. +# Note: esp32s3 and esp32s3_alt share a logical role — we search both. +ROLE_VIDS: dict[str, tuple[int, ...]] = { + "nrf52": (0x239A,), + "esp32s3": (0x303A, 0x10C4), +} + + +def _normalize_role(role: str) -> str: + """Collapse `esp32s3_alt` → `esp32s3` to match the tier conventions.""" + return role.split("_alt", 1)[0].lower() + + +# ---------- Core subprocess runner ----------------------------------------- + + +# If uhubctl hits a permission problem — most commonly Linux without the +# udev rules, or a macOS variant where the kernel holds the hub driver — +# it prints something like "Permission denied. Try running as root". +# Linux error text varies; we match a broad substring rather than exact. +_PERM_ERROR_PATTERNS = ( + "permission denied", + "operation not permitted", + "try running as root", + "need root", + "requires root", +) + + +def _run_uhubctl(args: Sequence[str], *, timeout: float = 30.0) -> dict[str, Any]: + """Invoke uhubctl with the given args. Returns `hw_tools._run`'s dict. + + Translates permission-denied failures into a `UhubctlError` with the + install hint, so callers don't have to match stderr themselves. Other + non-zero exits are returned as-is for the caller to interpret. + """ + binary = config.uhubctl_bin() + result = hw_tools._run(binary, args, timeout=timeout) # noqa: SLF001 + if result["exit_code"] != 0: + combined = (result.get("stderr") or "") + "\n" + (result.get("stdout") or "") + lower = combined.lower() + if any(pat in lower for pat in _PERM_ERROR_PATTERNS): + raise UhubctlError( + "uhubctl exited with a permission error. Install the udev " + "rules on Linux, or try `sudo` as a fallback: " + "https://github.com/mvp/uhubctl#linux-usb-permissions\n" + f"stderr: {result.get('stderr_tail')!r}" + ) + return result + + +# ---------- List / parse --------------------------------------------------- + + +def parse_list_output(output: str) -> list[dict[str, Any]]: + """Parse the default `uhubctl` stdout into structured hubs. + + Each hub: { + "location": "1-1.3", + "descriptor": "2109:2817 VIA Labs ...", + "vid": 0x2109, + "pid": 0x2817, + "ppps": bool, + "ports": [{"port": int, "status": str, "flags": str, + "device_vid": int | None, "device_pid": int | None, + "device_desc": str | None}, ...], + } + """ + hubs: list[dict[str, Any]] = [] + current: dict[str, Any] | None = None + + for line in output.splitlines(): + hm = _HUB_RE.match(line) + if hm: + descriptor = hm.group("descriptor") + hub_vid, hub_pid = None, None + vid_match = re.match(r"([0-9a-fA-F]{4}):([0-9a-fA-F]{4})", descriptor) + if vid_match: + hub_vid = int(vid_match.group(1), 16) + hub_pid = int(vid_match.group(2), 16) + current = { + "location": hm.group("location"), + "descriptor": descriptor, + "vid": hub_vid, + "pid": hub_pid, + "ppps": ", ppps" in descriptor or descriptor.endswith("ppps"), + "ports": [], + } + hubs.append(current) + continue + + pm = _PORT_RE.match(line) + if pm and current is not None: + device_vid = pm.group("device_vid") + device_pid = pm.group("device_pid") + current["ports"].append( + { + "port": int(pm.group("port")), + "status": pm.group("status"), + "flags": (pm.group("flags") or "").strip(), + "device_vid": int(device_vid, 16) if device_vid else None, + "device_pid": int(device_pid, 16) if device_pid else None, + "device_desc": (pm.group("device_desc") or "").strip() or None, + } + ) + return hubs + + +def list_hubs() -> list[dict[str, Any]]: + """Enumerate every hub uhubctl can see, with per-port device attachments. + + Pure read — no power state changes. Useful as a pre-flight check before + a destructive `power_off` call. + """ + result = _run_uhubctl([], timeout=15.0) + if result["exit_code"] != 0: + raise UhubctlError( + f"uhubctl list failed (exit {result['exit_code']}): {result.get('stderr_tail')!r}" + ) + return parse_list_output(result["stdout"]) + + +# ---------- Lookup / resolution ------------------------------------------- + + +def find_port_for_vid( + vid: int, pid: int | None = None, *, only_ppps: bool = True +) -> list[tuple[str, int]]: + """Return ALL (location, port) matches for a device VID (optionally +PID). + + `only_ppps=True` filters out hubs that don't advertise PPPS — we can't + control them anyway. Callers that want to diagnose a missing device can + pass `only_ppps=False` to see if the device is on a non-controllable + hub (and raise a clearer error). + """ + hubs = list_hubs() + matches: list[tuple[str, int]] = [] + for hub in hubs: + if only_ppps and not hub["ppps"]: + continue + for port in hub["ports"]: + if port["device_vid"] != vid: + continue + if pid is not None and port["device_pid"] != pid: + continue + matches.append((hub["location"], port["port"])) + return matches + + +def resolve_target(role: str) -> tuple[str, int]: + """Resolve a Meshtastic role to (hub_location, port_number). + + Priority: + 1. Env vars `MESHTASTIC_UHUBCTL_LOCATION_` + `_PORT_` + (e.g. `MESHTASTIC_UHUBCTL_LOCATION_NRF52=1-1.3`, `_PORT_NRF52=2`). + 2. VID auto-detect against `ROLE_VIDS[role]`, taking the first PPPS + match. + + Raises `UhubctlError` on ambiguity (multiple matches) or no-match. The + env-var path exists specifically to disambiguate when two devices share + a VID. + """ + role = _normalize_role(role) + env_key_loc = f"MESHTASTIC_UHUBCTL_LOCATION_{role.upper()}" + env_key_port = f"MESHTASTIC_UHUBCTL_PORT_{role.upper()}" + loc = os.environ.get(env_key_loc) + port_str = os.environ.get(env_key_port) + if loc and port_str: + try: + return (loc, int(port_str)) + except ValueError as exc: + raise UhubctlError( + f"{env_key_port}={port_str!r} is not a valid integer" + ) from exc + + if role not in ROLE_VIDS: + raise UhubctlError( + f"unknown role {role!r}; known roles: {sorted(ROLE_VIDS)}. " + f"Set {env_key_loc} + {env_key_port} to pin manually." + ) + + matches: list[tuple[str, int]] = [] + for vid in ROLE_VIDS[role]: + matches.extend(find_port_for_vid(vid)) + + if not matches: + vids = ", ".join(f"0x{v:04x}" for v in ROLE_VIDS[role]) + raise UhubctlError( + f"no controllable hub hosts a device with VID in {{{vids}}} " + f"for role={role!r}. Check the device is plugged into a " + f"PPPS-capable hub, or pin manually via {env_key_loc} + {env_key_port}." + ) + if len(matches) > 1: + shown = ", ".join(f"{loc}:port{p}" for loc, p in matches) + raise UhubctlError( + f"ambiguous: multiple devices match role={role!r} ({shown}). " + f"Pin the target via {env_key_loc} + {env_key_port}." + ) + return matches[0] + + +# ---------- Power actions -------------------------------------------------- + + +def _action( + action: str, + location: str, + port: int, + *, + delay_s: int | None = None, + timeout: float = 30.0, +) -> dict[str, Any]: + args: list[str] = ["-a", action, "-l", location, "-p", str(port)] + if delay_s is not None: + args.extend(["-d", str(delay_s)]) + # Suppress verbose "before" printout so our parser doesn't have to skip it. + args.append("-N") + result = _run_uhubctl(args, timeout=timeout) + if result["exit_code"] != 0: + raise UhubctlError( + f"uhubctl -a {action} -l {location} -p {port} failed " + f"(exit {result['exit_code']}): {result.get('stderr_tail')!r}" + ) + return { + "action": action, + "location": location, + "port": port, + "delay_s": delay_s, + "duration_s": result["duration_s"], + } + + +def power_on(location: str, port: int) -> dict[str, Any]: + """Drive the port VBUS high. Device re-enumerates in 1-3 s on healthy hubs.""" + return _action("on", location, port) + + +def power_off(location: str, port: int) -> dict[str, Any]: + """Drive the port VBUS low. Device disappears from `list_devices` immediately.""" + return _action("off", location, port) + + +def cycle(location: str, port: int, delay_s: int = 2) -> dict[str, Any]: + """Off → wait `delay_s` → on. The common hard-reset pattern.""" + # uhubctl's own `-a cycle` handles the delay internally; we use a + # slightly longer timeout to accommodate delay_s + enumeration. + return _action("cycle", location, port, delay_s=delay_s, timeout=30.0 + delay_s * 2) + + +__all__ = [ + "ROLE_VIDS", + "UhubctlError", + "cycle", + "find_port_for_vid", + "list_hubs", + "parse_list_output", + "power_off", + "power_on", + "resolve_target", +] diff --git a/mcp-server/src/meshtastic_mcp/userprefs.py b/mcp-server/src/meshtastic_mcp/userprefs.py index 59d7165f9..d5f8bab69 100644 --- a/mcp-server/src/meshtastic_mcp/userprefs.py +++ b/mcp-server/src/meshtastic_mcp/userprefs.py @@ -393,6 +393,7 @@ def build_testing_profile( long_name: str | None = None, disable_mqtt: bool = True, disable_position: bool = False, + enable_ui_log: bool = False, ) -> dict[str, Any]: """Build a USERPREFS dict for an isolated test-mesh device. @@ -423,6 +424,10 @@ def build_testing_profile( traffic never leaks to a public broker. disable_position: if True, disables GPS + position broadcasts — useful when test devices sit on a bench without antennas. + enable_ui_log: if True, stamps `USERPREFS_UI_TEST_LOG=true` so the + firmware emits one `Screen: frame N/M name=... reason=...` log + line per frame transition. Test-only; off by default because the + log is chatty (multiple times per second during UI interaction). """ if region not in KNOWN_REGIONS: @@ -475,6 +480,9 @@ def build_testing_profile( prefs["USERPREFS_CONFIG_OWNER_LONG_NAME"] = long_name if short_name is not None: prefs["USERPREFS_CONFIG_OWNER_SHORT_NAME"] = short_name + if enable_ui_log: + # Consumed by `#ifdef USERPREFS_UI_TEST_LOG` in src/graphics/Screen.cpp. + prefs["USERPREFS_UI_TEST_LOG"] = True return prefs diff --git a/mcp-server/tests/_power.py b/mcp-server/tests/_power.py new file mode 100644 index 000000000..0542bbed3 --- /dev/null +++ b/mcp-server/tests/_power.py @@ -0,0 +1,112 @@ +"""USB hub power control for tests — thin composition of the `uhubctl` +module + `_port_discovery.resolve_port_by_role`. + +Why separate from the production module: +- `meshtastic_mcp.uhubctl.cycle` returns as soon as uhubctl exits (VBUS is + back on, but the device hasn't finished enumerating as a CDC port yet). +- Tests that want to immediately issue a `connect(port=...)` need the NEW + `/dev/cu.*` path, which can differ from the pre-cycle path on nRF52 + boards (CDC re-enumeration assigns a fresh `cu.usbmodemNNNN`). +- `resolve_port_by_role` already handles that wait + path-resolution for + the `factory_reset` flow. Composing the two gives a one-call helper. + +Also exposes `is_uhubctl_available()` so fixtures can skip cleanly when +uhubctl isn't installed — we never want "no uhubctl" to look like a test +failure. +""" + +from __future__ import annotations + +import time +from typing import Any + +from meshtastic_mcp import config as config_mod +from meshtastic_mcp import uhubctl as uhubctl_mod + +from ._port_discovery import resolve_port_by_role + + +def is_uhubctl_available() -> bool: + """Return True iff `config.uhubctl_bin()` resolves AND the binary is callable. + + Soft-fails silently — fixtures use this to `pytest.skip` with an + actionable message when the operator hasn't installed uhubctl. + """ + try: + config_mod.uhubctl_bin() + except Exception: # noqa: BLE001 + return False + # Do NOT actually invoke uhubctl here — on macOS a non-sudo run would + # fail, which is a config issue, not a tool-missing issue. That gets + # surfaced to the user when they actually run a recovery action. + return True + + +def power_on(role: str) -> dict[str, Any]: + """Power on the hub port hosting `role`. Does NOT wait for re-enumeration. + Use `power_cycle` or follow with `resolve_port_by_role` to block on readiness. + """ + loc, port = uhubctl_mod.resolve_target(role) + return uhubctl_mod.power_on(loc, port) + + +def power_off(role: str) -> dict[str, Any]: + """Power off the hub port hosting `role`. The device disappears from + `list_devices` immediately. + """ + loc, port = uhubctl_mod.resolve_target(role) + return uhubctl_mod.power_off(loc, port) + + +def power_cycle( + role: str, + *, + delay_s: int = 2, + rediscover_timeout_s: float = 30.0, +) -> str: + """Cycle the port hosting `role`, wait for re-enumeration, return the + new port path. + + On nRF52 the post-cycle path typically matches the pre-cycle path, but + macOS may assign a different `/dev/cu.usbmodemNNNN` if the previous + CDC endpoint hasn't been fully released. `resolve_port_by_role` + handles that transparently. + """ + loc, port = uhubctl_mod.resolve_target(role) + uhubctl_mod.cycle(loc, port, delay_s=delay_s) + # After uhubctl exits, VBUS is on but the device may still be in + # bootloader init. Give it ~500 ms head-start before polling so we + # don't spam list_devices pointlessly. + time.sleep(0.5) + return resolve_port_by_role(role, timeout_s=rediscover_timeout_s) + + +def wait_for_absence(role: str, *, timeout_s: float = 10.0) -> None: + """Block until a device matching `role` is NOT in `list_devices`. + + Used by the recovery tier to assert power_off actually took effect. + Raises TimeoutError on failure. + """ + from meshtastic_mcp import devices as devices_mod + + from ._port_discovery import _ROLE_VIDS, _coerce_vid # type: ignore[attr-defined] + + if role not in _ROLE_VIDS: + raise ValueError(f"unknown role {role!r}") + wanted = _ROLE_VIDS[role] + deadline = time.monotonic() + timeout_s + while time.monotonic() < deadline: + found = devices_mod.list_devices(include_unknown=True) + if not any(_coerce_vid(d.get("vid")) in wanted for d in found): + return + time.sleep(0.3) + raise TimeoutError(f"role {role!r} still visible after {timeout_s}s of power_off") + + +__all__ = [ + "is_uhubctl_available", + "power_cycle", + "power_off", + "power_on", + "wait_for_absence", +] diff --git a/mcp-server/tests/conftest.py b/mcp-server/tests/conftest.py index 3d033b9b8..d4607b239 100644 --- a/mcp-server/tests/conftest.py +++ b/mcp-server/tests/conftest.py @@ -123,15 +123,24 @@ def pytest_collection_modifyitems( return (2, item.nodeid) if "/monitor/" in path or "tests/monitor" in path: return (3, item.nodeid) - if "/fleet/" in path or "tests/fleet" in path: + # Recovery tier: explicitly cycles device power via uhubctl. Slots + # between monitor (read-only) and ui (state-preserving) so any tier + # after it starts from a known re-enumerated + re-verified state. + if "/recovery/" in path or "tests/recovery" in path: return (4, item.nodeid) + # UI tier slots here — read-only w.r.t. mesh state, only mutates + # the on-screen UI (BACK×5 guard restores home before each test). + if "/ui/" in path or "tests/ui" in path: + return (5, item.nodeid) + if "/fleet/" in path or "tests/fleet" in path: + return (6, item.nodeid) # State-mutating tiers run last. if "/admin/" in path or "tests/admin" in path: - return (5, item.nodeid) + return (7, item.nodeid) if "/provisioning/" in path or "tests/provisioning" in path: - return (6, item.nodeid) + return (8, item.nodeid) # Top-level + anything else falls between. - return (7, item.nodeid) + return (9, item.nodeid) items.sort(key=sort_key) @@ -156,13 +165,20 @@ def session_seed(request: pytest.FixtureRequest) -> str: @pytest.fixture(scope="session") def test_profile(session_seed: str) -> dict[str, Any]: - """The canonical isolated-mesh test profile for this session.""" + """The canonical isolated-mesh test profile for this session. + + `enable_ui_log=True` stamps `USERPREFS_UI_TEST_LOG` so the firmware + emits `Screen: frame N/M name=... reason=...` log lines per UI + transition — consumed by the `tests/ui/` tier. Harmless on boards + without a screen (the `#ifdef` sits behind `HAS_SCREEN`). + """ return userprefs.build_testing_profile( psk_seed=session_seed, channel_name="McpTest", channel_num=88, region="US", modem_preset="LONG_FAST", + enable_ui_log=True, ) @@ -654,6 +670,7 @@ def pytest_generate_tests(metafunc: pytest.Metafunc) -> None: def baked_single( baked_mesh: dict[str, Any], baked_single_role: str, + hub_devices: dict[str, str], ) -> dict[str, Any]: """Function-scoped: a single verified baked device. @@ -662,10 +679,75 @@ def baked_single( (e.g. `test_owner_survives_reboot[nrf52]` + `test_owner_survives_reboot[esp32s3]`). Tests never hardcode a role and never skip a device that happens to be connected. + + Auto-recovery: if the baked device fails a pre-test `device_info` probe + AND uhubctl is available, power-cycle the port once and retry. Without + uhubctl, surface the wedge as a clear skip. This catches "device got + stuck between tests" without masking persistent regressions (a second + wedge after cycling still skips). """ if baked_single_role not in baked_mesh: pytest.skip(f"role {baked_single_role!r} not present on the hub") - return {"role": baked_single_role, **baked_mesh[baked_single_role]} + + entry = baked_mesh[baked_single_role] + port = entry.get("port") + if port: + try: + _run_with_timeout(lambda: info.device_info(port=port, timeout_s=3.0), 5.0) + except Exception: + # Device didn't respond. Try a power-cycle recovery if uhubctl + # is installed; otherwise surface a skip that names the root + # cause clearly. + from tests import _power + + if not _power.is_uhubctl_available(): + pytest.skip( + f"device {baked_single_role!r} unresponsive on {port}; " + "install uhubctl (`brew install uhubctl` / `apt install " + "uhubctl`) for auto power-cycle recovery" + ) + try: + new_port = _power.power_cycle(baked_single_role, delay_s=2) + except Exception as exc: # noqa: BLE001 + pytest.skip( + f"device {baked_single_role!r} wedged and power-cycle " + f"failed: {exc}" + ) + # Mutate both the session-scoped `hub_devices` map AND the + # baked_mesh entry so downstream fixtures see the recovered port. + hub_devices[baked_single_role] = new_port + baked_mesh[baked_single_role]["port"] = new_port + entry = baked_mesh[baked_single_role] + return {"role": baked_single_role, **entry} + + +@pytest.fixture +def power_cycle( + hub_devices: dict[str, str], +) -> Callable[..., str]: + """Return a callable `(role, delay_s=2) -> new_port` that hard-resets the + hub port hosting `role`. Skips the test cleanly when uhubctl isn't + installed — never want "no uhubctl" to look like a test failure. + + The callable mutates `hub_devices[role]` in place so subsequent fixture + lookups pick up the post-cycle port (mirrors the pattern in + provisioning/test_userprefs_survive_factory_reset.py). + """ + from tests import _power + + if not _power.is_uhubctl_available(): + pytest.skip( + "uhubctl not installed; this test needs it for power control. " + "Install via `brew install uhubctl` (macOS) or `apt install " + "uhubctl` (Debian/Ubuntu)." + ) + + def _cycle(role: str, delay_s: int = 2) -> str: + new_port = _power.power_cycle(role, delay_s=delay_s) + hub_devices[role] = new_port + return new_port + + return _cycle _DEFAULT_ROLE_ENVS = { @@ -960,6 +1042,45 @@ def _run_with_timeout(fn: Callable[[], Any], timeout: float) -> Any: raise TimeoutError(f"operation did not complete within {timeout}s") from exc +def _attach_ui_captures(item: pytest.Item, report: Any) -> None: + """Embed per-step UI captures (PNG + OCR) into the pytest-html extras. + + Runs for every UI-tier test on BOTH pass and fail so the HTML report + always shows the image strip + OCR transcript. Silently no-ops if + pytest-html isn't installed or the test didn't use `frame_capture`. + """ + captures = getattr(item, "_ui_captures", None) + if not captures: + return + try: + from pytest_html import extras as html_extras # type: ignore[import-untyped] + except ImportError: + return + + existing = getattr(report, "extras", None) or [] + extras_list = list(existing) + for cap in captures: + png_path = cap.get("png_path") + label = f"{cap.get('step', '?')}: {cap.get('label', '')}" + frame = cap.get("frame") or {} + frame_str = ( + f" — frame {frame.get('idx')} {frame.get('name')!r}" if frame else "" + ) + if png_path: + try: + with open(png_path, "rb") as fh: + import base64 + + b64 = base64.b64encode(fh.read()).decode("ascii") + extras_list.append(html_extras.png(b64, name=f"{label}{frame_str}")) + except OSError: + pass + ocr = (cap.get("ocr_text") or "").strip() + if ocr: + extras_list.append(html_extras.text(ocr, name=f"OCR: {label}{frame_str}")) + report.extras = extras_list # type: ignore[attr-defined] + + @pytest.hookimpl(hookwrapper=True) def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo[Any]) -> Any: """On test failure, attach serial capture + device state as report artifacts. @@ -967,10 +1088,20 @@ def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo[Any]) -> Hard-bounded by `_run_with_timeout` — if the device is unreachable (stuck port, unbaked firmware, dead board), the dump is skipped rather than hanging the session. + + For UI-tier tests, also embeds per-step camera captures + OCR on every + test (pass or fail) so the HTML report shows visual evidence of what + the device did. """ outcome = yield report = outcome.get_result() + # Attach UI captures on any outcome (pass + fail) — these are the whole + # point of the UI tier. Do this before the failure-only branch below so + # passing tests still get their image strip. + if report.when == "call": + _attach_ui_captures(item, report) + if report.when != "call" or report.outcome != "failed": return diff --git a/mcp-server/tests/mesh/test_peer_offline_recovery.py b/mcp-server/tests/mesh/test_peer_offline_recovery.py new file mode 100644 index 000000000..b8d0f7a63 --- /dev/null +++ b/mcp-server/tests/mesh/test_peer_offline_recovery.py @@ -0,0 +1,155 @@ +"""Isolation test for peer-offline-then-back mid-conversation. + +Verifies the mesh stack's behavior when a peer is physically powered +off mid-send via uhubctl, then powered back on. + +Flow (parametrized over every directed mesh_pair): + 1. Bilateral PKI warmup (same pattern as test_direct_with_ack). + 2. TX sends a broadcast text "msg-1" — RX confirms receipt via pubsub. + 3. Power OFF RX via uhubctl. The RX device disappears from the OS. + 4. TX sends a directed text "msg-2" with wantAck=True. Firmware retries + internally for ~30s before giving up. Assertion: the packet object + was accepted by the TX stack (non-None) — we don't assert an ACK + since there's no peer to send one. + 5. Power ON RX. Wait for re-enumeration + boot. + 6. Bilateral PKI re-nudge — RX's in-RAM PKI cache was wiped on reboot, + so the first directed send may err=35 without a fresh NodeInfo ping. + 7. TX sends a directed "msg-3" — RX receives it via pubsub, confirming + the mesh recovered. + +Skips cleanly if uhubctl isn't installed (via the `power_cycle` fixture's +auto-skip). Skips for pair directions where RX isn't power-controllable +(e.g. a USB-IF hub that doesn't support PPPS for its port). +""" + +from __future__ import annotations + +import time +from typing import Any + +import pytest +from meshtastic_mcp.connection import connect +from tests import _power +from tests._port_discovery import resolve_port_by_role + +from ._receive import ReceiveCollector, nudge_nodeinfo + + +@pytest.mark.timeout(360) +def test_peer_offline_then_recovers( + mesh_pair: dict[str, Any], + power_cycle, # noqa: ARG001 — forces uhubctl-availability skip + hub_devices: dict[str, str], +) -> None: + tx_port = mesh_pair["tx"]["port"] + rx_node_num = mesh_pair["rx"]["my_node_num"] + tx_role = mesh_pair["tx_role"] + rx_role = mesh_pair["rx_role"] + + unique_pre = f"peer-offline-pre-{tx_role}-to-{rx_role}-{int(time.time())}" + unique_post = f"peer-offline-post-{tx_role}-to-{rx_role}-{int(time.time())}" + + # Step 1 + 2: warm up + confirm baseline delivery works before the test. + with ReceiveCollector( + mesh_pair["rx"]["port"], topic="meshtastic.receive.text" + ) as rx: + rx.broadcast_nodeinfo_ping() + with connect(port=tx_port) as tx_iface: + nudge_nodeinfo(tx_iface) + # Wait for bilateral PKI (RX pubkey in TX's nodesByNum). + deadline = time.monotonic() + 45.0 + last_nudge = time.monotonic() + while time.monotonic() < deadline: + rec = (tx_iface.nodesByNum or {}).get(rx_node_num, {}) + if rec.get("user", {}).get("publicKey"): + break + if time.monotonic() - last_nudge > 15.0: + rx.broadcast_nodeinfo_ping() + nudge_nodeinfo(tx_iface) + last_nudge = time.monotonic() + time.sleep(1.0) + else: + pytest.skip( + f"bilateral PKI never completed ({tx_role}→{rx_role}); " + "can't run the offline test without a warm baseline" + ) + + tx_iface.sendText(unique_pre, destinationId=rx_node_num, wantAck=True) + got = rx.wait_for( + lambda pkt: pkt.get("decoded", {}).get("text") == unique_pre, + timeout=30, + ) + assert got is not None, ( + f"baseline directed send ({tx_role}→{rx_role}) didn't land — " + "skipping offline test to avoid false positive" + ) + + # Step 3: power off RX. uhubctl skips the test with a clear message if + # the RX role isn't on a controllable hub. + try: + _power.power_off(rx_role) + except Exception as exc: # noqa: BLE001 + pytest.skip(f"can't power-control {rx_role!r}: {exc}") + + try: + _power.wait_for_absence(rx_role, timeout_s=10.0) + except TimeoutError: + _power.power_on(rx_role) # restore hub state before failing + resolve_port_by_role(rx_role, timeout_s=30.0) + pytest.fail(f"{rx_role!r} didn't disappear after power_off") + + # Step 4: send to a peer that isn't there. Firmware will retry + # internally. We don't wait for an ACK (there won't be one); we just + # confirm TX's stack accepts the packet without crashing. + try: + with connect(port=tx_port) as tx_iface: + packet = tx_iface.sendText( + f"while-offline-{rx_role}", + destinationId=rx_node_num, + wantAck=True, + ) + assert packet is not None + # Give firmware a moment to do a retry or two while RX is down. + time.sleep(5.0) + except Exception as exc: # noqa: BLE001 — TX should survive the peer being gone + # Restore RX before reraising so the bench state is sane. + _power.power_on(rx_role) + resolve_port_by_role(rx_role, timeout_s=30.0) + raise AssertionError(f"TX crashed when sending to offline peer: {exc}") from exc + + # Step 5: power RX back on + rediscover. + _power.power_on(rx_role) + time.sleep(0.5) + new_rx_port = resolve_port_by_role(rx_role, timeout_s=30.0) + hub_devices[rx_role] = new_rx_port + + # Step 6 + 7: bilateral re-warmup + directed send that should now work. + with ReceiveCollector(new_rx_port, topic="meshtastic.receive.text") as rx: + # RX rebooted → its PKI cache is gone. Re-warm. + rx.broadcast_nodeinfo_ping() + with connect(port=tx_port) as tx_iface: + nudge_nodeinfo(tx_iface) + time.sleep(3.0) + + got = None + for _attempt in range(3): + packet = tx_iface.sendText( + unique_post, + destinationId=rx_node_num, + wantAck=True, + ) + assert packet is not None + got = rx.wait_for( + lambda pkt: pkt.get("decoded", {}).get("text") == unique_post, + timeout=30, + ) + if got is not None: + break + rx.broadcast_nodeinfo_ping() + nudge_nodeinfo(tx_iface) + time.sleep(5.0) + + assert got is not None, ( + f"post-recovery directed send {unique_post!r} ({tx_role}→{rx_role}) " + "never landed — recovery path may be broken" + ) diff --git a/mcp-server/tests/recovery/__init__.py b/mcp-server/tests/recovery/__init__.py new file mode 100644 index 000000000..cf8f3919e --- /dev/null +++ b/mcp-server/tests/recovery/__init__.py @@ -0,0 +1,6 @@ +"""Recovery tier — exercises `uhubctl` power control end-to-end. + +Requires `uhubctl` installed AND at least one connected device on a +PPPS-capable hub. The whole tier skips cleanly via +`tests/recovery/conftest.py::_recovery_tier_guard` when either is missing. +""" diff --git a/mcp-server/tests/recovery/conftest.py b/mcp-server/tests/recovery/conftest.py new file mode 100644 index 000000000..21116d07a --- /dev/null +++ b/mcp-server/tests/recovery/conftest.py @@ -0,0 +1,44 @@ +"""Recovery-tier gating + shared helpers. + +Session-scoped guard skips the whole tier when uhubctl isn't installed. +Tests under this directory assume uhubctl is callable AND that at least +one hub role is detected on a PPPS-capable port. +""" + +from __future__ import annotations + +import pytest + + +@pytest.fixture(scope="session", autouse=True) +def _recovery_tier_guard() -> None: + """Skip the tier when uhubctl is unavailable OR no device is on a + PPPS-capable hub. Prints the specific reason so operators know what + to fix.""" + from tests import _power + + if not _power.is_uhubctl_available(): + pytest.skip( + "uhubctl not installed; recovery tier needs it. " + "Install via `brew install uhubctl` or `apt install uhubctl`.", + allow_module_level=True, + ) + + # Probe: can we even list hubs? (A macOS user without sudo gets a + # permission error here — we'd rather find out once at tier-start than + # 6 tests later.) + from meshtastic_mcp import uhubctl + + try: + hubs = uhubctl.list_hubs() + except uhubctl.UhubctlError as exc: + pytest.skip( + f"uhubctl list failed: {exc}. Try the udev rules or `sudo` as a fallback.", + allow_module_level=True, + ) + + if not any(h["ppps"] for h in hubs): + pytest.skip( + "no PPPS-capable hubs detected — recovery tier has nothing to exercise.", + allow_module_level=True, + ) diff --git a/mcp-server/tests/recovery/test_list_hubs.py b/mcp-server/tests/recovery/test_list_hubs.py new file mode 100644 index 000000000..0a09a672a --- /dev/null +++ b/mcp-server/tests/recovery/test_list_hubs.py @@ -0,0 +1,43 @@ +"""Smoke test: `uhubctl_list` returns a well-formed structure. + +No destructive action. Runs first in the tier as a sanity check that the +tier's dependencies (uhubctl binary + permissions) are actually satisfied. +""" + +from __future__ import annotations + +import pytest +from meshtastic_mcp import uhubctl + + +@pytest.mark.timeout(30) +def test_list_hubs_returns_at_least_one_ppps_hub() -> None: + hubs = uhubctl.list_hubs() + assert hubs, "uhubctl found no hubs at all — is a USB hub connected?" + assert any(h["ppps"] for h in hubs), ( + "no PPPS-capable hubs detected; power control won't work. " + "Check that the hub supports Per-Port Power Switching." + ) + + +@pytest.mark.timeout(30) +def test_list_hubs_structure(hub_devices: dict[str, str]) -> None: + hubs = uhubctl.list_hubs() + for hub in hubs: + assert "location" in hub and hub["location"] + assert "ports" in hub and isinstance(hub["ports"], list) + for port in hub["ports"]: + assert "port" in port and isinstance(port["port"], int) + assert "status" in port + + # At least one of the detected Meshtastic roles should show up in some + # port's device_vid — otherwise the recovery tier can't drive them. + seen_vids = { + p["device_vid"] for h in hubs for p in h["ports"] if p["device_vid"] is not None + } + expected_any = {0x239A, 0x303A, 0x10C4} & seen_vids + assert expected_any or not hub_devices, ( + f"hub_devices detected roles {list(hub_devices)} but uhubctl sees " + f"VIDs {sorted(hex(v) for v in seen_vids)} — the devices may be on " + "a hub that uhubctl can't see (e.g. built-in laptop ports)." + ) diff --git a/mcp-server/tests/recovery/test_power_cycle_preserves_userprefs.py b/mcp-server/tests/recovery/test_power_cycle_preserves_userprefs.py new file mode 100644 index 000000000..9558a7fb4 --- /dev/null +++ b/mcp-server/tests/recovery/test_power_cycle_preserves_userprefs.py @@ -0,0 +1,60 @@ +"""Hard reset via uhubctl must NOT wipe NVS. Verify the test profile's +region + channel survive a power-cycle. + +Guards against a regression where a firmware change treats unexpected +power loss as a factory-reset trigger (e.g. bad EEPROM wear-leveling, +erase-on-boot-for-safety). Such a regression would be catastrophic for +field deployments. +""" + +from __future__ import annotations + +import time + +import pytest +from meshtastic_mcp import admin, info +from tests import _power +from tests._port_discovery import resolve_port_by_role + + +@pytest.mark.timeout(180) +def test_lora_config_survives_power_cycle( + baked_single: dict[str, object], + test_profile: dict[str, object], +) -> None: + role = baked_single["role"] + pre_port = baked_single["port"] + + pre_config = admin.get_config(section="lora", port=pre_port)["config"]["lora"] + pre_region = pre_config.get("region") + pre_preset = pre_config.get("modem_preset") + assert pre_region, f"lora.region not set pre-cycle on {role}" + + # Hard power-cycle. + _power.power_cycle(role, delay_s=2) + time.sleep(0.5) + new_port = resolve_port_by_role(role, timeout_s=30.0) + # Let the firmware complete boot before admin reads. + time.sleep(2.0) + # Quick readiness probe. + probe = info.device_info(port=new_port, timeout_s=10.0) + assert ( + probe.get("my_node_num") is not None + ), f"device {role!r} didn't respond after power-cycle" + + post_config = admin.get_config(section="lora", port=new_port)["config"]["lora"] + post_region = post_config.get("region") + post_preset = post_config.get("modem_preset") + + assert post_region == pre_region, ( + f"lora.region wiped by power-cycle on {role}: " + f"pre={pre_region!r} post={post_region!r}" + ) + assert post_preset == pre_preset, ( + f"lora.modem_preset wiped by power-cycle on {role}: " + f"pre={pre_preset!r} post={post_preset!r}" + ) + + # Channel-0 name should also match the test profile. + pri_ch = admin.get_channel_url(port=new_port) + assert pri_ch.get("url"), f"channel URL empty after power-cycle on {role}" diff --git a/mcp-server/tests/recovery/test_power_cycle_roundtrip.py b/mcp-server/tests/recovery/test_power_cycle_roundtrip.py new file mode 100644 index 000000000..37bc7c8d2 --- /dev/null +++ b/mcp-server/tests/recovery/test_power_cycle_roundtrip.py @@ -0,0 +1,61 @@ +"""Full power-cycle round-trip: off → verify gone → on → verify identity +preserved. + +Parametrized over every connected role. Validates both the uhubctl +plumbing AND that the device survives a hard reset with the same +`my_node_num` (no firmware-level identity regeneration). +""" + +from __future__ import annotations + +import time + +import pytest +from meshtastic_mcp import info +from tests import _power +from tests._port_discovery import resolve_port_by_role + + +@pytest.mark.timeout(180) +def test_power_cycle_preserves_node_identity( + baked_single: dict[str, object], +) -> None: + role = baked_single["role"] + pre_port = baked_single["port"] + pre_node_num = baked_single["my_node_num"] + pre_fw = baked_single.get("firmware_version") + + # Record pre-cycle state. + pre_info = info.device_info(port=pre_port, timeout_s=5.0) + assert pre_info.get("my_node_num") == pre_node_num + + # Power off; confirm the device actually disappears from list_devices. + _power.power_off(role) + try: + _power.wait_for_absence(role, timeout_s=10.0) + except TimeoutError: + # If it didn't disappear, power it back on so we don't leave the + # hub in a weird state for the next test. + _power.power_on(role) + resolve_port_by_role(role, timeout_s=30.0) + pytest.fail(f"device {role!r} stayed visible after power_off") + + # Power back on + re-discover port. + _power.power_on(role) + time.sleep(0.5) # head-start before polling + new_port = resolve_port_by_role(role, timeout_s=30.0) + + # Give the firmware a moment to finish boot before we hit it with admin. + time.sleep(2.0) + + post_info = info.device_info(port=new_port, timeout_s=10.0) + assert post_info.get("my_node_num") == pre_node_num, ( + f"my_node_num changed across power-cycle: pre={pre_node_num:#x} " + f"post={post_info.get('my_node_num'):#x}" + ) + # Firmware version must match (same bake, not a re-flash). + if pre_fw: + assert post_info.get("firmware_version") == pre_fw, ( + f"firmware changed across cycle: pre={pre_fw} " + f"post={post_info.get('firmware_version')}" + ) diff --git a/mcp-server/tests/tool_coverage.py b/mcp-server/tests/tool_coverage.py index b91bd4039..edf974e03 100644 --- a/mcp-server/tests/tool_coverage.py +++ b/mcp-server/tests/tool_coverage.py @@ -73,6 +73,13 @@ _TOOL_MAP: dict[str, tuple[str, str]] = { "reboot": ("meshtastic_mcp.admin", "reboot"), "shutdown": ("meshtastic_mcp.admin", "shutdown"), "factory_reset": ("meshtastic_mcp.admin", "factory_reset"), + "send_input_event": ("meshtastic_mcp.admin", "send_input_event"), + # `capture_screen` in server.py calls camera.get_camera — instrument that. + "capture_screen": ("meshtastic_mcp.camera", "get_camera"), + # USB power control via uhubctl. + "uhubctl_list": ("meshtastic_mcp.uhubctl", "list_hubs"), + "uhubctl_power": ("meshtastic_mcp.uhubctl", "power_on"), + "uhubctl_cycle": ("meshtastic_mcp.uhubctl", "cycle"), # USERPREFS "userprefs_manifest": ("meshtastic_mcp.userprefs", "build_manifest"), "userprefs_get": ("meshtastic_mcp.userprefs", "read_state"), diff --git a/mcp-server/tests/ui/__init__.py b/mcp-server/tests/ui/__init__.py new file mode 100644 index 000000000..006fc3c8e --- /dev/null +++ b/mcp-server/tests/ui/__init__.py @@ -0,0 +1,7 @@ +"""UI tier — input-broker-driven screen navigation tests. + +Only runs when a screen-bearing role (esp32s3/heltec-v3) is present on the +hub AND the firmware was baked with `enable_ui_log=True` (so the +`Screen: frame N/M name=... reason=...` log lines are emitted). The +`tests/ui/conftest.py` fixture forces that bake stamp. +""" diff --git a/mcp-server/tests/ui/_screen_log.py b/mcp-server/tests/ui/_screen_log.py new file mode 100644 index 000000000..97954db48 --- /dev/null +++ b/mcp-server/tests/ui/_screen_log.py @@ -0,0 +1,176 @@ +"""Parse `Screen: frame N/M name=X reason=Y` log lines from `_debug_log_buffer`. + +The firmware emits one line per frame transition when +`USERPREFS_UI_TEST_LOG` is defined (see src/graphics/Screen.cpp). Tests use +these helpers to assert which frame is shown / to wait for a transition to +settle before taking a camera capture. +""" + +from __future__ import annotations + +import re +import time +from dataclasses import dataclass +from typing import Iterable, Iterator + +FRAME_RE = re.compile( + r"Screen: frame (?P\d+)/(?P\d+) name=(?P\S+) reason=(?P\S+)" +) + + +@dataclass(frozen=True) +class FrameEvent: + idx: int + count: int + name: str + reason: str + raw: str + + @classmethod + def parse(cls, line: str) -> "FrameEvent | None": + m = FRAME_RE.search(line) + if not m: + return None + return cls( + idx=int(m["idx"]), + count=int(m["count"]), + name=m["name"], + reason=m["reason"], + raw=line, + ) + + +def iter_frame_events(lines: Iterable[str]) -> Iterator[FrameEvent]: + for line in lines: + evt = FrameEvent.parse(line) + if evt is not None: + yield evt + + +def get_current_frame(lines: list[str]) -> FrameEvent | None: + """Return the most recent FrameEvent in `lines`, or None if none found.""" + for line in reversed(lines): + evt = FrameEvent.parse(line) + if evt is not None: + return evt + return None + + +def wait_for_frame( + lines: list[str], + expected_name: str, + *, + timeout_s: float = 5.0, + poll_interval_s: float = 0.1, + reason: str | None = None, +) -> FrameEvent: + """Poll `lines` (the `_debug_log_buffer`) until a FrameEvent with + `name=expected_name` appears after the call started. Raises TimeoutError + with context if it doesn't arrive in `timeout_s`. + + `reason` optionally filters to events matching a specific cause + (e.g. `"fn_f1"`, `"next"`, `"rebuild"`). + """ + start_idx = len(lines) + deadline = time.monotonic() + timeout_s + last: FrameEvent | None = None + while time.monotonic() < deadline: + # Scan only lines appended since we started waiting. + for line in lines[start_idx:]: + evt = FrameEvent.parse(line) + if evt is None: + continue + last = evt + if evt.name == expected_name and (reason is None or evt.reason == reason): + return evt + time.sleep(poll_interval_s) + + seen = [e.name for e in iter_frame_events(lines[start_idx:])] + raise TimeoutError( + f"frame name={expected_name!r} reason={reason!r} not seen in {timeout_s}s; " + f"saw {len(seen)} transition(s): {seen!r}; last={last!r}" + ) + + +def wait_for_any_frame( + lines: list[str], + *, + timeout_s: float = 5.0, + poll_interval_s: float = 0.1, +) -> FrameEvent: + """Wait for ANY frame transition to appear after call-start. Useful for + `no-op` tests that want to confirm a transition did NOT happen (via + TimeoutError) vs. one that did. + """ + start_idx = len(lines) + deadline = time.monotonic() + timeout_s + while time.monotonic() < deadline: + for line in lines[start_idx:]: + evt = FrameEvent.parse(line) + if evt is not None: + return evt + time.sleep(poll_interval_s) + raise TimeoutError(f"no frame transition in {timeout_s}s") + + +def wait_for_reason( + lines: list[str], + reason: str, + *, + timeout_s: float = 5.0, + poll_interval_s: float = 0.1, +) -> FrameEvent: + """Wait for a frame event with `reason=` after call-start. + + Matches only on `reason` — useful when the caller knows *why* a + transition should happen (e.g. `fn_f1`, `rebuild`) but not which named + frame the firmware will land on for this particular board. + """ + start_idx = len(lines) + deadline = time.monotonic() + timeout_s + last: FrameEvent | None = None + while time.monotonic() < deadline: + for line in lines[start_idx:]: + evt = FrameEvent.parse(line) + if evt is None: + continue + last = evt + if evt.reason == reason: + return evt + time.sleep(poll_interval_s) + raise TimeoutError( + f"no frame with reason={reason!r} in {timeout_s}s; last={last!r}" + ) + + +def assert_no_frame_change( + lines: list[str], + *, + wait_s: float = 2.0, +) -> None: + """Assert that NO new FrameEvent lines arrive within `wait_s`. + + Used by idempotency / no-op tests (e.g. BACK on home frame). + """ + start_idx = len(lines) + time.sleep(wait_s) + new = [ + e for e in (FrameEvent.parse(ln) for ln in lines[start_idx:]) if e is not None + ] + if new: + raise AssertionError( + f"expected no frame change in {wait_s}s, but saw {len(new)} event(s): " + f"{[(e.reason, e.name) for e in new]!r}" + ) + + +__all__ = [ + "FRAME_RE", + "FrameEvent", + "assert_no_frame_change", + "get_current_frame", + "iter_frame_events", + "wait_for_any_frame", + "wait_for_frame", + "wait_for_reason", +] diff --git a/mcp-server/tests/ui/conftest.py b/mcp-server/tests/ui/conftest.py new file mode 100644 index 000000000..aedfdbc8f --- /dev/null +++ b/mcp-server/tests/ui/conftest.py @@ -0,0 +1,381 @@ +"""UI-tier fixtures: camera lifecycle, OCR warmup, per-test frame capture, +and a `ui_home_state` autouse guard that resets to the home frame before +every test (prevents state bleed if a prior test exited inside a menu). + +The camera + OCR modules live in `meshtastic_mcp/{camera,ocr}.py` (production +code, so the `capture_screen` MCP tool can share them). These fixtures wire +them into pytest + write per-test captures to `tests/ui_captures/…`. +""" + +from __future__ import annotations + +import re +import shutil +import time +from pathlib import Path +from typing import Any, Iterator + +import pytest +from meshtastic_mcp import admin as admin_mod +from meshtastic_mcp import camera as camera_mod +from meshtastic_mcp import ocr as ocr_mod +from meshtastic_mcp.input_events import InputEventCode + +from ._screen_log import FrameEvent, get_current_frame, wait_for_frame + +# Roles that carry a screen the UI tier can drive. Only esp32s3 (heltec-v3 +# SSD1306) qualifies today — nrf52 (rak4631) has no display. +UI_CAPABLE_ROLES = ("esp32s3",) + +# Where per-test captures land. One subdirectory per session seed, then per +# sanitized test nodeid — identical pattern to other pytest artifacts. +CAPTURES_ROOT = Path(__file__).resolve().parent.parent / "ui_captures" + + +def _sanitize_nodeid(nodeid: str) -> str: + return re.sub(r"[^a-zA-Z0-9_.-]+", "_", nodeid) + + +# ---------- Role gating ---------------------------------------------------- + + +@pytest.fixture +def ui_capable_role(request: pytest.FixtureRequest, hub_devices: dict[str, Any]) -> str: + """Resolve the single role the UI tier drives. + + Today that's `esp32s3`. Skips if the hub doesn't have one. A future + multi-screen hub could pick a role per parametrization. + """ + for role in UI_CAPABLE_ROLES: + if role in hub_devices: + return role + pytest.skip( + f"no UI-capable role on hub; need one of {UI_CAPABLE_ROLES} in {sorted(hub_devices)}" + ) + + +@pytest.fixture +def ui_port(ui_capable_role: str, hub_devices: dict[str, Any]) -> str: + port = ( + hub_devices[ui_capable_role].get("port") + if isinstance(hub_devices[ui_capable_role], dict) + else hub_devices[ui_capable_role] + ) + if not port: + pytest.skip(f"{ui_capable_role!r} has no usable port") + return port + + +# ---------- Camera + OCR session fixtures --------------------------------- + + +@pytest.fixture(scope="session") +def camera(ui_capable_role_session: str | None) -> Iterator[camera_mod.CameraBackend]: + """Session-scoped camera backend. Closed at teardown. + + Backend + device selected by env vars (see `meshtastic_mcp.camera`). + Falls through to `NullBackend` when no camera is configured, so the + tests run end-to-end on machines without hardware; they just won't + have useful images. + """ + role = ui_capable_role_session or "esp32s3" + cam = camera_mod.get_camera(role) + try: + yield cam + finally: + cam.close() + + +@pytest.fixture(scope="session") +def ui_capable_role_session(hub_devices: dict[str, Any]) -> str | None: + """Session-scoped lookup mirroring `ui_capable_role` but non-skipping. + + Used by the `camera` session fixture so it doesn't depend on a + test-scoped skip. + """ + for role in UI_CAPABLE_ROLES: + if role in hub_devices: + return role + return None + + +@pytest.fixture(scope="session", autouse=True) +def _ocr_warm() -> None: + """Pay easyocr's ~100 MB / cold-start cost ONCE per session. + + Subsequent `ocr_text()` calls hit the cached reader and return quickly. + Swallows errors — if OCR isn't installed, warm is a no-op. + """ + try: + ocr_mod.warm() + except Exception: # noqa: BLE001 — belt: never block the suite on OCR init + pass + + +@pytest.fixture(scope="session") +def _ui_screen_kept_on( + ui_capable_role_session: str | None, hub_devices: dict[str, Any] +) -> Iterator[None]: + """Keep the OLED on throughout the UI tier so input events aren't dropped. + + Why: `InputBroker::handleInputEvent` (src/input/InputBroker.cpp:118-122) + silently DROPS any event that arrives while the screen is off — it just + wakes the screen and returns. Every first event in each test would + disappear. We set `display.screen_on_secs = 86400` at session start + (effectively "always on" for the test window) and restore the prior + value at teardown. + """ + if ui_capable_role_session is None: + yield + return + + hub_entry = hub_devices[ui_capable_role_session] + port = hub_entry.get("port") if isinstance(hub_entry, dict) else hub_entry + if not port: + yield + return + + original: int | None = None + try: + current = admin_mod.get_config(section="display", port=port) + original = int( + current.get("config", {}).get("display", {}).get("screen_on_secs") or 0 + ) + except Exception: # noqa: BLE001 + pass + + try: + admin_mod.set_config("display.screen_on_secs", 86400, port=port) + # Send one wake event so the screen is actually ON going into the + # first test. The event itself gets dropped (screenWasOff), but the + # wake side-effect sticks. + try: + admin_mod.send_input_event(event_code=int(InputEventCode.FN_F1), port=port) + except Exception: # noqa: BLE001 + pass + time.sleep(1.5) # Let the screen finish its wake transition. + except ( + Exception + ): # noqa: BLE001 — best-effort; ui_home_state surfaces the real error + pass + + try: + yield + finally: + if original is not None: + try: + admin_mod.set_config("display.screen_on_secs", original, port=port) + except Exception: # noqa: BLE001 + pass + + +# ---------- Per-test capture + transcript ---------------------------------- + + +class FrameCapture: + """Per-test capture recorder. Created once per test via the + `frame_capture` fixture; call with a label to snapshot the screen. + """ + + def __init__( + self, + cam: camera_mod.CameraBackend, + dir_path: Path, + lines: list[str], + nodeid: str, + ) -> None: + self._cam = cam + self._dir = dir_path + self._lines = lines + self._nodeid = nodeid + self._step = 0 + self.captures: list[dict[str, Any]] = [] + self._transcript_path = dir_path / "transcript.md" + self._dir.mkdir(parents=True, exist_ok=True) + self._transcript_path.write_text( + f"# {nodeid} — {time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}\n\n", + encoding="utf-8", + ) + + def __call__(self, label: str) -> dict[str, Any]: + self._step += 1 + stem = f"{self._step:03d}-{re.sub(r'[^a-zA-Z0-9_-]+', '-', label)}" + png_path = self._dir / f"{stem}.png" + ocr_path = self._dir / f"{stem}.ocr.txt" + + try: + png = self._cam.capture() + except Exception as exc: # noqa: BLE001 + png = b"" + ocr_str = f"[capture error: {exc}]" + else: + camera_mod.save_capture(png, png_path) + try: + ocr_str = ocr_mod.ocr_text(png) + except Exception as exc: # noqa: BLE001 + ocr_str = f"[ocr error: {exc}]" + ocr_path.write_text(ocr_str or "", encoding="utf-8") + + frame = get_current_frame(self._lines) + entry: dict[str, Any] = { + "step": self._step, + "label": label, + "png_path": str(png_path) if png else None, + "ocr_text": ocr_str, + "frame": ( + { + "idx": frame.idx, + "name": frame.name, + "reason": frame.reason, + } + if frame is not None + else None + ), + } + self.captures.append(entry) + + with self._transcript_path.open("a", encoding="utf-8") as fh: + frame_str = ( + f"frame {frame.idx}/{frame.count} name={frame.name} reason={frame.reason}" + if frame is not None + else "frame " + ) + ocr_summary = (ocr_str or "").replace("\n", " / ")[:80] + fh.write( + f"{self._step}. **{label}** — {frame_str} — OCR: `{ocr_summary}`\n" + ) + return entry + + +@pytest.fixture +def frame_capture( + request: pytest.FixtureRequest, + camera: camera_mod.CameraBackend, + session_seed: str, +) -> Iterator[FrameCapture]: + nodeid = _sanitize_nodeid(request.node.nodeid) + dir_path = CAPTURES_ROOT / session_seed / nodeid + # Fresh directory per test run so reruns don't mix old and new images. + if dir_path.exists(): + shutil.rmtree(dir_path) + + lines = getattr(request.node, "_debug_log_buffer", []) + fc = FrameCapture(camera, dir_path, lines, nodeid) + # Stash so pytest_runtest_makereport can embed captures in HTML extras. + request.node._ui_captures = fc.captures # type: ignore[attr-defined] + yield fc + + +# ---------- Pre-test home-state reset -------------------------------------- + + +def _send_event(port: str, event: InputEventCode) -> None: + try: + admin_mod.send_input_event(event_code=int(event), port=port) + except Exception: # noqa: BLE001 + # Treat a failed event as soft — the subsequent frame-log assertion + # surfaces the real problem with better context. + pass + + +@pytest.fixture(autouse=True) +def ui_home_state( + request: pytest.FixtureRequest, + hub_devices: dict[str, Any], + _ui_screen_kept_on: None, +) -> Iterator[None]: + """Before every UI test, jump to frame 0 (usually `home`) via FN_F1 and + confirm the device emitted the expected frame log. + + Why FN_F1 (not BACK): FN_F1 maps to `switchToFrame(0)` and ALWAYS + produces a `reason=fn_f1` log line, regardless of whatever frame the + prior test left us on. BACK is context-sensitive (dismisses overlays + on some frames, no-op on others) and can silently fail to transition. + + This fixture doubles as the macro-presence detector: if no `fn_f1` + log arrives within 5 s, the firmware almost certainly wasn't baked + with `USERPREFS_UI_TEST_LOG`. Skip the tier with an actionable hint + instead of letting every test body fail with a confusing assertion. + + Autouse scope is restricted to `tests/ui/` by virtue of this fixture + living in that directory's conftest.py — no explicit nodeid guard + needed (and earlier attempts at one were wrong, matching `/tests/ui/` + against a nodeid that has no leading slash). + """ + role = next((r for r in UI_CAPABLE_ROLES if r in hub_devices), None) + if role is None: + yield + return + + hub_entry = hub_devices[role] + port = hub_entry.get("port") if isinstance(hub_entry, dict) else hub_entry + lines: list[str] = getattr(request.node, "_debug_log_buffer", []) + start_len = len(lines) + + # First: a wake event. The screen should already be kept on by + # `_ui_screen_kept_on`, but belt + suspenders — if it somehow + # powered off (sleep after factory_reset, etc.), this first FN_F1 + # gets dropped by InputBroker's screenWasOff guard. That's fine; + # the second FN_F1 below lands cleanly. + _send_event(port, InputEventCode.FN_F1) + time.sleep(0.4) + _send_event(port, InputEventCode.FN_F1) + + # Wait for the fn_f1 transition log. Any new `reason=fn_f1` line + # after call-start counts — we don't care about the name (it should + # be `home` or `deviceFocused` depending on board-specific frame order). + from ._screen_log import wait_for_reason + + try: + wait_for_reason(lines, "fn_f1", timeout_s=5.0) + except TimeoutError: + # One more try — FreeRTOS queue may be draining slowly. + _send_event(port, InputEventCode.FN_F1) + try: + wait_for_reason(lines, "fn_f1", timeout_s=5.0) + except TimeoutError: + # Look at what the _debug_log_buffer actually contains to + # disambiguate "macro off" from "macro on but event lost". + frame_lines = [ln for ln in lines[start_len:] if "Screen: frame" in ln] + processing_lines = [ + ln for ln in lines[start_len:] if "Processing input event" in ln + ] + if frame_lines: + pytest.skip( + f"ui_home_state: events fire but none reach Screen " + f"(saw {len(frame_lines)} frame line(s), " + f"{len(processing_lines)} admin inject(s)). " + f"Device may be in an unusual state — try `--force-bake`." + ) + else: + pytest.skip( + "ui_home_state: no `Screen: frame` log after FN_F1. " + "Firmware not baked with USERPREFS_UI_TEST_LOG — " + "run with `--force-bake` to reflash, or verify the " + "macro is active in the bake." + ) + yield + + +# ---------- Small helpers reused by tests --------------------------------- + + +def send_event( + port: str, event: InputEventCode | int | str, **kwargs: Any +) -> dict[str, Any]: + """Thin wrapper so tests read `send_event(port, InputEventCode.RIGHT)`.""" + return admin_mod.send_input_event(event_code=event, port=port, **kwargs) + + +__all__ = [ + "FrameCapture", + "UI_CAPABLE_ROLES", + "send_event", + "wait_for_frame", + "FrameEvent", +] + + +# Make the helpers discoverable to test modules via `from .conftest import …`. +# pytest auto-loads conftest.py, but the symbols above are also re-exported +# for readability in the test files. diff --git a/mcp-server/tests/ui/test_input_fn_jump.py b/mcp-server/tests/ui/test_input_fn_jump.py new file mode 100644 index 000000000..047aff7d2 --- /dev/null +++ b/mcp-server/tests/ui/test_input_fn_jump.py @@ -0,0 +1,61 @@ +"""FN_F1..F5 directly jumps to frame 0..4 via Screen::handleInputEvent. + +Parametrized over the 5 function keys. Each expects a +`Screen: frame / name=... reason=fn_f` log line, with +`idx == k-1`. We don't hardcode the frame *name* because the layout +depends on which modules are compiled in for this board. +""" + +from __future__ import annotations + +import time + +import pytest +from meshtastic_mcp.input_events import InputEventCode + +from ._screen_log import get_current_frame, wait_for_reason +from .conftest import FrameCapture, send_event + + +@pytest.mark.timeout(120) +@pytest.mark.parametrize( + "event,expected_idx,reason", + [ + (InputEventCode.FN_F1, 0, "fn_f1"), + (InputEventCode.FN_F2, 1, "fn_f2"), + (InputEventCode.FN_F3, 2, "fn_f3"), + (InputEventCode.FN_F4, 3, "fn_f4"), + (InputEventCode.FN_F5, 4, "fn_f5"), + ], + ids=["FN_F1", "FN_F2", "FN_F3", "FN_F4", "FN_F5"], +) +def test_fn_jump_direct_frame( + ui_port: str, + frame_capture: FrameCapture, + request: pytest.FixtureRequest, + event: InputEventCode, + expected_idx: int, + reason: str, +) -> None: + lines: list[str] = request.node._debug_log_buffer + start = get_current_frame(lines) + assert start is not None, "no frame log yet — USERPREFS_UI_TEST_LOG not wired?" + assert start.name in ( + "home", + "deviceFocused", + ), f"setup expected frame 0 landing, got {start.name!r}" + frame_capture("initial") + + if start.count <= expected_idx: + pytest.skip( + f"device has {start.count} frames; FN_F{expected_idx + 1} needs > {expected_idx}" + ) + + send_event(ui_port, event) + time.sleep(0.1) + evt = wait_for_reason(lines, reason, timeout_s=5.0) + assert evt.idx == expected_idx, ( + f"FN_F{expected_idx + 1} expected idx={expected_idx}, got {evt.idx} " + f"(name={evt.name}, count={evt.count})" + ) + frame_capture(f"after-{reason}") diff --git a/mcp-server/tests/ui/test_input_fn_oob.py b/mcp-server/tests/ui/test_input_fn_oob.py new file mode 100644 index 000000000..a33ff1cc5 --- /dev/null +++ b/mcp-server/tests/ui/test_input_fn_oob.py @@ -0,0 +1,61 @@ +"""Out-of-bounds FN_F5 when the device has <5 frames: no crash, idx unchanged. + +`Screen::handleInputEvent` dispatches FN_F5 unconditionally to +`ui->switchToFrame(4)`. The OLEDDisplayUi library typically clamps or +silently ignores out-of-range indices, but firmware bugs have existed +here — this test protects against a regression that would wedge the UI. + +If this test fails, first check: did the device actually crash (Guru +Meditation in the log)? Or did switchToFrame accept an OOB index and +leave the UI blank? +""" + +from __future__ import annotations + +import time + +import pytest +from meshtastic_mcp.input_events import InputEventCode + +from ._screen_log import get_current_frame, wait_for_reason +from .conftest import FrameCapture, send_event + + +@pytest.mark.timeout(90) +def test_fn_f5_out_of_bounds( + ui_port: str, + frame_capture: FrameCapture, + request: pytest.FixtureRequest, +) -> None: + lines: list[str] = request.node._debug_log_buffer + start = get_current_frame(lines) + assert start is not None + + if start.count > 5: + pytest.skip( + f"device has {start.count} frames; FN_F5 is in-bounds — not testing OOB here" + ) + + frame_capture("initial-home") + send_event(ui_port, InputEventCode.FN_F5) + time.sleep(0.5) + + try: + wait_for_reason(lines, "fn_f5", timeout_s=3.0) + except TimeoutError: + # Firmware may have ignored the event entirely — acceptable. + pass + + # Capture whatever is on screen (OCR will tell us if something weird + # happened). Device must remain responsive — subsequent events should + # still land. + frame_capture("after-fn_f5-oob") + + # Send a RIGHT to confirm the UI is still alive. If this times out, + # the OOB switchToFrame wedged the UI. + send_event(ui_port, InputEventCode.RIGHT) + post = wait_for_reason(lines, "next", timeout_s=5.0) + assert ( + post is not None + ), "UI wedged after OOB FN_F5 — RIGHT no longer produces frame log" + frame_capture("after-recovery-right") diff --git a/mcp-server/tests/ui/test_input_menu.py b/mcp-server/tests/ui/test_input_menu.py new file mode 100644 index 000000000..8799d7dfb --- /dev/null +++ b/mcp-server/tests/ui/test_input_menu.py @@ -0,0 +1,68 @@ +"""SELECT on the home frame opens the home menu; BACK closes it. + +The home menu is an overlay (menuHandler::homeBaseMenu), not a frame +transition — so we verify via OCR difference between before/after +captures rather than a `Screen: frame` log line. The underlying +mechanism is still InputBroker → Screen::handleInputEvent → menu +callback. +""" + +from __future__ import annotations + +import time + +import pytest +from meshtastic_mcp.input_events import InputEventCode + +from ._screen_log import get_current_frame +from .conftest import FrameCapture, send_event + + +@pytest.mark.timeout(120) +def test_select_opens_home_menu( + ui_port: str, + frame_capture: FrameCapture, + request: pytest.FixtureRequest, +) -> None: + lines: list[str] = request.node._debug_log_buffer + start = get_current_frame(lines) + assert start is not None + if start.name not in ("home", "deviceFocused"): + pytest.skip( + f"SELECT on {start.name!r} doesn't open homeBaseMenu; " + "test is only valid when the landing frame is home/deviceFocused" + ) + + initial = frame_capture("initial") + send_event(ui_port, InputEventCode.SELECT) + time.sleep(0.8) + opened = frame_capture("after-select") + + # The menu is an overlay (not a frame change). We cannot use log + # assertion — instead, OCR should differ because a menu list is now + # drawn on top. + initial_text = (initial.get("ocr_text") or "").strip() + opened_text = (opened.get("ocr_text") or "").strip() + if initial_text and opened_text: + # When OCR is available, require *some* difference between the two + # frames — even a single menu title changes the transcribed text. + assert initial_text != opened_text, ( + f"expected OCR diff after SELECT; both read {initial_text!r}. " + "If both are empty, check camera alignment + OCR backend." + ) + + # Back out — the menu dismisses on BACK. + send_event(ui_port, InputEventCode.BACK) + time.sleep(0.8) + closed = frame_capture("after-back") + + # Soft check: OCR after BACK should look different from the menu + # (either back to home or onto a previous frame — BACK's exact + # behavior when the menu is up vs. not-up varies). We don't assert + # equality because OLED rendering is pixel-stable but camera sampling + # introduces noise. + if opened_text and closed.get("ocr_text"): + close_text = (closed.get("ocr_text") or "").strip() + assert ( + close_text != opened_text + ), f"after BACK, OCR still looks like the menu: {close_text!r}" diff --git a/mcp-server/tests/ui/test_input_message_scroll.py b/mcp-server/tests/ui/test_input_message_scroll.py new file mode 100644 index 000000000..85dc2d8e2 --- /dev/null +++ b/mcp-server/tests/ui/test_input_message_scroll.py @@ -0,0 +1,60 @@ +"""Once we navigate to the textMessage frame, UP/DOWN exercises the +message-scroll path (or opens CannedMessages on empty devices). + +Weaker than a "no frame change" assertion because on a fresh bench +device the message store is usually empty, and the firmware's UP +handler in that case launches CannedMessage — which DOES rebuild +frames. We just verify the path doesn't crash + produce captures for +visual inspection. +""" + +from __future__ import annotations + +import time + +import pytest +from meshtastic_mcp.input_events import InputEventCode + +from ._screen_log import get_current_frame, wait_for_frame +from .conftest import FrameCapture, send_event + + +@pytest.mark.timeout(180) +def test_up_down_on_textmessage_survives( + ui_port: str, + frame_capture: FrameCapture, + request: pytest.FixtureRequest, +) -> None: + lines: list[str] = request.node._debug_log_buffer + frame_capture("initial") + + # Walk RIGHT until we land on textMessage — up to 15 hops. + for _i in range(15): + send_event(ui_port, InputEventCode.RIGHT) + time.sleep(0.3) + current = get_current_frame(lines) + if current is not None and current.name == "textMessage": + break + else: + pytest.skip( + "couldn't reach textMessage frame within 15 RIGHTs — not present on this board" + ) + + wait_for_frame(lines, "textMessage", timeout_s=5.0) + frame_capture("on-textMessage") + + # UP and DOWN exercise the message-scroll / canned-message-launch path. + # Capture after each so the HTML report shows any visual effect. + send_event(ui_port, InputEventCode.UP) + time.sleep(0.3) + frame_capture("after-up") + + send_event(ui_port, InputEventCode.DOWN) + time.sleep(0.3) + frame_capture("after-down") + + # Soft check: we should still be in a reachable frame (not wedged). + # The next test's `ui_home_state` will error out if the device is + # unresponsive, so we don't need a stricter guarantee here. + final = get_current_frame(lines) + assert final is not None, "no frame log after UP/DOWN — event path broke" diff --git a/mcp-server/tests/ui/test_input_navigation.py b/mcp-server/tests/ui/test_input_navigation.py new file mode 100644 index 000000000..1fe00b134 --- /dev/null +++ b/mcp-server/tests/ui/test_input_navigation.py @@ -0,0 +1,93 @@ +"""INPUT_BROKER_RIGHT cycles forward through frames; INPUT_BROKER_LEFT backs. + +The simplest UI test: fire N RIGHT events and assert the frame index +moves forward by N (modulo frameCount). Each step captures an image + +OCR for the HTML report. +""" + +from __future__ import annotations + +import time +from typing import Any + +import pytest +from meshtastic_mcp.input_events import InputEventCode + +from ._screen_log import get_current_frame, wait_for_frame +from .conftest import FrameCapture, send_event + + +@pytest.mark.timeout(120) +def test_input_right_cycles_frames( + ui_port: str, + frame_capture: FrameCapture, + request: pytest.FixtureRequest, +) -> None: + lines: list[str] = request.node._debug_log_buffer + start = get_current_frame(lines) + assert start is not None, "no frame log yet — USERPREFS_UI_TEST_LOG not wired?" + # FN_F1 in ui_home_state lands on frame 0. The name at frame 0 varies + # by board (home on heltec-v3, deviceFocused on others) — accept either. + assert start.name in ( + "home", + "deviceFocused", + ), f"setup expected home/deviceFocused at frame 0, got {start.name!r}" + + frame_capture("initial") + visited = [start.idx] + + for step in range(4): + send_event(ui_port, InputEventCode.RIGHT) + # Each RIGHT should bump the frame index by 1. The log fires with + # `reason=next` from showFrame(NEXT). + before_count = len(list(_frame_events(lines))) + deadline = time.monotonic() + 5.0 + while time.monotonic() < deadline: + if len(list(_frame_events(lines))) > before_count: + break + time.sleep(0.1) + evt = get_current_frame(lines) + assert evt is not None + assert ( + evt.reason == "next" + ), f"step {step}: expected reason=next, got {evt.reason!r}" + visited.append(evt.idx) + frame_capture(f"after-right-{step + 1}") + + # Sanity: each index should differ from its predecessor. + diffs = [visited[i + 1] - visited[i] for i in range(len(visited) - 1)] + assert all( + d in (1, -(start.count - 1)) for d in diffs + ), f"expected monotonic +1 steps (or a wrap), got visited={visited} diffs={diffs}" + + +@pytest.mark.timeout(120) +def test_input_left_returns_to_home( + ui_port: str, + frame_capture: FrameCapture, + request: pytest.FixtureRequest, +) -> None: + """After RIGHT×3 + LEFT×3, we should end up back on the starting frame.""" + lines: list[str] = request.node._debug_log_buffer + start = get_current_frame(lines) + assert start is not None + start_name = start.name + frame_capture("initial") + for _ in range(3): + send_event(ui_port, InputEventCode.RIGHT) + time.sleep(0.3) + frame_capture("after-right-3") + + for _ in range(3): + send_event(ui_port, InputEventCode.LEFT) + time.sleep(0.3) + + # Back to whichever frame we started on (home or deviceFocused). + wait_for_frame(lines, start_name, timeout_s=5.0) + frame_capture(f"after-left-3-back-{start_name}") + + +def _frame_events(lines: list[str]) -> Any: + from ._screen_log import iter_frame_events + + return iter_frame_events(lines) diff --git a/mcp-server/tests/ui/test_input_node_scroll.py b/mcp-server/tests/ui/test_input_node_scroll.py new file mode 100644 index 000000000..594b358a0 --- /dev/null +++ b/mcp-server/tests/ui/test_input_node_scroll.py @@ -0,0 +1,51 @@ +"""On the nodelist_nodes frame, UP/DOWN scrolls the list via +`NodeListRenderer::scrollUp/scrollDown` (src/graphics/Screen.cpp:1779-1788). +The firmware returns 0 before notifying observers, so no frame-change +log fires. Verify the path doesn't crash and we stay on nodelist_nodes. +""" + +from __future__ import annotations + +import time + +import pytest +from meshtastic_mcp.input_events import InputEventCode + +from ._screen_log import assert_no_frame_change, get_current_frame, wait_for_frame +from .conftest import FrameCapture, send_event + + +@pytest.mark.timeout(180) +def test_up_down_on_nodelist_no_frame_change( + ui_port: str, + frame_capture: FrameCapture, + request: pytest.FixtureRequest, +) -> None: + lines: list[str] = request.node._debug_log_buffer + frame_capture("initial") + + # Walk RIGHT until we land on nodelist_nodes. + for _i in range(15): + send_event(ui_port, InputEventCode.RIGHT) + time.sleep(0.3) + current = get_current_frame(lines) + if current is not None and current.name == "nodelist_nodes": + break + else: + pytest.skip("couldn't reach nodelist_nodes within 15 RIGHTs") + + wait_for_frame(lines, "nodelist_nodes", timeout_s=5.0) + frame_capture("on-nodelist") + + # UP/DOWN on nodelist scroll internally + `return 0` before + # notifyObservers — no frame-change log. Verify. + send_event(ui_port, InputEventCode.UP) + assert_no_frame_change(lines, wait_s=1.5) + send_event(ui_port, InputEventCode.DOWN) + assert_no_frame_change(lines, wait_s=1.5) + + final = get_current_frame(lines) + assert ( + final is not None and final.name == "nodelist_nodes" + ), f"UP/DOWN moved us off nodelist_nodes; now on {final!r}" + frame_capture("after-up-down") diff --git a/mcp-server/tests/unit/test_input_event_codes.py b/mcp-server/tests/unit/test_input_event_codes.py new file mode 100644 index 000000000..f92698edf --- /dev/null +++ b/mcp-server/tests/unit/test_input_event_codes.py @@ -0,0 +1,90 @@ +"""Pin `InputEventCode` values to the firmware `input_broker_event` enum. + +If this test fails, someone changed the firmware enum (or this Python +mirror) and they must stay in sync — the admin RPC sends these as u8 +wire values directly. + +Also exercises `coerce_event_code` for the happy + error paths. +""" + +from __future__ import annotations + +import pytest +from meshtastic_mcp.input_events import InputEventCode, coerce_event_code + + +class TestInputEventCodeValues: + """These values MUST match src/input/InputBroker.h exactly.""" + + def test_navigation_keys(self) -> None: + assert int(InputEventCode.UP) == 17 + assert int(InputEventCode.DOWN) == 18 + assert int(InputEventCode.LEFT) == 19 + assert int(InputEventCode.RIGHT) == 20 + + def test_action_keys(self) -> None: + assert int(InputEventCode.SELECT) == 10 + assert int(InputEventCode.CANCEL) == 24 + assert int(InputEventCode.BACK) == 27 + + def test_long_press_variants(self) -> None: + assert int(InputEventCode.SELECT_LONG) == 11 + assert int(InputEventCode.UP_LONG) == 12 + assert int(InputEventCode.DOWN_LONG) == 13 + + def test_fn_keys(self) -> None: + assert int(InputEventCode.FN_F1) == 0xF1 + assert int(InputEventCode.FN_F2) == 0xF2 + assert int(InputEventCode.FN_F3) == 0xF3 + assert int(InputEventCode.FN_F4) == 0xF4 + assert int(InputEventCode.FN_F5) == 0xF5 + + def test_system_events(self) -> None: + assert int(InputEventCode.SHUTDOWN) == 0x9B + assert int(InputEventCode.GPS_TOGGLE) == 0x9E + assert int(InputEventCode.SEND_PING) == 0xAF + + def test_auto_increment_block(self) -> None: + # C enum: `BACK = 27, USER_PRESS, ALT_PRESS, ALT_LONG` → 28, 29, 30. + assert int(InputEventCode.USER_PRESS) == 28 + assert int(InputEventCode.ALT_PRESS) == 29 + assert int(InputEventCode.ALT_LONG) == 30 + + +class TestCoerceEventCode: + def test_int_passthrough(self) -> None: + assert coerce_event_code(20) == 20 + assert coerce_event_code(0) == 0 + assert coerce_event_code(255) == 255 + + def test_enum_passthrough(self) -> None: + assert coerce_event_code(InputEventCode.RIGHT) == 20 + assert coerce_event_code(InputEventCode.FN_F1) == 0xF1 + + def test_name_case_insensitive(self) -> None: + assert coerce_event_code("right") == 20 + assert coerce_event_code("RIGHT") == 20 + assert coerce_event_code("Right") == 20 + + def test_input_broker_prefix_stripped(self) -> None: + assert coerce_event_code("INPUT_BROKER_FN_F1") == 0xF1 + assert coerce_event_code("input_broker_select") == 10 + + def test_hyphen_and_underscore_equivalence(self) -> None: + assert coerce_event_code("fn-f1") == 0xF1 + + def test_int_out_of_range_raises(self) -> None: + with pytest.raises(ValueError, match="u8"): + coerce_event_code(256) + with pytest.raises(ValueError, match="u8"): + coerce_event_code(-1) + + def test_unknown_name_raises(self) -> None: + with pytest.raises(ValueError, match="unknown event code name"): + coerce_event_code("NOT_A_KEY") + + def test_wrong_type_raises(self) -> None: + with pytest.raises(TypeError): + coerce_event_code(1.5) # type: ignore[arg-type] + with pytest.raises(TypeError): + coerce_event_code(None) # type: ignore[arg-type] diff --git a/mcp-server/tests/unit/test_uhubctl_parser.py b/mcp-server/tests/unit/test_uhubctl_parser.py new file mode 100644 index 000000000..373147950 --- /dev/null +++ b/mcp-server/tests/unit/test_uhubctl_parser.py @@ -0,0 +1,148 @@ +"""Pin the `uhubctl` default-output parser against canned real-world samples. + +uhubctl's output format has been stable since v2.x but occasionally adds +new hub-descriptor fields (e.g. the `, ppps` marker). The parser uses loose +regexes to tolerate additions; this test keeps us honest. + +Samples captured from: +- v2.6.0 on macOS (Homebrew) — two USB2 hubs, one populated with an + nRF52 and a CP2102, plus chained USB3 hubs. +- v2.5.0 on Linux (hypothetical — reconstructed from the project README). +""" + +from __future__ import annotations + +import pytest +from meshtastic_mcp.uhubctl import ( + ROLE_VIDS, + UhubctlError, + parse_list_output, +) + +# Actual `uhubctl` stdout on the developer's macOS bench, Apr 2026. +_SAMPLE_MACOS_V26 = """\ +Current status for hub 1-1.3 [2109:2817 VIA Labs, Inc. USB2.0 Hub, USB 2.10, 4 ports, ppps] + Port 1: 0100 power + Port 2: 0103 power enable connect [239a:8029 RAKwireless WisCore RAK4631 Board 920456B1E6972262] + Port 3: 0103 power enable connect [10c4:ea60 Silicon Labs CP2102 USB to UART Bridge Controller 0001] + Port 4: 0100 power +Current status for hub 1-2.3 [2109:0817 VIA Labs, Inc. USB3.0 Hub, USB 3.10, 4 ports, ppps] + Port 1: 02a0 power 5gbps Rx.Detect + Port 2: 02a0 power 5gbps Rx.Detect + Port 3: 02a0 power 5gbps Rx.Detect + Port 4: 02a0 power 5gbps Rx.Detect +Current status for hub 1-1 [2109:2817 VIA Labs, Inc. USB2.0 Hub, USB 2.10, 4 ports, ppps] + Port 1: 0100 power + Port 2: 0100 power + Port 3: 0503 power highspeed enable connect [2109:2817 VIA Labs, Inc. USB2.0 Hub, USB 2.10, 4 ports, ppps] + Port 4: 0100 power +""" + + +# Minimal Linux-style sample (fewer hubs, shows a non-PPPS hub). +_SAMPLE_LINUX_NONPPPS = """\ +Current status for hub 2-1.4 [05e3:0608 GenesysLogic USB2.1 Hub, USB 2.10, 4 ports] + Port 1: 0507 power highspeed suspend enable connect [239a:0029 Adafruit Feather Bootloader] + Port 2: 0100 power + Port 3: 0100 power + Port 4: 0100 power +""" + + +class TestParseListOutput: + def test_parses_macos_sample_hub_count(self) -> None: + hubs = parse_list_output(_SAMPLE_MACOS_V26) + assert len(hubs) == 3 + + def test_parses_hub_location_and_vid(self) -> None: + hubs = parse_list_output(_SAMPLE_MACOS_V26) + via_hub = hubs[0] + assert via_hub["location"] == "1-1.3" + assert via_hub["vid"] == 0x2109 + assert via_hub["pid"] == 0x2817 + assert via_hub["ppps"] is True + + def test_parses_port_with_device(self) -> None: + hubs = parse_list_output(_SAMPLE_MACOS_V26) + nrf52_hub = hubs[0] + port2 = next(p for p in nrf52_hub["ports"] if p["port"] == 2) + assert port2["device_vid"] == 0x239A + assert port2["device_pid"] == 0x8029 + assert "RAKwireless" in port2["device_desc"] + + def test_empty_port_has_no_device(self) -> None: + hubs = parse_list_output(_SAMPLE_MACOS_V26) + nrf52_hub = hubs[0] + port1 = next(p for p in nrf52_hub["ports"] if p["port"] == 1) + assert port1["device_vid"] is None + assert port1["device_pid"] is None + assert port1["device_desc"] is None + + def test_ports_count(self) -> None: + hubs = parse_list_output(_SAMPLE_MACOS_V26) + for hub in hubs: + assert len(hub["ports"]) == 4 # each sample hub has 4 ports + + def test_non_ppps_hub_flagged(self) -> None: + hubs = parse_list_output(_SAMPLE_LINUX_NONPPPS) + assert len(hubs) == 1 + assert hubs[0]["ppps"] is False + + def test_handles_empty_input(self) -> None: + assert parse_list_output("") == [] + + def test_handles_malformed_lines_gracefully(self) -> None: + # Lines that don't match HUB_RE or PORT_RE are ignored silently. + garbage = "uhubctl: warning: something weird\n" + _SAMPLE_LINUX_NONPPPS + hubs = parse_list_output(garbage) + assert len(hubs) == 1 + + +class TestRoleVids: + def test_nrf52_mapped(self) -> None: + assert 0x239A in ROLE_VIDS["nrf52"] + + def test_esp32s3_covers_both_vids(self) -> None: + # Espressif native USB + CP2102 USB-UART on heltec-v3 boards. + assert 0x303A in ROLE_VIDS["esp32s3"] + assert 0x10C4 in ROLE_VIDS["esp32s3"] + + +class TestResolveTargetErrorPaths: + def test_unknown_role_raises(self, monkeypatch: pytest.MonkeyPatch) -> None: + from meshtastic_mcp.uhubctl import resolve_target + + # Clear any env-var pinning that might make this pass accidentally. + for key in ( + "MESHTASTIC_UHUBCTL_LOCATION_FLUX", + "MESHTASTIC_UHUBCTL_PORT_FLUX", + ): + monkeypatch.delenv(key, raising=False) + with pytest.raises(UhubctlError, match="unknown role"): + resolve_target("flux") + + def test_invalid_env_port_raises(self, monkeypatch: pytest.MonkeyPatch) -> None: + from meshtastic_mcp.uhubctl import resolve_target + + monkeypatch.setenv("MESHTASTIC_UHUBCTL_LOCATION_NRF52", "1-1.3") + monkeypatch.setenv("MESHTASTIC_UHUBCTL_PORT_NRF52", "not-an-int") + with pytest.raises(UhubctlError, match="not a valid integer"): + resolve_target("nrf52") + + def test_env_var_pinning_wins(self, monkeypatch: pytest.MonkeyPatch) -> None: + from meshtastic_mcp.uhubctl import resolve_target + + # Env-var pinning should NOT require uhubctl to be running / installed. + monkeypatch.setenv("MESHTASTIC_UHUBCTL_LOCATION_NRF52", "9-9.9") + monkeypatch.setenv("MESHTASTIC_UHUBCTL_PORT_NRF52", "7") + assert resolve_target("nrf52") == ("9-9.9", 7) + + def test_normalize_role_strips_alt_suffix( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + from meshtastic_mcp.uhubctl import resolve_target + + # esp32s3_alt collapses to esp32s3 for env-var lookup. + monkeypatch.setenv("MESHTASTIC_UHUBCTL_LOCATION_ESP32S3", "2-2") + monkeypatch.setenv("MESHTASTIC_UHUBCTL_PORT_ESP32S3", "3") + assert resolve_target("esp32s3_alt") == ("2-2", 3) diff --git a/mcp-server/tests/unit/test_ui_screen_log.py b/mcp-server/tests/unit/test_ui_screen_log.py new file mode 100644 index 000000000..55029b38c --- /dev/null +++ b/mcp-server/tests/unit/test_ui_screen_log.py @@ -0,0 +1,80 @@ +"""Pin the `Screen: frame N/M name=X reason=Y` regex + FrameEvent dataclass. + +The firmware-side format lives in `src/graphics/Screen.cpp::logFrameChange`; +if the format string changes, this test — and the parser in +`tests/ui/_screen_log.py` — have to be updated together. +""" + +from __future__ import annotations + +from tests.ui._screen_log import FRAME_RE, FrameEvent, iter_frame_events + + +class TestFrameEventParse: + def test_exact_firmware_output(self) -> None: + raw = "Screen: frame 2/8 name=home reason=next" + evt = FrameEvent.parse(raw) + assert evt is not None + assert evt.idx == 2 + assert evt.count == 8 + assert evt.name == "home" + assert evt.reason == "next" + assert evt.raw == raw + + def test_with_log_prefix(self) -> None: + """Log lines may be preamble-wrapped by the firmware LOG_INFO macro + (timestamp, severity, etc.) — the regex uses .search() not .match() + so prefixes are fine.""" + raw = "[INFO] 00:12:34 567 Screen: frame 4/12 name=nodelist_nodes reason=fn_f3 " + evt = FrameEvent.parse(raw) + assert evt is not None + assert evt.idx == 4 + assert evt.count == 12 + assert evt.name == "nodelist_nodes" + assert evt.reason == "fn_f3" + + def test_rebuild_reason(self) -> None: + evt = FrameEvent.parse("Screen: frame 0/5 name=deviceFocused reason=rebuild") + assert evt is not None + assert evt.reason == "rebuild" + + def test_all_fn_reasons(self) -> None: + for k in range(1, 6): + evt = FrameEvent.parse( + f"Screen: frame {k - 1}/8 name=settings reason=fn_f{k}" + ) + assert evt is not None and evt.reason == f"fn_f{k}" + + def test_unknown_name_is_preserved(self) -> None: + """If the reverse-map returns 'unknown', that still parses cleanly.""" + evt = FrameEvent.parse("Screen: frame 99/100 name=unknown reason=prev") + assert evt is not None and evt.name == "unknown" + + def test_non_matching_line_returns_none(self) -> None: + assert FrameEvent.parse("BOOT Booting firmware 2.7.23") is None + assert FrameEvent.parse("") is None + assert FrameEvent.parse("Screen: without the right format") is None + + +class TestIterFrameEvents: + def test_filters_non_matching_lines(self) -> None: + lines = [ + "Booting...", + "Screen: frame 1/5 name=home reason=rebuild", + "Some other log line", + "Screen: frame 2/5 name=textMessage reason=next", + ] + evts = list(iter_frame_events(lines)) + assert len(evts) == 2 + assert evts[0].reason == "rebuild" + assert evts[1].reason == "next" + + +class TestRegexAnchoring: + def test_regex_is_compiled(self) -> None: + assert FRAME_RE.search("Screen: frame 0/0 name=home reason=next") is not None + + def test_regex_allows_unusual_names(self) -> None: + r"""Name is `\S+`, so compound names with underscores/digits match.""" + m = FRAME_RE.search("Screen: frame 5/10 name=nodelist_hopsignal reason=fn_f2") + assert m is not None and m["name"] == "nodelist_hopsignal" diff --git a/src/detect/ScanI2C.h b/src/detect/ScanI2C.h index b9745b29a..3d13a68af 100644 --- a/src/detect/ScanI2C.h +++ b/src/detect/ScanI2C.h @@ -96,7 +96,6 @@ class ScanI2C CW2015, SCD30, ADS1115, - CST3530, } DeviceType; // typedef uint8_t DeviceAddress; diff --git a/src/graphics/Screen.cpp b/src/graphics/Screen.cpp index 55ec93db5..60e1c43a6 100644 --- a/src/graphics/Screen.cpp +++ b/src/graphics/Screen.cpp @@ -1265,6 +1265,10 @@ void Screen::setFrames(FrameFocus focus) // Store the info about this frameset, for future setFrames calls this->framesetInfo = fsi; +#ifdef USERPREFS_UI_TEST_LOG + logFrameChange("rebuild", ui->getUiState()->currentFrame); +#endif + setFastFramerate(); // Draw ASAP } @@ -1419,11 +1423,77 @@ void Screen::handleOnPress() } } +#ifdef USERPREFS_UI_TEST_LOG +void Screen::logFrameChange(const char *reason, uint8_t targetIdx) +{ + // Reverse-map an index to a stable name string keyed off FramePositions + // field names — so the pytest harness can assert `name=nodelist_nodes` + // without caring about how the positions were ordered this boot. + const auto &p = framesetInfo.positions; + const char *name = "unknown"; + if (targetIdx == p.home) + name = "home"; + else if (targetIdx == p.deviceFocused) + name = "deviceFocused"; + else if (targetIdx == p.textMessage) + name = "textMessage"; + else if (targetIdx == p.nodelist_nodes) + name = "nodelist_nodes"; + else if (targetIdx == p.nodelist_location) + name = "nodelist_location"; + else if (targetIdx == p.nodelist_lastheard) + name = "nodelist_lastheard"; + else if (targetIdx == p.nodelist_hopsignal) + name = "nodelist_hopsignal"; + else if (targetIdx == p.nodelist_distance) + name = "nodelist_distance"; + else if (targetIdx == p.nodelist_bearings) + name = "nodelist_bearings"; + else if (targetIdx == p.system) + name = "system"; + else if (targetIdx == p.gps) + name = "gps"; + else if (targetIdx == p.lora) + name = "lora"; + else if (targetIdx == p.clock) + name = "clock"; + else if (targetIdx == p.chirpy) + name = "chirpy"; + else if (targetIdx == p.fault) + name = "fault"; + else if (targetIdx == p.waypoint) + name = "waypoint"; + else if (targetIdx == p.focusedModule) + name = "focusedModule"; + else if (targetIdx == p.log) + name = "log"; + else if (targetIdx == p.settings) + name = "settings"; + else if (targetIdx == p.wifi) + name = "wifi"; + else if (p.firstFavorite != 255 && p.lastFavorite != 255 && targetIdx >= p.firstFavorite && targetIdx <= p.lastFavorite) + name = "favorite"; + LOG_INFO("Screen: frame %u/%u name=%s reason=%s", (unsigned)targetIdx, (unsigned)framesetInfo.frameCount, name, reason); +} +#endif + void Screen::showFrame(FrameDirection direction) { // Only advance frames when UI is stable if (ui->getUiState()->frameState == FIXED) { +#ifdef USERPREFS_UI_TEST_LOG + // Log the *intended* target before the (async) transition fires, so + // tests see a deterministic record of what was requested. + if (framesetInfo.frameCount > 0) { + uint8_t curr = ui->getUiState()->currentFrame; + uint8_t target = (direction == FrameDirection::NEXT) + ? (uint8_t)((curr + 1) % framesetInfo.frameCount) + : (uint8_t)((curr + framesetInfo.frameCount - 1) % framesetInfo.frameCount); + logFrameChange(direction == FrameDirection::NEXT ? "next" : "prev", target); + } +#endif + if (direction == FrameDirection::NEXT) { ui->nextFrame(); } else { @@ -1755,22 +1825,37 @@ int Screen::handleInputEvent(const InputEvent *event) showFrame(FrameDirection::NEXT); } else if (event->inputEvent == INPUT_BROKER_FN_F1) { this->ui->switchToFrame(0); +#ifdef USERPREFS_UI_TEST_LOG + logFrameChange("fn_f1", 0); +#endif lastScreenTransition = millis(); setFastFramerate(); } else if (event->inputEvent == INPUT_BROKER_FN_F2) { this->ui->switchToFrame(1); +#ifdef USERPREFS_UI_TEST_LOG + logFrameChange("fn_f2", 1); +#endif lastScreenTransition = millis(); setFastFramerate(); } else if (event->inputEvent == INPUT_BROKER_FN_F3) { this->ui->switchToFrame(2); +#ifdef USERPREFS_UI_TEST_LOG + logFrameChange("fn_f3", 2); +#endif lastScreenTransition = millis(); setFastFramerate(); } else if (event->inputEvent == INPUT_BROKER_FN_F4) { this->ui->switchToFrame(3); +#ifdef USERPREFS_UI_TEST_LOG + logFrameChange("fn_f4", 3); +#endif lastScreenTransition = millis(); setFastFramerate(); } else if (event->inputEvent == INPUT_BROKER_FN_F5) { this->ui->switchToFrame(4); +#ifdef USERPREFS_UI_TEST_LOG + logFrameChange("fn_f5", 4); +#endif lastScreenTransition = millis(); setFastFramerate(); } else if (event->inputEvent == INPUT_BROKER_UP_LONG) { diff --git a/src/graphics/Screen.h b/src/graphics/Screen.h index e259f7691..023f36f38 100644 --- a/src/graphics/Screen.h +++ b/src/graphics/Screen.h @@ -673,6 +673,16 @@ class Screen : public concurrency::OSThread void handleOnPress(); void handleStartFirmwareUpdateScreen(); +#ifdef USERPREFS_UI_TEST_LOG + // Test-only: emits one LOG_INFO line on every frame transition so the + // pytest harness can assert which frame is shown. Gated behind a macro + // so the chatty log doesn't ship in release builds. Enabled via + // build_testing_profile(enable_ui_log=True) in mcp-server/userprefs.py. + // Member function (not free) because FramesetInfo is a private nested + // type — only methods of Screen can reach it. + void logFrameChange(const char *reason, uint8_t targetIdx); +#endif + // Info collected by setFrames method. // Index location of specific frames. // - Used to apply the FrameFocus parameter of setFrames diff --git a/src/modules/AdminModule.cpp b/src/modules/AdminModule.cpp index 7492d7361..8a1843bcb 100644 --- a/src/modules/AdminModule.cpp +++ b/src/modules/AdminModule.cpp @@ -1489,8 +1489,15 @@ void AdminModule::handleSendInputEvent(const meshtastic_AdminMessage_InputEvent LOG_DEBUG("Processing input event: event_code=%u, kb_char=%u, touch_x=%u, touch_y=%u", inputEvent.event_code, inputEvent.kb_char, inputEvent.touch_x, inputEvent.touch_y); - // Create InputEvent for injection - InputEvent event = {.inputEvent = (input_broker_event)inputEvent.event_code, + // Create InputEvent for injection. + // + // `.source` MUST be a non-null C string: the LOG_INFO below formats it + // with %s, and passing NULL to the esp-log formatter crashes with + // Guru Meditation LoadProhibited at strlen(NULL). Other InputBroker + // sources (buttons, rotary) always set this; the admin path was the + // only one leaving it default-null. + InputEvent event = {.source = "admin", + .inputEvent = (input_broker_event)inputEvent.event_code, .kbchar = (unsigned char)inputEvent.kb_char, .touchX = inputEvent.touch_x, .touchY = inputEvent.touch_y}; diff --git a/userPrefs.jsonc b/userPrefs.jsonc index b81f09362..a8201bab3 100644 --- a/userPrefs.jsonc +++ b/userPrefs.jsonc @@ -57,6 +57,7 @@ // "USERPREFS_MQTT_ROOT_TOPIC": "event/REPLACEME", // "USERPREFS_RINGTONE_NAG_SECS": "60", // "USERPREFS_NODEINFO_REPLY_SUPPRESS_SECS": "43200", + // "USERPREFS_UI_TEST_LOG": "true", // Test-only: emits `Screen: frame N/M name=... reason=...` log per UI transition (for the mcp-server ui test tier); off in release builds. "USERPREFS_RINGTONE_RTTTL": "24:d=32,o=5,b=565:f6,p,f6,4p,p,f6,p,f6,2p,p,b6,p,b6,p,b6,p,b6,p,b,p,b,p,b,p,b,p,b,p,b,p,b,p,b,1p.,2p.,p", // "USERPREFS_NETWORK_IPV6_ENABLED": "1", "USERPREFS_TZ_STRING": "tzplaceholder "