From 507842cea2c876d0555d29fa6e8d3f3acca1bc8f Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Thu, 12 Nov 2026 13:58:39 +0100 Subject: [PATCH 01/10] sensors: INA shunt set at runtime -- `sensor set ina.shunt `, kept in prefs Co-Authored-By: Claude Opus 5.5 --- docs/cli_commands.md | 18 +++++ examples/companion_radio/MyMesh.cpp | 4 ++ examples/companion_radio/NodePrefs.h | 2 + examples/companion_radio/main.cpp | 1 + examples/simple_repeater/MyMesh.cpp | 1 + examples/simple_room_server/MyMesh.cpp | 1 + examples/simple_sensor/SensorMesh.cpp | 1 + src/helpers/CommonCLI.cpp | 4 ++ src/helpers/CommonCLI.h | 2 + src/helpers/SensorManager.h | 10 +++ .../sensors/EnvironmentSensorManager.cpp | 68 +++++++++++++++++-- .../sensors/EnvironmentSensorManager.h | 1 + 12 files changed, 106 insertions(+), 7 deletions(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index f1f48a01..80f62035 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -1271,6 +1271,24 @@ Covers serial NMEA receivers (`MicroNMEALocationProvider`). --- +#### Set the INA current sensor's shunt resistor +**Usage:** +- `sensor get ina.shunt` +- `sensor set ina.shunt ` + +**Parameters:** +- `mOhm`: the shunt on the module, in milliohms (`10` for a shunt marked `R010`, + `100` for `R100`); `0` = the build's value (100 mOhm unless the build sets + `TELEM_INA219_SHUNT_VALUE` / `TELEM_INA226_SHUNT_VALUE` / `TELEM_INA3221_SHUNT_VALUE`) + +**Note:** Listed only when an INA219, INA226 or INA3221 was detected at boot. +Saved, applies at once and survives a reboot; it also works over the mesh as +admin, and on a companion as the custom variable `ina.shunt`. With the wrong value +the current is off by the ratio -- LaskaKit's INA226 modules carry 10 mOhm, the +default assumes 100. Current is reported in steps of 1 mA (CayenneLPP). + +--- + ### Bridge (When bridge support is compiled in) #### View the compiled bridge type diff --git a/examples/companion_radio/MyMesh.cpp b/examples/companion_radio/MyMesh.cpp index c360424c..3b752946 100644 --- a/examples/companion_radio/MyMesh.cpp +++ b/examples/companion_radio/MyMesh.cpp @@ -1928,6 +1928,10 @@ void MyMesh::handleCmdFrame(size_t len) { savePrefs(); } #endif + if (strcmp(sp, "ina.shunt") == 0) { // CUSTOM (TeTeHacko): survives a reboot + _prefs.ina_shunt_mohm = atof(np); + savePrefs(); + } writeOKFrame(); } else { writeErrFrame(ERR_CODE_ILLEGAL_ARG); diff --git a/examples/companion_radio/NodePrefs.h b/examples/companion_radio/NodePrefs.h index c5387976..def49ef1 100644 --- a/examples/companion_radio/NodePrefs.h +++ b/examples/companion_radio/NodePrefs.h @@ -53,6 +53,7 @@ public: uint8_t default_scope_key[16]; float tz_offset = 0; float adc_multiplier = 0; // battery ADC multiplier, 0 = board default + float ina_shunt_mohm = 0; // CUSTOM (TeTeHacko): INA shunt in mOhm, 0 = build default #ifdef ENABLE_WIFI_INTERFACE #ifndef WIFI_SSID #define WIFI_SSID "" @@ -225,6 +226,7 @@ private: def("tel_env", _parent->telemetry_mode_env); def("tz_offset", _parent->tz_offset); def("adc_mult", _parent->adc_multiplier); + def("ina_shunt", _parent->ina_shunt_mohm); } public: CompanionPrefs(NodePrefs* parent) : _parent(parent) { } diff --git a/examples/companion_radio/main.cpp b/examples/companion_radio/main.cpp index b6d6643d..f86529ab 100644 --- a/examples/companion_radio/main.cpp +++ b/examples/companion_radio/main.cpp @@ -319,6 +319,7 @@ void setup() { #if ENV_INCLUDE_GPS == 1 the_mesh.applyGpsPrefs(); #endif + sensors.applyInaShunt(the_mesh.getNodePrefs()->ina_shunt_mohm); // CUSTOM (TeTeHacko) #ifdef DISPLAY_CLASS ui_task.begin(disp, &sensors, the_mesh.getNodePrefs()); // still want to pass this in as dependency, as prefs might be moved diff --git a/examples/simple_repeater/MyMesh.cpp b/examples/simple_repeater/MyMesh.cpp index fce2f38d..c9b24501 100644 --- a/examples/simple_repeater/MyMesh.cpp +++ b/examples/simple_repeater/MyMesh.cpp @@ -1529,6 +1529,7 @@ void MyMesh::begin(FILESYSTEM *fs) { #if ENV_INCLUDE_GPS == 1 applyGpsPrefs(); #endif + sensors.applyInaShunt(_prefs.ina_shunt_mohm); // CUSTOM (TeTeHacko) } void MyMesh::sendFloodScoped(const TransportKey& scope, mesh::Packet* pkt, uint32_t delay_millis, uint8_t path_hash_size) { diff --git a/examples/simple_room_server/MyMesh.cpp b/examples/simple_room_server/MyMesh.cpp index 22b2afa4..023201c4 100644 --- a/examples/simple_room_server/MyMesh.cpp +++ b/examples/simple_room_server/MyMesh.cpp @@ -747,6 +747,7 @@ void MyMesh::begin(FILESYSTEM *fs) { #if ENV_INCLUDE_GPS == 1 applyGpsPrefs(); #endif + sensors.applyInaShunt(_prefs.ina_shunt_mohm); // CUSTOM (TeTeHacko) } void MyMesh::sendFloodScoped(const TransportKey& scope, mesh::Packet* pkt, uint32_t delay_millis, uint8_t path_hash_size) { diff --git a/examples/simple_sensor/SensorMesh.cpp b/examples/simple_sensor/SensorMesh.cpp index 6d44fe1b..fafb4fe0 100644 --- a/examples/simple_sensor/SensorMesh.cpp +++ b/examples/simple_sensor/SensorMesh.cpp @@ -873,6 +873,7 @@ void SensorMesh::begin(FILESYSTEM* fs) { #if ENV_INCLUDE_GPS == 1 applyGpsPrefs(); #endif + sensors.applyInaShunt(_prefs.ina_shunt_mohm); // CUSTOM (TeTeHacko) } bool SensorMesh::formatFileSystem() { diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index 550ab2bb..f341924f 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -413,6 +413,10 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, char* command, char* re const char *key = (num > 0) ? parts[0] : ""; const char *value = (num > 1) ? parts[1] : "null"; if (_sensors->setSettingValue(key, value)) { + if (strcmp(key, "ina.shunt") == 0) { // CUSTOM (TeTeHacko): survives a reboot + _prefs->ina_shunt_mohm = atof(value); + savePrefs(); + } strcpy(reply, "ok"); } else { strcpy(reply, "can't find custom var"); diff --git a/src/helpers/CommonCLI.h b/src/helpers/CommonCLI.h index fcc38bb7..24e82935 100644 --- a/src/helpers/CommonCLI.h +++ b/src/helpers/CommonCLI.h @@ -68,6 +68,7 @@ public: uint8_t advert_loc_policy = 0; uint32_t discovery_mod_timestamp = 0; float adc_multiplier = 0; + float ina_shunt_mohm = 0; // CUSTOM (TeTeHacko): INA shunt in mOhm, 0 = build default char owner_info[120]; uint8_t rx_boosted_gain = 0; // power settings uint8_t radio_fem_rxgain = 0; // LoRa FEM RX gain setting @@ -225,6 +226,7 @@ private: protected: void structure() override { def("adc_mult", _parent->adc_multiplier); + def("ina_shunt", _parent->ina_shunt_mohm); def("pwr_sav_en", _parent->powersaving_enabled); def("bicon", _parent->batt_icon); def("bicon_lo", _parent->batt_icon_lo); diff --git a/src/helpers/SensorManager.h b/src/helpers/SensorManager.h index d5b109de..ce55975a 100644 --- a/src/helpers/SensorManager.h +++ b/src/helpers/SensorManager.h @@ -1,6 +1,7 @@ #pragma once #include +#include #include "sensors/LocationProvider.h" #define TELEM_PERM_BASE 0x01 // 'base' permission includes battery @@ -60,6 +61,15 @@ public: // With a periodic collector that costs one cycle and needs no scheduling. virtual void requestLocationRefresh() { } + // CUSTOM (TeTeHacko): the INA shunt (mOhm) from prefs back into the driver + // after boot; 0 = keep the build's value. A no-op without an INA chip. + void applyInaShunt(float mohm) { + if (mohm <= 0) return; + char v[16]; + snprintf(v, sizeof(v), "%.3f", mohm); + setSettingValue("ina.shunt", v); + } + // Live I2C scan, written into dest as text. Returns the number of devices // that answered, or -1 when the platform has no bus to scan. // diff --git a/src/helpers/sensors/EnvironmentSensorManager.cpp b/src/helpers/sensors/EnvironmentSensorManager.cpp index 13300291..8d8b8dbe 100644 --- a/src/helpers/sensors/EnvironmentSensorManager.cpp +++ b/src/helpers/sensors/EnvironmentSensorManager.cpp @@ -114,6 +114,9 @@ static Adafruit_INA3221 INA3221; #ifndef TELEM_INA219_ADDRESS #define TELEM_INA219_ADDRESS 0x40 // INA219 single channel current sensor I2C address #endif +#ifndef TELEM_INA219_SHUNT_VALUE +#define TELEM_INA219_SHUNT_VALUE 0.100 // CUSTOM (TeTeHacko): what Adafruit's calibration assumes +#endif #include static Adafruit_INA219 INA219(TELEM_INA219_ADDRESS); #endif @@ -146,6 +149,18 @@ static class INA226 INA226_ALT(TELEM_INA226_ALT_ADDR(TELEM_INA226_ADDRESS), TELE static class INA226* active_ina226 = &INA226; // `class`: the object INA226 hides the type #endif +#if ENV_INCLUDE_INA219 || ENV_INCLUDE_INA226 || ENV_INCLUDE_INA3221 +// CUSTOM (TeTeHacko): the shunt is a property of the module, not of the +// firmware -- `sensor set ina.shunt `, kept in prefs (ina_shunt), 0 = the +// build's value for the chip. INA219/INA226 current is computed here from the +// shunt voltage (as in the Chytra Budka), so a new value needs no recalibration; +// INA3221 gets it through its driver. +static float ina_shunt_mohm = 0; +static float ina_shunt_ohm(float build_default) { + return ina_shunt_mohm > 0 ? ina_shunt_mohm / 1000.0f : build_default; +} +#endif + #if ENV_INCLUDE_MLX90614 #ifndef TELEM_MLX90614_ADDRESS #define TELEM_MLX90614_ADDRESS 0x5A // MLX90614 IR temperature sensor I2C address @@ -326,7 +341,7 @@ static void query_lps22hb(uint8_t ch, uint8_t, CayenneLPP& lpp) { static uint8_t init_ina3221(TwoWire* wire, uint8_t addr) { if (!INA3221.begin(addr, wire)) return 0; for (int i = 0; i < TELEM_INA3221_NUM_CHANNELS; i++) { - INA3221.setShuntResistance(i, TELEM_INA3221_SHUNT_VALUE); + INA3221.setShuntResistance(i, ina_shunt_ohm(TELEM_INA3221_SHUNT_VALUE)); } // Each enabled hardware channel becomes its own telemetry channel. uint8_t enabled = 0; @@ -401,9 +416,11 @@ static void query_ina219(uint8_t ch, uint8_t, CayenneLPP& lpp) { // begin() selects 12-bit single-sample bus and shunt conversions, 532 us each: // 3 ms covers the wake-up and one fresh pair with margin. delay(3); - lpp.addVoltage(ch, active_ina219->getBusVoltage_V()); - lpp.addCurrent(ch, active_ina219->getCurrent_mA() / 1000.0f); - lpp.addPower(ch, active_ina219->getPower_mW() / 1000.0f); + const float volts = active_ina219->getBusVoltage_V(); + const float amps = active_ina219->getShuntVoltage_mV() / 1000.0f / ina_shunt_ohm(TELEM_INA219_SHUNT_VALUE); + lpp.addVoltage(ch, volts); + lpp.addCurrent(ch, amps); + lpp.addPower(ch, volts * amps); active_ina219->powerSave(true); } #endif @@ -451,9 +468,11 @@ static void query_ina226(uint8_t ch, uint8_t, CayenneLPP& lpp) { ina->shutDown(); return; } - lpp.addVoltage(ch, ina->getBusVoltage()); - lpp.addCurrent(ch, ina->getCurrent_mA() / 1000.0f); - lpp.addPower(ch, ina->getPower_mW() / 1000.0f); + const float volts = ina->getBusVoltage(); + const float amps = ina->getShuntVoltage() / ina_shunt_ohm(TELEM_INA226_SHUNT_VALUE); + lpp.addVoltage(ch, volts); + lpp.addCurrent(ch, amps); + lpp.addPower(ch, volts * amps); ina->shutDown(); } #endif @@ -820,11 +839,21 @@ bool EnvironmentSensorManager::querySensors(uint8_t requester_permissions, Cayen } +// CUSTOM (TeTeHacko): an INA chip whose shunt `ina.shunt` applies to is active. +bool EnvironmentSensorManager::hasShuntIna() const { + for (int j = 0; j < _active_sensor_count; j++) { + const char* n = _active_sensors[j].name; + if (n && (strcmp(n, "INA219") == 0 || strcmp(n, "INA226") == 0 || strcmp(n, "INA3221") == 0)) return true; + } + return false; +} + int EnvironmentSensorManager::getNumSettings() const { int settings = 0; #if ENV_INCLUDE_GPS if (gps_detected) settings += 1; // GPS enablement #endif + if (hasShuntIna()) settings += 1; // ina.shunt return settings; } @@ -835,6 +864,7 @@ const char* EnvironmentSensorManager::getSettingName(int i) const { return "gps"; } #endif + if (hasShuntIna() && i == settings++) return "ina.shunt"; return NULL; } @@ -849,10 +879,34 @@ const char* EnvironmentSensorManager::getSettingValue(int i) const { return _location->isGpsOn() ? "1" : "0"; } #endif + #if ENV_INCLUDE_INA219 || ENV_INCLUDE_INA226 || ENV_INCLUDE_INA3221 + if (hasShuntIna() && i == settings++) { + static char buf[16]; // mOhm; 0 = the build's value + snprintf(buf, sizeof(buf), "%.3f", ina_shunt_mohm); + return buf; + } + #endif return NULL; } bool EnvironmentSensorManager::setSettingValue(const char* name, const char* value) { + #if ENV_INCLUDE_INA219 || ENV_INCLUDE_INA226 || ENV_INCLUDE_INA3221 + if (strcmp(name, "ina.shunt") == 0) { + if (!hasShuntIna()) return false; + // a number of mOhm, 0 = the build's value; atof() alone would take "nan" + const char* c = value; + if (!((*c >= '0' && *c <= '9') || *c == '.')) return false; + float mohm = atof(value); + if (!(mohm >= 0.0f && mohm <= 10000.0f)) return false; + ina_shunt_mohm = mohm; + #if ENV_INCLUDE_INA3221 + for (int i = 0; i < TELEM_INA3221_NUM_CHANNELS; i++) { + INA3221.setShuntResistance(i, ina_shunt_ohm(TELEM_INA3221_SHUNT_VALUE)); + } + #endif + return true; + } + #endif #if ENV_INCLUDE_GPS if (gps_detected && strcmp(name, "gps") == 0) { if (strcmp(value, "0") == 0) { diff --git a/src/helpers/sensors/EnvironmentSensorManager.h b/src/helpers/sensors/EnvironmentSensorManager.h index 254f0f57..a29d59d0 100644 --- a/src/helpers/sensors/EnvironmentSensorManager.h +++ b/src/helpers/sensors/EnvironmentSensorManager.h @@ -58,4 +58,5 @@ public: const char* getSettingValue(int i) const override; bool setSettingValue(const char* name, const char* value) override; int scanI2C(char* dest, size_t max_len) override; + bool hasShuntIna() const; // CUSTOM (TeTeHacko): `ina.shunt` applies }; From b06fd957b9407ae0cb54e2adc427e4260a68843f Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Thu, 12 Nov 2026 14:20:29 +0100 Subject: [PATCH 02/10] radio: RX duty cycle (RXPS) from EasySkyMesh PowerSaving v18, opt-in Co-Authored-By: Claude Opus 5.5 --- examples/simple_repeater/MyMesh.cpp | 13 + examples/simple_room_server/MyMesh.cpp | 9 + examples/simple_sensor/SensorMesh.cpp | 9 + src/helpers/CommonCLI.h | 13 + src/helpers/CommonRadioPrefs.cpp | 66 +++++ src/helpers/CommonRadioPrefs.h | 16 ++ src/helpers/radiolib/CustomSX1262.h | 65 +++++ src/helpers/radiolib/CustomSX1262Wrapper.h | 49 ++++ src/helpers/radiolib/RXPowerSaving.cpp | 251 +++++++++++++++++++ src/helpers/radiolib/RXPowerSaving.h | 278 +++++++++++++++++++++ src/helpers/radiolib/RXPowerSavingCLI.cpp | 274 ++++++++++++++++++++ src/helpers/radiolib/RXPowerSavingCLI.h | 18 ++ src/helpers/radiolib/RadioLibWrappers.cpp | 249 ++++++++++++++++++ src/helpers/radiolib/RadioLibWrappers.h | 77 +++++- 14 files changed, 1386 insertions(+), 1 deletion(-) create mode 100644 src/helpers/radiolib/RXPowerSaving.cpp create mode 100644 src/helpers/radiolib/RXPowerSaving.h create mode 100644 src/helpers/radiolib/RXPowerSavingCLI.cpp create mode 100644 src/helpers/radiolib/RXPowerSavingCLI.h diff --git a/examples/simple_repeater/MyMesh.cpp b/examples/simple_repeater/MyMesh.cpp index c9b24501..fd0a7a9b 100644 --- a/examples/simple_repeater/MyMesh.cpp +++ b/examples/simple_repeater/MyMesh.cpp @@ -1514,6 +1514,9 @@ void MyMesh::begin(FILESYSTEM *fs) { radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr); radio_driver.setTxPower(_prefs.tx_power_dbm); +#ifdef WITH_RX_POWERSAVING + _prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw); // CUSTOM (TeTeHacko) +#endif radio_driver.setRxBoostedGainMode(_prefs.rx_boosted_gain); MESH_DEBUG_PRINTLN("RX Boosted Gain Mode: %s", @@ -1938,12 +1941,18 @@ void MyMesh::loop() { if (set_radio_at && millisHasNowPassed(set_radio_at)) { // apply pending (temporary) radio params set_radio_at = 0; // clear timer radio_driver.setParams(pending_freq, pending_bw, pending_sf, pending_cr); +#ifdef WITH_RX_POWERSAVING + _prefs.getRadioPrefs()->applyRxPowerSaving(pending_sf, pending_bw); // timing is in symbols +#endif MESH_DEBUG_PRINTLN("Temp radio params"); } if (revert_radio_at && millisHasNowPassed(revert_radio_at)) { // revert radio params to orig revert_radio_at = 0; // clear timer radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr); +#ifdef WITH_RX_POWERSAVING + _prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw); +#endif MESH_DEBUG_PRINTLN("Radio params restored"); } @@ -1971,6 +1980,10 @@ void MyMesh::loop() { bool MyMesh::hasPendingWork() const { #if defined(WITH_BRIDGE) if (bridge.isRunning()) return true; // bridge needs WiFi radio, can't sleep +#endif +#ifdef WITH_RX_POWERSAVING + // no MCU sleep while the noise-floor window samples RSSI + if (radio_driver.isRxPowerSavingCalibrationActive()) return true; #endif return _mgr->getOutboundTotal() > 0; } diff --git a/examples/simple_room_server/MyMesh.cpp b/examples/simple_room_server/MyMesh.cpp index 023201c4..e92fa4e0 100644 --- a/examples/simple_room_server/MyMesh.cpp +++ b/examples/simple_room_server/MyMesh.cpp @@ -735,6 +735,9 @@ void MyMesh::begin(FILESYSTEM *fs) { radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr); radio_driver.setTxPower(_prefs.tx_power_dbm); +#ifdef WITH_RX_POWERSAVING + _prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw); // CUSTOM (TeTeHacko) +#endif radio_driver.setRxBoostedGainMode(_prefs.rx_boosted_gain); board.attachDynamicPrefs(_prefs.getCustom()); @@ -1073,12 +1076,18 @@ void MyMesh::loop() { if (set_radio_at && millisHasNowPassed(set_radio_at)) { // apply pending (temporary) radio params set_radio_at = 0; // clear timer radio_driver.setParams(pending_freq, pending_bw, pending_sf, pending_cr); +#ifdef WITH_RX_POWERSAVING + _prefs.getRadioPrefs()->applyRxPowerSaving(pending_sf, pending_bw); +#endif MESH_DEBUG_PRINTLN("Temp radio params"); } if (revert_radio_at && millisHasNowPassed(revert_radio_at)) { // revert radio params to orig revert_radio_at = 0; // clear timer radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr); +#ifdef WITH_RX_POWERSAVING + _prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw); +#endif MESH_DEBUG_PRINTLN("Radio params restored"); } diff --git a/examples/simple_sensor/SensorMesh.cpp b/examples/simple_sensor/SensorMesh.cpp index fafb4fe0..a7dd69a5 100644 --- a/examples/simple_sensor/SensorMesh.cpp +++ b/examples/simple_sensor/SensorMesh.cpp @@ -862,6 +862,9 @@ void SensorMesh::begin(FILESYSTEM* fs) { radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr); radio_driver.setTxPower(_prefs.tx_power_dbm); +#ifdef WITH_RX_POWERSAVING + _prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw); // CUSTOM (TeTeHacko) +#endif board.attachDynamicPrefs(_prefs.getCustom()); @@ -1024,12 +1027,18 @@ void SensorMesh::loop() { if (set_radio_at && millisHasNowPassed(set_radio_at)) { // apply pending (temporary) radio params set_radio_at = 0; // clear timer radio_driver.setParams(pending_freq, pending_bw, pending_sf, pending_cr); +#ifdef WITH_RX_POWERSAVING + _prefs.getRadioPrefs()->applyRxPowerSaving(pending_sf, pending_bw); +#endif MESH_DEBUG_PRINTLN("Temp radio params"); } if (revert_radio_at && millisHasNowPassed(revert_radio_at)) { // revert radio params to orig revert_radio_at = 0; // clear timer radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr); +#ifdef WITH_RX_POWERSAVING + _prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw); +#endif MESH_DEBUG_PRINTLN("Radio params restored"); } diff --git a/src/helpers/CommonCLI.h b/src/helpers/CommonCLI.h index 24e82935..8fe0672e 100644 --- a/src/helpers/CommonCLI.h +++ b/src/helpers/CommonCLI.h @@ -71,6 +71,9 @@ public: float ina_shunt_mohm = 0; // CUSTOM (TeTeHacko): INA shunt in mOhm, 0 = build default char owner_info[120]; uint8_t rx_boosted_gain = 0; // power settings +#ifdef WITH_RX_POWERSAVING + RxPowerSavingConfig rxps; // CUSTOM (TeTeHacko): RX duty cycle, off by default +#endif uint8_t radio_fem_rxgain = 0; // LoRa FEM RX gain setting uint8_t radio_fem_txgain = 0; // LoRa FEM TX gain setting uint8_t path_hash_mode = 0; // which path mode to use when sending @@ -125,10 +128,20 @@ private: def("agc_int", _parent->agc_reset_interval); def("hash_mode", _parent->path_hash_mode); def("multi_ack", _parent->multi_acks); +#ifdef WITH_RX_POWERSAVING + def("rxps_en", _parent->rxps.enabled); + def("rxps_rx_us", _parent->rxps.rx_us); + def("rxps_sleep_us", _parent->rxps.sleep_us); + def("rxps_level", _parent->rxps.level); + def("rxps_preamble", _parent->rxps.preamble); +#endif def("rsilence", _parent->radio_silence_min); } public: RadioPrefs(NodePrefs* parent) : _parent(parent) { } +#ifdef WITH_RX_POWERSAVING + RxPowerSavingConfig* getRxPowerSavingConfig() override { return &_parent->rxps; } +#endif // CommonRadioPrefs interface float getFreq() const override { return _parent->freq; } void setFreq(float f) override { _parent->freq = f; markDirty(); } diff --git a/src/helpers/CommonRadioPrefs.cpp b/src/helpers/CommonRadioPrefs.cpp index 44e0eba3..70064cef 100644 --- a/src/helpers/CommonRadioPrefs.cpp +++ b/src/helpers/CommonRadioPrefs.cpp @@ -3,6 +3,9 @@ #include "Utils.h" #include "target.h" #include +#ifdef WITH_RX_POWERSAVING +#include "radiolib/RXPowerSavingCLI.h" +#endif namespace { @@ -17,8 +20,35 @@ bool looksLikeANumber(const char* s) { return isdigit((unsigned char)*s) || *s == '.'; } +#ifdef WITH_RX_POWERSAVING +RxPowerSavingControl* rxpsControl() { +#ifdef WRAPPER_CLASS + return &radio_driver; +#else + return nullptr; +#endif +} +#endif + } // namespace +#ifdef WITH_RX_POWERSAVING +bool CommonRadioPrefs::applyRxPowerSaving(uint8_t sf, float bw) { + _active_sf = sf; + _active_bw = bw; + RxPowerSavingConfig* config = getRxPowerSavingConfig(); + if (!config) return false; + // temporary radio parameters must not overwrite the saved automatic periods + RxPowerSavingConfig active = *config; + return applyRxPowerSavingConfig(&active, sf, bw, rxpsControl()); +} + +bool CommonRadioPrefs::isRxPowerSavingCalibrationActive() const { + const auto* control = rxpsControl(); + return control && control->isRxPowerSavingCalibrationActive(); +} +#endif + bool CommonRadioPrefs::getByKey(const char* key, char* value, size_t max_len) { if (strcmp(key, "fem_rxgain") == 0) { snprintf(value, max_len, "%d", (uint32_t)getFEMRxGain()); @@ -45,6 +75,30 @@ bool CommonRadioPrefs::setByKey(const char* key, const char* value) { } bool CommonRadioPrefs::handleCommand(const char* command, uint32_t sender_timestamp, char* reply) { +#ifdef WITH_RX_POWERSAVING + if (strncmp(command, "get radio.rxps", 14) == 0 && (command[14] == 0 || command[14] == ' ')) { + const char* suffix = command + 14; + while (*suffix == ' ') ++suffix; + if (*suffix) return false; + auto* config = getRxPowerSavingConfig(); + if (!config) { strcpy(reply, "Error: unsupported"); return true; } + const uint8_t sf = _active_sf ? _active_sf : getSpreadFactor(); + const float bw = _active_sf ? _active_bw : getBandwidth(); + RxPowerSavingConfig active = *config; + normalizeRxPowerSavingConfig(&active, sf, bw, + rxPowerSavingCaptureCost(rxpsControl()), rxPowerSavingTransition(rxpsControl())); + RXPowerSavingCLI::get(&active, rxpsControl(), sf, bw, reply, 160); + return true; + } + if (strncmp(command, "set radio.rxps ", 15) == 0) { + auto* config = getRxPowerSavingConfig(); + if (!config) { strcpy(reply, "Error: unsupported"); return true; } + if (RXPowerSavingCLI::set(command + 15, + _active_sf ? _active_sf : getSpreadFactor(), _active_sf ? _active_bw : getBandwidth(), + config, rxpsControl(), reply, 160)) markDirty(); + return true; + } +#endif if (strcmp(command, "get radio") == 0) { char freq[16], bw[16]; strcpy(freq, StrHelper::ftoa(getFreq())); @@ -66,7 +120,19 @@ bool CommonRadioPrefs::handleCommand(const char* command, uint32_t sender_timest setCodingRate(cr); setFreq(freq); setBandwidth(bw); +#ifdef WITH_RX_POWERSAVING + // the RXPS timing is in symbols: a new SF/BW can make it invalid + auto* rxps = getRxPowerSavingConfig(); + const bool timing_ok = !rxps || !rxps->enabled || normalizeRxPowerSavingConfig( + rxps, sf, bw, rxPowerSavingCaptureCost(rxpsControl()), rxPowerSavingTransition(rxpsControl())); + if (!timing_ok && rxpsControl()) { + rxpsControl()->setRxPowerSaving(false, rxps->rx_us, rxps->sleep_us); + rxpsControl()->setRxPowerSavingConfigError(true); + } + strcpy(reply, timing_ok ? "OK - reboot to apply" : "OK - reboot to apply; RXPS continuous: invalid timing"); +#else strcpy(reply, "OK - reboot to apply"); +#endif } else { strcpy(reply, "Error, invalid radio params"); } diff --git a/src/helpers/CommonRadioPrefs.h b/src/helpers/CommonRadioPrefs.h index d0083b8c..8a56b8a8 100644 --- a/src/helpers/CommonRadioPrefs.h +++ b/src/helpers/CommonRadioPrefs.h @@ -1,9 +1,16 @@ #pragma once #include "ConfigSerializer.h" #include "KeyValueStore.h" +#ifdef WITH_RX_POWERSAVING +#include "radiolib/RXPowerSaving.h" +#endif class CommonRadioPrefs : public ConfigSerializer, public KeyValueStore { bool _is_dirty = false; +#ifdef WITH_RX_POWERSAVING + uint8_t _active_sf = 0; // what the radio runs now (tempradio differs from prefs) + float _active_bw = 0; +#endif protected: CommonRadioPrefs() { } public: @@ -64,6 +71,15 @@ public: bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply); +#ifdef WITH_RX_POWERSAVING + // CUSTOM (TeTeHacko): RXPS, see radiolib/RXPowerSaving.h. Prefs that carry an + // RXPS config override getRxPowerSavingConfig(); apply after every change of + // the radio's SF/BW (the timing is in symbols). + virtual RxPowerSavingConfig* getRxPowerSavingConfig() { return nullptr; } + bool applyRxPowerSaving(uint8_t sf, float bw); + bool isRxPowerSavingCalibrationActive() const; +#endif + bool setByKey(const char* key, const char* value) override; // for dynamic key/value access bool getByKey(const char* key, char* value, size_t max_len) override; }; diff --git a/src/helpers/radiolib/CustomSX1262.h b/src/helpers/radiolib/CustomSX1262.h index e49ee64d..70b0c59f 100644 --- a/src/helpers/radiolib/CustomSX1262.h +++ b/src/helpers/radiolib/CustomSX1262.h @@ -2,6 +2,9 @@ #include #include "MeshCore.h" +#ifdef WITH_RX_POWERSAVING +#include "RXPowerSaving.h" // MC_TCXO_DELAY_US +#endif class CustomSX1262 : public SX1262 { uint32_t _preambleMillis = 66; @@ -12,6 +15,68 @@ class CustomSX1262 : public SX1262 { public: CustomSX1262(Module *mod) : SX1262(mod) { } +#ifdef WITH_RX_POWERSAVING + // CUSTOM (TeTeHacko): RXPS support, from EasySkyMesh PowerSaving v18. + // The sleep -> RX transition RadioLib subtracts from a duty-cycle sleep; + // protected in the RadioLib base, read through here. + uint32_t getTcxoDelay() const { return tcxoDelay; } + + // RadioLib's begin() installs a 5000 us TCXO startup delay, which is also the + // floor of every duty-cycle sleep. MC_TCXO_DELAY_US (1600, 4x the worst of + // five measured modules) is written afterwards and the RC calibrations redone. + // Every variant reaches the radio through this class (std_init() calls it). + int16_t begin(float freq = 434.0, float bw = 125.0, uint8_t sf = 9, uint8_t cr = 7, + uint8_t syncWord = RADIOLIB_SX126X_SYNC_WORD_PRIVATE, int8_t power = 10, + uint16_t preambleLength = 8, float tcxoVoltage = 1.6, + bool useRegulatorLDO = false) { + int16_t state = SX1262::begin(freq, bw, sf, cr, syncWord, power, preambleLength, + tcxoVoltage, useRegulatorLDO); + if (state == RADIOLIB_ERR_NONE) state = applyMeshCoreTcxoDelay(); + return state; + } + + // tcxoVoltage read back from the chip object: begin() zeroes it when it falls + // back to an XTAL, and a TCXO supply on DIO3 of a board without one is worse + // than a long delay. + int16_t applyMeshCoreTcxoDelay() { + if (tcxoVoltage <= 0.0f) return RADIOLIB_ERR_NONE; + int16_t state = setTCXO(tcxoVoltage, MC_TCXO_DELAY_US); + RADIOLIB_ASSERT(state); + state = calibrate(RADIOLIB_SX126X_CALIBRATE_ALL); + delay(50); + return state; + } + + int16_t startReceiveDutyCycle(uint32_t rxPeriod, uint32_t sleepPeriod, + RadioLibIrqFlags_t irqFlags = RADIOLIB_IRQ_RX_DEFAULT_FLAGS, + RadioLibIrqFlags_t irqMask = RADIOLIB_IRQ_RX_DEFAULT_MASK) { + int16_t state = SX1262::startReceiveDutyCycle(rxPeriod, sleepPeriod, irqFlags, irqMask); + if (state == RADIOLIB_ERR_NONE) { + // RadioLib stages RX through standby, which leaves a host-controlled + // RXEN switch in IDLE; set it back to RX for the whole duty cycle. + this->mod->setRfSwitchState(Module::MODE_RX); + } + return state; + } + + // BUSY is high in the duty cycle's sleep phase. + bool isChipBusy() { + uint32_t busy = this->mod->getGpio(); + return busy != RADIOLIB_NC && this->mod->hal->digitalRead(busy); + } + + int16_t stopRTC() { + uint8_t rtcStop = 0x00; + int16_t state = writeRegister(RADIOLIB_SX126X_REG_RTC_CTRL, &rtcStop, 1); + RADIOLIB_ASSERT(state); + uint8_t rtcEvent = 0; + state = readRegister(RADIOLIB_SX126X_REG_EVENT_MASK, &rtcEvent, 1); + RADIOLIB_ASSERT(state); + rtcEvent |= 0x02; + return writeRegister(RADIOLIB_SX126X_REG_EVENT_MASK, &rtcEvent, 1); + } +#endif + #ifdef RP2040_PLATFORM bool std_init(SPIClassRP2040* spi = NULL) #else diff --git a/src/helpers/radiolib/CustomSX1262Wrapper.h b/src/helpers/radiolib/CustomSX1262Wrapper.h index 3f16dc3d..fd37821e 100644 --- a/src/helpers/radiolib/CustomSX1262Wrapper.h +++ b/src/helpers/radiolib/CustomSX1262Wrapper.h @@ -12,7 +12,19 @@ class CustomSX1262Wrapper : public RadioLibWrapper { public: CustomSX1262Wrapper(CustomSX1262& radio, mesh::MainBoard& board) : RadioLibWrapper(radio, board) { } +#ifdef WITH_RX_POWERSAVING + // The duty-cycle sleep floor is this board's TCXO delay + 1000 us (RadioLib + // subtracts it from the sleep; below it the register underflows). + uint32_t rxPowerSavingTransitionUs() const override { + return ((CustomSX1262 *)_radio)->getTcxoDelay() + 1000; + } + bool supportsRxPowerSaving() const override { return true; } +#endif + void setParams(float freq, float bw, uint8_t sf, uint8_t cr) override { +#ifdef WITH_RX_POWERSAVING + prepareForRadioConfig(); +#endif ((CustomSX1262 *)_radio)->setFrequency(freq); ((CustomSX1262 *)_radio)->setSpreadingFactor(sf); ((CustomSX1262 *)_radio)->setBandwidth(bw); @@ -29,8 +41,17 @@ public: return crc; } bool isReceivingPacket() override { +#ifdef WITH_RX_POWERSAVING + // In the sleep phase (BUSY high) an SPI probe of the IRQ flags would wake the + // chip and break the cycle -- and there is nothing to receive. Outside RXPS + // this stays a real channel check: Dispatcher::checkSend() relies on it. + if (_rx_ps_armed && ((CustomSX1262 *)_radio)->isChipBusy()) return false; +#endif return ((CustomSX1262 *)_radio)->isReceiving(); } +#ifdef WITH_RX_POWERSAVING + bool isChipBusy() override { return ((CustomSX1262 *)_radio)->isChipBusy(); } +#endif #if defined(LORA_POLL_IRQ) || defined(PIN_DIAG) // CUSTOM (TeTeHacko): SX126x native status bits. TIMEOUT is in the mask because // an RX window that expires has to end the wait too -- with the DIO1 line dead @@ -42,8 +63,10 @@ public: float getCurrentRSSI() override { return ((CustomSX1262 *)_radio)->getRSSI(false); } +#ifndef WITH_RX_POWERSAVING // with it, the base class answers from the values cached at RX float getLastRSSI() const override { return ((CustomSX1262 *)_radio)->getRSSI(); } float getLastSNR() const override { return ((CustomSX1262 *)_radio)->getSNR(); } +#endif float packetScore(float snr, int packet_len) override { int sf = ((CustomSX1262 *)_radio)->spreadingFactor; @@ -51,11 +74,17 @@ public: } uint8_t getSpreadingFactor() const override { return ((CustomSX1262 *)_radio)->spreadingFactor; } virtual void powerOff() override { +#ifdef WITH_RX_POWERSAVING + if (_rx_ps_armed) stopReceiveDutyCycle(); +#endif ((CustomSX1262 *)_radio)->sleep(false); } bool supportsRxBoostedGain() const override { return true; } bool setRxBoostedGainMode(bool en) override { +#ifdef WITH_RX_POWERSAVING + prepareForRadioConfig(); +#endif return ((CustomSX1262 *)_radio)->setRxBoostedGainMode(en) == RADIOLIB_ERR_NONE; } bool getRxBoostedGainMode() const override { @@ -64,6 +93,26 @@ public: void doResetAGC() override { sx126xResetAGC((SX126x *)_radio, getRxBoostedGainMode()); } +#ifdef WITH_RX_POWERSAVING +protected: + int16_t armDutyCycle(RadioLibIrqFlags_t irq_flags, RadioLibIrqFlags_t irq_mask, + uint32_t* eff_rx_us, uint32_t* eff_sleep_us) override { + // RadioLib programs exactly what is asked (it subtracts the wake-up + // transition from the sleep internally). + *eff_rx_us = _rx_ps_rx_us; + *eff_sleep_us = _rx_ps_sleep_us; + return ((CustomSX1262 *)_radio)->startReceiveDutyCycle(_rx_ps_rx_us, _rx_ps_sleep_us, irq_flags, irq_mask); + } + int16_t stopDutyCycleHardware() override { + int16_t standby_err = _radio->standby(); + int16_t rtc_err = ((CustomSX1262 *)_radio)->stopRTC(); + return standby_err != RADIOLIB_ERR_NONE ? standby_err : rtc_err; + } + // continuous RX keeps the preamble-detect IRQ, like CustomSX1262::startReceive() + int16_t startContinuousReceive() override { return ((CustomSX1262 *)_radio)->startReceive(); } +public: +#endif + #ifdef RADIO_DIAG protected: // CUSTOM (TeTeHacko): `radiostat`, chip side. mode: 2 STBY_RC, 3 STBY_XOSC, diff --git a/src/helpers/radiolib/RXPowerSaving.cpp b/src/helpers/radiolib/RXPowerSaving.cpp new file mode 100644 index 00000000..5461bb11 --- /dev/null +++ b/src/helpers/radiolib/RXPowerSaving.cpp @@ -0,0 +1,251 @@ +// CUSTOM (TeTeHacko): from EasySkyMesh PowerSaving v18 (IoTThinks/MeshCore, +// MIT, https://github.com/IoTThinks/MeshCore/tree/PowerSaving-v18) -- RXPS, the +// SX126x/LR11x0 RX duty cycle. Compiled only with -D WITH_RX_POWERSAVING. +#ifdef WITH_RX_POWERSAVING +#include "RXPowerSaving.h" +#include + +static uint32_t ceilRxPowerSavingValue(float value) { + uint32_t rounded = (uint32_t)value; + return value > (float)rounded ? rounded + 1 : rounded; +} + +// Both radios program their duty cycle in 15.625 us ticks and truncate the +// microsecond value on the way in, so a period of 10013 us is really 10000 us +// on air while the CLI happily reports 10013. Snapping to the nearest tick and +// returning the smallest microsecond value that still lands on it makes the +// reported periods the ones the hardware runs - which matters here, because the +// register value turned out to be what a duty-cycle defect keys on, not the +// microseconds we asked for. +static uint32_t rxPowerSavingTickToUs(uint64_t tick) { + if (tick == 0) tick = 1; + return (uint32_t)((tick * 125 + 7) / 8); // ceil(tick * 15.625) +} + +static uint32_t snapRxPowerSavingToTick(uint32_t us) { + return rxPowerSavingTickToUs(((uint64_t)us * 8 + 62) / 125); // nearest +} + +// Rounding the listen window to the *nearest* tick can shave a few microseconds +// off, and the timer guard below has no room to give: it must hold with the +// register values the radio actually runs. So that one rounds up. +static uint32_t snapRxPowerSavingUpToTick(uint32_t us) { + return rxPowerSavingTickToUs(((uint64_t)us * 8 + 124) / 125); // ceil +} + +bool isValidRxPowerSavingPeriod(uint32_t us) { + return us >= RX_POWERSAVING_MIN_PERIOD_US && us <= RX_POWERSAVING_MAX_PERIOD_US; +} + +uint8_t rxPowerSavingPreambleForSF(uint8_t sf) { + return sf <= 8 ? 32 : 16; +} + +bool isRxPowerSavingNumeric(const char* value) { + if (value == nullptr || *value == 0) return false; + while (*value) { + if (*value < '0' || *value > '9') return false; + value++; + } + return true; +} + +float rxPowerSavingCaptureCost(const RxPowerSavingControl* control) { + return control != nullptr ? control->rxPowerSavingCaptureCostSymbols() + : RX_POWERSAVING_CAPTURE_COST_SYMBOLS; +} + +uint32_t rxPowerSavingTransition(const RxPowerSavingControl* control) { + return control != nullptr ? control->rxPowerSavingTransitionUs() + : RX_POWERSAVING_TRANSITION_US; +} + +// rxPeriod register values measured to break SetRxDutyCycle on SX1262: the +// radio latches the preamble and then never validates a header, losing 35% of +// packets at SF6 and all of them at SF7. Both were reproduced on two boards +// with an LR1110 witnessing 100% of the same transmissions, and both bands are +// exactly one tick wide - 639 and 641 are lossless. +// +// This list is certainly incomplete: about thirty values were sampled out of +// the thousands a profile can generate. Levels 1-10 do not need it because the +// timer guard makes any value safe; it exists only for the unguarded maximum, +// where it is the one protection left. +static const uint32_t RX_POWERSAVING_BAD_RX_TICKS[] = {320, 640}; + +static uint32_t avoidBadRxPowerSavingTick(uint32_t rx_us) { + const uint32_t tick = (rx_us * 8) / 125; + for (uint32_t bad : RX_POWERSAVING_BAD_RX_TICKS) { + // One tick longer costs 15.625 us of listening and steps clear of the band. + if (tick == bad) return (uint32_t)((((uint64_t)tick + 1) * 125 + 7) / 8); + } + return rx_us; +} + +bool calcRxPowerSavingLevel(uint8_t level, uint8_t sf, float bw, uint8_t preamble, + uint32_t* rx_us, uint32_t* sleep_us, + float capture_cost_symbols, uint32_t transition_us) { + if (rx_us == nullptr || sleep_us == nullptr || level < 1 || + level > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL || sf < 5 || sf > 12 || + !isfinite(bw) || bw <= 0.0f || !isfinite(capture_cost_symbols) || + capture_cost_symbols <= 0 || capture_cost_symbols >= preamble || transition_us >= RX_POWERSAVING_MAX_PERIOD_US || (preamble != 16 && preamble != 32)) { + return false; + } + const bool unguarded = isRxPowerSavingUnguardedLevel(level); + + const float symbol_us = (1000.0f * (float)(1UL << sf)) / bw; + if (!isfinite(symbol_us) || symbol_us * 64.0f > (float)(UINT32_MAX / 8)) return false; + // Worst case a preamble starts the instant an RX window closes, so the part + // that survives into the next window is `preamble - sleep`. The absolute + // limit is therefore reached when that equals the chip's capture cost; the + // unguarded levels are pinned to geometries measured at or past that point, + // which is why they still need it. + const float sleep_edge_symbols = (float)preamble - capture_cost_symbols; + + float sleep_symbols; + float rx_symbols = 0.0f; // only used by the unguarded levels + if (unguarded) { + // Kept on the old interpolation because that is the geometry the bench + // measured: overdrive is the top of the profile, and `riskyWorkingMax` is + // the point past it where delivery started to fall. + float amount = 1.0f; + if (isRxPowerSavingRiskyWorkingMaxLevel(level)) { + const float virtual_level = preamble == 16 ? RX_POWERSAVING_RISKY_WORKING_MAX_VIRTUAL_P16 + : RX_POWERSAVING_RISKY_WORKING_MAX_VIRTUAL_P32; + amount = (virtual_level - 1.0f) / 9.0f; + } + const float rx_start_symbols = preamble == 16 ? 12.0f : 16.0f; + const float sleep_start_symbols = preamble == 16 ? 2.0f : 15.0f; + rx_symbols = rx_start_symbols + amount * (8.0f - rx_start_symbols); + sleep_symbols = sleep_start_symbols + amount * (sleep_edge_symbols - sleep_start_symbols); + } else { + // Guarded levels state their catch directly, so the sleep is just what is + // left of the preamble - no capture cost involved. The pad makes the node + // catch a fifth of a symbol more than promised, which is what keeps the + // generated register pairs off the defective ones. + const float catch_symbols = rxPowerSavingLevelCatch(level, preamble); + // A level that undertakes to catch less than this radio needs to latch is + // not usable: say so rather than return a geometry that cannot work. + if (catch_symbols < capture_cost_symbols) return false; + sleep_symbols = (float)preamble - catch_symbols - RX_POWERSAVING_MARGIN_PAD_SYMBOLS; + if (sleep_symbols < 0.0f) sleep_symbols = 0.0f; + } + + *sleep_us = (uint32_t)(sleep_symbols * symbol_us); + + // Below the hardware floor the duty cycle cannot be armed at all: the driver + // returns -708 and the wrapper quietly runs continuous RX, so the node keeps + // reporting power saving while spending full RX current. Just above that the + // SX1262 arms with ERR_NONE and then detects no preambles at all, which is + // worse. Measured floor: 6050-6100 us dead, 6200 us and up lossless. + const uint32_t min_sleep_us = transition_us + RX_POWERSAVING_MIN_SLEEP_MARGIN_US; + if (*sleep_us < min_sleep_us) { + if ((float)min_sleep_us > sleep_edge_symbols * symbol_us) { + // Even zero margin would not fit above the floor: no level of this + // profile can duty cycle at this SF/BW. Say so instead of returning + // something that will silently fall back. + return false; + } + // The floor eats into the margin. Levels below it collapse onto one point; + // the reply still reports the periods, so the loss of margin is visible. + *sleep_us = min_sleep_us; + } + *sleep_us = transition_us + snapRxPowerSavingToTick(*sleep_us - transition_us); + + // SetRxDutyCycle timer guard, straight out of the SX1261/2 datasheet: on + // preamble detection the radio restarts its timer with 2*rxPeriod + + // sleepPeriod (register values), and the packet dies if the header does not + // arrive inside it. The datasheet states the requirement as + // Tpreamble + Theader <= 2 * rxPeriod + sleepPeriod + // Measured: when it holds, no period value causes trouble. When it is broken + // the SX1262 usually gets away with it - but not always, and the exceptions + // are a single register tick wide. rxPeriod 640 (exactly 10.000 ms) loses + // 60-65% of packets at SF6 and everything at SF7, on two different boards, + // while 639 and 641 are lossless; rxPeriod 320 behaves the same way. Nothing + // in the register value predicts which ticks misbehave, so satisfy the + // condition instead of dodging the values. The listen window is therefore not + // a free parameter on the guarded scale - it is whatever the condition needs. + const float sync_symbols = + sf <= 6 ? RX_POWERSAVING_SYNC_SYMBOLS_LOW_SF : RX_POWERSAVING_SYNC_SYMBOLS; + const float need_us = + ((float)preamble + sync_symbols + RX_POWERSAVING_HEADER_SYMBOLS + + RX_POWERSAVING_TIMER_SLACK_SYMBOLS) * symbol_us; + // Work in the radio's own units: the driver truncates (sleep - transition) to + // 15.625 us ticks, so the microsecond difference overstates the programmed + // sleep by up to one tick - enough to leave the condition short on every + // level of a profile. + const uint32_t sleep_ticks = ((*sleep_us - transition_us) * 8) / 125; + const float programmed_sleep_us = (float)sleep_ticks * RX_POWERSAVING_TICK_US; + + if (unguarded) { + *rx_us = ceilRxPowerSavingValue(rx_symbols * symbol_us); + } else { + const float min_rx_us = (need_us - programmed_sleep_us) / 2.0f; + *rx_us = ceilRxPowerSavingValue(min_rx_us > 0.0f ? min_rx_us : symbol_us); + } + + *rx_us = snapRxPowerSavingUpToTick(*rx_us); + if (unguarded) *rx_us = avoidBadRxPowerSavingTick(*rx_us); + return true; +} + +void ensureRxPowerSavingDefaults(uint32_t* rx_us, uint32_t* sleep_us) { + if (!isValidRxPowerSavingPeriod(*rx_us)) *rx_us = RX_POWERSAVING_DEFAULT_RX_US; + if (!isValidRxPowerSavingPeriod(*sleep_us)) *sleep_us = RX_POWERSAVING_DEFAULT_SLEEP_US; +} + +bool recalcRxPowerSavingFromLevel(uint8_t level, uint8_t sf, float bw, uint8_t preamble, + uint32_t* rx_us, uint32_t* sleep_us, + float capture_cost_symbols, uint32_t transition_us) { + if (level < 1 || level > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL) return false; + if (preamble == 0) preamble = rxPowerSavingPreambleForSF(sf); + + uint32_t calculated_rx_us = 0; + uint32_t calculated_sleep_us = 0; + if (!calcRxPowerSavingLevel(level, sf, bw, preamble, &calculated_rx_us, &calculated_sleep_us, + capture_cost_symbols, transition_us) || + !isValidRxPowerSavingPeriod(calculated_rx_us) || + !isValidRxPowerSavingPeriod(calculated_sleep_us)) { + return false; + } + + *rx_us = calculated_rx_us; + *sleep_us = calculated_sleep_us; + return true; +} + +bool normalizeRxPowerSavingConfig(RxPowerSavingConfig* config, uint8_t sf, float bw, + float capture_cost_symbols, uint32_t transition_us) { + if (config == nullptr || sf < 5 || sf > 12 || !isfinite(bw) || bw <= 0) return false; + RxPowerSavingConfig proposed = *config; + proposed.enabled = proposed.enabled ? 1 : 0; + if (proposed.level > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL) { + proposed.level = RX_POWERSAVING_BALANCED_LEVEL; + } + if (proposed.preamble != 0 && proposed.preamble != 16 && proposed.preamble != 32) { + proposed.preamble = RX_POWERSAVING_PROFILE_PREAMBLE; + } + if (proposed.level == 0) { + if (!isValidRxPowerSavingPeriod(proposed.rx_us) || + !isValidRxPowerSavingPeriod(proposed.sleep_us)) return false; + } else if (!recalcRxPowerSavingFromLevel(proposed.level, sf, bw, proposed.preamble, + &proposed.rx_us, &proposed.sleep_us, + capture_cost_symbols, transition_us)) { + return false; + } + *config = proposed; + return true; +} + +bool applyRxPowerSavingConfig(RxPowerSavingConfig* config, uint8_t sf, float bw, + RxPowerSavingControl* control) { + if (config == nullptr) return false; + const bool valid = !config->enabled || normalizeRxPowerSavingConfig( + config, sf, bw, rxPowerSavingCaptureCost(control), rxPowerSavingTransition(control)); + if (control == nullptr) return !config->enabled; + const bool accepted = control->setRxPowerSaving( + config->enabled && valid, config->rx_us, config->sleep_us); + control->setRxPowerSavingConfigError(!valid); + return valid && accepted; +} + +#endif // WITH_RX_POWERSAVING diff --git a/src/helpers/radiolib/RXPowerSaving.h b/src/helpers/radiolib/RXPowerSaving.h new file mode 100644 index 00000000..9174ed60 --- /dev/null +++ b/src/helpers/radiolib/RXPowerSaving.h @@ -0,0 +1,278 @@ +// CUSTOM (TeTeHacko): from EasySkyMesh PowerSaving v18 (IoTThinks/MeshCore, +// MIT, https://github.com/IoTThinks/MeshCore/tree/PowerSaving-v18) -- RXPS, the +// SX126x/LR11x0 RX duty cycle. Compiled only with -D WITH_RX_POWERSAVING. +#pragma once + +#include + +static constexpr uint32_t RX_POWERSAVING_DEFAULT_RX_US = 65625UL; +static constexpr uint32_t RX_POWERSAVING_DEFAULT_SLEEP_US = 60000UL; +static constexpr uint32_t RX_POWERSAVING_MIN_PERIOD_US = 1000UL; +static constexpr uint32_t RX_POWERSAVING_MAX_PERIOD_US = 30000000UL; + +// The level scale is a catch dial, in symbols of the sender's preamble. +// +// Level N means: "at least this many symbols of the sender's preamble land +// inside an open RX window." That is the quantity the radio actually needs - +// a preamble is latched once enough of it has been heard - so the level states +// the requirement directly instead of stating a distance from an edge. +// +// The arithmetic follows from that in one step. Worst case, a preamble starts +// the instant an RX window closes, so what survives into the next window is +// `preamble - sleep`. Requiring that to be at least the level's catch gives +// +// sleep = preamble - catch +// +// and the chip's capture cost never enters the geometry. It becomes a +// validation instead: a level is usable when its catch is at least the cost. +// The floor of the scale is 8 symbols precisely because that is what the +// slower of the two families needs (LR11x0 8, SX126x 6), so **every level +// means the same geometry on both radios** - which the previous margin-based +// scale could not do, because the cost sat inside its formula. +// +// The two profiles get their own ladders. On a 16-symbol preamble there are +// only 8 symbols to spend between the floor and the whole preamble, so the +// steps are single symbols; on a 32-symbol preamble there are 24, so the low +// levels can take much larger strides where reception is guaranteed anyway. +static constexpr uint8_t RX_POWERSAVING_GUARDED_LEVELS = 8; +static constexpr float RX_POWERSAVING_LEVEL_CATCH_P16[RX_POWERSAVING_GUARDED_LEVELS] = { + 15.0f, 14.0f, 13.0f, 12.0f, 11.0f, 10.0f, 9.0f, 8.0f +}; +static constexpr float RX_POWERSAVING_LEVEL_CATCH_P32[RX_POWERSAVING_GUARDED_LEVELS] = { + 24.0f, 20.0f, 16.0f, 14.0f, 12.0f, 10.0f, 9.0f, 8.0f +}; + +// Smallest catch any guarded level asks for, and the reason it is 8: the +// LR11x0 needs 8 symbols to latch where the SX126x needs 6. +static constexpr float RX_POWERSAVING_MIN_CATCH_SYMBOLS = 8.0f; + +// On top of the ladder, every guarded level sleeps this much less than the +// arithmetic demands - so it catches 0.2 symbols more than its level promises. +// The reason is not capture safety: it is that specific register pairs the +// calculation lands on are defective (preamble latched, header never +// validated) in the same way isolated rxPeriod ticks 320 and 640 are. Nudging +// every generated geometry off those points cost 0.05 mA and took the worst +// measured cell from 3.33% packet loss to 0.11% across the whole ladder. +// Levels 9 and 10 are exempt - their geometries are pinned to bench +// measurements and shifting them would invalidate that data. +static constexpr float RX_POWERSAVING_MARGIN_PAD_SYMBOLS = 0.2f; + +// Past the guarded scale sit two settings that break the datasheet's +// SetRxDutyCycle timer condition on purpose. Overdrive is lossless and 4-12 +// percentage points cheaper in duty cycle; `riskyWorkingMax` is the measured +// working edge and drops ~2% of packets by design. +static constexpr uint8_t RX_POWERSAVING_OVERDRIVE_LEVEL = 9; +static constexpr uint8_t RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL = 10; +static constexpr float RX_POWERSAVING_RISKY_WORKING_MAX_VIRTUAL_P32 = 11.0f; +static constexpr float RX_POWERSAVING_RISKY_WORKING_MAX_VIRTUAL_P16 = 10.25f; + +// Top of the guarded scale: catches the ladder floor of 8 symbols (8.2 with +// the pad), the cheapest setting that still meets the datasheet condition and +// still works on both radio families. The CLI calls it `max`. +static constexpr uint8_t RX_POWERSAVING_MAX_LEVEL = RX_POWERSAVING_GUARDED_LEVELS; + +static constexpr uint8_t RX_POWERSAVING_CONSERVATIVE_LEVEL = 3; // catches 13 (P16) / 16 (P32) +static constexpr uint8_t RX_POWERSAVING_BALANCED_LEVEL = 6; // catches 10 (P16) / 10 (P32) +static constexpr uint8_t RX_POWERSAVING_PROFILE_PREAMBLE = 16; +static constexpr uint8_t RX_POWERSAVING_MAX_CONSEC_ARM_FAILURES = 3; + +// Symbols of a sender's preamble consumed before a packet can be latched: +// ~2 to latch the preamble plus ~2 lost to RX-window startup, measured on +// SX1262 at SF8/BW62.5. Capture needs sleep <= sender_preamble - this. +// Note this is well below the 8 symbols RadioLib quotes (SX126x.h) - that +// figure is the datasheet's margin for *reliable* latching, not the floor. +// +// Chip dependent, so it belongs with the driver rather than with each board: +// a wrapper overrides rxPowerSavingCaptureCostSymbols() and every variant using +// that radio picks it up. LR1110 needs about one symbol more - on the bench it +// held 300/300 at a margin of 7.78 symbols and started dropping packets at +// 6.89, for both profiles, where SX1262 is clean down to 6. +static constexpr float RX_POWERSAVING_CAPTURE_COST_SYMBOLS = 6.0f; +static constexpr float RX_POWERSAVING_CAPTURE_COST_SYMBOLS_LR11X0 = 8.0f; + +// TCXO startup delay handed to SetDIO3AsTCXOCtrl (SX126x DS 13.3.6) / +// SetTcxoMode (LR11x0 UM 6.3.2). RadioLib defaults it to 5000 us and nothing +// overrode it, so every board paid 5 ms on every duty-cycle wake whatever +// crystal was fitted. Measured lowest working value on five modules: T096 400, +// Tracker V2 300, Waveshare 150, ThinkNode M3 200, T1000-E 200 us - so 1600 +// keeps 4x margin over the worst of them. +// +// One knob for the whole tree, in `arduino_base`, because it is a property of +// the parts MeshCore is built with rather than of any one board. A variant that +// needs its own value defines it in its own build_flags and the later -D wins. +#ifndef MC_TCXO_DELAY_US + #define MC_TCXO_DELAY_US 1600 +#endif + +// Sleep -> RX transition: RadioLib subtracts tcxoDelay + 1000 us from the +// requested sleep before writing the register, and the hardware spends that +// long saving context, restarting the XTAL and locking the PLL. Everything +// below derives from it, so a board that knows its real TCXO delay overrides +// one method and both the sleep floor and the timer guard follow. +static constexpr uint32_t RX_POWERSAVING_TRANSITION_US = MC_TCXO_DELAY_US + 1000; + +// Slack the timer guard leaves on top of the datasheet condition, in symbols. +// +// Closing the condition exactly is not enough. The calculator lands on register +// pairs that satisfy it by a hair and still lose packets: rx=2476/sleep=2455 +// ticks clears it by 22 us at 0.12 symbol and drops 2-6% on every SX1262 tried, +// while moving any one component clears the fault. It is the same family as the +// isolated bad ticks 320 and 640 - the condition does not predict which pairs +// misbehave, so the answer is to stop generating geometries that sit on its +// edge. One whole symbol of slack is what the bench evidence supports. +#ifndef MC_RXPS_TIMER_SLACK_SYMBOLS + #define MC_RXPS_TIMER_SLACK_SYMBOLS 1.0f +#endif +static constexpr float RX_POWERSAVING_TIMER_SLACK_SYMBOLS = MC_RXPS_TIMER_SLACK_SYMBOLS; + +// Both radio families program their duty cycle in these units, and truncate the +// microsecond value on the way in. Everything the timer guard compares has to +// be expressed in whole ticks or it comes out short by a fraction of one. +static constexpr float RX_POWERSAVING_TICK_US = 15.625f; + +// Margin above the transition before a duty cycle actually works; see below. +static constexpr uint32_t RX_POWERSAVING_MIN_SLEEP_MARGIN_US = 250; + +// Symbols between the end of the sender's preamble and the end of the header: +// the LoRa sync word plus the 8-symbol explicit header. SF5/SF6 use a longer +// sync word than SF7 and above. Used by the SetRxDutyCycle timer guard. +static constexpr float RX_POWERSAVING_SYNC_SYMBOLS_LOW_SF = 6.25f; +static constexpr float RX_POWERSAVING_SYNC_SYMBOLS = 4.25f; +static constexpr float RX_POWERSAVING_HEADER_SYMBOLS = 8.0f; + +// Shortest sleep that actually produces a working duty cycle. +// +// RadioLib subtracts tcxoDelay + 1000 us from the requested sleep before +// writing the register. At or below that the register underflows and arming +// fails with RADIOLIB_ERR_INVALID_SLEEP_PERIOD (-708), after which the wrapper +// falls back to continuous RX while the config still says power saving is on. +// Measured on SX1262: the P16 profile fails to arm on levels 1-5 at SF6 and on +// levels 1-2 at SF7, exactly where that bound predicts. +// +// But arming successfully is NOT the boundary. Just above it the SX1262 accepts +// the command, returns ERR_NONE, and then detects **zero** preambles - a +// silently deaf receiver, which is worse than the honest -708. Measured twice, +// on two different SF and RX windows: sleep 6050-6100 us is dead, 6200 us and +// everything above it is lossless (40/40 at every value up to 21617 us). The +// chip needs roughly 200 us of *programmed* sleep, i.e. ~12 register ticks, so +// this leaves 250 us of margin on top of the transition time. +// +// The default assumes the 5000 us TCXO delay RadioLib installs; a wrapper that +// can read its radio overrides this with the board's real value. +static constexpr uint32_t RX_POWERSAVING_MIN_SLEEP_US = + RX_POWERSAVING_TRANSITION_US + RX_POWERSAVING_MIN_SLEEP_MARGIN_US; + +class RxPowerSavingArmRetryState { + uint8_t _consecutive_failures = 0; + +public: + bool canAttempt() const { + return _consecutive_failures < RX_POWERSAVING_MAX_CONSEC_ARM_FAILURES; + } + void recordSuccess() { _consecutive_failures = 0; } + void recordFailure() { + if (_consecutive_failures < RX_POWERSAVING_MAX_CONSEC_ARM_FAILURES) { + _consecutive_failures++; + } + } + void reset() { _consecutive_failures = 0; } + uint8_t consecutiveFailures() const { return _consecutive_failures; } +}; + +struct RxPowerSavingConfig { + uint8_t enabled = 0; + uint32_t rx_us = RX_POWERSAVING_DEFAULT_RX_US; + uint32_t sleep_us = RX_POWERSAVING_DEFAULT_SLEEP_US; + uint8_t level = RX_POWERSAVING_BALANCED_LEVEL; + uint8_t preamble = RX_POWERSAVING_PROFILE_PREAMBLE; +}; + +struct RxPowerSavingStatus { + bool supported = false; + bool armed = false; + int16_t last_error = 0; + uint32_t arm_failures = 0; + // Periods the radio actually runs with. A driver may clamp the requested + // values to satisfy a hardware constraint, so these can differ from the + // configured rx_us/sleep_us. Zero means "nothing armed yet". + uint32_t effective_rx_us = 0; + uint32_t effective_sleep_us = 0; +}; + +class RxPowerSavingControl { +public: + virtual ~RxPowerSavingControl() = default; + + virtual bool setRxPowerSaving(bool enabled, uint32_t rx_us, uint32_t sleep_us) { + (void)rx_us; + (void)sleep_us; + return !enabled; + } + virtual RxPowerSavingStatus getRxPowerSavingStatus() const { return {}; } + virtual void setRxPowerSavingConfigError(bool invalid) { (void)invalid; } + virtual bool isRxPowerSavingCalibrationActive() const { return false; } + + // Symbols of the sender's preamble consumed before a packet can be latched. + // Overridden per radio family; see RX_POWERSAVING_CAPTURE_COST_SYMBOLS. + virtual float rxPowerSavingCaptureCostSymbols() const { + return RX_POWERSAVING_CAPTURE_COST_SYMBOLS; + } + + // Sleep -> RX transition of this radio, in microseconds. The sleep floor and + // the SetRxDutyCycle timer guard are both derived from it, so a wrapper that + // can read its own tcxoDelay only needs to override this one method. + virtual uint32_t rxPowerSavingTransitionUs() const { + return RX_POWERSAVING_TRANSITION_US; + } +}; + +// Margin this level asks for, in symbols. Only meaningful on the guarded scale. +// Symbols of the sender's preamble this level undertakes to catch. The two +// profiles have separate ladders, so the profile has to be passed in; anything +// other than 16 or 32 is treated as the 16-symbol profile, matching the +// validation in calcRxPowerSavingLevel(). +inline float rxPowerSavingLevelCatch(uint8_t level, uint8_t preamble) { + if (level < 1 || level > RX_POWERSAVING_GUARDED_LEVELS) return 0.0f; + return preamble == 32 ? RX_POWERSAVING_LEVEL_CATCH_P32[level - 1] + : RX_POWERSAVING_LEVEL_CATCH_P16[level - 1]; +} + +inline bool isRxPowerSavingOverdriveLevel(uint8_t level) { + return level == RX_POWERSAVING_OVERDRIVE_LEVEL; +} + +inline bool isRxPowerSavingRiskyWorkingMaxLevel(uint8_t level) { + return level == RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL; +} + +// Both levels past the guarded scale run outside the datasheet's timer +// condition. Worth surfacing wherever a level is reported. +inline bool isRxPowerSavingUnguardedLevel(uint8_t level) { + return level >= RX_POWERSAVING_OVERDRIVE_LEVEL; +} + +bool isValidRxPowerSavingPeriod(uint32_t us); +uint8_t rxPowerSavingPreambleForSF(uint8_t sf); +bool isRxPowerSavingNumeric(const char* value); +// capture_cost_symbols defaults to the SX126x figure so callers without a radio +// handy still compile; anything holding a RxPowerSavingControl should pass +// rxPowerSavingCaptureCost(control) instead. +float rxPowerSavingCaptureCost(const RxPowerSavingControl* control); +uint32_t rxPowerSavingTransition(const RxPowerSavingControl* control); +bool calcRxPowerSavingLevel(uint8_t level, uint8_t sf, float bw, uint8_t preamble, + uint32_t* rx_us, uint32_t* sleep_us, + float capture_cost_symbols = RX_POWERSAVING_CAPTURE_COST_SYMBOLS, + uint32_t transition_us = RX_POWERSAVING_TRANSITION_US); +void ensureRxPowerSavingDefaults(uint32_t* rx_us, uint32_t* sleep_us); +bool recalcRxPowerSavingFromLevel(uint8_t level, uint8_t sf, float bw, uint8_t preamble, + uint32_t* rx_us, uint32_t* sleep_us, + float capture_cost_symbols = RX_POWERSAVING_CAPTURE_COST_SYMBOLS, + uint32_t transition_us = RX_POWERSAVING_TRANSITION_US); +bool normalizeRxPowerSavingConfig(RxPowerSavingConfig* config, uint8_t sf, float bw, + float capture_cost_symbols = RX_POWERSAVING_CAPTURE_COST_SYMBOLS, + uint32_t transition_us = RX_POWERSAVING_TRANSITION_US); + +// The requested configuration survives a timing failure; only the radio falls back. +bool applyRxPowerSavingConfig(RxPowerSavingConfig* config, uint8_t sf, float bw, + RxPowerSavingControl* control); +static constexpr int16_t RX_POWERSAVING_ERR_TIMING = -10001; diff --git a/src/helpers/radiolib/RXPowerSavingCLI.cpp b/src/helpers/radiolib/RXPowerSavingCLI.cpp new file mode 100644 index 00000000..bce4f36e --- /dev/null +++ b/src/helpers/radiolib/RXPowerSavingCLI.cpp @@ -0,0 +1,274 @@ +// CUSTOM (TeTeHacko): from EasySkyMesh PowerSaving v18 (IoTThinks/MeshCore, +// MIT, https://github.com/IoTThinks/MeshCore/tree/PowerSaving-v18) -- RXPS, the +// SX126x/LR11x0 RX duty cycle. Compiled only with -D WITH_RX_POWERSAVING. +#ifdef WITH_RX_POWERSAVING +#include "RXPowerSavingCLI.h" + +#include +#include +#include +#include +#include + +// Suffix printed after the level so an unguarded profile is never mistaken for +// an ordinary one, in both the `set` echo and the `get` report. +static const char* rxPowerSavingLevelTag(uint8_t level) { + if (isRxPowerSavingRiskyWorkingMaxLevel(level)) return "(riskyWorkingMax)"; + if (isRxPowerSavingOverdriveLevel(level)) return "(overdrive)"; + return ""; +} + +static bool parseRxPowerSavingUint32(const char* value, uint32_t* parsed) { + if (parsed == nullptr || !isRxPowerSavingNumeric(value)) return false; + + uint32_t result = 0; + while (*value) { + uint32_t digit = (uint32_t)(*value++ - '0'); + if (result > (UINT32_MAX - digit) / 10U) return false; + result = result * 10U + digit; + } + *parsed = result; + return true; +} + +bool RXPowerSavingCLI::set(const char* value, uint8_t sf, float bw, + RxPowerSavingConfig* config, RxPowerSavingControl* control, + char* reply, size_t reply_size) { + if (value == nullptr || config == nullptr || reply == nullptr || reply_size == 0) return false; + + RxPowerSavingConfig proposed = *config; + uint8_t level = 0; + uint8_t preamble = rxPowerSavingPreambleForSF(sf); + bool level_requested = false; + bool preamble_overridden = false; + + ensureRxPowerSavingDefaults(&proposed.rx_us, &proposed.sleep_us); + + if (strcmp(value, "off") == 0) { + proposed.enabled = 0; + } else if (strcmp(value, "on") == 0 || strcmp(value, "conservative") == 0) { + proposed.enabled = 1; + level = RX_POWERSAVING_CONSERVATIVE_LEVEL; + preamble = RX_POWERSAVING_PROFILE_PREAMBLE; + level_requested = true; + preamble_overridden = true; + } else if (strcmp(value, "max") == 0) { + // Top of the guarded scale. Like every named preset it assumes the worst + // case a mixed network can present - a sender using a 16-symbol preamble - + // so at SF<=8 it is markedly less economical than `level 10`, which follows + // the SF and picks the 32-symbol profile. `max preamble 32` gets that back. + proposed.enabled = 1; + level = RX_POWERSAVING_MAX_LEVEL; + preamble = RX_POWERSAVING_PROFILE_PREAMBLE; + level_requested = true; + preamble_overridden = true; + } else if (strcmp(value, "overdrive") == 0) { + // One step past the guarded scale: measured lossless, outside the + // datasheet's timer condition. Same worst-case preamble as the presets above. + proposed.enabled = 1; + level = RX_POWERSAVING_OVERDRIVE_LEVEL; + preamble = RX_POWERSAVING_PROFILE_PREAMBLE; + level_requested = true; + preamble_overridden = true; + } else if (strcmp(value, "riskyWorkingMax") == 0) { + // This one is not lossless, so the risk is explicit in its name. Same + // worst-case preamble as the presets above. + proposed.enabled = 1; + level = RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL; + preamble = RX_POWERSAVING_PROFILE_PREAMBLE; + level_requested = true; + preamble_overridden = true; + } else if (strcmp(value, "balanced") == 0) { + proposed.enabled = 1; + level = RX_POWERSAVING_BALANCED_LEVEL; + preamble = RX_POWERSAVING_PROFILE_PREAMBLE; + level_requested = true; + preamble_overridden = true; + } else { + char input[128]; + if (strlen(value) >= sizeof(input)) { + snprintf(reply, reply_size, + "ERROR: use off|on|conservative|balanced|max|overdrive|riskyWorkingMax|level <1-10>| "); + return false; + } + strcpy(input, value); + + const char* parts[4]; + int count = mesh::Utils::parseTextParts(input, parts, 4, ' '); + uint32_t first = 0; + uint32_t second = 0; + if (count == 1 && parseRxPowerSavingUint32(parts[0], &first)) { + if (first < 1 || first > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL) { + snprintf(reply, reply_size, "ERROR: level range is 1-%u (or max|overdrive|riskyWorkingMax); preamble is 16 or 32", + RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL); + return false; + } + level = (uint8_t)first; + level_requested = true; + proposed.enabled = 1; + } else if (count >= 2 && strcmp(parts[1], "preamble") == 0 && + (strcmp(parts[0], "max") == 0 || strcmp(parts[0], "overdrive") == 0 || + strcmp(parts[0], "riskyWorkingMax") == 0)) { + if (count != 3 || !parseRxPowerSavingUint32(parts[2], &first) || + (first != 16 && first != 32)) { + snprintf(reply, reply_size, "ERROR: use %s preamble <16|32>", parts[0]); + return false; + } + level = strcmp(parts[0], "overdrive") == 0 ? RX_POWERSAVING_OVERDRIVE_LEVEL + : strcmp(parts[0], "max") == 0 ? RX_POWERSAVING_MAX_LEVEL + : RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL; + preamble = (uint8_t)first; + level_requested = true; + preamble_overridden = true; + proposed.enabled = 1; + } else if (count == 2 && strcmp(parts[0], "level") == 0 && + parseRxPowerSavingUint32(parts[1], &first)) { + if (first < 1 || first > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL) { + snprintf(reply, reply_size, "ERROR: level range is 1-%u (or max|overdrive|riskyWorkingMax); preamble is 16 or 32", + RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL); + return false; + } + level = (uint8_t)first; + level_requested = true; + proposed.enabled = 1; + } else if (count == 4 && strcmp(parts[0], "level") == 0 && + parseRxPowerSavingUint32(parts[1], &first) && + strcmp(parts[2], "preamble") == 0 && + parseRxPowerSavingUint32(parts[3], &second)) { + if (first < 1 || first > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL || + (second != 16 && second != 32)) { + snprintf(reply, reply_size, "ERROR: level range is 1-%u (or max|overdrive|riskyWorkingMax); preamble is 16 or 32", + RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL); + return false; + } + level = (uint8_t)first; + preamble = (uint8_t)second; + level_requested = true; + preamble_overridden = true; + proposed.enabled = 1; + } else if (count == 2 && parseRxPowerSavingUint32(parts[0], &first) && + parseRxPowerSavingUint32(parts[1], &second)) { + proposed.rx_us = first; + proposed.sleep_us = second; + proposed.enabled = 1; + } else { + snprintf(reply, reply_size, + "ERROR: use off|on|conservative|balanced|max|overdrive|riskyWorkingMax|level <1-10>| "); + return false; + } + } + + if (proposed.enabled && (sf < 5 || sf > 12 || !isfinite(bw) || bw <= 0)) { + if (control) { + control->setRxPowerSaving(false, proposed.rx_us, proposed.sleep_us); + control->setRxPowerSavingConfigError(true); + } + snprintf(reply, reply_size, "ERROR: invalid SF/BW for RXPS"); + return false; + } + if (level_requested && + !recalcRxPowerSavingFromLevel(level, sf, bw, preamble, + &proposed.rx_us, &proposed.sleep_us, + rxPowerSavingCaptureCost(control), + rxPowerSavingTransition(control))) { + // Level and preamble were validated above, so the only way to get here is + // that no sleep exists which both arms the hardware and still lets a + // preamble of this length be caught - i.e. the symbol is too short for RXPS + // at this SF/BW. Saying "level range is 1-10" would send the user hunting + // for the wrong thing. + if (control) { + control->setRxPowerSaving(false, proposed.rx_us, proposed.sleep_us); + control->setRxPowerSavingConfigError(true); + } + snprintf(reply, reply_size, "ERROR: RXPS does not fit this SF/BW with preamble %lu", + (unsigned long)preamble); + return false; + } + if (!isValidRxPowerSavingPeriod(proposed.rx_us) || + !isValidRxPowerSavingPeriod(proposed.sleep_us)) { + snprintf(reply, reply_size, "ERROR: range is %lu-%lu us", + (unsigned long)RX_POWERSAVING_MIN_PERIOD_US, + (unsigned long)RX_POWERSAVING_MAX_PERIOD_US); + return false; + } + + bool applied = control != nullptr + ? control->setRxPowerSaving(proposed.enabled != 0, proposed.rx_us, proposed.sleep_us) + : proposed.enabled == 0; + if (!applied) { + snprintf(reply, reply_size, "ERROR: RX powersaving unsupported"); + return false; + } + + if (control) control->setRxPowerSavingConfigError(false); + + if (level_requested) { + proposed.level = level; + proposed.preamble = preamble_overridden ? preamble : 0; + } else if (strcmp(value, "off") != 0) { + proposed.level = 0; + proposed.preamble = 0; + } + + *config = proposed; + snprintf(reply, reply_size, "OK - %s,level=%lu%s,preamble=%lu,rx=%lu,sleep=%lu", + config->enabled ? "on" : "off", (unsigned long)config->level, + rxPowerSavingLevelTag(config->level), + (unsigned long)config->preamble, (unsigned long)config->rx_us, + (unsigned long)config->sleep_us); + return true; +} + +void RXPowerSavingCLI::get(const RxPowerSavingConfig* config, + const RxPowerSavingControl* control, + uint8_t sf, float bw, char* reply, size_t reply_size) { + if (config == nullptr || reply == nullptr || reply_size == 0) return; + + RxPowerSavingStatus status = control != nullptr + ? control->getRxPowerSavingStatus() + : RxPowerSavingStatus{}; + // Preamble symbols the node actually catches. Not simply the number the level + // asked for: the sleep floor can shorten the sleep further, and at SF6 with + // the 16-symbol profile that collapses the first few levels onto the same + // point. Reporting the requested value there would be a lie. + char margin[24]; + margin[0] = 0; + if (status.last_error == 0 && isValidRxPowerSavingPeriod(config->sleep_us) && + config->level >= 1 && config->level <= RX_POWERSAVING_GUARDED_LEVELS && + sf >= 5 && sf <= 12 && isfinite(bw) && bw > 0.0f) { + const uint8_t preamble = config->preamble ? config->preamble : rxPowerSavingPreambleForSF(sf); + const float symbol_us = (1000.0f * (float)(1UL << sf)) / bw; + const float effective = (float)preamble - (float)config->sleep_us / symbol_us; + // No %f on this platform's printf, and rounding the whole and fractional + // parts separately overflows: 4.999 came out as "4.10". + const float scaled = effective * 10.0f + (effective < 0.0f ? -0.5f : 0.5f); + if (isfinite(scaled) && scaled > (float)INT_MIN && scaled < (float)INT_MAX) { + const int tenths = (int)scaled; + snprintf(margin, sizeof(margin), ",catch=%d.%d", tenths / 10, + tenths < 0 ? -(tenths % 10) : tenths % 10); + } + } + + // Overdrive has to be visible here, otherwise it reads as an ordinary level + // and nobody remembers it runs outside the datasheet rule. + int len = snprintf(reply, reply_size, + "> desired=%s,effective=%s,supported=%s,err=%d,fail=%lu,level=%lu%s%s,preamble=%lu,rx=%lu,sleep=%lu", + config->enabled ? "on" : "off", status.armed ? "armed" : "continuous", + status.supported ? "yes" : "no", (int)status.last_error, + (unsigned long)status.arm_failures, (unsigned long)config->level, + rxPowerSavingLevelTag(config->level), margin, + (unsigned long)config->preamble, (unsigned long)config->rx_us, + (unsigned long)config->sleep_us); + + // Only report the periods the hardware really runs with when a driver had to + // clamp them - printing them always would not fit the 160 byte reply buffer. + if (len > 0 && (size_t)len < reply_size && status.armed && + (status.effective_rx_us != config->rx_us || + status.effective_sleep_us != config->sleep_us)) { + snprintf(reply + len, reply_size - (size_t)len, ",erx=%lu,eslp=%lu", + (unsigned long)status.effective_rx_us, + (unsigned long)status.effective_sleep_us); + } +} + +#endif // WITH_RX_POWERSAVING diff --git a/src/helpers/radiolib/RXPowerSavingCLI.h b/src/helpers/radiolib/RXPowerSavingCLI.h new file mode 100644 index 00000000..554b490a --- /dev/null +++ b/src/helpers/radiolib/RXPowerSavingCLI.h @@ -0,0 +1,18 @@ +// CUSTOM (TeTeHacko): from EasySkyMesh PowerSaving v18 (IoTThinks/MeshCore, +// MIT, https://github.com/IoTThinks/MeshCore/tree/PowerSaving-v18) -- RXPS, the +// SX126x/LR11x0 RX duty cycle. Compiled only with -D WITH_RX_POWERSAVING. +#pragma once + +#include + +#include "RXPowerSaving.h" + +class RXPowerSavingCLI { +public: + static bool set(const char* value, uint8_t sf, float bw, RxPowerSavingConfig* config, + RxPowerSavingControl* control, char* reply, size_t reply_size); + // sf/bw are needed to turn the stored periods back into symbols, which is + // what the level scale is expressed in. + static void get(const RxPowerSavingConfig* config, const RxPowerSavingControl* control, + uint8_t sf, float bw, char* reply, size_t reply_size); +}; diff --git a/src/helpers/radiolib/RadioLibWrappers.cpp b/src/helpers/radiolib/RadioLibWrappers.cpp index fbfcbb22..1420e91c 100644 --- a/src/helpers/radiolib/RadioLibWrappers.cpp +++ b/src/helpers/radiolib/RadioLibWrappers.cpp @@ -11,6 +11,12 @@ #define NUM_NOISE_FLOOR_SAMPLES 64 #define SAMPLING_THRESHOLD 14 +#ifdef WITH_RX_POWERSAVING +#define NF_CALIB_INTERVAL_MS 60000UL // continuous-RX window for the noise floor, this often +#define NF_CALIB_TIMEOUT_MS 5000UL // ... and at most this long +#define NF_CALIB_SETTLE_MS 20UL // RSSI settles after leaving the duty cycle +#endif + static volatile uint8_t state = STATE_IDLE; #ifdef RADIO_DIAG static volatile uint32_t diag_isr_count = 0; // DIO1 edges that reached the MCU @@ -56,6 +62,9 @@ uint32_t RadioLibWrapper::getRngSeed() { } void RadioLibWrapper::setTxPower(int8_t dbm) { +#ifdef WITH_RX_POWERSAVING + prepareForRadioConfig(); // PA config is a standby-only command +#endif #if defined(USE_LR2021) // Upstream 114093ee: on LR2021, setOutputPower() writes the PA config and // TxParams, which are standby-only commands, and recvRaw() keeps state == @@ -73,6 +82,9 @@ void RadioLibWrapper::setTxPower(int8_t dbm) { } void RadioLibWrapper::idle() { +#ifdef WITH_RX_POWERSAVING + if (_rx_ps_armed) stopReceiveDutyCycle(); +#endif _radio->standby(); state = STATE_IDLE; // need another startReceive() } @@ -99,6 +111,13 @@ void RadioLibWrapper::resetAGC() { // make sure we're not mid-receive of packet! if ((state & STATE_INT_READY) != 0 || isReceivingPacket()) return; +#ifdef WITH_RX_POWERSAVING + if (_rx_ps_armed) stopReceiveDutyCycle(); + // Duty cycling never samples RSSI outside a calibration window, so the + // reconvergence below has to have one: schedule it now. (Upstream RXPS + // recalibrates synchronously here -- up to ~0.3 s blocking the main loop.) + _nf_last_calib = 0; +#endif doResetAGC(); state = STATE_IDLE; // trigger a startReceive() @@ -143,6 +162,25 @@ void RadioLibWrapper::loop() { pollIrq(); #endif +#ifdef WITH_RX_POWERSAVING + if (_rx_ps_restart_pending && (state & ~STATE_INT_READY) != STATE_TX_WAIT && + !isPacketPendingOrReceiving()) { + _rx_ps_restart_pending = false; + requestRestartRecv(); + } + noiseFloorCalibCheck(); + + if (state == STATE_RX && _num_floor_samples < NUM_NOISE_FLOOR_SAMPLES) { + // no RSSI while duty cycling (the chip sleeps between windows), nor in the + // settle time right after a calibration window opened + if (!_rx_ps_armed && !(_nf_calib_active && (long)(millis() - _nf_sample_from) < 0) && + !isReceivingPacket()) { + sampleNoiseFloorOnce(); + } + } else if (publishNoiseFloor()) { + if (_nf_calib_active) endNoiseFloorCalib(millis()); + } +#else if (state == STATE_RX && _num_floor_samples < NUM_NOISE_FLOOR_SAMPLES) { if (!isReceivingPacket()) { int rssi = getCurrentRSSI(); @@ -162,13 +200,18 @@ void RadioLibWrapper::loop() { MESH_DEBUG_PRINTLN("RadioLibWrapper: noise_floor = %d", (int)_noise_floor); #endif } +#endif } void RadioLibWrapper::startRecv() { #if defined(USE_LR2021) _radio->standby(); // without this LR2021 can throw -706 when calling startReceive after hardware CAD when side detectors are enabled #endif +#ifdef WITH_RX_POWERSAVING + int err = startReceiveMode(); +#else int err = _radio->startReceive(); +#endif if (err == RADIOLIB_ERR_NONE) { state = STATE_RX; } else { @@ -176,6 +219,175 @@ void RadioLibWrapper::startRecv() { } } +#ifdef WITH_RX_POWERSAVING +// Clear the RX/idle state so the next loop calls startRecv() again, without +// dropping a STATE_INT_READY the ISR may raise meanwhile: a plain +// `state = STATE_IDLE` loses that flag -- and a received packet -- when setFlag() +// fires between the test and the store. +void RadioLibWrapper::requestRestartRecv() { + noInterrupts(); + if ((state & ~STATE_INT_READY) != STATE_TX_WAIT) { + state &= STATE_INT_READY; + } + interrupts(); +} + +bool RadioLibWrapper::isPacketPendingOrReceiving() { + return (state & STATE_INT_READY) != 0 || isReceivingPacket(); +} + +void RadioLibWrapper::sampleNoiseFloorOnce() { + int rssi = getCurrentRSSI(); + if (rssi < _noise_floor + SAMPLING_THRESHOLD) { + _num_floor_samples++; + _floor_sample_sum += rssi; + } +} + +bool RadioLibWrapper::publishNoiseFloor() { + if (_num_floor_samples < NUM_NOISE_FLOOR_SAMPLES || _floor_sample_sum == 0) return false; + _noise_floor = _floor_sample_sum / NUM_NOISE_FLOOR_SAMPLES; + if (_noise_floor < -120) { + _noise_floor = -120; // clamp to lower bound of -120dBi + } + _floor_sample_sum = 0; + #ifdef MESH_DEBUG_NOISE_FLOOR + MESH_DEBUG_PRINTLN("RadioLibWrapper: noise_floor = %d", (int)_noise_floor); + #endif + return true; +} + +void RadioLibWrapper::noiseFloorCalibCheck() { + unsigned long now = millis(); + if (_nf_calib_active) { + if (!_rx_ps_enabled || (long)(now - _nf_calib_deadline) >= 0) { + endNoiseFloorCalib(now); + } else if (_rx_ps_armed && !isPacketPendingOrReceiving()) { + requestRestartRecv(); // a packet delayed the switch to continuous RX + } + } else if (_rx_ps_enabled && _rx_ps_armed && state == STATE_RX && + (_nf_last_calib == 0 || now - _nf_last_calib >= NF_CALIB_INTERVAL_MS) && + !isPacketPendingOrReceiving()) { + _nf_calib_active = true; + _nf_calib_deadline = now + NF_CALIB_TIMEOUT_MS; + _nf_sample_from = now + NF_CALIB_SETTLE_MS; + _num_floor_samples = 0; + _floor_sample_sum = 0; + requestRestartRecv(); // startReceiveMode() goes continuous while calibrating + } +} + +void RadioLibWrapper::endNoiseFloorCalib(unsigned long now) { + _nf_calib_active = false; + _nf_last_calib = now; + if (!isPacketPendingOrReceiving()) requestRestartRecv(); +} + +int16_t RadioLibWrapper::startReceiveMode() { + // A preamble that arrived after the scheduler's idle check must not be + // aborted by stopping the duty cycle for a calibration window. + if (_nf_calib_active && _rx_ps_armed && isPacketPendingOrReceiving()) { + return RADIOLIB_ERR_NONE; + } + if (_rx_ps_armed) stopReceiveDutyCycle(); + if (!_rx_ps_enabled || _nf_calib_active) { + _rx_ps_armed = false; + const int16_t err = startContinuousReceive(); + _rx_ps_last_error = err; + return err; + } + if (!_rx_ps_arm_retry.canAttempt()) { + // arming failed repeatedly: continuous RX until the config changes + _rx_ps_armed = false; + const int16_t err = startContinuousReceive(); + if (err != RADIOLIB_ERR_NONE) _rx_ps_last_error = err; + return err; + } + + const RadioLibIrqFlags_t irq_flags = + RADIOLIB_IRQ_RX_DEFAULT_FLAGS | (1UL << RADIOLIB_IRQ_PREAMBLE_DETECTED); + const RadioLibIrqFlags_t irq_mask = + (1UL << RADIOLIB_IRQ_RX_DONE) | (1UL << RADIOLIB_IRQ_TIMEOUT) | + (1UL << RADIOLIB_IRQ_CRC_ERR) | (1UL << RADIOLIB_IRQ_HEADER_ERR); + + uint32_t eff_rx_us = _rx_ps_rx_us; + uint32_t eff_sleep_us = _rx_ps_sleep_us; + int16_t err = armDutyCycle(irq_flags, irq_mask, &eff_rx_us, &eff_sleep_us); + if (err == RADIOLIB_ERR_NONE) { + _rx_ps_armed = true; + _rx_ps_last_error = RADIOLIB_ERR_NONE; + _rx_ps_arm_retry.recordSuccess(); + _rx_ps_eff_rx_us = eff_rx_us; + _rx_ps_eff_sleep_us = eff_sleep_us; + return err; + } + + _rx_ps_armed = false; + _rx_ps_last_error = err; + _rx_ps_eff_rx_us = 0; + _rx_ps_eff_sleep_us = 0; + n_rx_ps_arm_failures++; + _rx_ps_arm_retry.recordFailure(); + MESH_DEBUG_PRINTLN("RadioLibWrapper: startReceiveDutyCycle(%d), continuous RX fallback", err); + stopDutyCycleHardware(); + int16_t fallback_err = startContinuousReceive(); + if (fallback_err != RADIOLIB_ERR_NONE) _rx_ps_last_error = fallback_err; + return fallback_err; +} + +void RadioLibWrapper::stopReceiveDutyCycle() { + int16_t err = stopDutyCycleHardware(); + _rx_ps_armed = false; + _rx_ps_eff_rx_us = 0; + _rx_ps_eff_sleep_us = 0; + if (err != RADIOLIB_ERR_NONE) _rx_ps_last_error = err; +} + +bool RadioLibWrapper::isPacketReady() { + if (!_rx_ps_armed) return true; + return _radio->checkIrq(RADIOLIB_IRQ_RX_DONE) != 0; +} + +void RadioLibWrapper::prepareForRadioConfig() { + if (!_rx_ps_armed) return; + stopReceiveDutyCycle(); + requestRestartRecv(); +} + +bool RadioLibWrapper::setRxPowerSaving(bool enabled, uint32_t rx_us, uint32_t sleep_us) { + if (enabled && (!isValidRxPowerSavingPeriod(rx_us) || !isValidRxPowerSavingPeriod(sleep_us))) { + _rx_ps_enabled = false; + _rx_ps_last_error = RX_POWERSAVING_ERR_TIMING; + requestRestartRecv(); + return false; + } + if (enabled && !supportsRxPowerSaving()) return false; + + _rx_ps_enabled = enabled; + _rx_ps_rx_us = rx_us; + _rx_ps_sleep_us = sleep_us; + _rx_ps_last_error = RADIOLIB_ERR_NONE; + _rx_ps_arm_retry.reset(); // new config, a fresh chance for the hardware + _rx_ps_restart_pending = true; + if ((state & ~STATE_INT_READY) != STATE_TX_WAIT && !isPacketPendingOrReceiving()) { + _rx_ps_restart_pending = false; + requestRestartRecv(); + } + return true; +} + +RxPowerSavingStatus RadioLibWrapper::getRxPowerSavingStatus() const { + RxPowerSavingStatus status; + status.supported = supportsRxPowerSaving(); + status.armed = _rx_ps_armed; + status.last_error = _rx_ps_config_error ? RX_POWERSAVING_ERR_TIMING : _rx_ps_last_error; + status.arm_failures = n_rx_ps_arm_failures; + status.effective_rx_us = _rx_ps_eff_rx_us; + status.effective_sleep_us = _rx_ps_eff_sleep_us; + return status; +} +#endif + bool RadioLibWrapper::isInRecvMode() const { return (state & ~STATE_INT_READY) == STATE_RX; } @@ -183,7 +395,20 @@ bool RadioLibWrapper::isInRecvMode() const { int RadioLibWrapper::recvRaw(uint8_t* bytes, int sz) { int len = 0; if (state & STATE_INT_READY) { +#ifdef WITH_RX_POWERSAVING + // While duty cycling DIO1 also carries timeouts; only a real RX_DONE has data. + if (isPacketReady()) { + if (_rx_ps_armed) stopReceiveDutyCycle(); + len = _radio->getPacketLength(); + if (len > 0) { + _last_snr = _radio->getSNR(); + _last_rssi = _radio->getRSSI(); + _last_metrics_valid = true; + } + } +#else len = _radio->getPacketLength(); +#endif if (len > 0) { if (len > sz) { len = sz; } int err = _radio->readData(bytes, len); @@ -210,12 +435,16 @@ int RadioLibWrapper::recvRaw(uint8_t* bytes, int sz) { } if (state != STATE_RX) { +#ifdef WITH_RX_POWERSAVING + startRecv(); // duty cycle or continuous, as configured +#else int err = _radio->startReceive(); if (err == RADIOLIB_ERR_NONE) { state = STATE_RX; } else { MESH_DEBUG_PRINTLN("RadioLibWrapper: error: startReceive(%d)", err); } +#endif } return len; } @@ -225,6 +454,9 @@ uint32_t RadioLibWrapper::getEstAirtimeFor(int len_bytes) { } bool RadioLibWrapper::startSendRaw(const uint8_t* bytes, int len) { +#ifdef WITH_RX_POWERSAVING + if (_rx_ps_armed) stopReceiveDutyCycle(); +#endif _board->onBeforeTransmit(); int err = _radio->startTransmit((uint8_t *) bytes, len); if (err == RADIOLIB_ERR_NONE) { @@ -320,10 +552,19 @@ int RadioLibWrapper::probeDio1(uint32_t* irq_out, int* dio1_level, int* probe_le bool RadioLibWrapper::isChannelActive() { // int.thresh: RSSI-based interference detection (relative to noise floor) +#ifdef WITH_RX_POWERSAVING + // no RSSI read while the duty-cycling chip sleeps (BUSY high) + if (_threshold != 0 && !(_rx_ps_armed && isChipBusy()) && + getCurrentRSSI() > _noise_floor + _threshold) return true; +#else if (_threshold != 0 && getCurrentRSSI() > _noise_floor + _threshold) return true; +#endif // cad: hardware channel activity detection if (_cad_enabled) { +#ifdef WITH_RX_POWERSAVING + if (_rx_ps_armed) stopReceiveDutyCycle(); +#endif int16_t result = performChannelScan(); // scanChannel() triggers DIO interrupt (CAD done) which sets STATE_INT_READY // via setFlag() ISR. Clear it before restarting RX so recvRaw() doesn't @@ -337,9 +578,17 @@ bool RadioLibWrapper::isChannelActive() { } float RadioLibWrapper::getLastRSSI() const { +#ifdef WITH_RX_POWERSAVING + if (_last_metrics_valid) return _last_rssi; + if (_rx_ps_armed) return 0; +#endif return _radio->getRSSI(); } float RadioLibWrapper::getLastSNR() const { +#ifdef WITH_RX_POWERSAVING + if (_last_metrics_valid) return _last_snr; + if (_rx_ps_armed) return 0; +#endif return _radio->getSNR(); } diff --git a/src/helpers/radiolib/RadioLibWrappers.h b/src/helpers/radiolib/RadioLibWrappers.h index adf74af7..11f10031 100644 --- a/src/helpers/radiolib/RadioLibWrappers.h +++ b/src/helpers/radiolib/RadioLibWrappers.h @@ -2,6 +2,15 @@ #include #include +#ifdef WITH_RX_POWERSAVING +// CUSTOM (TeTeHacko): RX duty cycle ("RXPS"), ported from EasySkyMesh PowerSaving +// v18 (IoTThinks/MeshCore, MIT). Build-flag only and off at runtime by default: +// without the flag this class is byte-for-byte what it was. See RXPowerSaving.h. +#include "RXPowerSaving.h" +#if defined(LORA_POLL_IRQ) + #error "WITH_RX_POWERSAVING and LORA_POLL_IRQ do not mix: polling the IRQ register wakes a duty-cycling chip" +#endif +#endif #ifdef USE_CC310_HW_CRYPTO #include @@ -11,7 +20,11 @@ struct PacketMillis { uint32_t payloadMillis; // header-valid -> rx-done deadline }; -class RadioLibWrapper : public mesh::Radio { +class RadioLibWrapper : public mesh::Radio +#ifdef WITH_RX_POWERSAVING + , public RxPowerSavingControl +#endif +{ protected: PhysicalLayer* _radio; mesh::MainBoard* _board; @@ -26,6 +39,51 @@ protected: void idle(); void startRecv(); +#ifdef WITH_RX_POWERSAVING + // RXPS state. _rx_ps_enabled = what the config asks for, _rx_ps_armed = the + // chip is duty cycling right now (cleared by anything that takes it out). + bool _rx_ps_restart_pending = false; + bool _rx_ps_config_error = false; + bool _rx_ps_enabled = false; + bool _rx_ps_armed = false; + uint32_t _rx_ps_rx_us = RX_POWERSAVING_DEFAULT_RX_US; + uint32_t _rx_ps_sleep_us = RX_POWERSAVING_DEFAULT_SLEEP_US; + uint32_t _rx_ps_eff_rx_us = 0; // periods the driver actually armed with + uint32_t _rx_ps_eff_sleep_us = 0; + int16_t _rx_ps_last_error = 0; + uint32_t n_rx_ps_arm_failures = 0; + RxPowerSavingArmRetryState _rx_ps_arm_retry; + // Noise floor while duty cycling: RSSI cannot be sampled in the sleep phase, + // so every NF_CALIB_INTERVAL the receiver goes continuous for a short window. + bool _nf_calib_active = false; + unsigned long _nf_last_calib = 0; + unsigned long _nf_calib_deadline = 0; + unsigned long _nf_sample_from = 0; + // RSSI/SNR of the last packet, read at RX: reading the registers later, with + // the chip asleep between windows, would wake it and return nothing useful. + float _last_rssi = 0, _last_snr = 0; + bool _last_metrics_valid = false; + + void requestRestartRecv(); + bool isPacketPendingOrReceiving(); + void prepareForRadioConfig(); + void sampleNoiseFloorOnce(); + bool publishNoiseFloor(); + void noiseFloorCalibCheck(); + void endNoiseFloorCalib(unsigned long now); + int16_t startReceiveMode(); + void stopReceiveDutyCycle(); + // eff_rx_us/eff_sleep_us report the periods the driver really programmed. + virtual int16_t armDutyCycle(RadioLibIrqFlags_t irq_flags, RadioLibIrqFlags_t irq_mask, + uint32_t* eff_rx_us, uint32_t* eff_sleep_us) { + (void)irq_flags; (void)irq_mask; (void)eff_rx_us; (void)eff_sleep_us; + return RADIOLIB_ERR_UNSUPPORTED; + } + virtual int16_t stopDutyCycleHardware() { return _radio->standby(); } + virtual int16_t startContinuousReceive() { return _radio->startReceive(); } + virtual bool isPacketReady(); + virtual bool isChipBusy() { return false; } +#endif #ifdef LORA_POLL_IRQ void pollIrq(); // CUSTOM (TeTeHacko): DIO1-less completion detection, see .cpp #endif @@ -41,7 +99,17 @@ public: } void begin() override; +#ifdef WITH_RX_POWERSAVING + virtual void powerOff() { if (_rx_ps_armed) stopReceiveDutyCycle(); _radio->sleep(); } + + virtual bool supportsRxPowerSaving() const { return false; } + void setRxPowerSavingConfigError(bool invalid) override { _rx_ps_config_error = invalid; } + bool setRxPowerSaving(bool enabled, uint32_t rx_us, uint32_t sleep_us) override; + RxPowerSavingStatus getRxPowerSavingStatus() const override; + bool isRxPowerSavingCalibrationActive() const override { return _nf_calib_active; } +#else virtual void powerOff() { _radio->sleep(); } +#endif int recvRaw(uint8_t* bytes, int sz) override; uint32_t getEstAirtimeFor(int len_bytes) override; bool startSendRaw(const uint8_t* bytes, int len) override; @@ -89,7 +157,14 @@ public: void kickRx(); uint32_t getPacketsRecvErrors() const { return n_recv_errors; } uint32_t getPacketsSent() const { return n_sent; } +#ifdef WITH_RX_POWERSAVING + void resetStats() { + n_recv = n_sent = n_recv_errors = n_rx_ps_arm_failures = 0; + _rx_ps_arm_retry.reset(); // a fresh set of arm attempts, see startReceiveMode() + } +#else void resetStats() { n_recv = n_sent = n_recv_errors = 0; } +#endif virtual float getLastRSSI() const override; virtual float getLastSNR() const override; From e3200086c48fa964feacbe7c56bb204db674d618 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Thu, 12 Nov 2026 16:24:57 +0100 Subject: [PATCH 03/10] pub-release: changelog since the previous release in the release body Co-Authored-By: Claude Opus 5.5 --- .github/workflows/pub-release.yml | 65 +++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pub-release.yml b/.github/workflows/pub-release.yml index 5e74964d..1d8c18ae 100644 --- a/.github/workflows/pub-release.yml +++ b/.github/workflows/pub-release.yml @@ -12,7 +12,9 @@ # Runs on every push to main -- the export pushes there only after an # upstream merge (private repo, tth-upstream-sync) -- and by hand. # Release tag tth-, titled with the stamped version (v1.18.0-tth); -# the newest KEEP releases stay, older ones are deleted. +# the newest KEEP releases stay, older ones are deleted. The body is a +# changelog since the previous release: our own commits, then the upstream +# PRs the upstream merges brought in. # nRF52: .uf2 (drag onto the bootloader drive) and .zip (DFU over BLE or # serial); ESP32: -merged.bin (fresh install at 0x0) and .bin (update). name: pub-release @@ -160,8 +162,65 @@ jobs: rxlog / pktlog rings for the repeater observer. Czech mesh defaults (meshcore.cz): 869.432 MHz / 62.5 kHz / SF7 / CR5; repeater: zero-hop advert off, flood advert 25 h, af 9 (10 % duty cycle), regions cz + cs. Apply to a fresh or erased node only.' - body=$(printf '%s\n\ncommit %s, run %s\n\n%s\nWhat this fork changes against upstream: see README.md.\n' \ - "$VERSION" "$SHA" "$GITHUB_RUN_NUMBER" "$note") + web="$GITEA/$GITHUB_REPOSITORY" + gh=https://github.com/meshcore-dev/MeshCore + max=60 + # changelog against the newest older release that HEAD descends from + prev="" base="" + while read -r t c; do + if [ "$c" != "$SHA" ] && git merge-base --is-ancestor "$c" "$SHA" 2>/dev/null; then + prev=$t base=$c + break + fi + done < <(curl -sSf --config - "$api/releases?limit=50" <<<"$auth" | + jq -r --arg t "$TAG" 'map(select(.tag_name | startswith("tth-")) | select(.tag_name != $t)) + | sort_by(.created_at) | reverse | .[] | "\(.tag_name) \(.target_commitish)"') + # no older release: the last 20 commits of our own line + [ -n "$base" ] || base=$(git rev-list --first-parent --max-count=21 "$SHA" | tail -1) + # ours: commits on our main itself (first parent), not what the + # upstream merges brought in + ours=$(git log --first-parent --no-merges --format="- %s ([%h]($web/commit/%H))" "$base..$SHA") + # upstream: the first-parent line of each merged upstream branch, + # PR merges as their title, direct commits as their subject + declare -A seen=() + ups=() + for m in $(git log --first-parent --merges --grep='^Merge upstream' --format=%H "$base..$SHA"); do + for c in $(git log --first-parent --format=%H "$m^1..$m^2"); do + s=$(git log -1 --format=%s "$c") + if [[ $s =~ ^Merge\ pull\ request\ \#([0-9]+)\ from\ ([^/]+)/(.*)$ ]]; then + pr=${BASH_REMATCH[1]} + [ -z "${seen[$pr]:-}" ] || continue + seen[$pr]=1 + t=$(git log -1 --format=%b "$c" | sed -n '/./{p;q}') + ups+=("- ${t:-${BASH_REMATCH[3]}} ([#$pr]($gh/pull/$pr), ${BASH_REMATCH[2]})") + elif [[ $s != Merge* ]]; then + [ -z "${seen[$c]:-}" ] || continue + seen[$c]=1 + ups+=("- $s ([${c:0:7}]($gh/commit/$c))") + fi + done + done + n=${#ups[@]} + body=$( + echo "$VERSION" + echo + if [ -n "$prev" ]; then + echo "Od předchozího vydání · since [$prev]($web/releases/tag/$prev)" + echo + fi + echo "### Změny forku · fork changes" + echo "${ours:-- žádné · none}" + echo + echo "### Z upstreamu MeshCore · from upstream ($n)" + [ "$n" -gt 0 ] && printf '%s\n' "${ups[@]:0:$max}" || echo "- žádné · none" + [ "$n" -le "$max" ] || echo "- … a dalších $((n - max)) · and $((n - max)) more" + echo + echo "### Po flashi · after flashing" + echo "$note" + echo "What this fork changes against upstream: see README.md." + echo + echo "commit $SHA, run $GITHUB_RUN_NUMBER" + ) jq -n --arg t "$TAG" --arg c "$SHA" --arg n "$VERSION" --arg b "$body" \ '{tag_name: $t, target_commitish: $c, name: $n, body: $b}' >"$RUNNER_TEMP/rel.json" id=$(curl -sSf --config - -X POST -H 'Content-Type: application/json' \ From 03d06d5176752e78133afb1b43271e8e3c8ece58 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Thu, 12 Nov 2026 16:26:23 +0100 Subject: [PATCH 04/10] ci: fall back to the image's python3 when setup-python's build cannot run Co-Authored-By: Claude Opus 5.5 --- .../setup-build-environment/action.yml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/.github/actions/setup-build-environment/action.yml b/.github/actions/setup-build-environment/action.yml index cba2d2e5..fc640f3d 100644 --- a/.github/actions/setup-build-environment/action.yml +++ b/.github/actions/setup-build-environment/action.yml @@ -12,10 +12,29 @@ runs: key: ${{ runner.os }}-pio - name: Install Python + id: python + continue-on-error: true uses: actions/setup-python@v6 with: python-version: '3.13' + # CUSTOM (TeTeHacko): setup-python's build for the runner OS can need a + # newer CPU than the runner host has ("CPU ISA level is lower than + # required"); fall back to the image's own python3 in a venv + - name: Python fallback + if: steps.python.outcome == 'failure' + shell: bash + run: | + set -euo pipefail + venv="$RUNNER_TEMP/pyenv" + if ! python3 -m venv "$venv"; then + apt-get update -qq + apt-get install -y -qq python3 python3-venv + python3 -m venv --clear "$venv" + fi + echo "$venv/bin" >>"$GITHUB_PATH" + "$venv/bin/python" --version + - name: Install PlatformIO shell: bash run: | From 0d3cb6051d9f197278bf2975b22d5309c4130ed0 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Thu, 12 Nov 2026 16:53:44 +0100 Subject: [PATCH 05/10] rxps: measured on the bench, documented, built into the public releases Co-Authored-By: Claude Opus 5.5 --- .github/workflows/pub-release.yml | 3 +++ README.md | 19 +++++++++++++++ docs/cli_commands.md | 39 +++++++++++++++++++++++++++++++ docs/power.md | 35 ++++++++++++++++++++++++++- 4 files changed, 95 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pub-release.yml b/.github/workflows/pub-release.yml index 5e74964d..b18947bb 100644 --- a/.github/workflows/pub-release.yml +++ b/.github/workflows/pub-release.yml @@ -44,7 +44,10 @@ env: # FILTER_CHANNEL_PSKS = [channel_filter] in platformio.ini (#meshcore, Public, # #test -- public keys): compiles the repeater's `filter` (deny-forward by # sender name); inert until an operator adds a name. + # WITH_RX_POWERSAVING compiles `set radio.rxps` (SX1262 RX duty cycle); off + # until an operator sets it. PUB_FLAGS: >- + -D WITH_RX_POWERSAVING -D LORA_FREQ=869.432 -D LORA_BW=62.5 -D LORA_SF=7 -D LORA_CR=5 -D ADVERT_INTERVAL_DEFAULT=0 -D FLOOD_ADVERT_INTERVAL_DEFAULT=25 -D AIRTIME_FACTOR_DEFAULT=9.0 -D DEFAULT_REGIONS=\"cz,cs\" diff --git a/README.md b/README.md index 0f9b0c40..221ba25d 100644 --- a/README.md +++ b/README.md @@ -76,11 +76,20 @@ označený `CUSTOM (TeTeHacko)`. Nic z toho nemění protokol na rádiu. a záznam o hardfaultu přežijí teplý reset (`.noinit`); `clkreboot`. * Na solárních uzlech žádná blikající LED a pomalejší BLE advertising; stav baterie jako ikona na konci advertovaného jména (volitelné). +* Volitelný RX duty cycle (`set radio.rxps`, port PowerSaving z EasySkyMesh): + SX1262 mezi krátkými okny poslechu spí. Ve veřejných buildech je zabudovaný + a **vypnutý**; `max` na lavici ušetřil ~2,3 mA bez ztráty paketů + ([docs/power.md](docs/power.md)). Jen SX1262, ne LR1110 (T1000-E). ### Senzory a companiony * `simple_sensor`: telemetrie z externí stanice po UART (`BudkaLinkSensorManager`, jeden LPP kanál na veličinu), `sensor read`. +* Senzory, které jinak měří nepřetržitě (INA219, INA226, INA260, INA3221, + BMP280), mezi čteními telemetrie spí a měří jen na vyžádání (nápad a první + patch pro INA219: Alkel Brostl). Čipy INA se rozlišují podle ID, takže + INA226 už se nedetekuje jako INA219. Odpor bočníku se nastavuje za běhu + a ukládá se: `sensor set ina.shunt `. * Companion: `gps duty` přežije reboot, export klíče a PIN jsou na neověřeném USB spojení zamčené, kopie data sestavení má hlídanou délku. KISS modem: oprava o jedna vedle při zkracování jména. @@ -237,11 +246,21 @@ twice a day; everything below is on top of that. Our code is marked hardfault record survive a warm reset (`.noinit`); `clkreboot`. * No blinking LED and slower BLE advertising on solar nodes; battery level as an icon at the end of the advertised name (opt-in). +* Optional RX duty cycle (`set radio.rxps`, ported from EasySkyMesh + PowerSaving): the SX1262 sleeps between short listening windows. Built into + the public releases and **off**; `max` saved ~2.3 mA on the bench with no + packet loss ([docs/power.md](docs/power.md)). SX1262 only, not the LR1110 + (T1000-E). ### Sensors and companions * `simple_sensor`: telemetry from an external station over UART (`BudkaLinkSensorManager`, one LPP channel per meter), `sensor read`. +* Sensors that would otherwise convert continuously (INA219, INA226, INA260, + INA3221, BMP280) sleep between telemetry reads and measure on demand (idea + and first INA219 patch: Alkel Brostl). INA chips are told apart by their ID, + so an INA226 is no longer taken for an INA219. The shunt is set at runtime + and saved: `sensor set ina.shunt `. * Companion: `gps duty` persists, key export / PIN gated on an unauthenticated USB link, bounded build-date copy. KISS modem: off-by-one in the name clamp. diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 80f62035..c80447ab 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -545,6 +545,45 @@ so the icon and the Grafana percentage tell one story. --- +#### View or change the RX duty cycle (rxps) -- CUSTOM (TeTeHacko) +**Usage:** +- `get radio.rxps` +- `set radio.rxps off|on|balanced|max` +- `set radio.rxps level <1-10> [preamble <16|32>]` +- `set radio.rxps max preamble <16|32>` + +The SX1262 sleeps between short listening windows (`SetRxDutyCycle`) instead +of listening all the time, and stays awake through a packet once it hears a +preamble. Ported from EasySkyMesh PowerSaving v18 (IoTThinks). Repeater, room +server and sensor; SX1262 only (an LR11x0 reports `supported=no`). Present +only in builds with `-D WITH_RX_POWERSAVING` (the public releases have it) and +off until you set it; the setting is saved. + +**Parameters:** +- `on` (= `conservative`, level 3), `balanced` (level 6), `max` (level 8): the + higher the level, the longer the sleep. The named presets assume senders + with a 16-symbol preamble (the MeshCore default), so they are safe on a + mixed mesh. +- `level `: the same scale by number; without `preamble` it follows the SF. + 9 (`overdrive`) and 10 (`riskyWorkingMax`) are past the datasheet's timing + condition -- 10 is known to lose packets. +- ` `: raw window lengths. + +`get radio.rxps` shows the requested and the effective state +(`desired=on,effective=armed`), the window lengths and two error counters. If +arming fails three times in a row, the radio falls back to continuous RX by +itself (`effective=continuous`, `fail` counts up). The noise-floor calibration +also runs in continuous RX. + +**Default:** `off` + +**Note:** Measured 12. 11. 2026 on a XIAO nRF52840 + Wio-SX1262 at 5 V +(866.5 MHz / SF8 / BW62.5, A/B/A/B, 15 min cells): `max` saves **~2.3 mA** +(cell repeatability 0.3 mA). A 3-board zero-hop test lost nothing on `max` +(0/120). See `docs/power.md`. + +--- + ### Routing #### View or change this node's repeat flag diff --git a/docs/power.md b/docs/power.md index 3db23982..ae130697 100644 --- a/docs/power.md +++ b/docs/power.md @@ -13,7 +13,7 @@ figures are. | **GPS running continuously** | **46.0 mA** (spread 43.7-47.5) | `gps duty` recovers 42-45 of it | | BLE advertising + Bluefruit's blinking LED | see below | defaults changed, LED off, 1 s interval | | `powersaving on` (MCU light sleep) | **~1 mA, not separable from zero** | keep it on (free), but it is not a lever | -| RX duty cycle (EasySkyMesh "rxps") | ~2 mA on our SF7 preset | **not worth pre-release code** whose failure mode is a deaf repeater | +| RX duty cycle (`set radio.rxps`, from EasySkyMesh) | **~2.3 mA** at `max` (XIAO, 12. 11. 2026) | opt-in, off by default: worth it on a small panel, see below | | `radio.rxgain off` | ~0.7 mA | **no** — 1-3 dB of sensitivity is what a mast node is for | | FEM LNA control | n/a | SenseCap has no FEM, only an RXEN switch | @@ -89,6 +89,39 @@ Bench boards keep both upstream behaviours (`-D RPT_BLE_CONN_LED=1`, stands: ship with BLE **on**, verify the node on site, and only then turn it off over the mesh — otherwise a node that does not come up has no way in. +## RX duty cycle (rxps) + +Ported from EasySkyMesh PowerSaving v18 behind `-D WITH_RX_POWERSAVING` (the +public releases have it), SX1262 only, **off until set**. The radio listens in +short windows and sleeps between them, staying awake through a packet once it +hears a preamble; after three failed arms it falls back to continuous RX by +itself. Commands: `docs/cli_commands.md`, `radio.rxps`. + +Measured 12. 11. 2026 on a XIAO nRF52840 + Wio-SX1262 (not the SenseCAP of +the rest of this page), bench preset 866.5 MHz / SF8 / BW62.5, fed at 5 V +through an INA226 (10 mOhm) read every 5 s; the only other load was a UC96 on +the XIAO's USB port. A/B/A/B, 15 min cells, the first 2 min of each dropped: + +| cell | rxps | mean | median | +|---|---|---|---| +| 1 | off | 33.84 mA | 32.2 mA | +| 2 | max | 31.31 mA | 30.5 mA | +| 3 | off | 33.53 mA | 32.5 mA | +| 4 | max | 31.36 mA | 30.3 mA | + +`max` (level 8) against the mean of its neighbours: **-2.4 / -2.2 mA**, pooled +-2.35 mA (medians -1.95 mA); off vs off differs by 0.3 mA, max vs max by +0.05 mA. That is the radio's share, so it carries over to other SX1262 boards +in absolute terms; the 33 mA base is this bench (meter, BLE advertising), not +a node. Behind the XIAO's linear regulator the battery sees the same current: +~7-8 mW at 3.3 V. + +Reception: a 3-board zero-hop matrix (20 rounds, each link witnessed by +another board) lost 0/120 with rxps off, 1/120 at `on` (level 3) and 0/120 at +`max`; rxps stayed armed with no error counts. One loss in 120 is not +distinguishable from chance. Not measured: mixed SF/preamble senders, a busy +live mesh. On a mast, where 2 mA of ~24 is not the problem, leave it off. + ## MCU sleep `powersaving on` makes the nRF52 wait in WFE between events (it wakes on any From d4afea1eb3edec291f5d701af26a376e613918b1 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Thu, 12 Nov 2026 17:31:24 +0100 Subject: [PATCH 06/10] pub-release: tag v1.18.0+tth., dated title and asset names Co-Authored-By: Claude Opus 5.5 --- .github/workflows/pub-release.yml | 89 ++++++++++++++++++++----------- 1 file changed, 57 insertions(+), 32 deletions(-) diff --git a/.github/workflows/pub-release.yml b/.github/workflows/pub-release.yml index 9cf2fb1c..43c570c3 100644 --- a/.github/workflows/pub-release.yml +++ b/.github/workflows/pub-release.yml @@ -11,7 +11,10 @@ # # Runs on every push to main -- the export pushes there only after an # upstream merge (private repo, tth-upstream-sync) -- and by hand. -# Release tag tth-, titled with the stamped version (v1.18.0-tth); +# Release tag v1.18.0+tth.[.n] (the n-th release of that day), +# titled "v1.18.0+tth · 12. 11. 2026"; assets carry the tag in their names, the +# body the version the node reports (`ver`: v1.18.0-tth). Until 12. 11. +# 2026 the tags were tth-; pruning and the changelog know both; # the newest KEEP releases stay, older ones are deleted. The body is a # changelog since the previous release: our own commits, then the upstream # PRs the upstream merges brought in. @@ -83,39 +86,58 @@ jobs: - name: Commit and tag id: src + env: + TOKEN: ${{ secrets.GITEA_TOKEN || github.token }} + REPLACE: ${{ github.event.inputs.replace }} run: | set -euo pipefail git fetch -q --tags sha=$(git rev-parse HEAD) - echo "sha=$sha" >>"$GITHUB_OUTPUT" - echo "tag=tth-${sha:0:8}" >>"$GITHUB_OUTPUT" - git describe --tags --abbrev=0 --match '*v[0-9]*' HEAD - - - name: Release exists? - env: - TOKEN: ${{ secrets.GITEA_TOKEN || github.token }} - TAG: ${{ steps.src.outputs.tag }} - REPLACE: ${{ github.event.inputs.replace }} - run: | - set -euo pipefail + # upstream base as tools/build_version.py finds it: "companion-v1.18.0" -> v1.18.0 + desc=$(git describe --tags --abbrev=0 --match '*v[0-9]*' --exclude '*+tth*' --exclude 'backup/*' HEAD) + [[ $desc =~ v[0-9].* ]] && base=${BASH_REMATCH[0]} || base=$desc + # the COMMIT's date (Prague), so a rebuild of the same commit keeps its tag + day=$(TZ=Europe/Prague git show -s --format=%cd --date=format-local:%Y%m%d HEAD) + human=$(TZ=Europe/Prague git show -s --format=%cd --date=format-local:'%-d. %-m. %Y' HEAD) api="$GITEA/api/v1/repos/$GITHUB_REPOSITORY" auth="header = \"Authorization: token $TOKEN\"" - id=$(curl -sS --config - "$api/releases/tags/$TAG" <<<"$auth" | jq -r '.id // empty') - if [ -n "$id" ]; then - if [ "$REPLACE" != "true" ]; then - echo "::error::release $TAG already exists (id $id); set replace=true to rebuild it" - exit 1 + enc() { jq -rn --arg s "$1" '$s|@uri'; } + # v1.18.0+tth.20261112, a second release of the day .2, ... + n=1 + while :; do + tag="$base+tth.$day" + [ "$n" -eq 1 ] || tag="$tag.$n" + rel=$(curl -sS --config - "$api/releases/tags/$(enc "$tag")" <<<"$auth") + id=$(jq -r '.id // empty' <<<"$rel") + [ -n "$id" ] || break + if [ "$(jq -r .target_commitish <<<"$rel")" = "$sha" ]; then + if [ "$REPLACE" != "true" ]; then + echo "::error::release $tag already exists (id $id); set replace=true to rebuild it" + exit 1 + fi + curl -sSf --config - -X DELETE "$api/releases/$id" <<<"$auth" + curl -sSf --config - -X DELETE "$api/tags/$(enc "$tag")" <<<"$auth" || true + echo "removed old $tag" + break fi - curl -sSf --config - -X DELETE "$api/releases/$id" <<<"$auth" - curl -sSf --config - -X DELETE "$api/tags/$TAG" <<<"$auth" || true - echo "removed old $TAG" - fi + n=$((n + 1)) + done + title="$base+tth · $human" + [ "$n" -eq 1 ] || title="$title ($n)" + echo "release $tag: $title (commit $sha)" + { + echo "sha=$sha" + echo "tag=$tag" + echo "title=$title" + } >>"$GITHUB_OUTPUT" - name: Setup Build Environment uses: ./.github/actions/setup-build-environment - name: Build and package id: build + env: + TAG: ${{ steps.src.outputs.tag }} run: | set -euo pipefail sha=$(git rev-parse --short=8 HEAD) @@ -131,15 +153,15 @@ jobs: b=".pio/build/$env" if [ -f "$b/firmware.zip" ]; then # nRF52 python3 bin/uf2conv/uf2conv.py "$b/firmware.hex" -c -o "$b/firmware.uf2" -f 0xADA52840 - cp "$b/firmware.uf2" "$dist/$env$suffix-$sha.uf2" - cp "$b/firmware.zip" "$dist/$env$suffix-$sha.zip" + cp "$b/firmware.uf2" "$dist/$env$suffix-$TAG.uf2" + cp "$b/firmware.zip" "$dist/$env$suffix-$TAG.zip" v=$(grep -m1 -aoE 'v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?' "$b/firmware.elf" || true) case "$v" in *+) echo "::error::$env is dirty ($v)"; exit 1 ;; esac [ -n "$version" ] || version="$v" else # ESP32 PLATFORMIO_BUILD_FLAGS="$PUB_FLAGS $2" pio run -t mergebin -e "$env" - cp "$b/firmware.bin" "$dist/$env$suffix-$sha.bin" - cp "$b/firmware-merged.bin" "$dist/$env$suffix-$sha-merged.bin" + cp "$b/firmware.bin" "$dist/$env$suffix-$TAG.bin" + cp "$b/firmware-merged.bin" "$dist/$env$suffix-$TAG-merged.bin" fi echo "::endgroup::" } @@ -155,6 +177,7 @@ jobs: TOKEN: ${{ secrets.GITEA_TOKEN || github.token }} SHA: ${{ steps.src.outputs.sha }} TAG: ${{ steps.src.outputs.tag }} + TITLE: ${{ steps.src.outputs.title }} VERSION: ${{ steps.build.outputs.version }} run: | set -euo pipefail @@ -176,7 +199,7 @@ jobs: break fi done < <(curl -sSf --config - "$api/releases?limit=50" <<<"$auth" | - jq -r --arg t "$TAG" 'map(select(.tag_name | startswith("tth-")) | select(.tag_name != $t)) + jq -r --arg t "$TAG" 'map(select(.tag_name | startswith("tth-") or test("[+]tth[.]")) | select(.tag_name != $t)) | sort_by(.created_at) | reverse | .[] | "\(.tag_name) \(.target_commitish)"') # no older release: the last 20 commits of our own line [ -n "$base" ] || base=$(git rev-list --first-parent --max-count=21 "$SHA" | tail -1) @@ -205,10 +228,12 @@ jobs: done n=${#ups[@]} body=$( - echo "$VERSION" + echo "$TITLE" + echo + echo "Verze v uzlu · \`ver\`: $VERSION" echo if [ -n "$prev" ]; then - echo "Od předchozího vydání · since [$prev]($web/releases/tag/$prev)" + echo "Od předchozího vydání · since [$prev]($web/releases/tag/$(jq -rn --arg s "$prev" '$s|@uri'))" echo fi echo "### Změny forku · fork changes" @@ -224,22 +249,22 @@ jobs: echo echo "commit $SHA, run $GITHUB_RUN_NUMBER" ) - jq -n --arg t "$TAG" --arg c "$SHA" --arg n "$VERSION" --arg b "$body" \ + jq -n --arg t "$TAG" --arg c "$SHA" --arg n "$TITLE" --arg b "$body" \ '{tag_name: $t, target_commitish: $c, name: $n, body: $b}' >"$RUNNER_TEMP/rel.json" id=$(curl -sSf --config - -X POST -H 'Content-Type: application/json' \ --data-binary "@$RUNNER_TEMP/rel.json" "$api/releases" <<<"$auth" | jq -r .id) for f in dist/*; do curl -sSf --config - -X POST -F "attachment=@$f" \ - "$api/releases/$id/assets?name=$(basename "$f")" <<<"$auth" >/dev/null + "$api/releases/$id/assets?name=$(jq -rn --arg s "${f##*/}" '$s|@uri')" <<<"$auth" >/dev/null echo "uploaded $(basename "$f")" done echo "released $TAG = $VERSION (id $id)" # keep the newest $KEEP, oldest go (with their tags) curl -sSf --config - "$api/releases?limit=50" <<<"$auth" | - jq -r --argjson k "$KEEP" 'map(select(.tag_name | startswith("tth-"))) + jq -r --argjson k "$KEEP" 'map(select(.tag_name | startswith("tth-") or test("[+]tth[.]"))) | sort_by(.created_at) | reverse | .[$k:][] | "\(.id) \(.tag_name)"' | while read -r old_id old_tag; do curl -sSf --config - -X DELETE "$api/releases/$old_id" <<<"$auth" - curl -sSf --config - -X DELETE "$api/tags/$old_tag" <<<"$auth" || true + curl -sSf --config - -X DELETE "$api/tags/$(jq -rn --arg s "$old_tag" '$s|@uri')" <<<"$auth" || true echo "pruned $old_tag" done From a2dacb805dbebe08da150bef1968bf5a308d9537 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Thu, 12 Nov 2026 17:47:25 +0100 Subject: [PATCH 07/10] pub-release: changelog unfolds merges of our own branches Co-Authored-By: Claude Opus 5.5 --- .github/workflows/pub-release.yml | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pub-release.yml b/.github/workflows/pub-release.yml index 43c570c3..81898439 100644 --- a/.github/workflows/pub-release.yml +++ b/.github/workflows/pub-release.yml @@ -203,9 +203,20 @@ jobs: | sort_by(.created_at) | reverse | .[] | "\(.tag_name) \(.target_commitish)"') # no older release: the last 20 commits of our own line [ -n "$base" ] || base=$(git rev-list --first-parent --max-count=21 "$SHA" | tail -1) - # ours: commits on our main itself (first parent), not what the - # upstream merges brought in - ours=$(git log --first-parent --no-merges --format="- %s ([%h]($web/commit/%H))" "$base..$SHA") + # ours: commits on our main itself (first parent); a merge of one of + # our own branches (feat/...) is unfolded into the branch's commits, + # an upstream merge is left to the upstream list below + fmt="- %s ([%h]($web/commit/%H))" + ours="" + for c in $(git log --first-parent --format=%H "$base..$SHA"); do + if git rev-parse -q --verify "$c^2" >/dev/null; then + git log -1 --format=%s "$c" | grep -q '^Merge upstream' && continue + ours+=$(git log --no-merges --format="$fmt" "$c^1..$c^2")$'\n' + else + ours+=$(git log -1 --format="$fmt" "$c")$'\n' + fi + done + ours=${ours%$'\n'} # upstream: the first-parent line of each merged upstream branch, # PR merges as their title, direct commits as their subject declare -A seen=() From e6a318442372642ec3359740e757816f298a71b8 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Thu, 12 Nov 2026 19:16:42 +0100 Subject: [PATCH 08/10] pub-release, README: formatted flashing notes, release names, dutycycle Co-Authored-By: Claude Opus 5.5 --- .github/workflows/pub-release.yml | 37 +++++++++++++++++++++++++------ README.md | 34 ++++++++++++++++++---------- docs/cli_commands.md | 2 +- docs/power.md | 18 +++++++++++---- 4 files changed, 67 insertions(+), 24 deletions(-) diff --git a/.github/workflows/pub-release.yml b/.github/workflows/pub-release.yml index 81898439..f60e23c3 100644 --- a/.github/workflows/pub-release.yml +++ b/.github/workflows/pub-release.yml @@ -44,7 +44,7 @@ env: GITEA: https://git.rfa.cz KEEP: 5 # 869.432/62.5/SF7/CR5; repeater + room server: zero-hop advert off, flood - # advert 25 h, af 9 (= 10 % duty cycle); repeater: regions cz,cs next to *. + # advert 25 h, AIRTIME_FACTOR 9 (= `dutycycle` 10 %); repeater: regions cz,cs next to *. # Path hash 2 B is this fork's default anyway. TX power stays the board's. # FILTER_CHANNEL_PSKS = [channel_filter] in platformio.ini (#meshcore, Public, # #test -- public keys): compiles the repeater's `filter` (deny-forward by @@ -183,11 +183,34 @@ jobs: set -euo pipefail api="$GITEA/api/v1/repos/$GITHUB_REPOSITORY" auth="header = \"Authorization: token $TOKEN\"" - note='BLE PIN 123456 and admin password "password" are placeholders: change them after flashing. - *-observer: repeater with a BLE console (OFF after flashing: set a PIN, then send ble on) and the - rxlog / pktlog rings for the repeater observer. - Czech mesh defaults (meshcore.cz): 869.432 MHz / 62.5 kHz / SF7 / CR5; repeater: zero-hop advert off, - flood advert 25 h, af 9 (10 % duty cycle), regions cz + cs. Apply to a fresh or erased node only.' + readme="$GITEA/$GITHUB_REPOSITORY#o-tomto-forku-meshcore-tth" + note=$(cat <\` (nejvýš 15 + znaků), \`ble pin <6 číslic>\`. + - **Výchozí nastavení pro český mesh** ([meshcore.cz](https://meshcore.cz/)): 869,432 MHz / 62,5 kHz / SF7 / CR5; + repeater a room server: zero-hop advert vypnutý, flood advert á 25 h, duty cycle 10 % (\`get dutycycle\`); repeater: + regiony \`cz\` a \`cs\`. **Platí jen pro nový nebo smazaný uzel** – nové nahrání ponechá uložené nastavení. + - **\`*-observer\`**: repeater s BLE konzolí a buffery \`rxlog\` / \`pktlog\` pro repeater observer. BLE je po nahrání + vypnuté: nejdřív \`ble pin\`, pak \`ble on\`. + - **RX duty cycle** (\`set radio.rxps\`, jen SX1262) je zabudovaný a vypnutý. + - Ověření: \`ver\` ukáže verzi z řádku *Verze v uzlu* výše. Co fork mění proti upstreamu: [README]($readme). + +
English + + - **BLE PIN \`123456\` and admin password \`password\` are placeholders.** Change them after flashing: \`password + \` (15 characters at most), \`ble pin <6 digits>\`. + - **Czech mesh defaults** ([meshcore.cz](https://meshcore.cz/)): 869.432 MHz / 62.5 kHz / SF7 / CR5; repeater and room + server: zero-hop advert off, flood advert every 25 h, 10 % duty cycle (\`get dutycycle\`); repeater: regions \`cz\` + and \`cs\`. **A fresh or erased node only** – a reflash keeps the saved settings. + - **\`*-observer\`**: repeater with a BLE console and the \`rxlog\` / \`pktlog\` rings for the repeater observer. BLE + is off after flashing: \`ble pin\` first, then \`ble on\`. + - **RX duty cycle** (\`set radio.rxps\`, SX1262 only) is built in and off. + - Check: \`ver\` shows the version from the *Verze v uzlu* (node version) line above. What the fork changes against + upstream: [README]($readme). + +
+ EOF + ) web="$GITEA/$GITHUB_REPOSITORY" gh=https://github.com/meshcore-dev/MeshCore max=60 @@ -255,8 +278,8 @@ jobs: [ "$n" -le "$max" ] || echo "- … a dalších $((n - max)) · and $((n - max)) more" echo echo "### Po flashi · after flashing" + echo echo "$note" - echo "What this fork changes against upstream: see README.md." echo echo "commit $SHA, run $GITHUB_RUN_NUMBER" ) diff --git a/README.md b/README.md index 221ba25d..d62e90b2 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ uzel nepotřebuje obvyklé kolečko nastavování: * rádio 869,432 MHz / 62,5 kHz / SF7 / CR5 (všechny buildy); * repeater a room server: zero-hop advert vypnutý, flood advert každých 25 h, - `af 9` (10% duty cycle); + duty cycle 10 % (`get dutycycle` → `10.0%`; zastaralé `af` je 9); * repeater: regiony `cz` a `cs` vedle `*` – vlastní `cz-` přidáš přes `region put cz-xxx cz` + `region save`; * 2bajtové path hashe (výchozí v tomto forku); @@ -129,10 +129,14 @@ Releasy do `tth-654d53f3` `ble pin` nemají: BLE tam nech vypnuté a používej ### Nahrání releasu -Soubory jsou v [Releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases), -jedna sada pro každou desku a roli (`_-`): `.zip` a `.uf2` -pro nRF52, `.bin` pro ESP32 (`-merged.bin` je celý obraz pro prázdnou desku, -obyčejný `.bin` aktualizace). Kontrolní součty jsou v `SHA256SUMS`. +Soubory jsou v [Releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases). +Release se jmenuje podle upstreamové verze a data, např. +`v1.18.0+tth.20261112` (druhý téhož dne `.2`), a v popisu má změny od +předchozího releasu. Pro každou desku a roli je jedna sada +(`_-`, např. `Xiao_nrf52_repeater-v1.18.0+tth.20261112.zip`): +`.zip` a `.uf2` pro nRF52, `.bin` pro ESP32 (`-merged.bin` je celý obraz pro +prázdnou desku, obyčejný `.bin` aktualizace). Kontrolní součty jsou +v `SHA256SUMS`. Releasy do 12. 11. 2026 se jmenovaly `tth-`. **nRF52 (XIAO, RAK4631, SenseCAP Solar, T1000-E, T114) přes [webový flasher MeshCore](https://flasher.meshcore.io)** – Chrome, Edge nebo @@ -145,7 +149,8 @@ Chromium na počítači (Web Serial; ne Firefox ani Safari): 4. Klikni na **Flash!** a vyber ten nový port. Zhruba 30 s, pak se deska restartuje do nového firmwaru. 5. **Console** ve flasheru (nebo jakýkoli sériový terminál, 115200) ověří - výsledek: `ver` ukáže `v1.xx.x-tth`, sha odpovídá názvu souboru. + výsledek: `ver` ukáže `v1.xx.x-tth`, stejně jako řádek „Verze v uzlu“ + v popisu releasu. **Neklikej na Erase Flash**, pokud nechceš nový uzel: smaže identitu (klíč uzlu a všechno, co ho zná) i veškeré nastavení. Obyčejné nahrání je zachová. @@ -272,7 +277,7 @@ freshly flashed node does not need the usual round of settings: * radio 869.432 MHz / 62.5 kHz / SF7 / CR5 (all builds); * repeater and room server: zero-hop advert off, flood advert every 25 h, - `af 9` (10 % duty cycle); + 10 % duty cycle (`get dutycycle` → `10.0%`; the deprecated `af` reads 9); * repeater: regions `cz` and `cs` next to `*` -- add your own `cz-` with `region put cz-xxx cz` + `region save`; * 2-byte path hashes (this fork's default); @@ -299,10 +304,14 @@ up to `tth-654d53f3` do not have `ble pin`: keep BLE off there and use USB. ### Flashing a release -Files are in [Releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases), -one set per board and role (`_-`): `.zip` and `.uf2` for -nRF52 boards, `.bin` for ESP32 (`-merged.bin` is the full image for a blank -board, the plain `.bin` an update). `SHA256SUMS` lists the checksums. +Files are in [Releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases). +A release is named after the upstream version and the date, e.g. +`v1.18.0+tth.20261112` (a second one that day `.2`), and its notes list the +changes since the previous release. One set per board and role +(`_-`, e.g. `Xiao_nrf52_repeater-v1.18.0+tth.20261112.zip`): +`.zip` and `.uf2` for nRF52 boards, `.bin` for ESP32 (`-merged.bin` is the +full image for a blank board, the plain `.bin` an update). `SHA256SUMS` lists +the checksums. Releases up to 12. 11. 2026 were named `tth-`. **nRF52 (XIAO, RAK4631, SenseCAP Solar, T1000-E, T114) with the [MeshCore web flasher](https://flasher.meshcore.io)** -- Chrome, Edge or @@ -315,7 +324,8 @@ Chromium on a computer (Web Serial; not Firefox or Safari): 4. Click **Flash!** and pick that new port. About 30 s, then the board restarts into the new firmware. 5. **Console** in the flasher (or any serial terminal, 115200) checks the - result: `ver` shows `v1.xx.x-tth`, the sha from the file name. + result: `ver` shows `v1.xx.x-tth`, the same as the "Verze v uzlu" + (node version) line in the release notes. **Do not click Erase Flash** unless you want a new node: it wipes the identity (the node's key and everything that knows it) together with all diff --git a/docs/cli_commands.md b/docs/cli_commands.md index c80447ab..5c02833f 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -580,7 +580,7 @@ also runs in continuous RX. **Note:** Measured 12. 11. 2026 on a XIAO nRF52840 + Wio-SX1262 at 5 V (866.5 MHz / SF8 / BW62.5, A/B/A/B, 15 min cells): `max` saves **~2.3 mA** (cell repeatability 0.3 mA). A 3-board zero-hop test lost nothing on `max` -(0/120). See `docs/power.md`. +(0/240 over two runs, the second on the public release). See `docs/power.md`. --- diff --git a/docs/power.md b/docs/power.md index ae130697..5b885bad 100644 --- a/docs/power.md +++ b/docs/power.md @@ -116,10 +116,20 @@ in absolute terms; the 33 mA base is this bench (meter, BLE advertising), not a node. Behind the XIAO's linear regulator the battery sees the same current: ~7-8 mW at 3.3 V. -Reception: a 3-board zero-hop matrix (20 rounds, each link witnessed by -another board) lost 0/120 with rxps off, 1/120 at `on` (level 3) and 0/120 at -`max`; rxps stayed armed with no error counts. One loss in 120 is not -distinguishable from chance. Not measured: mixed SF/preamble senders, a busy +Reception: a 3-board zero-hop matrix (x1, x3, x4; rxps switched on x1 and x4, +x3 the reference with rxps off; 20 rounds per phase, each link witnessed by +another board), run twice -- on the development build, then repeated on the +public release `v1.18.0+tth.20261112` (`ver` v1.18.0-tthd4afea1): + +| phase | development build | public release | together | +|---|---|---|---| +| rxps off | 0/120 | 1/120 | 1/240 | +| `on` (level 3) | 1/120 | 2/120 | 3/240 | +| `max` (level 8) | 0/120 | 0/120 | **0/240** | + +rxps stayed armed throughout, no error counts. Single losses happen with rxps +off as well, and of the three at level 3 one was on x3, which had rxps off: the +bench shows no degradation at any level. Not measured: mixed SF/preamble senders, a busy live mesh. On a mast, where 2 mA of ~24 is not the problem, leave it off. ## MCU sleep From b7b397b9b124e4d46ea5233fc08ea8fcd6a739d4 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Thu, 12 Nov 2026 22:08:33 +0100 Subject: [PATCH 09/10] README: nRF52 boot undervoltage lock is off, waiting for upstream #2088 --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index d62e90b2..0f995e20 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,13 @@ označený `CUSTOM (TeTeHacko)`. Nic z toho nemění protokol na rádiu. SX1262 mezi krátkými okny poslechu spí. Ve veřejných buildech je zabudovaný a **vypnutý**; `max` na lavici ušetřil ~2,3 mA bez ztráty paketů ([docs/power.md](docs/power.md)). Jen SX1262, ne LR1110 (T1000-E). +* Podpěťová pojistka při startu (`PWRMGT_VOLTAGE_BOOTLOCK`) je na nRF52 + **vypnutá**, stejně jako v upstreamu od v1.18.0 + ([#2377](https://github.com/meshcore-dev/MeshCore/pull/2377)): pevný práh + 3,3 V nepouštěl k životu uzly na LiFePO4 nebo LTO. Firmware tak naběhne na + jakékoli chemii článku; před hlubokým vybitím má chránit BMS nebo ochranná + destička článku. Konfigurovatelná pojistka podle chemie čeká na upstream + ([#2088](https://github.com/meshcore-dev/MeshCore/pull/2088)). ### Senzory a companiony @@ -256,6 +263,13 @@ twice a day; everything below is on top of that. Our code is marked the public releases and **off**; `max` saved ~2.3 mA on the bench with no packet loss ([docs/power.md](docs/power.md)). SX1262 only, not the LR1110 (T1000-E). +* The nRF52 boot undervoltage lock (`PWRMGT_VOLTAGE_BOOTLOCK`) is **off**, + as in upstream since v1.18.0 + ([#2377](https://github.com/meshcore-dev/MeshCore/pull/2377)): its fixed + 3.3 V threshold kept LiFePO4 and LTO nodes from booting. The firmware boots + on any cell chemistry; deep-discharge protection is up to the BMS or the + cell's protection board. A configurable, chemistry-aware lock is waiting + for upstream ([#2088](https://github.com/meshcore-dev/MeshCore/pull/2088)). ### Sensors and companions From 845a2282095442dad72ff9a2eb30443755d606f6 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Fri, 13 Nov 2026 16:03:03 +0100 Subject: [PATCH 10/10] tools/ public with a local config, private tools to .tth/tools/ Co-Authored-By: Claude Opus 5.5 --- .gitignore | 2 +- docs/budka-sensor.md | 2 +- docs/power.md | 4 +- tools/README.md | 61 ++++ tools/bench_soak.py | 247 ++++++++++++++++ tools/ble_cli.py | 184 ++++++++++++ tools/ble_dfu.py | 363 +++++++++++++++++++++++ tools/ble_flash_node.sh | 259 +++++++++++++++++ tools/ble_pair.py | 200 +++++++++++++ tools/board_probe.py | 433 ++++++++++++++++++++++++++++ tools/build_version.py | 10 + tools/companion_backup.py | 260 +++++++++++++++++ tools/config.example.ini | 32 +++ tools/flash_node.sh | 484 +++++++++++++++++++++++++++++++ tools/fleet.py | 26 ++ tools/fleet_test.py | 569 +++++++++++++++++++++++++++++++++++++ tools/fw_room_smoke.py | 119 ++++++++ tools/gen_node_id.py | 177 ++++++++++++ tools/mctools_config.py | 173 +++++++++++ tools/mesh_sniffer.py | 445 +++++++++++++++++++++++++++++ tools/power_ab.py | 461 ++++++++++++++++++++++++++++++ tools/preset_trace.py | 85 ++++++ tools/radio_stall_watch.py | 129 +++++++++ tools/serial_cli.py | 116 ++++++++ tools/serial_tcp_proxy.py | 86 ++++++ tools/xiao_serial_dfu.sh | 75 +++++ tools/xiao_uf2_flash.sh | 314 ++++++++++++++++++++ 27 files changed, 5312 insertions(+), 4 deletions(-) create mode 100644 tools/README.md create mode 100755 tools/bench_soak.py create mode 100755 tools/ble_cli.py create mode 100644 tools/ble_dfu.py create mode 100755 tools/ble_flash_node.sh create mode 100755 tools/ble_pair.py create mode 100755 tools/board_probe.py create mode 100755 tools/companion_backup.py create mode 100644 tools/config.example.ini create mode 100755 tools/flash_node.sh create mode 100755 tools/fleet.py create mode 100755 tools/fleet_test.py create mode 100755 tools/fw_room_smoke.py create mode 100755 tools/gen_node_id.py create mode 100755 tools/mctools_config.py create mode 100755 tools/mesh_sniffer.py create mode 100755 tools/power_ab.py create mode 100644 tools/preset_trace.py create mode 100755 tools/radio_stall_watch.py create mode 100755 tools/serial_cli.py create mode 100755 tools/serial_tcp_proxy.py create mode 100755 tools/xiao_serial_dfu.sh create mode 100755 tools/xiao_uf2_flash.sh diff --git a/.gitignore b/.gitignore index 961dd4ac..e9e57d4b 100644 --- a/.gitignore +++ b/.gitignore @@ -29,5 +29,5 @@ __pycache__/ # PID soubor lokálního helperu (běhový balast, ne konfigurace) ether.pid -# data z pochůzkových testů (tools/walk.sh fetch) — polohy, necommitovat +# data z pochůzkových testů (.tth/tools/walk.sh fetch) — polohy, necommitovat walk-data/ diff --git a/docs/budka-sensor.md b/docs/budka-sensor.md index fd3bac1c..b61f07cd 100644 --- a/docs/budka-sensor.md +++ b/docs/budka-sensor.md @@ -40,7 +40,7 @@ Budka `mc_tx` pad → XIAO **D0**, GND ↔ GND, each board on its own USB. A A line with a bad checksum is dropped whole; a value not refreshed for 2 min is left out. Meter channels stay reserved while a meter is missing. -Read it with `tools/budka_telem.py `. The sensor +Read it with `.tth/tools/budka_telem.py `. The sensor answers only clients in its ACL — a request from anyone else is dropped (`recv matches no peers` in a `MESH_DEBUG` build). Add the companion from the sensor's USB console with `setperm 1`, or log in as admin. diff --git a/docs/power.md b/docs/power.md index 5b885bad..428c4c37 100644 --- a/docs/power.md +++ b/docs/power.md @@ -137,7 +137,7 @@ live mesh. On a mast, where 2 mA of ~24 is not the problem, leave it off. `powersaving on` makes the nRF52 wait in WFE between events (it wakes on any interrupt, including LoRa DIO1). Upstream ships it **off**, and it was missing from our provisioning, so every node built from that file ran the core at 64 MHz -around the clock. It is now in `tools/provision/repeater-cz-silent.txt`. +around the clock. It is now in our provisioning file. **But it buys about 1 mA, not the 3-4 that seemed obvious.** Measured with GPS held off so its sync windows could not pollute the cells: paired estimate @@ -171,5 +171,5 @@ drain directly costs collected frames. 40.9 mA against 24.1-24.5 in its neighbours). Put `gps off` in every cell of such a run and restore `gps duty` afterwards. -See `tools/README.md` (`power_ab.py`) for the alternating-cell design that makes +See `tools/power_ab.py --help` for the alternating-cell design that makes these deltas trustworthy in the first place. diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 00000000..d3e893b6 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,61 @@ + +# tools/ + +Host-side tools for MeshCore nodes of this fork: consoles, flashing, bench +tests and diagnostics. Every script answers `--help` without touching a port, +a node or the network. + +## Your boards: the local config + +The tools carry no board serial, MAC or host of anyone's bench. Names like +`b1` resolve through one file outside the repo: + + ~/.config/meshcore-tools/config.ini (or $MESHCORE_TOOLS_CONFIG) + +Start from [`config.example.ini`](config.example.ini); the format and the shell +interface are in `mctools_config.py --help`. Without a config everything still +works with full USB serial numbers, BLE MACs and port paths. Two fields matter +for safety: `protect` (flashing tools refuse the board unless told to) and +`refuse` (console tools do not open it at all, e.g. the radio of an observer +running other firmware). No secrets go in there. + +Serial ports are always matched in `/dev/serial/by-id` by the USB serial +number: a `ttyACM` number changes with every replug and would point a tool at +a different board. + +## Consoles + +| tool | what | +|---|---| +| `serial_cli.py` | text console over USB: send commands, print the replies | +| `ble_cli.py` | the same console over BLE (Nordic UART); needs a bonded node | +| `ble_pair.py` | non-interactive BLE pairing by PIN (bluetoothctl over a pty) | +| `serial_tcp_proxy.py` | a board's USB console on a localhost TCP port, for a board on another host (SSH tunnel) | + +## Flashing + +| tool | what | +|---|---| +| `flash_node.sh` | flash any board: picks USB DFU, UF2 or BLE from what the board is doing, refuses `protect`ed boards | +| `xiao_uf2_flash.sh` | XIAO nRF52840 through its UF2 drive, to a named board, verified by reading the version back | +| `xiao_serial_dfu.sh` | XIAO with a text console over USB serial DFU: no drive, no mount, no root | +| `ble_flash_node.sh` | BLE OTA of a node out of reach of a cable, with the checks around it (silence, services, version) | +| `ble_dfu.py` | legacy Nordic DFU over BLE for the Adafruit nRF52 bootloader (buttonless, both phases) | +| `build_version.py` | PlatformIO pre-script: real version and build time for `ver` | + +## Bench and diagnostics + +| tool | what | +|---|---| +| `board_probe.py` | what runs on each board on USB, and whether that changed | +| `fleet_test.py` | regression smoke test of the bench boards after a firmware change | +| `bench_soak.py` | long run: who hears whom over time, when a board reboots or goes deaf | +| `radio_stall_watch.py` | watch a `RADIO_DIAG` node until its receiver stalls | +| `mesh_sniffer.py` | passive sniffer: every frame the radio hears, decoded on the host | +| `preset_trace.py` | TRACE along a fixed path on a chosen radio preset | +| `fw_room_smoke.py` | smoke test of a firmware room server over the air | +| `power_ab.py` | A/B current measurement with a UC96 meter (alternating cells) | +| `companion_backup.py` | back up a companion (contacts, channels, settings) before flashing, diff and restore after | +| `gen_node_id.py` | a node identity whose path hash collides with no known repeater | + +`fleet.py` and `mctools_config.py` are the shared board lookup. diff --git a/tools/bench_soak.py b/tools/bench_soak.py new file mode 100755 index 00000000..272bdacb --- /dev/null +++ b/tools/bench_soak.py @@ -0,0 +1,247 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Dlouhý běh lavice: kdo koho slyší, v čase, a kdy deska rebootuje nebo ohluchne. + +Vzniklo 23. 9. 2026 kvůli second-mast: po OTA na nový firmware přestala přijímat +(`recv 0`) a na zerohop hlásila `sent 0` + `tx_timeout 4`, přestože ob2 vedle ní +slyšel všechny čtyři adverty. Rádio vysílalo, ale IRQ se nedostalo do MCU. +`fleet_test.py` je jednorázový snímek za pár sekund -- tohle je stejná otázka +položená stokrát za sebou, protože chyba přišla až po minutách běhu. + + tools/bench_soak.py --boards b1,b2 --hours 8 + tools/bench_soak.py --period 30 --out /tmp/soak # all bench boards of the config + +Co dělá, v kolech (každých --period s, vysílá jedna deska, dokola): + 1. snímek `stats-packets` a `stats-core` na všech deskách, + 2. vysílající pošle `advert.zerohop` (nikdo ho nerebroadcastuje, takže + „B slyšel A" nejde splnit přes třetí desku a netřeba sahat na `repeat`), + 3. po --settle s druhý snímek. + +Orákulum je vždy JINÁ deska: slyšel = `recv` příjemce vzrostl. Vlastní `sent` +vysílajícího se jen zapisuje vedle -- u second-mast lhal (0, zatímco vysílala). + +Konzole se drží otevřené celou dobu a KAŽDÝ řádek jde s časem do logu, takže se +zachytí i to, co deska vypíše sama (boot `RESETREAS`, `!!! HARDFAULT`). Když +deska zmizí z USB, nástroj to zapíše a čeká, až se vrátí -- nic nerestartuje. + +Nic nemění: žádné `set`, žádné `reboot`. Prefs pro test nastav předem ručně. +PAST (z fleet_test.py): na testované desce nesmí viset BLE klient -- USB a BLE +konzole dělí jeden buffer a prokládají znaky. +""" +import argparse +import glob +import json +import os +import re +import signal +import sys +import threading +import time +from datetime import datetime, timezone + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from board_probe import _open as open_port +from fleet import serial_for + +FLAG_RE = re.compile(r"boot:|RESETREAS|HARDFAULT|LOCKUP|WATCHDOG", re.IGNORECASE) + + +def now(): + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +class Board: + """Jedna konzole: čtecí vlákno loguje vše, `cmd()` sbírá odpověď z okna.""" + + def __init__(self, name, log_fh, events): + self.name = name + self.sn = serial_for(name) + self.log = log_fh + self.events = events + self.s = None + self.lines = [] # řádky od posledního cmd() + self.lock = threading.Lock() + self.stop = False + self.up = False + threading.Thread(target=self._reader, daemon=True).start() + + def _path(self): + hits = [p for p in glob.glob("/dev/serial/by-id/*") if self.sn in p] + return hits[0] if len(hits) == 1 else None + + def _event(self, kind, **kw): + ev = {"t": now(), "board": self.name, "event": kind, **kw} + self.events.append(ev) + self.log.write(json.dumps(ev, ensure_ascii=False) + "\n") + self.log.flush() + print(f"[{ev['t']}] {self.name}: {kind} {kw if kw else ''}", flush=True) + + def _reader(self): + buf = b"" + while not self.stop: + if self.s is None: + p = self._path() + if p: + try: + self.s = open_port(p) + if self.up is False and self.events is not None: + self._event("usb_up", port=os.path.basename(p)) + self.up = True + except Exception: + self.s = None + time.sleep(1) + continue + try: + d = self.s.read(4096) + except Exception as e: + self._event("usb_gone", err=str(e)[:80]) + self.up = False + try: + self.s.close() + except Exception: + pass + self.s = None + continue + if not d: + time.sleep(0.02) + continue + buf += d + while b"\n" in buf: + raw, buf = buf.split(b"\n", 1) + line = raw.decode("utf-8", "replace").rstrip("\r") + if not line.strip(): + continue + self.log.write(f"{now()} {self.name} | {line}\n") + if FLAG_RE.search(line): + self._event("flagged_line", line=line[:200]) + with self.lock: + self.lines.append(line) + self.log.flush() + + def cmd(self, text, window=1.5): + if self.s is None: + return None + with self.lock: + self.lines = [] + try: + self.s.write((text + "\r").encode()) + except Exception: + return None + time.sleep(window) + with self.lock: + return "\n".join(self.lines) + + def stats(self): + out = {} + for c in ("stats-packets", "stats-core"): + r = self.cmd(c) + m = re.search(r"\{.*\}", r or "") + if not m: + return None + try: + out.update(json.loads(m.group(0))) + except ValueError: + return None + return out + + +def main(): + ap = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("--boards", default=None, + help="desky z lokalniho configu, čárkou (default: všechny role=bench bez refuse)") + ap.add_argument("--hours", type=float, default=8.0) + ap.add_argument("--period", type=float, default=60.0, help="s mezi koly") + ap.add_argument("--settle", type=float, default=4.0, help="s po advertu") + ap.add_argument("--out", default=".", help="adresář na log + JSONL") + a = ap.parse_args() + if a.boards is None: + from mctools_config import by_role + + a.boards = ",".join(n for n, b in by_role("bench").items() if b.get("serial") and not b.get("refuse")) + if not a.boards: + ap.error("no --boards and no role=bench board in the local config (tools/mctools_config.py)") + + os.makedirs(a.out, exist_ok=True) + stamp = datetime.now().strftime("%Y%m%d-%H%M%S") + log = open(os.path.join(a.out, f"soak-{stamp}.log"), "a") + rounds_fh = open(os.path.join(a.out, f"soak-{stamp}.jsonl"), "a") + events = [] + boards = [Board(n.strip(), log, events) for n in a.boards.split(",")] + if len(boards) < 2: + sys.exit("potřeba aspoň dvě desky -- svědkem musí být JINÁ deska") + + stop = {"v": False} + signal.signal(signal.SIGINT, lambda *_: stop.update(v=True)) + signal.signal(signal.SIGTERM, lambda *_: stop.update(v=True)) + + time.sleep(3) + last_up = {} + pairs = {} # (tx, rx) -> [heard, tried] + miss_streak = {} # (tx, rx) -> po sobě jdoucí neslyšení + reboots = {b.name: 0 for b in boards} + txto = {b.name: 0 for b in boards} + t_end = time.time() + a.hours * 3600 + rnd = 0 + while not stop["v"] and time.time() < t_end: + t0 = time.time() + tx = boards[rnd % len(boards)] + before = {b.name: b.stats() for b in boards} + ok = tx.cmd("advert.zerohop", window=1.0) + time.sleep(a.settle) + after = {b.name: b.stats() for b in boards} + + rec = {"t": now(), "round": rnd, "tx": tx.name, + "tx_cmd_ok": bool(ok and "OK" in ok), "heard": {}, "boards": {}} + for b in boards: + s0, s1 = before[b.name], after[b.name] + rec["boards"][b.name] = s1 + if s1 and "uptime_secs" in s1: + u = s1["uptime_secs"] + if b.name in last_up and u < last_up[b.name]: + reboots[b.name] += 1 + b._event("reboot", uptime_before=last_up[b.name], uptime_now=u) + last_up[b.name] = u + if s0 and s1: + d_to = s1.get("tx_timeout", 0) - s0.get("tx_timeout", 0) + if d_to > 0: + txto[b.name] += d_to + b._event("tx_timeout", delta=d_to) + if b is tx or not (s0 and s1): + continue + heard = s1.get("recv", 0) - s0.get("recv", 0) >= 1 + rec["heard"][b.name] = heard + key = (tx.name, b.name) + h = pairs.setdefault(key, [0, 0]) + h[1] += 1 + h[0] += int(heard) + miss_streak[key] = 0 if heard else miss_streak.get(key, 0) + 1 + if miss_streak[key] == 3: + b._event("deaf?", tx=tx.name, streak=3, + note="3 kola po sobě neslyšel -- ověř svědkem") + tb, ta = before[tx.name], after[tx.name] + if tb and ta: + rec["tx_sent_delta"] = ta.get("sent", 0) - tb.get("sent", 0) + rounds_fh.write(json.dumps(rec, ensure_ascii=False) + "\n") + rounds_fh.flush() + rnd += 1 + time.sleep(max(0.0, a.period - (time.time() - t0))) + + for b in boards: + b.stop = True + summary = { + "rounds": rnd, + "pairs": {f"{k[0]}->{k[1]}": f"{v[0]}/{v[1]}" for k, v in sorted(pairs.items())}, + "reboots": reboots, + "tx_timeouts": txto, + "events": len(events), + } + print(json.dumps(summary, ensure_ascii=False, indent=1)) + rounds_fh.write(json.dumps({"summary": summary}, ensure_ascii=False) + "\n") + bad = any(v for v in reboots.values()) or any(v for v in txto.values()) or \ + any(v[0] < v[1] for v in pairs.values()) + sys.exit(1 if bad else 0) + + +if __name__ == "__main__": + main() diff --git a/tools/ble_cli.py b/tools/ble_cli.py new file mode 100755 index 00000000..b140f283 --- /dev/null +++ b/tools/ble_cli.py @@ -0,0 +1,184 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Text console of a MeshCore node over BLE (Nordic UART Service). + +The same console you get on USB serial, but wireless -- which is the only way +in once a node is mounted somewhere without a cable. Works against any build +that has `BLE_PIN_CODE` set (repeater, room server, companion_radio_ble). + +Why this exists as a tool rather than a snippet: the NUS write has a size limit +that is easy to miss and fails in a misleading way (see CHUNK below), and the +BlueZ/bleak connect path needs retries to be usable for anything longer than a +single command. Every ad-hoc script re-learned both the hard way. + + # single command (a MAC, or a board name from the local config) + ble_cli.py AA:BB:CC:DD:EE:10 ver + ble_cli.py hill-rpt ver + + # several, one connection + ble_cli.py AA:BB:CC:DD:EE:10 "get radio" "get name" stats-radio + + # from a file, one command per line, '#' comments ignored + ble_cli.py AA:BB:CC:DD:EE:10 -f provision.txt + + # {epoch} expands to the host's current unix time -- the point being that a + # provisioning FILE can carry `time {epoch}`, which a shell cannot reach + ble_cli.py AA:BB:CC:DD:EE:10 "time {epoch}" + + # keep reconnecting per command (slow, but survives a flaky link) + ble_cli.py AA:BB:CC:DD:EE:10 --per-command "gps on" "set af 9" + +PAIRING: the console characteristics are SECMODE_ENC_WITH_MITM, so the node +must be bonded first or the connect pops a passkey dialog on the desktop: + + bluetoothctl --agent KeyboardOnly # then: pair , enter the BLE PIN + +`erase` on the node wipes the bond too (bonds live in InternalFS), so re-pair +after one. + +CAUTION: one console at a time. USB and BLE read into the same command buffer +in the firmware (`simple_repeater/main.cpp`, "commands share the buffer"), so +two consoles at once interleave into one line and can crash the node. +""" +import argparse +import asyncio +import sys +import time + +from bleak import BleakClient, BleakScanner + +NUS_RX = "6e400002-b5a3-f393-e0a9-e50e24dcca9e" # write (host -> node) +NUS_TX = "6e400003-b5a3-f393-e0a9-e50e24dcca9e" # notify (node -> host) + +# A NUS write carries at most ATT_MTU-3 bytes, and BlueZ will not split it for +# you. At the default MTU of 23 that is 20 bytes -- and MeshCore nodes are +# routinely left at 23. A longer write is rejected with +# "[org.bluez.Error.Failed] Failed to initiate write", which reads like a +# dropped link rather than "your command was too long": commands up to 18 +# characters work and everything longer fails, deterministically. Hence chunking +# every write, always. +CHUNK = 20 + + +def log(*a): + print(*a, file=sys.stderr, flush=True) + + +async def send(client, buf, cmd, wait): + buf.clear() + # {epoch} -> host unix time, expanded HERE rather than at parse time so that + # it is the time the command is actually sent: --per-command reconnects cost + # seconds each, and a whole -f file can take minutes. + # + # It exists for `time {epoch}` in a provisioning file. -f reads lines verbatim, + # so a `$(date +%s)` in one is sent as literal text and the node answers + # "Unknown command" -- which is why the clock line in a provisioning file + # was a commented-out note telling you to substitute the epoch by hand. Every + # clock in this firmware is volatile without GPS or an I2C RTC, and a node + # whose RTC still says May 2024 has its adverts dropped as replays. + cmd = cmd.replace("{epoch}", str(int(time.time()))) + data = (cmd + "\r\n").encode() + for i in range(0, len(data), CHUNK): + await client.write_gatt_char(NUS_RX, data[i:i + CHUNK], response=False) + await asyncio.sleep(0.15) + await asyncio.sleep(wait) + out = bytes(buf).decode("utf-8", "replace").strip() + # the node echoes nothing, but replies are prefixed "-> " or "> " + for p in ("-> ", "> "): + if out.startswith(p): + out = out[len(p):] + # the EXPANDED command goes back too, so the printout says what was really + # sent rather than the `{epoch}` template + return cmd, out.strip() + + +async def run(mac, cmds, wait, per_command, tries): + async def connect(): + last = None + for attempt in range(tries): + try: + dev = await BleakScanner.find_device_by_address(mac, timeout=20) + if dev is None: + # a connected peripheral stops advertising; a stale link on + # the adapter is the usual reason it cannot be found + raise RuntimeError(f"{mac} not advertising (already connected?)") + c = BleakClient(dev, timeout=30) + await c.connect() + return c + except Exception as e: # noqa: BLE001 + last = e + log(f" [connect {attempt + 1}/{tries}] {type(e).__name__}: {e}") + await asyncio.sleep(4) + raise SystemExit(f"cannot connect to {mac}: {last}") + + results = [] + if per_command: + for cmd in cmds: + c = await connect() + try: + buf = bytearray() + await c.start_notify(NUS_TX, lambda _h, d: buf.extend(d)) + results.append(await send(c, buf, cmd, wait)) + finally: + await c.disconnect() + await asyncio.sleep(2) + else: + c = await connect() + try: + buf = bytearray() + await c.start_notify(NUS_TX, lambda _h, d: buf.extend(d)) + for cmd in cmds: + results.append(await send(c, buf, cmd, wait)) + finally: + await c.disconnect() + return results + + + +def _mac(key): + """A board name from the local config (tools/mctools_config.py) -> its MAC. + Optional on purpose: ble_flash_node.sh --via copies this file ALONE to a + remote host, where there is no config and a MAC is given anyway.""" + try: + from mctools_config import mac_for + except ImportError: + return key + return mac_for(key) or key + +def main(): + ap = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("mac", help="BLE address of the node, or its name in the local config") + ap.add_argument("cmds", nargs="*", help="console commands") + ap.add_argument("-f", "--file", help="read commands from a file, one per line") + ap.add_argument("-w", "--wait", type=float, default=3.0, + help="seconds to collect the reply (default 3; raise for " + "paged output like rxlog/nodes)") + ap.add_argument("--per-command", action="store_true", + help="reconnect for every command -- slower, but survives a " + "link that drops mid-sequence") + ap.add_argument("--tries", type=int, default=5, help="connect attempts") + # intermixed, not plain parse_args: with a trailing `cmds` of nargs="*", an + # option BETWEEN the MAC and the commands (` -w 8 rxlog`, the form this + # tool's own help suggests) makes argparse on Python <= 3.12 drop the + # commands with "unrecognized arguments". 3.13 fixed it, so it works on an + # Arch workstation and fails on the Debian hosts (bridge-host, cabin-host) that are + # the only way to reach a mast node -- exactly where you cannot debug it. + a = ap.parse_intermixed_args() + + a.mac = _mac(a.mac) + cmds = list(a.cmds) + if a.file: + with open(a.file) as fh: + cmds += [ln.strip() for ln in fh + if ln.strip() and not ln.lstrip().startswith("#")] + if not cmds: + ap.error("no commands given") + + + for cmd, out in asyncio.run(run(a.mac, cmds, a.wait, a.per_command, a.tries)): + print(f"{cmd}\t{out}") + + +if __name__ == "__main__": + main() diff --git a/tools/ble_dfu.py b/tools/ble_dfu.py new file mode 100644 index 00000000..a536aaeb --- /dev/null +++ b/tools/ble_dfu.py @@ -0,0 +1,363 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Legacy Nordic DFU (SDK ~11, dfu_version 0.5) over BLE pro Adafruit nRF52 bootloader. +Generický BlueZ adaptér přes bleak (bez Nordic donglu). + +Fáze 1: připoj běžící APP, enable notify na 1531, zapiš 0x01 (buttonless) → reboot do bootloaderu. +Fáze 2: reconnect na bootloader (advertuje 1530 DFU svc), proveď START/INIT/IMAGE(PRN)/VALIDATE/ACTIVATE. + BLE DFU je flaky (dropnutá receipt notif → přenos spadne). Fáze 2 se proto + auto-retryuje: po pádu pošle RESET (bootloader → čistý IDLE) a zkusí znovu. + +Použití: ble_dfu.py [phase1|phase2] + phase1 JEN buttonless reboot do bootloaderu, pak skončí (flash si dodělá + volající — po USB je to ~20 s místo minut po BLE) + phase2 přeskočí fázi 1 (buttonless) — použij když uzel UŽ visí v bootloaderu + (advertuje SCAP_DFU), např. po přerušeném DFU. Zotavení bez power-cycle. +""" +import asyncio +import os +import re +import struct +import sys +import zipfile +from bleak import BleakClient, BleakScanner + +DFU_SVC = "00001530-1212-efde-1523-785feabcd123" +CP_UUID = "00001531-1212-efde-1523-785feabcd123" # control point (write+notify) +PKT_UUID = "00001532-1212-efde-1523-785feabcd123" # packet (write-no-resp) + +# opcody +START_DFU, INIT_DFU, RECEIVE_FW, VALIDATE, ACTIVATE_RESET, RESET, REPORT, PKT_RCPT_REQ = 1,2,3,4,5,6,7,8 +RESP, PKT_RCPT = 0x10, 0x11 + +class Notif: + def __init__(self): self.q = asyncio.Queue() + def cb(self, _h, data): self.q.put_nowait(bytes(data)) + async def wait(self, timeout=30): + return await asyncio.wait_for(self.q.get(), timeout) + +def log(*a): print(*a, flush=True) + +async def expect_resp(nf, opcode, timeout=30): + while True: + d = await nf.wait(timeout) + if d and d[0] == RESP and d[1] == opcode: + if d[2] != 1: + raise RuntimeError(f"DFU resp opcode {opcode} status {d[2]} (fail)") + return d + if d and d[0] == PKT_RCPT: + continue # receipt, ignoruj tady + log(" (neočekávaná notif:", d.hex(), ")") + +def mac_plus_one(mac): + p = mac.upper().split(":") + p[-1] = "%02X" % ((int(p[-1], 16) + 1) & 0xFF) + return ":".join(p) + +async def find(mac, want_dfu=False, timeout=30): + """Najdi zařízení. POZOR: běžící APP inzeruje DFU službu taky (kvůli + buttonless), takže 'want_dfu' NESMÍ matchovat jen podle DFU svc -> spletl by + si app s bootloaderem. Bootloader advertuje SCAP_DFU na MAC+1 (SenseCap na + stožáru) NEBO AdaDFU na TÉŽE MAC (XIAO, novější SenseCap Solar). + + ADRESA JE POVINNÁ. Dřív stačil název obsahující "DFU" bez ohledu na adresu a + bralo se prostě první zařízení ze skenu -- s víc deskami v bootloaderu + najednou to sáhne na cizí. Stalo se: cíl CE:72:…:02, připojilo se + FE:11:…:C4. Zachytilo se to jen proto, že se log četl ručně; o pár sekund + později by START_DFU přepsal jinou desku.""" + boot_mac = mac_plus_one(mac) + log(f" scan (want_dfu={want_dfu}, mac={mac}, boot={boot_mac})...") + devs = await BleakScanner.discover(timeout=timeout, return_adv=True) + cand, rejected = [], [] + for d, adv in devs.values(): + addr = d.address.upper() + has_dfu = DFU_SVC in [u.lower() for u in (adv.service_uuids or [])] + name = (d.name or adv.local_name or "") + if want_dfu: + if not has_dfu: + continue + looks_like_dfu = "DFU" in name.upper() + right_addr = addr in (boot_mac, mac.upper()) + if looks_like_dfu and right_addr: + cand.append((d, adv, 0)) + elif looks_like_dfu: + rejected.append(f"{addr} {name!r}") + elif addr == mac.upper(): + cand.append((d, adv, 1)) + cand.sort(key=lambda x: x[2]) + for d, adv, _ in cand: + log(f" kandidát: {d.address} {d.name!r} dfu={DFU_SVC in [u.lower() for u in (adv.service_uuids or [])]}") + if rejected: + log(f" (v bootloaderu i CIZÍ desky, ignoruji: {', '.join(rejected)})") + return cand[0][0] if cand else None + +async def connect_app(mac, tries=5): + """Scan + connect s opakováním, jako to dělá ble_cli.py. + + Jediný pokus NESTAČÍ a stálo to 22. 8. 2026 hodinu na second-mast: BLE konzole + (`ble_cli.py ver`) na tomtéž uzlu a z téhož hostu prošla bez zaváhání, kdežto + DFU umřelo na `TimeoutError` z `local_disconnect_monitor_event.wait()`. Rozdíl + NEBYL v uzlu, v bondu ani ve vzdálenosti (−64 dBm) — jen v tom, že ble_cli + connect opakuje a tady se zkoušel jednou. Vypadá to jako mrtvá deska, a není. + """ + last = None + for attempt in range(tries): + try: + dev = await BleakScanner.find_device_by_address(mac, timeout=25) + if dev is None: + # připojený peripheral přestane advertovat -- obvyklý důvod je + # viset spojení na adaptéru + raise RuntimeError("APP nenalezen ve scanu (už připojený?)") + c = BleakClient(dev, timeout=30) + await c.connect() + return c + except Exception as e: # noqa: BLE001 + last = e + log(f" [connect {attempt + 1}/{tries}] {type(e).__name__}: {str(e)[:60]}") + await asyncio.sleep(4) + raise RuntimeError(f"APP nenalezen ve scanu / connect selhal: {last}") + +async def phase1_buttonless(mac): + log("== FÁZE 1: buttonless reboot do bootloaderu ==") + c = await connect_app(mac) + try: + log(" připojen k APP, is_connected:", c.is_connected) + svcs = [s.uuid.lower() for s in c.services] + if DFU_SVC not in svcs: + raise RuntimeError("APP nemá DFU službu 1530") + nf = Notif() + await c.start_notify(CP_UUID, nf.cb) # write-authorize vyžaduje notify enabled + try: + await c.write_gatt_char(CP_UUID, bytes([START_DFU]), response=True) + except Exception as e: + log(" (write 0x01 → disconnect, očekávané):", type(e).__name__) + finally: + # write 0x01 uzel odpojí sám, takže disconnect() tu obvykle jen uklízí + try: + await c.disconnect() + except Exception: # noqa: BLE001 + pass + log(" APP odpojen, čekám na reboot bootloaderu...") + await asyncio.sleep(4) + +class ImageDone(Exception): + """Bootloader potvrdil celý image dřív, než smyčka došla na PRN práh.""" + +class ChunkTooBig(Exception): + """Bootloader neodpověděl na první receipt -> nezvládá velké pakety.""" + +async def send_image(c, nf, pkt_char, data, prn=8, chunk=None): + if chunk is None: + mtu = getattr(c, "mtu_size", 23) or 23 + chunk = max(20, mtu - 3) + log(f" posílám image {len(data)} B, chunk {chunk} B, PRN {prn}") + sent = 0 + since_rcpt = 0 + total = len(data) + for off in range(0, total, chunk): + piece = data[off:off+chunk] + await c.write_gatt_char(pkt_char, piece, response=False) + sent += len(piece) + since_rcpt += 1 + if prn and since_rcpt >= prn: + since_rcpt = 0 + # počkej na receipt [0x11, <4B received>] + while True: + try: + d = await nf.wait(60) + except asyncio.TimeoutError: + # Ticho po PRVNÍ skupině = bootloader ty pakety vůbec + # nepobral. Není to congestion, ale velikost: legacy DFU + # (SDK 11) na některých bootloaderech bere jen 20 B, a když + # BlueZ vyjedná MTU 247, posíláme 244 B a přenos umře pod + # 48 kB. Pozorováno: XIAO nRF52840 (AdaDFU, MTU 247) padá, + # SenseCap Solar (AdaDFU, MTU zůstane 23) i mast-three + # (SCAP_DFU na MAC+1, MTU 247) jedou. Volající to zkusí + # znovu s 20 B. + if sent <= prn * chunk and chunk > 20: + raise ChunkTooBig() + raise + if d and d[0] == PKT_RCPT: + got = struct.unpack(" 3 else "" + skip_phase1 = mode == "phase2" + + # `phase1` = jen prepni uzel do bootloaderu a skonci. Ma to smysl u desky, + # ktera je zaroven na USB: BLE OTA trva jednotky az patnact minut podle MTU, + # kdezto po USB je to ~20 s. BLE se tedy pouzije jen na to, na co USB nestaci + # -- companion build nema textovou konzoli, takze `dfu` prikazem ho tam + # neposles. Tuhle kombinaci pouziva tools/flash_node.sh. + if mode == "phase1": + await phase1_buttonless(mac) + log("== uzel je v bootloaderu; flash dokonci volajici (napr. po USB) ==") + return + z = zipfile.ZipFile(zippath) + fw_bin = z.read("firmware.bin") + fw_dat = z.read("firmware.dat") + log(f"firmware.bin {len(fw_bin)} B, firmware.dat {len(fw_dat)} B, cíl {mac}") + + # STALENESS GUARD. `pio run` builds firmware.zip, `pio run -t create_uf2` + # builds firmware.uf2, and NEITHER refreshes the other. Flashing one board + # from the .zip and another from the .uf2 then silently gives them different + # firmware -- that is how x3 ended up 50 min behind the rest of the fleet, + # missing a command the others had. firmware.elf is relinked by every build, + # so it is the reference. + elf = os.path.join(os.path.dirname(os.path.abspath(zippath)), "firmware.elf") + if os.path.exists(elf) and os.path.getmtime(elf) > os.path.getmtime(zippath): + sys.exit(f"CHYBA: {os.path.basename(zippath)} je STARŠÍ než firmware.elf — " + f"nalil bys starý obraz.\n" + f" Sprav: pio run -e && pio run -e -t create_uf2") + # Put the version on the record BEFORE it lands on the board, not after. + m = re.search(rb"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", fw_bin) + if m: + log(f" verze v obrazu: {m.group(0).decode()}") + if skip_phase1: + log("== FÁZE 1 přeskočena (uzel už v bootloaderu) ==") + else: + await phase1_buttonless(mac) + # BLE DFU je flaky — přenos občas spadne uprostřed (dropnutá receipt notif). + # Auto-retry: po pádu vyresetuj bootloader do IDLE a zkus phase2 znovu. + ATTEMPTS = 6 + chunk = None # None = mtu-3; prepne se na 20 po ChunkTooBig + for i in range(ATTEMPTS): + try: + await phase2_dfu(mac, fw_bin, fw_dat, chunk=chunk) + return # hotovo + except ChunkTooBig: + # Tenhle bootloader nebere mtu-3 velke pakety. Nejde to zachranit + # v behu -- START_DFU podruhe vrati status 2 (INVALID_STATE) -- + # takze RESET, nove spojeni a znovu, natvrdo po 20 B. + log("!! bootloader nezvlada velke pakety -> opakuji s 20 B") + chunk = 20 + await recover_to_bootloader(mac) + except Exception as e: + log(f"!! DFU pokus {i+1}/{ATTEMPTS} selhal: {type(e).__name__}: {str(e)[:80]}") + if i == ATTEMPTS - 1: + raise + await recover_to_bootloader(mac) + +if {"-h", "--help"} & set(sys.argv[1:]): + print(__doc__.strip()) + sys.exit(0) +asyncio.run(main()) diff --git a/tools/ble_flash_node.sh b/tools/ble_flash_node.sh new file mode 100755 index 00000000..dd5772d2 --- /dev/null +++ b/tools/ble_flash_node.sh @@ -0,0 +1,259 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MIT +# Ostrý flash MeshCore uzlu přes BLE OTA, celý postup na jeden příkaz. +# +# Existuje proto, že samotné `ble_dfu.py` je jen přenos obrazu. Kolem něj je +# pokaždé stejných šest věcí, a každá z nich už jednou něco stála: +# +# 1. ČISTÝ STROM. Verze ze špinavého stromu má `+` a na stožáru pak nepoznáš, +# co na uzlu je. Skript odmítne pokračovat. +# 2. PŘEDLETOVÁ KONTROLA prefs. Prefs v InternalFS přebíjejí build flagy a +# flash je NEPŘEPÍŠE — takže se musí přečíst PŘED i PO a porovnat. +# 3. TICHO u uzlu s odpojenou antenou (`--require-silence`). Vysílání do +# odpojené antény poškozuje PA; build je mlčící z konstrukce, ale prefs to +# přebijou, takže se ticho ověřuje na uzlu, ne v ini. +# 4. UVOLNĚNÍ LINKU. Zastavit službu (most) NESTAČÍ, spojení drží BlueZ. +# 5. OVĚŘENÍ VERZE proti obrazu, ne "vypadá to dobře". +# 6. VRÁCENÍ SLUŽBY do provozu a kontrola, že zase teče. +# +# Použití: +# tools/ble_flash_node.sh --env SenseCap_Solar_repeater --mac AA:BB:CC:DD:EE:10 \ +# --require-silence +# +# tools/ble_flash_node.sh --env SenseCap_Solar_repeater \ +# --mac AA:BB:CC:DD:EE:11 --via gateway-host \ +# --python /opt/ble-bridge/venv/bin/python \ +# --stop-service ble-bridge.service +# +# --check-only jen přečte stav uzlu a skončí (nic nemění, nic neflashuje) +# +# `--via` flashuje ze vzdáleného hostu, protože BLE má metry: mast-three je +# v dosahu bridge-host, ne pracovní stanice. Nic se tam neinstaluje — použije se +# python, který na hostu už je (`--python`). +set -euo pipefail + +ENV_NAME="" +MAC="" +VIA="" +PY="python3" +STOP_SVC="" +REQUIRE_SILENCE=0 +CHECK_ONLY=0 +REPO="$(cd "$(dirname "$(readlink -f "$0")")/.." && pwd)" + +while [ $# -gt 0 ]; do + case "$1" in + --env) + ENV_NAME="$2" + shift 2 + ;; + --mac) + MAC="$2" + shift 2 + ;; + --via) + VIA="$2" + shift 2 + ;; + --python) + PY="$2" + shift 2 + ;; + --stop-service) + STOP_SVC="$2" + shift 2 + ;; + --require-silence) + REQUIRE_SILENCE=1 + shift + ;; + --check-only) + CHECK_ONLY=1 + shift + ;; + -h | --help) + sed -n '3,33p' "$0" + exit 0 + ;; + *) + echo "neznámý argument: $1" >&2 + exit 2 + ;; + esac +done +[ -n "$MAC" ] || { + echo "chybí --mac" >&2 + exit 2 +} +[ -n "$ENV_NAME" ] || [ "$CHECK_ONLY" = 1 ] || { + echo "chybí --env" >&2 + exit 2 +} + +PIO="${PIO:-$HOME/.platformio/penv/bin/pio}" +CLI_CMDS=(ver "get name" "get repeat" "get advert.interval" "get flood.advert.interval" "get freq") + +# Konzole uzlu: buď lokálně, nebo na hostu z --via (tam se nahrají nástroje). +# timeout: ble_cli.py sám žádný nemá. 27. 9. 2026 na mast-three visel připojený +# a hluchý 35 minut, most celou dobu stál a flash se k DFU vůbec nedostal. +NODE_CLI_TIMEOUT=${NODE_CLI_TIMEOUT:-180} +node_cli() { + if [ -n "$VIA" ]; then + # shellcheck disable=SC2029 + ssh "$VIA" "timeout $NODE_CLI_TIMEOUT $PY /tmp/ble_cli.py $MAC $(printf '%q ' "$@")" 2>/dev/null + else + timeout "$NODE_CLI_TIMEOUT" "$PY" "$REPO/tools/ble_cli.py" "$MAC" "$@" 2>/dev/null + fi +} + +pref() { grep -E "^$1[[:space:]]" <<<"$2" | cut -f2- | tr -d '\r'; } + +if [ -n "$VIA" ]; then + scp -q -p "$REPO/tools/ble_cli.py" "$VIA:/tmp/" || { + echo "scp ble_cli.py selhalo" >&2 + exit 1 + } +fi + +# Uvolnit link MUSÍ být PŘED předletovou kontrolou: když linku drží most, na +# konzoli se nedostaneš ani ty. A když cokoli dál selže, služba se musí vrátit +# do provozu — proto trap, ne "restart na konci". +SVC_STOPPED=0 +restore_svc() { + [ "$SVC_STOPPED" = 1 ] || return 0 + echo "== vracím $STOP_SVC ==" >&2 + ssh "$VIA" "systemctl start $STOP_SVC" >/dev/null 2>&1 || true + SVC_STOPPED=0 +} +trap restore_svc EXIT + +if [ -n "$STOP_SVC" ] && [ "$CHECK_ONLY" = 0 ]; then + echo "== uvolnění linku ($STOP_SVC) ==" + # Zastavit službu NESTAČÍ — spojení drží BlueZ, další připojení pak selže. + ssh "$VIA" "systemctl stop $STOP_SVC; bluetoothctl disconnect $MAC >/dev/null 2>&1 || true; sleep 3" + SVC_STOPPED=1 +fi + +echo "== stav uzlu $MAC ==" +BEFORE="$(node_cli "${CLI_CMDS[@]}")" || { + echo "uzel neodpovídá na BLE konzoli" >&2 + exit 1 +} +echo "$BEFORE" | sed 's/^/ /' + +V_BEFORE="$(pref ver "$BEFORE")" +REPEAT_BEFORE="$(pref 'get repeat' "$BEFORE")" +ADV_BEFORE="$(pref 'get advert.interval' "$BEFORE")" +FADV_BEFORE="$(pref 'get flood.advert.interval' "$BEFORE")" + +if [ "$REQUIRE_SILENCE" = 1 ]; then + if [ "$ADV_BEFORE" != "0" ] || [ "$FADV_BEFORE" != "0" ] || [ "$REPEAT_BEFORE" != "off" ]; then + cat >&2 <&2 + echo " by pak nešlo poznat, co na něm je. Commitni, nebo stashni." >&2 + exit 1 +fi +(cd "$REPO" && "$PIO" run -e "$ENV_NAME" >/dev/null) || { + echo "build selhal" >&2 + exit 1 +} +ZIP="$REPO/.pio/build/$ENV_NAME/firmware.zip" +ELF="$REPO/.pio/build/$ENV_NAME/firmware.elf" +# Bez roury schválně. `strings "$ELF" | grep -m1 ...` tady padalo na SIGPIPE +# (exit 141): grep po prvním nálezu rouru zavře, `strings` ji dostane a +# `set -o pipefail` z toho udělá pád celého skriptu -- uprostřed flashe, se +# zastaveným mostem. Je to race, takže to roky procházelo; spuštěné hned po +# `pio run` ale selhalo 3/3 (21. 9. 2026, mast-three, dvakrát v ostrém běhu). +# `grep -a` čte ELF přímo, žádná roura = není co zavřít. +# `|| true`, protože skript běží pod `set -e`: bez toho by neúspěšný grep +# skript ukončil rovnou na tomhle přiřazení a STOP hláška o dva řádky níž by +# se nikdy nevypsala — operátor by dostal holý nenulový exit uprostřed flashe, +# klidně už se zastaveným mostem. +V_EXPECT="$(grep -m1 -aoE 'v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]*\+?' "$ELF" || true)" +# `grep -m1 -o` zastaví po prvním ŘÁDKU, ale vypíše z něj VŠECHNY shody. ELF +# má .rodata oddělenou nulami bez newline, takže dvakrát vražený literál verze +# dá dvouřádkový V_EXPECT, porovnání s `ver` z uzlu pak nesedí a povedený OTA +# se ohlásí jako chyba. Necháváme první řádek. +V_EXPECT="${V_EXPECT%%$'\n'*}" +[ -n "$V_EXPECT" ] || { + echo "STOP: v obrazu není stampovaná verze (env bez stampingu?)" >&2 + exit 1 +} +echo " obraz: $V_EXPECT ($(stat -c%s "$ZIP") B)" +echo " na uzlu teď: $V_BEFORE" + +echo "== DFU ==" +if [ -n "$VIA" ]; then + scp -q -p "$ZIP" "$REPO/tools/ble_dfu.py" "$VIA:/tmp/" + ssh "$VIA" "cd /tmp && nohup timeout 1500 $PY /tmp/ble_dfu.py /tmp/firmware.zip $MAC > /tmp/dfu_$MAC.log 2>&1 &" || true + until ssh "$VIA" "grep -qE 'HOTOVO|SELHALO|Traceback' /tmp/dfu_$MAC.log" 2>/dev/null; do sleep 20; done + ssh "$VIA" "tail -4 /tmp/dfu_$MAC.log" | sed 's/^/ /' + ssh "$VIA" "grep -q HOTOVO /tmp/dfu_$MAC.log" || { + echo "DFU SELHALO — zotavení: ble_dfu.py … phase2" >&2 + exit 1 + } +else + "$PY" "$REPO/tools/ble_dfu.py" "$ZIP" "$MAC" | tail -4 | sed 's/^/ /' +fi + +echo "== ověření po flashi ==" +for _ in $(seq 1 30); do + sleep 10 + AFTER="$(node_cli "${CLI_CMDS[@]}" || true)" + [ -n "$(pref ver "$AFTER")" ] && break +done +echo "$AFTER" | sed 's/^/ /' + +V_AFTER="$(pref ver "$AFTER")" +FAIL=0 +case "$V_AFTER" in +"$V_EXPECT"*) echo " verze OK" ;; +*) + echo " CHYBA: uzel hlásí '$V_AFTER', čekáno '$V_EXPECT'" >&2 + FAIL=1 + ;; +esac +# Prefs flash nepřepisuje, takže rozdíl = něco je špatně (nebo si je uzel resetoval). +for p in repeat:REPEAT advert.interval:ADV flood.advert.interval:FADV; do + key="${p%%:*}" + var="${p##*:}" + b_var="${var}_BEFORE" + before="${!b_var}" + after="$(pref "get $key" "$AFTER")" + if [ "$before" != "$after" ]; then + echo " CHYBA: $key se změnil: '$before' -> '$after'" >&2 + FAIL=1 + fi +done +[ "$FAIL" = 0 ] && echo " prefs beze změny" + +if [ "$SVC_STOPPED" = 1 ]; then + echo "== vrácení služby ==" + restore_svc + sleep 15 + ssh "$VIA" "systemctl is-active $STOP_SVC" | sed 's/^/ /' + echo " a ověř DATA, ne jen službu:" + echo " ssh $VIA \"journalctl -u $STOP_SVC --since -5min | grep 'full scrape'\"" +fi + +[ "$FAIL" = 0 ] || exit 1 +echo "== HOTOVO: $MAC na $V_AFTER ==" diff --git a/tools/ble_pair.py b/tools/ble_pair.py new file mode 100755 index 00000000..6812ede0 --- /dev/null +++ b/tools/ble_pair.py @@ -0,0 +1,200 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Non-interactive BLE pairing by PIN, driving bluetoothctl over a pty. + +A MeshCore node's console characteristics are SECMODE_ENC_WITH_MITM, so the +first connection to an unpaired node raises a passkey dialog on the desktop -- +useless from a script. This registers its own KeyboardOnly agent and answers +the prompt. + + ble_pair.py AA:BB:CC:DD:EE:10 # one node + ble_pair.py AA:BB:CC:DD:EE:10 hill-rpt # MACs or config board names + +The PIN comes from platformio.local.ini ([secrets] ble_pin) and is never +printed. That is the same value the firmware was built with, so a node whose +PIN does not match here was built from a different tree. + +WHY A SCRIPT, AND WHY STATE-DRIVEN: the first version marched through +bluetoothctl on a fixed schedule and sent `pair` before the agent was +registered. The passkey prompt then went to the default agent and the node +stayed unpaired -- with no error anywhere. Every step here waits for the +output that proves the previous one landed. + +BONDING IS NOT ONLY FOR THE CONSOLE. The buttonless-DFU control point is +declared with the same SECMODE_ENC_WITH_MITM +(`helpers/nrf52/SerialBLEInterface.cpp`), so `ble_dfu.py` phase 1 cannot write +its trigger to an unpaired node either. It fails as a plain write error, which +does not look like "you are not bonded". + +AFTERWARDS, DISCONNECT BEFORE FLASHING. bluetoothctl leaves the node +*connected* once pairing succeeds, and a connected peripheral stops +advertising -- so `ble_dfu.py` immediately fails its scan with "APP nenalezen +ve scanu". Run `bluetoothctl disconnect ` first. + + ble_pair.py && bluetoothctl disconnect && ble_dfu.py fw.zip + +DOCK-QUIET NODES ADVERTISE ONLY WHEN UNDOCKED. On dual USB/BLE companion +builds (T1000-E, Wio L1), BLE advertising is suppressed while a USB host holds +DTR high. Unplug USB, or hold the port open with DTR deasserted, or nothing on +this page will find the node. +""" +import atexit +import os +import pty +import re +import select +import signal +import sys +import time + +INI = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), + "platformio.local.ini") + + +def read_pin(): + # A node built from an env that does not take [secrets] (e.g. a companion env + # that keeps the variant's default BLE_PIN_CODE) needs a different PIN. Give + # it as a FILE, not a value, so it stays out of argv, env dumps and history. + pin_file = os.environ.get("BLE_PIN_FILE") + if pin_file: + with open(pin_file) as fh: + pin = fh.read().strip() + if not pin.isdigit(): + sys.exit(f"BLE_PIN_FILE {pin_file} does not hold a numeric PIN") + return pin + try: + with open(INI) as fh: + lines = fh.readlines() + except FileNotFoundError: + sys.exit(f"{INI} not found -- it holds the real PIN and is git-ignored") + pin = None + for line in lines: # last one wins, same as PlatformIO + m = re.match(r"\s*ble_pin\s*=\s*(\d+)", line) + if m: + pin = m.group(1) + if not pin: + sys.exit(f"no [secrets] ble_pin in {INI}") + return pin + + + +def _mac(key): + """A board name from the local config (tools/mctools_config.py) -> its MAC. + Optional on purpose: ble_flash_node.sh --via copies this file ALONE to a + remote host, where there is no config and a MAC is given anyway.""" + try: + from mctools_config import mac_for + except ImportError: + return key + return mac_for(key) or key + +def main(): + macs = [_mac(m) for m in sys.argv[1:]] + if not macs: + sys.exit(f"usage: {os.path.basename(sys.argv[0])} [MAC...]") + pin = read_pin() + + pid, fd = pty.fork() + if pid == 0: + os.execvp("bluetoothctl", ["bluetoothctl"]) + + def drain(seconds, want=None, mac=None): + """Read for `seconds` (or until `want` matches), answering prompts.""" + end = time.time() + seconds + hit = None + while time.time() < end: + r, _, _ = select.select([fd], [], [], 0.4) + if not r: + continue + try: + chunk = os.read(fd, 4096).decode("utf-8", "replace") + except OSError: + break + clean = re.sub(r"\x1b\[[0-9;?]*[a-zA-Z]", "", chunk) + for ln in clean.splitlines(): + t = ln.strip() + if not t or "RSSI" in t or t.startswith("[NEW] Device"): + continue # scan noise + if pin and pin in t: # bluetoothctl echoes the typed passkey + t = t.replace(pin, "******") + print(" bt|", t[:110], flush=True) + low = clean.lower() + if "passkey" in low or "enter pin" in low or "pin code" in low: + os.write(fd, (pin + "\n").encode()) + print(" -> PIN sent", flush=True) + elif "(yes/no)" in low: + os.write(fd, b"yes\n") + print(" -> confirmed", flush=True) + if want and mac and re.search(want, clean, re.I) and mac in clean: + hit = True + break + if "failed" in low and mac and mac.lower() in low: + hit = False + break + return hit + + def send(cmd, wait=1.5, want=None, mac=None): + os.write(fd, (cmd + "\n").encode()) + print(f"$ {cmd}", flush=True) + return drain(wait, want, mac) + + # ÚKLID MUSÍ PROBĚHNOUT I PŘI ZABITÍ. Registrovaný `default-agent` odpovídá + # na CIZÍ párovací požadavky a `scan on` drží discovery -- když se skript + # zabije uprostřed (stalo se 22. 8. 2026 vlastním `timeout 60`), zůstane + # hostitel v tomhle stavu a začne se chovat jako párovatelné zařízení pro + # okolí. Na notebooku na vzdálené stanoviště z toho vyskočil párovací požadavek na televizi. + def cleanup(*_a): + try: + for c in ("scan off", "pairable off", "discoverable off", + "agent off", "quit"): + os.write(fd, (c + "\n").encode()) + time.sleep(0.4) + except OSError: + pass + + atexit.register(cleanup) + for _sig in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP): + signal.signal(_sig, lambda *_a: sys.exit(130)) + + send("agent KeyboardOnly", 2) + send("default-agent", 2) + failed = [] + for mac in macs: + print(f"===== {mac} =====", flush=True) + send(f"remove {mac}", 3) # a stale bond makes `pair` a no-op + send("scan on", 1) + # ČEKEJ, DOKUD HO SKEN NEUVIDÍ, ne pevných pár sekund. `remove` smaže + # i objevené zařízení, takže `pair` hned poté řekne "Device not + # available" — a to vypadá úplně stejně jako špatný PIN. Repeater navíc + # po 30 s přepne z rychlého advertisingu na pomalý, takže se do krátkého + # okna netrefí. Stálo to 22. 8. 2026 dvě hodiny hledání na dvou hostech. + if drain(45, want=r"Device", mac=mac): + print(" (uzel ve skenu, páruju)", flush=True) + else: + print(f" POZOR: {mac} se za 45 s ve skenu neobjevil — `pair` nejspíš " + f"skončí na 'not available'. Uzel neadvertuje?", flush=True) + ok = send(f"pair {mac}", 45, want=r"Bonded: yes|Pairing successful", mac=mac) + print(f" paired: {ok}", flush=True) + if not ok: + failed.append(mac) + send("scan off", 1) + send(f"trust {mac}", 3) + # `agent off` odregistruje KeyboardOnly agenta -- bez toho by host dál + # odpovídal na cizí párovací požadavky, dokud bluetoothctl neskončí + send("agent off", 1) + send("quit", 1) + os.close(fd) + + if failed: + print("NOT PAIRED: " + ", ".join(failed)) + print("A wrong PIN and a node that stopped advertising look the same " + "here -- check both.") + sys.exit(1) + print("done -- disconnect before running ble_dfu.py") + + +if __name__ == "__main__": + if {"-h", "--help"} & set(sys.argv[1:]): + print(__doc__.strip()) + sys.exit(0) + main() diff --git a/tools/board_probe.py b/tools/board_probe.py new file mode 100755 index 00000000..8926f488 --- /dev/null +++ b/tools/board_probe.py @@ -0,0 +1,433 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Otisk XIAO desek na USB: co na které z nich BĚŽÍ, a jestli se to změnilo. + + tools/board_probe.py --all + tools/board_probe.py --all --compare + tools/board_probe.py --all --compare --expect-changed + +Vzniklo 1. 9. 2026 poté, co `pio run -t upload --upload-port ` ohlásil +FAILED a obraz přistál na **x2**, desce, která na té příkazové řádce nebyla. +Poznat to šlo až po hodině: x2 přestal odpovídat konzoli i companion protokolu +a vypadal jako zaseklý, přitom na něm normálně běžel KISS modem, který ani +jedno z toho nemá. Tři replugy nepomohly a pomoct nemohly. + +Otisk je proto přes VŠECHNY protokoly, které na těch deskách jezdí, ne jen přes +ten, který zrovna čekáme: + + text MeshCore repeater/analyzer `ver` -> v1.17.1-tth... + companion MeshCore companion_radio CMD_DEVICE_QUERY (bez textové konzole) + kiss examples/kiss_modem SetHardware GetVersion (0x11 -> 0x91) + modem openhop_modem port `XIAO-Wio-SX1262`, mlčí na vše + bootloader UF2 port bez "Studio" / se "Sense" + +`modem` a `bootloader` se poznají podle JMÉNA portu, ne podle idProduct: obojí +drží 0044 a AGENTS.md čte 0044 jako bootloader, což pro openhop_modem neplatí. +""" +import argparse +import glob +import multiprocessing +import os +import re +import struct +import sys +import time + +try: + import serial +except ImportError: + sys.exit("chybi pyserial") + +# Kolik sekund nejvys smi trvat otisk CELE sbernice. +# Musi pokryt PLNY cyklus jedne desky: settle 0,9 + text 1,2 + companion 1,5 + +# KISS 1,2 + GetDeviceName 1,2 = ~6 s (zmereno 2. 9. 2026 na x4: 6,4 s, tri behy +# za sebou stejne). S kratsim deadlinem se posledni protokol nestihne a deska se +# oznaci jako "visi", i kdyz normalne odpovida -- presne to se stalo KISS modemu +# na x4 pri BOARD_PROBE_DEADLINE=6. +PROBE_DEADLINE = float(os.environ.get("BOARD_PROBE_DEADLINE", "12")) + + +def usb_boards(): + """[(serial, port, board, state_hint)] pro kazdou desku flotily na USB. + + Typ desky i rezim se poznaji z JMENA portu, protoze idProduct lze -- 0044 + drzi jak UF2 bootloader XIAO, tak openhop_modem, coz je aplikace. A na + T1000-E je to jmeno primo obracene, nez by clovek cekal: + + Seeed_Studio_XIAO_nRF52840_ XIAO, aplikace (MeshCore build) + Seeed_XIAO_nRF52840_Sense_ XIAO, bootloader + Seeed_XIAO-Wio-SX1262_ XIAO, openhop_modem (APLIKACE, ne boot) + Seeed_Studio_T1000-E-BOOT_ T1000-E, APLIKACE <- "-BOOT" ma aplikace! + Seeed_Studio_T1000-E_ T1000-E, bootloader (+ UF2 disk T1000-E) + """ + pats = [ + # (regex na jmeno portu, deska, stav) + (r"Seeed_Studio_T1000-E-BOOT_", "t1000e", "app"), + (r"Seeed_Studio_T1000-E_", "t1000e", "boot"), + (r"Seeed_XIAO-Wio-SX1262_", "xiao", "modem"), + (r"Seeed_Studio_XIAO_nRF52840_", "xiao", "app"), + (r"Seeed_XIAO_nRF52840", "xiao", "boot"), + (r"Wio|TRACKER", "wio-l1", "app"), + ] + out = [] + for port in sorted(glob.glob("/dev/serial/by-id/*")): + name = os.path.basename(port) + m = re.search(r"_([0-9A-F]{16})-if00", name) + if not m: + continue # ESP32 a spol. -- neni to nase nRF52 flotila + for rx, board, state in pats: + if re.search(rx, name): + out.append((m.group(1), port, board, state)) + break + return out + + +def port_busy(dev): + """Drzi ten port jiny proces? Vrati jeho pid, nebo None. + + Sahat na port, ktery uz nekdo ma otevreny, neni jen zbytecne -- je to + SKODLIVE. 2. 9. 2026 tenhle probe otevrel port, na kterem openHop drzel KISS + spojeni; demon zahlasil "multiple access on port", oznacil link za degradovany + a nakonec si RADIO VYPNUL (`Radio is disabled`) a nesl si to v repeater.db, + takze to neresil ani restart kontejneru. Kontrola stavu nesmi rozbit to, co + kontroluje. + + Ctou se /proc/*/fd, takze to nepotrebuje root ani lsof; cizi procesy pod jinym + UID neuvidime, ale docker tady bezi pod nasim (--user $(id -u)), takze ten ano. + """ + try: + real = os.path.realpath(dev) + except OSError: + return None + me = os.getpid() + for pid in os.listdir("/proc"): + if not pid.isdigit() or int(pid) == me: + continue + d = f"/proc/{pid}/fd" + try: + entries = os.listdir(d) + except OSError: + continue + for fd in entries: + try: + if os.path.realpath(f"{d}/{fd}") == real: + return pid + except OSError: + continue + return None + + +def _open(port): + s = serial.Serial(port, 115200, timeout=0) + s.dtr = True + s.rts = True + time.sleep(0.9) + s.reset_input_buffer() + return s + + +def _drain(s, w): + buf, t = b"", time.time() + while time.time() - t < w: + try: + d = s.read(8192) + except Exception: + # "device reports readiness to read but returned no data" -- deska + # se odpojila uprostred cteni. Vracime, co uz mame; neni to duvod + # shodit cely otisk. + break + if d: + buf += d + else: + time.sleep(0.02) + return buf + + +def _kiss_frame(raw, resp_code): + """Vrat KISS ramec zacinajici 0xC0, jehoz treti bajt je `resp_code`. + + Bez tohohle se raw[1]/raw[2] cetly z offsetu 0, tedy z toho, co v bufferu + zbylo po predchozim protokolu -- a odpoved se dala minout i kdyz prisla. + """ + i = -1 + while True: + i = raw.find(bytes([0xC0]), i + 1) + if i < 0: + return raw + fr = raw[i:] + if len(fr) > 4 and fr[1] == 0x06 and fr[2] == resp_code: + return fr + + +def probe(port): + """('text'|'companion'|'kiss'|'nic', verze) -- zkusí protokoly po řadě.""" + try: + s = _open(port) + except Exception as e: + return ("nedostupny", type(e).__name__) + try: + # Prvni prikaz po otevreni portu se casto ztrati, proto to prazdne CRLF. + s.write(b"\r\n") + time.sleep(0.4) + s.reset_input_buffer() + + s.write(b"ver\r\n") + txt = _drain(s, 1.2).decode(errors="replace") + m = re.search(r"(v\d+\.\d+\.\d+-tth[0-9a-f]+\+?)", txt) + if m: + return ("text", m.group(1)) + + s.reset_input_buffer() + s.write(b"<" + struct.pack("' v bufferu. + # Driv stacilo, aby za '>' byly dva bajty a neprazdny zbytek, a vratilo se + # ("companion", "?") -- takze opozdena radka textove konzole nebo + # MESH_DEBUG_PRINTLN se ctla jako companion ramec. flash_node.sh pak + # porovnal "?" s ocekavanou verzi a oznamil "FLASH SE NEAPLIKOVAL" na + # desce, na ktere bezel spravny firmware -- presne ta trida falesne + # diagnozy, kvuli ktere tenhle nastroj vznikl. + # + # Prohledavaji se VSECHNY vyskyty '>' a uzna se jen plnohodnotny + # RESP_DEVICE_INFO (kod 13, aspon 80 B, delka souhlasi s tim, co dorazilo). + i = -1 + while True: + i = raw.find(b">", i + 1) + if i < 0: + break + if len(raw) < i + 3: + continue + ln = struct.unpack("= 80 and fr[0] == 13: # RESP_DEVICE_INFO + return ("companion", fr[60:80].split(b"\0")[0].decode(errors="replace")) + + s.reset_input_buffer() + s.write(bytes([0xC0, 0x06, 0x11, 0xC0])) # KISS GetVersion + raw = _drain(s, 1.2) + # Kotvit na ZACATEK KISS ramce (0xC0), ne na offset 0: pred odpovedi muze + # lezet zbytek predchoziho vystupu a raw[1]/raw[2] by pak cetly cizi bajty. + raw = _kiss_frame(raw, 0x91) + if len(raw) > 4 and raw[1] == 0x06 and raw[2] == 0x91: + # GetVersion (0x11) vrací verzi KISS PROTOKOLU, ne našeho buildu -- + # ta je k nerozeznání mezi dvěma různými firmwary. Stampovaná verze + # jede v GetDeviceName (0x16), viz KissModem::handleGetDeviceName. + s.reset_input_buffer() + s.write(bytes([0xC0, 0x06, 0x16, 0xC0])) # KISS GetDeviceName + nm = _kiss_frame(_drain(s, 1.2), 0x96) + if len(nm) > 4 and nm[1] == 0x06 and nm[2] == 0x96: + txt = nm[3:-1].decode(errors="replace") + m = re.search(r"(v\d+\.\d+\.\d+-tth[0-9a-f]+\+?)", txt) + if m: + return ("kiss", m.group(1)) + return ("kiss", txt.strip() or "?") + # Starší KISS build bez stampované verze v GetDeviceName. + return ("kiss", "proto" + ".".join(str(b) for b in raw[3:-1])) + + return ("nic", "-") + finally: + try: + s.close() + except Exception: + pass + + +def _probe_one(sn, port, board, state): + """Otisk jedne desky. Bezi ve VLASTNIM PROCESU (viz fingerprint).""" + if state in ("boot", "modem"): + # Bootloader nemluvi nasim protokolem a openhop_modem nemluvi vubec; + # ptat se jich je jen ztrata casu (a u boot i riziko, ze to vypada + # jako zaseknuta deska). + return (sn, f"{board}/{state}", "-") + busy = port_busy(port) + if busy: + return (sn, f"{board}/obsazeny", f"drzi pid {busy} -- nesaham") + kind, ver = probe(port) + return (sn, f"{board}/{kind}", ver) + + +def _worker(i, sn, port, board, state, q): + try: + q.put((i,) + _probe_one(sn, port, board, state)) + except Exception as e: # nikdy nenech potomka umrit potichu + q.put((i, sn, f"{board}/chyba", type(e).__name__)) + + +def fingerprint(): + """Otisk cele sbernice. Paralelne -- porty jsou nezavisle a serazovat je za + sebe se necetlo: pet desek po ~9 s (settle + tri protokoly, u mlcicich desek + plny timeout) delalo pres dve minuty, coz je na kontrolu spoustenou PRED a PO + kazdym flashem moc. Poradi vysledku je dane vstupem, ne dobehem. + + KAZDA DESKA VE VLASTNIM PROCESU, ne ve vlakne. Puvodni verze mela daemon + vlakna a tvrdy deadline, jenze `serial.Serial()` umi na nereagujici desce + viset v open(2) UVNITR C kodu, ktery NEPOUSTI GIL -- takze jedna zaseklá + deska zmrazila i vsechny ostatni probe vlakna a ta pak deadline nestihla. + Projev: 2. 9. 2026 hlasil x4 (zdravy KISS modem, sam o sobe 6,4 s) + "visi neodpovida v case" pri deadline 12 s, zatimco cely beh trval 42 s. + Diagnoza "deska neodpovida" na desce, ktera odpovida, je horsi nez zadna. + + Proces se da terminate() i uprostred blokujiciho open(2), takze deadline + plati doopravdy a zbytek flotily se otiskne v normalnim case. + + "visi" u T1000-E NENI diagnoza desky. Obe karty (B3F160.., B612AE..) visi + v serial.Serial() open(2) i pres 60 s, kazda samostatne ve vlastnim procesu + (zmereno 2. 9. 2026) -- pyserial se z nich otisk proste nedozvi a zvysovani + deadlinu s tim nic neudela. Deska pritom muze byt uplne v poradku; na + T1000-E se pta textova konzole primo, ne tenhle nastroj.""" + boards = usb_boards() + rows = [None] * len(boards) + if not boards: + return [] + + ctx = multiprocessing.get_context("fork") # fork: potomek zdedi uz nactene moduly + q = ctx.Queue() + procs = [] + for i, (sn, port, b, st) in enumerate(boards): + p = ctx.Process(target=_worker, args=(i, sn, port, b, st, q), daemon=True) + p.start() + procs.append(p) + + deadline = time.time() + PROBE_DEADLINE + got = 0 + while got < len(boards) and time.time() < deadline: + try: + i, sn, kind, ver = q.get(timeout=max(0.05, deadline - time.time())) + except Exception: + break + rows[i] = (sn, kind, ver) + got += 1 + + for p in procs: + if p.is_alive(): + p.terminate() # utne i blokujici open(2) + for p in procs: + p.join(timeout=1.0) + # SIGKILL na to, co terminate() neslozilo. main() konci `os._exit`, ktery + # obchazi atexit handler multiprocessingu -- prezivsi potomek by tedy zustal + # bezet A DRZET SERIOVY PORT, takze dalsi beh (flash_node.sh pousti probe + # tretkrat za flash) by tu desku ohlasil jako `obsazeny drzi pid `: + # nastroj obvinujici vlastni pozustatky. + for p in procs: + if p.is_alive(): + p.kill() + for p in procs: + p.join(timeout=0.5) + + for i, (sn, _, board, _) in enumerate(boards): + if rows[i] is None: + rows[i] = (sn, f"{board}/visi", "neodpovida v case") + return [r for r in rows if r] + + +def _parse_pairs(path): + """[(serial, (kind, verze))] z otisku. Verze muze obsahovat mezery (starsi + KISS build vraci "Seeed Xiao-nrf52"), takze split(None, 2) -- split() na tri + pole by zbytek utnul a porovnani by hlasilo ZMENU tam, kde se nic nezmenilo. + + Radek s PRAZDNOU verzi se NEZAHAZUJE. Driv to filtroval `len(p) >= 3`, takze + deska, u ktere probe verzi nevyplnil, z predchoziho otisku zmizela a pak se + ohlasila jako "ZMIZELA z USB" -- falesny poplach o desce, ktera tam celou dobu + byla. + """ + out = [] + for line in open(path): + if not line.strip(): + continue + p = line.split(None, 2) + if len(p) < 2: + continue + out.append((p[0], (p[1], p[2].strip() if len(p) > 2 else ""))) + return out + + +def _parse(path): + return [(sn, k, v) for sn, (k, v) in _parse_pairs(path)] + + +def fmt(rows): + return "\n".join(f"{sn} {kind} {str(ver).strip()}" for sn, kind, ver in rows) + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--all", action="store_true") + ap.add_argument("--compare", help="soubor s predchozim otiskem") + ap.add_argument("--now", help="soubor s AKTUALNIM otiskem (jinak se sbernice" + " otiskne znovu)") + ap.add_argument("--expect-changed", help="seriak, ktery se zmenit MA") + a = ap.parse_args() + + # --now existuje proto, aby volajici, ktery uz otisk ma, nemusel platit dalsi + # probe (az PROBE_DEADLINE) -- a hlavne aby verdikt o zmenach a jeho vlastni + # kontrola verze vychazely z TEHOZ vzorku sbernice, ne ze dvou ruznych. + rows = _parse(a.now) if a.now else fingerprint() + now = {sn: (k, v) for sn, k, v in rows} + + if not a.compare: + print(fmt(rows)) + return 0 + + prev = dict(_parse_pairs(a.compare)) + + bad = False + for sn in sorted(set(prev) | set(now)): + was, is_ = prev.get(sn), now.get(sn) + tag = "" + if was != is_: + # Poradi je zamerne: deska, ktera ZMIZELA, neni uspech ani kdyz je to + # cil. Po flashi se to na tehle lavici stava bezne a hlaska "zmeneno + # (cil)" by to zakryla -- pritom se z desky nedá precist, co na ni je, + # takze flash NENI overeny. Chce to replug a spustit znovu. + if is_ is None: + tag = " <- ZMIZELA z USB (po flashi bezne) -- replug a spust znovu" + bad = True + elif was is None: + tag = " <- NOVA deska na sbernici" + elif (a.expect_changed + and sn.endswith(a.expect_changed.upper()) + and len([x for x in set(prev) | set(now) + if x.endswith(a.expect_changed.upper())]) == 1): + tag = " <- zmeneno (cil)" + else: + tag = " <- !!! ZMENENO, PRESTOZE TO NEBYL CIL !!!" + bad = True + print(f" {sn} {was[0] if was else '-':10s} {was[1] if was else '-':22s}" + f" -> {is_[0] if is_ else '-':10s} {is_[1] if is_ else '-':22s}{tag}") + + if a.expect_changed: + want = a.expect_changed.upper() + hits = [x for x in sorted(set(prev) | set(now)) if x.endswith(want)] + if len(hits) > 1: + # Kratky suffix umi sednout na vic seriaku; driv se vzal jeden podle + # poradi ve slovniku, takze "zmeneno (cil)" mohlo omluvit ZMENU NA JINE + # DESCE. + print(f"\n{a.expect_changed} sedi na {len(hits)} desky ({', '.join(hits)})" + f" -- upresni seriove cislo, jinak nejde rict, ktera se zmenit mela.") + bad = True + elif not hits: + # Driv: cil chybel v obou otiscich -> smycka ho nikdy nenavstivila, + # `bad` zustalo False a beh skoncil "ok, zmenil se jen cil". Otisk, + # ve kterem cil nikdy nikdo nevidel, neni uspech. + print(f"\nCIL {a.expect_changed} NENI V ZADNEM z otisku -- neni z ceho" + f" rict, ze se zmenil. Sedi to seriove cislo?") + bad = True + elif prev.get(hits[0]) == now.get(hits[0]): + print(f"\nCIL {a.expect_changed} SE NEZMENIL -- flash se neaplikoval," + f" i kdyby nastroj hlasil uspech.") + bad = True + + print("\nVERDIKT:", "PROBLEM (viz vys)" if bad else "ok, zmenil se jen cil") + return 1 if bad else 0 + + +if __name__ == "__main__": + rc = main() + # os._exit misto sys.exit: vlakno, ktere visi v serial.Serial() open(2), + # drzi otevreny file descriptor a interpret na nej pri uklidu ceka -- otisk + # se vypsal za par sekund, ale proces dobihal jeste ~30 s (a pod `timeout` + # se tvaril jako zaseknuty). Vysledek uz je venku, uklizet nemame co. + sys.stdout.flush() + sys.stderr.flush() + os._exit(rc) diff --git a/tools/build_version.py b/tools/build_version.py index 5b80deea..3b3e54f6 100644 --- a/tools/build_version.py +++ b/tools/build_version.py @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MIT # CUSTOM (TeTeHacko): real version and build timestamp for the `ver` command. # # WIRE THIS INTO EVERY ENV WE FLASH. Without it the node reports the fallback @@ -18,6 +19,15 @@ # Import("env") has to come first, hence the file-wide ruff exemption. # ruff: noqa: F821, E402 # mypy: disable-error-code="name-defined" +if __name__ == "__main__": # run by hand (--help): the header above, nothing else + with open(__file__) as _f: + for _ln in _f: + if not _ln.startswith("#"): + break + if "SPDX-License-Identifier" not in _ln: + print(_ln[2:].rstrip() if _ln.startswith("# ") else "") + raise SystemExit(0) + Import("env") import re import subprocess diff --git a/tools/companion_backup.py b/tools/companion_backup.py new file mode 100755 index 00000000..c72bdd4e --- /dev/null +++ b/tools/companion_backup.py @@ -0,0 +1,260 @@ +#!/usr/bin/python +# SPDX-License-Identifier: MIT +"""Záloha companionu (L1, karta) přes companion protokol PŘED flashem. + + tools/companion_backup.py /dev/serial/by-id/usb-...L1... L1-pre-flash + tools/companion_backup.py --diff ~/.local/share/meshcore-backups/.json + tools/companion_backup.py # místo portu MAC = přes BLE (bond nutný) + +Uloží self_info (jméno, rádio, poloha, path hash…), device query, custom vars, +kontakty a kanály do ~/.local/share/meshcore-backups/-.json (0600 — +jsou v tom klíče kanálů). Na stdout nic tajného, jen souhrn; `--diff` porovná se +starší zálohou (po flashi), klíče kanálů porovnává jen jako shodu. + +Solo navíc vystavuje nastavení přes companion CLI (`keys`, `get`, `set`; +ui-core/SettingsCli.h): záloha je uloží všechna do sekce `cli` a `--restore` +je vrátí. Live Share cíl/zapnutí/scope (`share.to`, `share.on`, `share.scope`) +umí CLI až od solo-tth s tímhle doplňkem — 16. 10. 2026 po v2.0 skončil Live +Share na kanálu Public a nebylo jak to zjistit. Co CLI nezná (bot, část UI), +musí po flashi zkontrolovat člověk na zařízení. + +Hodiny flash nepřežijí (L1 22. 10. 2026 po v2.0.1 o 10 h pozadu), proto +`--diff` (= běh po flashi) a samostatné `--sync-time` nastaví čas hostu +(CMD_SET_DEVICE_TIME — lokální příkaz po USB, nic nevysílá). Firmware čas +dozadu odmítne; uzel napřed se jen ohlásí. + + tools/companion_backup.py L1-post --restore .json # jen ukáže + tools/companion_backup.py L1-post --restore .json --apply # zapíše + +`--restore` Live Share nikdy NEZAPNE (to je vysílání do meshe) — jen vypne, +když bylo v záloze vypnuté; zapnout ho je na člověku. Privátní klíč přes USB náš firmware nevydá +(`private_key_export_disabled`), záloha identity je ve vaultu (keys.yml). + +Spouští se interpretem meshcli (#!/usr/bin/python), tam je knihovna meshcore. +Knihovna shazuje DTR a L1 bez DTR na USB mlčí ⇒ _dtr_on() + cx_dly=1,5 s. +Když je k L1 připojený telefon přes BLE, USB mlčí — vypni na telefonu BT. +""" +import argparse +import asyncio +import datetime as dt +import json +import os +import re +import sys +import time + +if {"-h", "--help"} & set(sys.argv[1:]): + print(__doc__.strip()) + sys.exit(0) + +from meshcore import EventType, MeshCore # noqa: E402 + +DIR = os.path.expanduser("~/.local/share/meshcore-backups") + + +def plain(x): + if isinstance(x, (bytes, bytearray)): + return x.hex() + if isinstance(x, dict): + return {str(k): plain(v) for k, v in x.items()} + if isinstance(x, (list, tuple)): + return [plain(v) for v in x] + return x + + +def _dtr_on(): + """Knihovna meshcore po otevření portu SHAZUJE DTR (serial_cx.connection_made: + `dtr = False`, kvůli deskám, které DTR resetuje). Solo DualSerialInterface ale + bez DTR na USB neposlouchá — odtud „No response … serial companion?“ u + meshcli na L1. Proto DTR po otevření zase nahodit.""" + from meshcore import serial_cx + proto = serial_cx.SerialConnection.MCSerialClientProtocol + orig = proto.connection_made + + def connection_made(self, transport): + orig(self, transport) + if getattr(transport, "serial", None): + transport.serial.dtr = True + proto.connection_made = connection_made + + +async def connect(port): + # a BLE MAC instead of a port: a companion that is not on USB here (the + # probe card sits on another host, reachable over BLE only) + ble = re.fullmatch(r"([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}", port) is not None + if not ble: + _dtr_on() + for attempt in range(4): + try: + if ble: + mc = await MeshCore.create_ble(port, default_timeout=8) + else: + mc = await MeshCore.create_serial(port, 115200, default_timeout=8, cx_dly=1.5) + if mc and mc.self_info: + return mc + if mc: + await mc.disconnect() + except (OSError, asyncio.TimeoutError, ConnectionError) as e: + print(f"pokus {attempt + 1}: {e}", file=sys.stderr) + await asyncio.sleep(2 + attempt * 2) + sys.exit("companion neodpovídá (připojený telefon přes BLE? po flashi chvíli počkej)") + + +async def cli(mc, cmd): + ev = await mc.commands.run_cli_command(cmd) + return ev.payload.get("text", "").strip() if ev.type == EventType.CLI_REPLY else None + + +async def cli_settings(mc): + """Všechny klíče z `keys` (po stránkách) a jejich hodnoty z `get`; None, když + firmware Solo CLI nemá (upstream companion: „Unknown command“).""" + keys, page = [], 1 + while page < 20: + r = await cli(mc, "keys" if page == 1 else f"keys {page}") + if not r or r.startswith(("Unknown", "Error", "No more")): + break + more = "(more: keys" in r + keys += r.split(" (more:")[0].split() + if not more: + break + page += 1 + if not keys: + return None + out = {} + for k in keys: + r = await cli(mc, f"get {k}") + out[k] = r[2:] if r and r.startswith("> ") else r + return out + + +RESTORE_FIRST = ["share.to", "share.scope"] # cíl dřív než cokoli, co by vysílalo + + +async def restore(mc, saved, apply): + cur = await cli_settings(mc) or {} + order = [k for k in RESTORE_FIRST if k in saved] + [k for k in saved if k not in RESTORE_FIRST] + plan = [] + for k in order: + v = saved[k] + if v is None or cur.get(k) == v or k not in cur: + continue + if k == "share.on" and v == "on": + plan.append((k, v, "PŘESKOČENO — zapnutí Live Share vysílá, zapni ho na zařízení")) + continue + plan.append((k, v, (await cli(mc, f"set {k} {v}")) if apply else "(--apply zapíše)")) + return plan + + +async def node_offset(mc): + ev = await mc.commands.get_time() + return ev.payload["time"] - int(time.time()) if ev.type == EventType.CURRENT_TIME else None + + +async def sync_clock(mc): + before = await node_offset(mc) + ev = await mc.commands.set_time(int(time.time())) + return {"before_s": before, "set": ev.type == EventType.OK, "after_s": await node_offset(mc)} + + +async def backup(port, restore_from=None, apply=False, sync=False): + mc = await connect(port) + out = {"taken_at": dt.datetime.now().astimezone().isoformat(timespec="seconds"), "port": port, + "self_info": plain(mc.self_info)} + ev = await mc.commands.send_device_query() + out["device"] = plain(ev.payload) if ev.type != EventType.ERROR else None + ev = await mc.commands.get_custom_vars() + out["custom_vars"] = plain(ev.payload) if ev.type != EventType.ERROR else None + ev = await mc.commands.get_contacts() + out["contacts"] = plain(ev.payload) if ev.type != EventType.ERROR else None + chans = [] + for i in range(40): + ev = await mc.commands.get_channel(i) + if ev.type == EventType.ERROR: + break + chans.append(plain(ev.payload)) + out["channels"] = chans + out["cli"] = await cli_settings(mc) + plan = await restore(mc, restore_from, apply) if restore_from else None + if plan and apply: + out["cli"] = await cli_settings(mc) + out["clock"] = await sync_clock(mc) if sync else {"before_s": await node_offset(mc)} + await mc.disconnect() + return out, plan + + +def summary(b): + si = b["self_info"] + used = [c for c in b["channels"] if c.get("channel_name")] + return (f"{si.get('name')} pubkey {str(si.get('public_key'))[:8]} · {si.get('radio_freq')}/{si.get('radio_bw')}/" + f"SF{si.get('radio_sf')}/CR{si.get('radio_cr')} · fw {(b.get('device') or {}).get('ver')} · " + f"{len(b.get('contacts') or {})} kontaktů · kanály: " + + ", ".join(f"{c.get('channel_idx')}={c.get('channel_name')}" for c in used)) + + +def diff(old, new): + keys = sorted(set(old["self_info"]) | set(new["self_info"])) + d = [f"self_info.{k}: {old['self_info'].get(k)} → {new['self_info'].get(k)}" + for k in keys if old["self_info"].get(k) != new["self_info"].get(k)] + if old.get("custom_vars") != new.get("custom_vars"): + d.append(f"custom_vars: {old.get('custom_vars')} → {new.get('custom_vars')}") + oc = {c["channel_idx"]: c for c in old["channels"]} + for c in new["channels"]: + o = oc.get(c["channel_idx"], {}) + if o.get("channel_name") != c.get("channel_name") or o.get("channel_secret") != c.get("channel_secret"): + d.append(f"kanál {c['channel_idx']}: {o.get('channel_name')} → {c.get('channel_name')}" + + (" (jiný klíč)" if o.get("channel_secret") != c.get("channel_secret") else "")) + oc, nc = old.get("cli") or {}, new.get("cli") or {} + for k in sorted(set(oc) | set(nc)): + if oc.get(k) != nc.get(k): + d.append(f"cli {k}: {oc.get(k)} → {nc.get(k)}") + ok, nk = set(old.get("contacts") or {}), set(new.get("contacts") or {}) + if ok != nk: + d.append(f"kontakty: −{len(ok - nk)} +{len(nk - ok)}") + return d + + +def main(): + ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("port", help="/dev/serial/by-id/... nebo BLE MAC") + ap.add_argument("name", help="jméno zálohy, např. L1-pre-flash") + ap.add_argument("--diff", metavar="JSON", help="porovnat se starší zálohou") + ap.add_argument("--restore", metavar="JSON", help="vrátit nastavení z CLI sekce zálohy (bez --apply jen ukáže)") + ap.add_argument("--apply", action="store_true", help="s --restore opravdu zapsat") + ap.add_argument("--sync-time", action="store_true", help="nastavit čas hostu (s --diff automaticky)") + a = ap.parse_args() + saved = None + if a.restore: + with open(os.path.expanduser(a.restore)) as f: + saved = json.load(f).get("cli") + if not saved: + sys.exit(f"{a.restore}: záloha nemá sekci cli (starší skript nebo firmware bez Solo CLI)") + b, plan = asyncio.run(backup(a.port, saved, a.apply, a.sync_time or bool(a.diff))) + os.makedirs(DIR, mode=0o700, exist_ok=True) + path = os.path.join(DIR, f"{a.name}-{dt.datetime.now().astimezone().date()}.json") + fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) + with os.fdopen(fd, "w") as f: + json.dump(b, f, ensure_ascii=False, indent=1) + print(f"záloha: {path}\n{summary(b)}") + if b["cli"] is not None: + sh = {k: v for k, v in b["cli"].items() if k.startswith("share.")} + print(f"CLI: {len(b['cli'])} klíčů; Live Share: " + ", ".join(f"{k}={v}" for k, v in sh.items())) + else: + print("CLI: firmware Solo CLI nemá — Solo prefs zkontroluj na zařízení") + c = b["clock"] + if "set" not in c: + print(f"hodiny: odchylka {c['before_s']:+} s" if c["before_s"] is not None else "hodiny: nepřečteny") + elif c["set"]: + print(f"hodiny: odchylka {c['before_s']:+} s → srovnáno ({c['after_s']:+} s)") + else: + print(f"hodiny: odchylka {c['before_s']:+} s → firmware nastavení odmítl (čas dozadu?)") + if plan is not None: + print("\nobnova z " + a.restore + ":\n" + ("\n".join(f"- set {k} {v} → {r}" for k, v, r in plan) + if plan else "- nic, vše sedí")) + if a.diff: + with open(os.path.expanduser(a.diff)) as f: + d = diff(json.load(f), b) + print("\nrozdíly proti " + a.diff + ":\n" + ("\n".join("- " + x for x in d) if d else "- žádné")) + + +if __name__ == "__main__": + main() diff --git a/tools/config.example.ini b/tools/config.example.ini new file mode 100644 index 00000000..15688a34 --- /dev/null +++ b/tools/config.example.ini @@ -0,0 +1,32 @@ +; SPDX-License-Identifier: MIT +; Config of the MeshCore tools -- copy to ~/.config/meshcore-tools/config.ini +; (or point $MESHCORE_TOOLS_CONFIG at it) and describe YOUR boards. +; Format and the shell interface: tools/mctools_config.py --help. +; No secrets here: admin passwords stay in platformio.local.ini. + +; A bench board on USB: tools take `b1` (or `1`) instead of the serial number. +[board.b1] +serial = 0123456789ABCDEF +mac = AA:BB:CC:DD:EE:01 +aliases = 1 +role = bench + +; A board that keeps an identity you do not want overwritten by accident: +; flash_node.sh refuses it unless told to. +[board.home-card] +serial = FEDCBA9876543210 +mac = AA:BB:CC:DD:EE:02 +role = probe +protect = keeps its identity and a client database + +; A radio that runs other firmware (e.g. a KISS modem of an observer): console +; tools refuse to open its port at all. +[board.modem] +serial = 00112233445566AA +role = bench +refuse = observer radio, not a MeshCore console + +; A deployed node, reached over BLE only (no USB serial). +[board.hill-rpt] +mac = AA:BB:CC:DD:EE:10 +role = live diff --git a/tools/flash_node.sh b/tools/flash_node.sh new file mode 100755 index 00000000..05fc4687 --- /dev/null +++ b/tools/flash_node.sh @@ -0,0 +1,484 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MIT +# Flash any board of the fleet -- pick the route from what the board is doing, +# and prove where the image landed. +# +# tools/flash_node.sh [target] [--force-protected] +# +# target USB serial (full or unique suffix), a BLE MAC, or a board name/alias +# from the local config (tools/mctools_config.py). +# Omit only when exactly one board of the fleet is plugged in. +# +# WHY A DISPATCHER. Which route works depends on the board AND on what it is +# doing right now. The rules are written out in .claude/skills/flash-node +# and AGENTS.md -- prose, i.e. the kind of thing that gets skipped mid-task. On +# 2026-09-01 three of them were skipped in one session: `pio -t upload` went to a +# board already in DFU (it touches unconditionally, kicking it back out), a +# hand-rolled nrfutil went to a board in the application (it does NOT touch, so +# nothing was listening), and a failed upload was retried instead of asking for a +# replug -- which is how an image ended up on a board nobody named. The rules +# therefore live here, where the board's state is actually known: +# +# board state route +# ------ ---------------- ------------------------------------------------ +# xiao application pio -t upload (env has upload_protocol=nrfutil, +# so PlatformIO touches; ~35 s, no buttons) +# xiao bootloader + disk hand off to xiao_uf2_flash.sh +# xiao bootloader, no hand-rolled nrfutil (does not touch; the board is +# disk (serial-only) already where it needs to be) +# t1000e application with `dfu uf2` on the console -> wait for the port to +# a text console rename -> hand-rolled nrfutil on the CDC port +# t1000e bootloader hand-rolled nrfutil straight away +# wio-l1 application 1200-baud touch -> UF2 drive "TRACKER L1" +# sensecap anywhere not over USB: BLE OTA, tools/ble_dfu.py +# +# CDC is preferred over the UF2 drive wherever both work: mounting the drive +# needs root, and `sudo` over SSH without a terminal has nobody to ask for a +# password. Writing to a CDC port works as the ordinary user. +# +# Whatever the route: the whole bus is fingerprinted before and after, the target +# must come back with the new version READ OFF THE BOARD, and every other board +# must be untouched. "Device programmed" is not evidence -- both flashes that went +# wrong that day printed it. +set -uo pipefail +case "${1:-}" in -h | --help) + sed -n '3,/^[^#]/{/^#/s/^# \{0,1\}//p}' "$0" + exit 0 + ;; +esac + +HERE="$(cd "$(dirname "$0")" && pwd)" +ROOT="$(cd "$HERE/.." && pwd)" +die() { + echo "CHYBA: $*" >&2 + exit 1 +} + +# JEN JEDEN FLASH NAJEDNOU. Dva soubezne behy si lezou do cesty na sdilenych +# zdrojich -- jeden BLE adapter, jedna USB sbernice, jeden .pio/build adresar. +# 2. 9. 2026 se kvuli tomu spustily TRI instance zaraz (spousteny na pozadi, bez +# kontroly, jestli predchozi dobehla): kazda si zvlast retryovala BLE connect, +# takze se karta porad dokola pripojovala a odpojovala a zaplavila plochu +# notifikacemi. Nebyla to chyba retry logiky, ale toho, ze bezely tri. +exec 9>"${TMPDIR:-/tmp}/.meshcore-flash-node.lock" +if ! flock -n 9; then + die "uz bezi jiny flash (zamek ${TMPDIR:-/tmp}/.meshcore-flash-node.lock). + Pockej, az dobehne -- soubezne flashovani si leze do cesty na BLE i na USB." +fi + +# Desky, na ktere se podle AGENTS.md nesaha bez vyslovneho zadani. Drzi identitu, +# historii nebo produkcni roli, a prepsat je omylem je draha chyba. +# Ktere to jsou, rika lokalni config (pole `protect`, tools/mctools_config.py). +cfg() { python3 "$HERE/mctools_config.py" "$@" 2>/dev/null; } +PROTECTED="$(cfg list --has protect --field serial || true)" + +# Cil se da zadat i jako BLE MAC, takze gate musi znat OBOJI. Do 2. 9. 2026 se +# kontrola delala az po dispatchi a obe BLE cesty (`flash_over_ble` a vetev pro +# MAC) z ni utekly `exit`em driv, nez na ni dosla rada -- chranenou domaci +# T1000-E slo pres BLE prepsat bez --force-protected. Ta karta uz o identitu +# jednou nenavratne prisla. +is_protected() { + local t="$1" sn mac + for sn in $PROTECTED; do + case "$t" in *"$sn"*) return 0 ;; esac + mac="$(ble_mac_for "$sn")" + [ -n "$mac" ] && [ "$(printf %s "$t" | tr a-f A-F)" = "$mac" ] && return 0 + done + return 1 +} + +guard_protected() { + is_protected "$1" || return 0 + [ "$FORCE" = "1" ] || die "$1 je CHRANENA deska (AGENTS.md: bez vyslovneho + zadani na ni nesahat). Kdyz to fakt chces: --force-protected" +} + +# BLE adresy desek, ktere nemaji textovou konzoli. Companion build se do +# bootloaderu neda poslat prikazem `dfu` (zadna konzole neni), takze jediny zpusob +# je buttonless DFU pres BLE. Kdyz je pak deska ZAROVEN na USB, samotny prenos jde +# po USB: ~20 s misto 3-15 min po BLE (podle vyjednaneho MTU). +ble_mac_for() { + cfg mac "$1" || true # pole `mac` v lokalnim configu +} + +# Deska, ktera po flashi "spadla z USB", NENI mrtva -- 2. 9. 2026 x1 i x4 v tom +# stavu normalne advertovaly na BLE. Softwarovy replug pritom neni z ceho udelat: +# vsechny desky visi primo na root hubu (xhci), a ten neumi prepinat napajeni +# portu, takze ani uhubctl by nepomohl. BLE OTA je proto jedina cesta, jak takovou +# desku doflashovat BEZ RUKOU -- a nepotrebuje USB touch, takze ji ani nema jak +# shodit znovu. +# +# Pozor na dock-quiet: deska, ktera JE na USB, drzi DTR a proto neadvertuje +# (potvrzeno tyz den na x2). BLE zachrana tedy funguje prave pro ty desky, ktere +# z USB vypadly -- coz je presne kdyz je potreba. +# Vraci: 0 = MAC videna, 1 = scan bezel a MAC tam nebyla, 2 = ADAPTER NEVIDEL NIC. +# Ten treti stav je potreba rozlisit, protoze scanner na tehle pracovni stanici je +# HLUCHY (MediaTek; `Discovering: yes` a presto nulovy vystup -- viz pamet +# "BLE jen z desktop"). Bez toho rozliseni skript hlasil "deska neadvertuje" i +# tehdy, kdyz neslysi adapter, tedy obvinoval desku z vady hostitele. +ble_reachable() { + local mac="$1" out + out="$(timeout 20 bash -c "bluetoothctl --timeout 12 scan on 2>/dev/null" || true)" + printf %s "$out" | grep -q "$mac" && return 0 + printf %s "$out" | grep -qE "^\s*\[NEW\] Device |Device [0-9A-F]{2}:" || return 2 + return 1 +} + +flash_over_ble() { + local mac="$1" + echo "== cesta: BLE OTA na $mac (bez USB, tedy bez rizika replugu)" + "$PIO" run -e "$ENV_NAME" >/dev/null 2>&1 || die "build selhal" + bluetoothctl disconnect "$mac" >/dev/null 2>&1 || true + sleep 2 + python3 "$HERE/ble_dfu.py" ".pio/build/$ENV_NAME/firmware.zip" "$mac" +} + +ENV_NAME="" +TARGET="" +FORCE=0 +PASSTHRU=() +for arg in "$@"; do + case "$arg" in + --force-protected) FORCE=1 ;; + # Vse ostatni s -- se predava ble_flash_node.sh (--require-silence, --via, + # --stop-service, --check-only); tady by to nemelo co delat. + --*) PASSTHRU+=("$arg") ;; + *) if [ -z "$ENV_NAME" ]; then ENV_NAME="$arg"; else TARGET="$arg"; fi ;; + esac +done +[ -n "$ENV_NAME" ] || { + echo "usage: $(basename "$0") [serial|board|mac] [--force-protected]" >&2 + exit 1 +} + +# Nastroje a pracovni adresar PRED jakoukoli cestou. Do 2. 9. 2026 se PIO +# prirazovalo AZ ZA vetvi pro BLE MAC, ktera ho pouzivala -- se `set -u` to +# znamenalo "PIO: unbound variable" a cela dokumentovana cesta na stozar/vzdálené stanoviště +# byla mrtva. `cd "$ROOT"` bylo taky pozdeji, takze build i relativni cesta do +# .pio/build mirily do cwd volajiciho. +PIO="$HOME/.platformio/penv/bin/pio" +[ -x "$PIO" ] || PIO="$(command -v pio)" || die "pio nenalezeno" +NRF="$HOME/.platformio/packages/tool-adafruit-nrfutil" +cd "$ROOT" || die "nelze do $ROOT" + +# Jmeno nebo alias desky z lokalniho configu -> seriove cislo. Serial, jeho +# unikatni suffix i BLE MAC projdou beze zmeny. +case "$TARGET" in +"" | *:*:*:*:*:*) ;; +*) SN="$(cfg serial "$TARGET")" && TARGET="$SN" ;; +esac + +# Cil zadany jako BLE MAC = deska na USB vubec neni (stozar, vzdálené stanoviště). Predava se +# ble_flash_node.sh, ktery kolem prenosu dela sest veci, jez tady chybely: +# odmitnuti spinaveho stromu, prefs PRED i PO (prefs v InternalFS prebijeji build +# flagy a flash je nepresipe), --require-silence u uzlu s odpojenou antenou, +# uvolneni linku v BlueZ, overeni verze proti obrazu a vraceni sluzby. Presne +# u mastovych/chatovych uzlu, kam tahle vetev miri, je ticho ochrana PA. +case "$TARGET" in +*:*:*:*:*:*) + guard_protected "$TARGET" + BFN="$HERE/ble_flash_node.sh" + [ -x "$BFN" ] || die "$BFN nenalezen" + echo "== cil je BLE MAC $TARGET -- deska neni na USB, predavam ble_flash_node.sh" + echo " (pokud ma uzel odpojenou antenu, pridej --require-silence)" + exec "$BFN" --env "$ENV_NAME" --mac "$TARGET" "${PASSTHRU[@]}" + ;; +esac + +# Spinavy strom da verzi s '+', a na uzlu pak nepoznas, co na nem je (AGENTS.md). +if [ -n "$(git status --porcelain 2>/dev/null)" ]; then + echo "VAROVANI: strom neni cisty -- obraz dostane verzi s '+'." >&2 +fi + +echo "== env: $ENV_NAME${TARGET:+ cil: $TARGET}" +echo "== otisk desek PRED flashem" +BEFORE="$("$HERE/board_probe.py" --all)" || die "otisk se nezdaril" +echo "$BEFORE" | sed 's/^/ /' + +if [ -n "$TARGET" ]; then + hits="$(echo "$BEFORE" | grep -c -- "$TARGET" || true)" + if [ "$hits" = "0" ]; then + # Neni na USB. Drive to znamenalo "rekni si o replug"; kdyz ale deska + # advertuje, da se doflashovat pres BLE a ruce nejsou potreba. + guard_protected "$TARGET" + MAC="$(ble_mac_for "$TARGET")" + if [ -n "$MAC" ]; then + echo "== $TARGET neni na USB; zkousim, jestli je na BLE ($MAC)" + ble_reachable "$MAC" + BR=$? + if [ "$BR" = "0" ]; then + flash_over_ble "$MAC" + exit $? + fi + [ "$BR" = "2" ] && die "$TARGET neni na USB a BLE scan na tomhle hostu NEVIDEL + ANI JEDNO zarizeni -- to neni vypoved o desce, ale o adapteru. Na tehle + pracovni stanici je scanner hluchy (MediaTek): $(bluetoothctl) hlasi + Discovering: yes a presto nic. Bud replug po USB, nebo BLE cestu spust + z hostu, ktery ji slysi, nebo pres ble_flash_node.sh --via." + die "$TARGET neni na USB ani neadvertuje na BLE -- replug. + POZOR, nez z toho udelas diagnozu: BLE zachrana funguje jen tehdy, kdyz + ten build BLE vubec MA. USB-only companion (env *_companion_radio_usb, + napr. Xiao_x4_cmp_usb) ho nema, takze tam neadvertuje ani zdrava deska -- + overeno 2. 9. 2026 na x2, ktera tehdy jela USB build. Dnesni Xiao_x2_cmp + je naopak BLE companion: na USB mlci a advertuje (11. 10. 2026). BLE MAC + v tabulce vyse muze byt z doby, kdy na desce jel jiny build." + fi + die "cil $TARGET neni na sbernici a neznam k nemu BLE adresu." + fi + [ "$hits" = "1" ] || die "cil $TARGET je na sbernici ${hits}x -- upresni seriove cislo" +else + n="$(echo "$BEFORE" | grep -c . || true)" + [ "$n" = "1" ] || die "na sbernici je $n desek -- rekni ktera: $(basename "$0") $ENV_NAME " + TARGET="$(echo "$BEFORE" | awk '{print $1}')" +fi + +guard_protected "$TARGET" + +FULL="$(echo "$BEFORE" | awk -v t="$TARGET" '$1 ~ t {print $2}')" +BOARD="${FULL%%/*}" +STATE="${FULL##*/}" +# shellcheck disable=SC2010 # by-id names are [A-Za-z0-9_:.-]; $TARGET is a regex +PORT="/dev/serial/by-id/$(ls /dev/serial/by-id/ | grep -- "$TARGET" | head -1)" +echo "== cil: $BOARD, stav: $STATE" + +# Stav, ktery NENI zjisteny protokol, znamena "nevim, co na desce bezi" -- a do +# `xiao/*` propadal na `pio -t upload`, tedy 1200baudovy touch naslepo. U stavu +# `obsazeny` je to nejhorsi: board_probe.py se portu, ktery drzi nekdo jiny, +# schvalne NESAHA, protoze 2. 9. 2026 dotek portu, ktery drzel openHop, oznacil +# link za degradovany a vypnul radio natrvalo do repeater.db. Ta pojistka byla +# v probe a do dispatcheru se nepropsala. +case "$STATE" in +obsazeny) + die "port desky $TARGET drzi jiny proces ($(echo "$BEFORE" | grep -- "$TARGET" | cut -d' ' -f3-)). + Nesaham na nej: dotek zive linky umi protistrane vypnout radio natrvalo. + Zastav toho, kdo port drzi, a spust znovu." + ;; +visi | nic | nedostupny | chyba) + die "stav desky $TARGET se nepodarilo zjistit (probe hlasi '$STATE'), takze + nevim, kterou cestou flashovat -- a hadat znamena touch naslepo. + U T1000-E je 'visi' bezne (pyserial ji neotiskne): + dostan ji do bootloaderu rucne (dlouhy stisk do 8 s od startu) a spust + znovu, pak to pujde vetvi t1000e/boot." + ;; +esac + +# OCEKAVANA VERZE. Bez ni umi otisk rict jen "neco se zmenilo", coz je slabe: +# 2. 9. 2026 pio dvakrat ohlasilo SUCCESS a na desce zustal STARY firmware +# (bootloader nestihl novy obraz aktivovat, protoze deska spadla z USB), a +# jindy naopak flash "selhal" a firmware se pritom nalil. Jedine, cemu se da +# verit, je verze PRECTENA Z DESKY -- a porovnat se musi proti tomu, co je +# v obrazu, ne proti predchozimu stavu. +"$PIO" run -e "$ENV_NAME" >/dev/null 2>&1 || die "build selhal" +WANT_VER="$(strings ".pio/build/$ENV_NAME/firmware.elf" 2>/dev/null | + grep -oE "v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?" | head -1)" +[ -n "$WANT_VER" ] || die "obraz nema stampovanou verzi -- po flashi by neslo + overit, co na desce doopravdy je. Zapoj do envu: extra_scripts = \${stamped.extra_scripts}" +echo "== ocekavana verze: $WANT_VER" + +has_uf2_drive() { + local d s blk + for d in /sys/bus/usb/devices/*/; do + s="$(cat "$d/serial" 2>/dev/null)" || continue + case "$s" in *"$TARGET"*) ;; *) continue ;; esac + blk="$(ls -d "$d"*/host*/target*/*/block/* 2>/dev/null | head -1)" || true + [ -n "$blk" ] && return 0 + done + return 1 +} + +# nrfutil umi skoncit tracebackem a PRESTO vratit 0 -- videno 1. 9. 2026 na +# "No data received on serial port". Cte se tedy i vystup, ne jen navratovy kod. +run_nrfutil() { + local port="$1" out + # ZADNY dalsi `pio run`: build je jednou nahore, u cteni WANT_VER. Stamping meni + # FIRMWARE_BUILD_DATE pri kazdem behu, takze kazde volani znamenalo PLNY rebuild + # (10-30 s) -- a hlavne se pak flashoval jiny artefakt, nez ze ktereho se + # WANT_VER precetla, cimz ta kontrola prestavala overovat odeslany obraz. + out="$(PYTHONPATH="$NRF/site-packages" "$HOME/.platformio/penv/bin/python" \ + "$NRF/adafruit-nrfutil.py" dfu serial \ + -pkg ".pio/build/$ENV_NAME/firmware.zip" -p "$port" -b 115200 --singlebank 2>&1)" || + { + echo "$out" | tail -4 + return 1 + } + echo "$out" | tail -3 + case "$out" in *NordicSemiException* | *"Not able to proceed"* | *Traceback*) return 1 ;; esac + return 0 +} + +# T1000-E: aplikace s textovou konzoli se do bootloaderu posle sama prikazem +# `dfu uf2`. Port se pritom PREJMENUJE z "...T1000-E-BOOT..." na "...T1000-E..." +# (ano, "-BOOT" ma aplikace) a pyserial hodi OSError: [Errno 5] -- to je reboot, +# ne chyba. +t1000e_to_bootloader() { + echo "== posilam 'dfu uf2' na konzoli, deska se rebootne do bootloaderu" + python3 - "$PORT" <<'PY' || true +import serial, sys, time +try: + s = serial.Serial(sys.argv[1], 115200, timeout=0) + s.dtr = True; s.rts = True + time.sleep(1.5) + s.write(b"dfu uf2\r\n"); s.flush() + time.sleep(2) + s.close() +except Exception as e: + print(f" ({type(e).__name__} pri odesilani -- deska se rebootuje)") +PY + for _ in $(seq 30); do + local p + # shellcheck disable=SC2010 # by-id names are [A-Za-z0-9_:.-]; $TARGET is a regex + p="$(ls /dev/serial/by-id/ 2>/dev/null | grep -- "$TARGET" | grep -v -- "-BOOT" | head -1)" + [ -n "$p" ] && { + PORT="/dev/serial/by-id/$p" + echo " bootloader port: $PORT" + return 0 + } + sleep 1 + done + return 1 +} + +RC=0 +case "$BOARD/$STATE" in +xiao/boot) + if has_uf2_drive; then + echo "== cesta: UF2 disk -> predavam xiao_uf2_flash.sh" + "$PIO" run -e "$ENV_NAME" -t create_uf2 >/dev/null 2>&1 || die "create_uf2 selhal" + # NE `exec`: tim by se predalo rizeni a preskocila zaverecna kontrola, ze + # se nezmenila zadna JINA deska -- tedy presne ta pojistka, kvuli ktere + # tenhle skript vznikl. xiao_uf2_flash.sh si overi svuj cil, my overime zbytek. + "$HERE/xiao_uf2_flash.sh" ".pio/build/$ENV_NAME/firmware.uf2" "$TARGET" || RC=$? + # `else` tady CHYBELO, takze po uspesnem UF2 flashi beh propadl do nrfutil na + # $PORT zachyceny PRED flashem -- ten uz neexistuje, protoze se deska + # rebootla do aplikace. Kazdy uspesny UF2 flash se tim ohlasil jako selhany, + # vcetne rady "dvojklikni RESET a spust znovu" pro flash, ktery prosel. + else + echo "== cesta: rucni nrfutil (bootloader bez UF2 disku = serial-only rezim)" + if ! run_nrfutil "$PORT"; then + # Videno 1. 9. 2026 na x2: bootloader vystavuje CDC (USB tridy 02+0a, zadne + # mass storage), ale na DFU protokol neodpovida -- nrfutil skonci na "No + # data received", se `--singlebank` i bez nej. Deska neni mrtva a replug + # s tim nehne, protoze v bootloaderu zustane; chce to DVOJKLIK na RESET, + # kterym se bootloader prepne do UF2 rezimu a VYSTAVI DISK. Pak uz tenhle + # skript sam zvoli druhou cestu (xiao_uf2_flash.sh). + echo >&2 + echo "Bootloader neodpovida na serial DFU, a UF2 disk nevystavuje." >&2 + echo "DVOJKLIKNI na male tlacitko RESET -- tim se prepne do UF2 rezimu" >&2 + echo "a objevi se disk. Pak spust tenhle skript znovu, uz pujde diskem." >&2 + RC=1 + fi + fi + ;; +xiao/*) + echo "== cesta: pio -t upload (deska je v APLIKACI, touch si udela sam)" + "$PIO" run -e "$ENV_NAME" -t upload --upload-port "$PORT" || RC=$? + ;; +t1000e/boot) + echo "== cesta: rucni nrfutil (T1000-E uz je v bootloaderu)" + run_nrfutil "$PORT" || RC=1 + ;; +t1000e/text) + t1000e_to_bootloader || die "deska se do 30 s neprepnula do bootloaderu" + run_nrfutil "$PORT" || RC=1 + ;; +t1000e/*) + # Companion build nema textovou konzoli, takze `dfu uf2` nema kam poslat. + # Buttonless DFU pres BLE ho tam dostane -- a protoze deska JE na USB, + # samotny prenos pak jde po kabelu (~20 s misto minut po BLE). + MAC="$(ble_mac_for "$TARGET")" + [ -n "$MAC" ] || die "T1000-E ve stavu '$STATE' nema textovou konzoli a k seriaku + $TARGET neznam BLE adresu. Doplň pole mac do configu ($(cfg path || echo "$HOME/.config/meshcore-tools/config.ini")), nebo desku dostan + do bootloaderu rucne (dlouhy stisk do 8 s od startu)." + echo "== cesta: BLE buttonless -> bootloader, pak flash po USB" + echo " BLE $MAC (jen prepnuti; prenos pojede po kabelu)" + "$PIO" run -e "$ENV_NAME" >/dev/null 2>&1 || die "build selhal" + # Pripojeny BLE klient by uzel drzel a buttonless zapis by nemel kam -- + # zastavit sluzbu NESTACI, spojeni drzi BlueZ (skill flash-node). + bluetoothctl disconnect "$MAC" >/dev/null 2>&1 || true + sleep 2 + if ! python3 "$HERE/ble_dfu.py" ".pio/build/$ENV_NAME/firmware.zip" "$MAC" phase1; then + die "buttonless pres BLE se nepovedl. BLE DFU je flaky a jeden pokus o connect + nestaci -- ale NESPOUSTEJ to opakovane, RESET po kazdem padu umi desku + uštvat doopravdy (skill flash-node)." + fi + # Bootloader se na USB hlasi BEZ "-BOOT" v nazvu portu -- ano, obracene. + echo "== cekam na bootloader port" + BOOTPORT="" + for _ in $(seq 30); do + # shellcheck disable=SC2010 # by-id names are [A-Za-z0-9_:.-]; $TARGET is a regex + p="$(ls /dev/serial/by-id/ 2>/dev/null | grep -- "$TARGET" | grep -v -- "-BOOT" | head -1)" + [ -n "$p" ] && { + BOOTPORT="/dev/serial/by-id/$p" + break + } + sleep 1 + done + [ -n "$BOOTPORT" ] || die "deska se do 30 s neobjevila v bootloaderu na USB" + echo " bootloader port: $BOOTPORT" + run_nrfutil "$BOOTPORT" || RC=1 + ;; +wio-l1/*) + echo "== cesta: Wio L1 -> predavam MeshCore-solo/flash-l1.sh (touch + disk TRACKER L1)" + L1="$HOME/projects/MeshCore-solo/flash-l1.sh" + [ -x "$L1" ] || die "$L1 nenalezen" + "$PIO" run -e "$ENV_NAME" -t create_uf2 >/dev/null 2>&1 || die "create_uf2 selhal" + "$L1" "$ROOT/.pio/build/$ENV_NAME/firmware.uf2" || RC=$? + ;; +*) + die "kombinaci '$BOARD/$STATE' neumim. Deska neodpovida zadnemu protokolu -- + vytahni ji z USB, zapoj zpatky a spust znovu." + ;; +esac + +if [ "$RC" != "0" ]; then + echo >&2 + echo "FLASH SELHAL. NEOPAKUJ ho -- jeden 1200baudovy touch na power session." >&2 + echo "Vytahni desku z USB, zapoj zpatky, a spust tenhle skript znovu." >&2 + echo >&2 + echo "Kontroluji, jestli to nezapsalo jinam:" >&2 + "$HERE/board_probe.py" --all --compare <(echo "$BEFORE") >&2 + exit 1 +fi + +echo "== otisk desek PO flashi (necham CDC nabehnout)" +sleep 8 +AFTER="$("$HERE/board_probe.py" --all)" +# JEDEN otisk pro obe kontrole. Driv se sbernice otiskovala dvakrat za sebou +# (kazdy az PROBE_DEADLINE dlouhy) a verdikt o zmenach se pocital z jineho +# vzorku, nez overeni verze. +# +# A `|| true` tady BYT NESMI. Do 2. 9. 2026 tam bylo, takze verdikt "zmenila se +# i jina deska" se jen vypsal a skript skoncil nulou -- tedy presne ten nalez, +# pro ktery tenhle nastroj vznikl (obraz mel jit na x4 a pristal na x2), se dal +# prehlednout a kazdy volajici, ktery se ridi exit kodem, videl uspech. +if ! "$HERE/board_probe.py" --all --compare <(echo "$BEFORE") \ + --expect-changed "$TARGET" --now <(echo "$AFTER"); then + echo >&2 + die "otisk sbernice nesouhlasi (viz vys). Bud se zmenila i JINA deska, nebo se + cil nezmenil -- obojim smerem to znamena, ze obraz sel jinam, nez mel." +fi + +GOT_VER="$(echo "$AFTER" | awk -v t="$TARGET" '$1 ~ t {print $3}')" +# Rozlisuj NEOVERITELNE od OVERENE SPATNE. board_probe umi vratit stavovy text +# misto verze (napr. T1000-E, kterou pyserial neotiskne), a +# ten se drive porovnal s WANT_VER a vypsal "FLASH SE NEAPLIKOVAL" po flashi, +# ktery klidne prosel. Dokumentovana cesta `flash_node.sh t1000e_repeater B3F160` +# tak koncila chybou vzdycky. +case "$GOT_VER" in +"" | "-" | neodpovida | drzi | nenalezen) + echo >&2 + echo "NEOVERENO: flash probehl bez chyby, ale verzi z $TARGET nejde precist" >&2 + echo "(probe hlasi '$STATE'). NEZNAMENA to, ze flash selhal -- u T1000-E je to" >&2 + echo "bezny stav. Over rucne z konzole: 'ver' ma dat $WANT_VER." >&2 + exit 2 + ;; +esac +if [ "$GOT_VER" != "$WANT_VER" ]; then + echo >&2 + die "FLASH SE NEAPLIKOVAL. Deska hlasi '$GOT_VER', obraz ma '$WANT_VER'. + Nastroj pred tim mohl hlasit uspech -- 'Device programmed' i 'SUCCESS' + umi vypsat i beh, po kterem na desce zustal stary firmware (bootloader + nestihl novy obraz aktivovat). Spust znovu; pokud to vytrva, chce to + replug." +fi +echo "== OVERENO NA DESCE: $TARGET bezi $GOT_VER" diff --git a/tools/fleet.py b/tools/fleet.py new file mode 100755 index 00000000..9eda1863 --- /dev/null +++ b/tools/fleet.py @@ -0,0 +1,26 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Board names -> USB serial numbers, for the Python tools. + +A thin view of the local config (tools/mctools_config.py, +~/.config/meshcore-tools/config.ini): the tools refer to boards by name, and +`/dev/serial/by-id` is matched on the serial number -- a ttyACM number +changes with every replug and would point a console at a DIFFERENT board. + +There used to be a table here, and a copy of it in five other places (the +shell flashers, the sniffer, the console and a hook). One board reflashed, +the copies drifted, and a stale entry aimed a console at the wrong board. +Now there is one file, outside the repo. +""" + +from mctools_config import boards, serial_for # noqa: F401 (re-exported) + +# name -> serial, only boards that have one (a BLE-only node has none) +FLEET = {n: b["serial"] for n, b in boards().items() if b.get("serial")} + +# the same keyed by each alias too (mesh_sniffer takes `--board 0`) +FLEET_BARE = dict(FLEET) +for _b in boards().values(): + for _a in (x.strip() for x in _b.get("aliases", "").split(",")): + if _a and _b.get("serial"): + FLEET_BARE[_a] = _b["serial"] diff --git a/tools/fleet_test.py b/tools/fleet_test.py new file mode 100755 index 00000000..a767a162 --- /dev/null +++ b/tools/fleet_test.py @@ -0,0 +1,569 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Regression smoke test for the bench fleet -- run it after every firmware change. + + tools/fleet_test.py [--boards 0,1,2,4] [--rounds 1] [--json out.json] + +Grew out of a one-off hw_check.py written to tell a dead radio from a dead IRQ +line. The lesson that made it worth keeping: **a node's own counters cannot +certify the node**. `sent` only says the firmware believes it transmitted, which +is exactly what a dead DIO1 line breaks -- bench-board reported `sent 0` for a week +while a second board heard every frame it sent. So every RF claim here is made by +a DIFFERENT board than the one under test. + +What it does, in order: + + 1. identity version/build per board; flags unstamped ("v1.16.0" with no -tth, + identical in every build ever made) and dirty ("+") images, and + boards that are not on the same build as the rest. + 2. config freq/bw/sf/cr must agree across the fleet, names must be unique. + Without this the matrix below measures nothing -- two boards on + different spreading factors simply cannot hear each other, which + looks exactly like broken hardware. + 3. matrix N x N. Each board sends a ZERO-HOP advert in turn; every other + board must count it. Zero-hop is deliberate: nobody rebroadcasts + it, so "B heard A" cannot be satisfied by C's relay of A -- and + it means the test never has to touch `repeat` prefs. + 4. hygiene tx_timeout / tx_start_fail / recv_errors must not move during the + run, on any board. + 5. commands console builds only: the command surface answers (informational, + plus a hard fail on the handful every repeater build must have). + +Nothing here writes prefs, changes radio settings or reboots anything. + +Handles both build flavours on the bench: the text console (repeater/analyzer) +and the binary companion protocol (companion_radio, which has no text console). +Detection is automatic. + +TRAP: do not leave a BLE client connected to a board under test. The USB and BLE +consoles share one command[160] buffer (simple_repeater/main.cpp), so two live +consoles interleave characters into one line and the node ends up executing +garbage. An earlier A/B run was invalidated exactly that way. +""" +import argparse +import glob +import json +import os +import re +import struct +import subprocess +import sys +import time +from datetime import datetime, timezone + +import serial + +HERE = os.path.dirname(os.path.abspath(__file__)) +FLASH_SH = os.path.join(HERE, "xiao_uf2_flash.sh") + +# Companion protocol (examples/companion_radio/MyMesh.cpp) +CMD_APP_START, CMD_SEND_SELF_ADVERT = 1, 7 +CMD_DEVICE_QUERY, CMD_GET_STATS = 22, 56 +STATS_TYPE_PACKETS = 2 +RESP_SELF_INFO, RESP_DEVICE_INFO, RESP_STATS = 5, 13, 24 + + +def fleet_table(): + """Fleet number -> USB serial, read out of xiao_uf2_flash.sh. + + Parsed rather than duplicated on purpose: two copies of this table would + drift, and mixing up which board is which is the single most expensive + mistake on this bench (a flash went to x4 while the log said x3). + """ + try: + src = open(FLASH_SH).read() + except OSError as e: + sys.exit(f"nelze precist {FLASH_SH}: {e}") + tbl = dict(re.findall(r"^\s*([0-9])\)\s*TARGET=([0-9A-F]{16})\s*;;", src, re.M)) + if not tbl: + sys.exit(f"v {FLASH_SH} nenalezena tabulka desek -- zmenil se format?") + return tbl + + +def discover(wanted): + """[(fleet_no, serial, port)] for XIAO boards actually on USB. + + Always through /dev/serial/by-id and matched on the SERIAL NUMBER: ttyACM* + renumbers on every replug, so a positional guess talks to another board. + """ + tbl = fleet_table() + found, modems = [], [] + # Hledaji se OBA product stringy, ale znamenaji ruzne desky: + # + # usb-Seeed_Studio_XIAO_nRF52840_ MeshCore build (PID 8044) + # usb-Seeed_XIAO-Wio-SX1262_ openhop_modem firmware (PID 0044) + # + # Prejmenovani dela openhop_modem, ne bootloader -- je to hloupe SX1262 PHY + # pro openHop demona, takze na MeshCore konzoli ani companion protokol + # neodpovi a zadnou UF2 mechaniku nevystavi (openHop config: + # radio_type: pymc_usb). + # + # Hlasi se zvlast, protoze obe chybne odpovedi na tohle stoji cas: pri globu + # jen na "XIAO_nRF52840" se 1. 9. 2026 matice smrskla na jednu desku bez + # vysvetleni, a pri globu na oboji to vypadalo jako dve zaseknute desky + # (nasledoval replug a pokus o nrfutil, oboje zbytecne -- deska byla v poradku). + for port in sorted(glob.glob("/dev/serial/by-id/*XIAO-Wio-SX1262*")): + m = re.search(r"_([0-9A-F]{16})-if00", port) + if m: + sn = m.group(1) + modems.append((next((n for n, s in tbl.items() if s == sn), "?"), sn)) + if modems: + for no, sn in modems: + print(f" x{no} ({sn}): openhop_modem firmware, ne MeshCore uzel -- vynechavam") + + for port in sorted(glob.glob("/dev/serial/by-id/*XIAO_nRF52840*")): + m = re.search(r"_([0-9A-F]{16})-if00", port) + if not m: + continue + sn = m.group(1) + no = next((n for n, s in tbl.items() if s == sn), "?") + if wanted and no not in wanted: + continue + found.append((no, sn, port)) + return found + + +# ---------------------------------------------------------------- transports + +class Node: + """Common bits. Ports are opened once and held: reopening costs ~1.3 s of + settle time per command (CDC on nRF52 is deaf until DTR is raised), which + turns an N x N matrix into minutes of dead waiting.""" + + def __init__(self, no, sn, port): + self.no, self.sn, self.port = no, sn, port + self.name = f"x{no}" + # serial_for_url: a /dev path, or socket://host:port for a board on + # another host (--remote; DTR/RTS are then held by the far end). + self.s = serial.serial_for_url(port, 115200, timeout=0) + self.s.dtr = True + self.s.rts = True + time.sleep(1.3) + self.s.reset_input_buffer() + self.info = {} + + def close(self): + try: + self.s.close() + except Exception: + pass + + +class ConsoleNode(Node): + """Repeater / analyzer build: line-oriented text console.""" + + kind = "console" + + def cmd(self, c, timeout=3.0, quiet=0.25): + """Send and read until the reply has stopped arriving. + + Idle-based rather than a fixed sleep: paged analyzer replies (rxlog) are + kilobytes and a fixed wait either truncates them or wastes seconds on + every one-line answer. + """ + self.s.reset_input_buffer() + self.s.write((c + "\r\n").encode()) + buf, deadline, last = b"", time.time() + timeout, None + while time.time() < deadline: + chunk = self.s.read(8192) + if chunk: + buf += chunk + last = time.time() + elif last and time.time() - last > quiet: + break + else: + time.sleep(0.02) + return buf.decode(errors="replace") + + def stats(self): + m = re.search(r"\{.*\}", self.cmd("stats-packets")) + return json.loads(m.group(0)) if m else {} + + def radio_stats(self): + m = re.search(r"\{.*\}", self.cmd("stats-radio")) + return json.loads(m.group(0)) if m else {} + + def identify(self): + ver = self.cmd("ver") + m = re.search(r"->\s*(\S+)\s*\(Build:\s*([^)]*)\)", ver) + self.info["version"] = m.group(1) if m else "?" + self.info["build"] = m.group(2).strip() if m else "?" + r = re.search(r"->\s*>?\s*([\d.]+),([\d.]+),(\d+),(\d+)", self.cmd("get radio")) + self.info["radio"] = (f"{float(r.group(1)):.3f}/{float(r.group(2))}/" + f"{r.group(3)}/{r.group(4)}") if r else "?" + n = re.search(r"->\s*>?\s*(.+)", self.cmd("get name")) + self.info["node"] = n.group(1).strip() if n else "?" + + def advert(self): + return "OK" in self.cmd("advert.zerohop", timeout=4.0) + + +class CompanionNode(Node): + """companion_radio build: binary frames, no text console at all. + + Framing is '<' + uint16 LE length + payload outbound, '>' + length + payload + inbound (src/helpers/ArduinoSerialInterface.cpp). + """ + + kind = "companion" + + def send(self, payload): + self.s.write(b"<" + struct.pack("") + if i < 0 or len(buf) < i + 3: + break + ln = struct.unpack("= 80: + self.info["build"] = d[8:20].split(b"\0")[0].decode(errors="replace") + self.info["version"] = d[60:80].split(b"\0")[0].decode(errors="replace") + # RESP_CODE_SELF_INFO: code, adv_type, tx_power, max_tx_power, + # pub_key[32], lat[4], lon[4], multi_acks, + # loc_policy, telemetry, manual_contacts, + # freq[4], bw[4], sf, cr, name[...] + self.send(bytes([CMD_APP_START, 1, 0, 0, 0, 0, 0, 0]) + b"fleet") + s = self.recv(RESP_SELF_INFO) + if s and len(s) >= 58: + freq, bw = struct.unpack("" in n.cmd("ver", timeout=2.0): + return n + n.close() + c = CompanionNode(no, sn, port) + if c.handshake(): + return c + c.close() + return None + + +# -------------------------------------------------------------------- checks + +class Report: + def __init__(self): + self.rows = [] + + def add(self, section, name, ok, detail): + self.rows.append((section, name, bool(ok), detail)) + mark = "OK " if ok else "FAIL" + print(f" [{mark}] {name}: {detail}", flush=True) + + def note(self, text): + print(f" {text}", flush=True) + + @property + def failed(self): + return [r for r in self.rows if not r[2]] + + +def check_identity(nodes, rep): + print("\n== 1. identita a verze", flush=True) + for n in nodes: + v, b = n.info.get("version", "?"), n.info.get("build", "?") + rep.note(f"x{n.no} {n.info.get('node','?'):<14} {v} ({b}) [{n.kind}]") + vers = {n.info.get("version", "?") for n in nodes} + stale = [n for n in nodes if not re.search(r"-tth[0-9a-f]+", n.info.get("version", ""))] + dirty = [n for n in nodes if n.info.get("version", "").endswith("+")] + rep.add("identity", "vsechny obrazy jsou stampovane", not stale, + "ok" if not stale else + f"bez -tth: {[n.name for n in stale]} -- env nema ${{stamped.extra_scripts}}, " + "verze je literal shodny ve vsech buildech") + rep.add("identity", "zadny obraz z spinaveho stromu", not dirty, + "ok" if not dirty else f"konci na '+': {[n.name for n in dirty]}") + # Deliberately a note, not a check. The bench legitimately runs several envs + # at once (repeater, bot, companion), so "all on one version" is not a + # property this fleet has -- asserting it would cry wolf on every run and + # train you to ignore the summary. What matters is that you can SEE what is + # where, and the two things above, which are rule violations in any env. + if len(vers) > 1: + by_ver = {} + for n in nodes: + by_ver.setdefault(n.info.get("version", "?"), []).append(n.name) + rep.note("ruzne buildy na lavici: " + + " | ".join(f"{v}: {' '.join(b)}" for v, b in sorted(by_ver.items()))) + + +def check_config(nodes, rep): + print("\n== 2. konfigurace radia", flush=True) + radios = {} + for n in nodes: + radios.setdefault(n.info.get("radio", "?"), []).append(n.name) + rep.add("config", "shodne parametry radia", len(radios) == 1, + " | ".join(f"{r}: {v}" for r, v in radios.items())) + names = [n.info.get("node", "?") for n in nodes] + dupes = {x for x in names if names.count(x) > 1} + rep.add("config", "jmena uzlu jsou unikatni", not dupes, + "ok" if not dupes else f"duplicity: {sorted(dupes)}") + return len(radios) == 1 + + +def check_matrix(nodes, rep, rounds): + print(f"\n== 3. krizova matice ({len(nodes)} desek, {rounds}x)", flush=True) + if len(nodes) < 2: + rep.add("matrix", "matice potrebuje aspon 2 desky", False, + f"pripojena je {len(nodes)}") + return {} + + heard = {t.name: {r.name: 0 for r in nodes if r is not t} for t in nodes} + rssi = {t.name: {} for t in nodes} + for rnd in range(rounds): + for tx in nodes: + others = [n for n in nodes if n is not tx] + before = {n.name: n.stats() for n in nodes} + tx.advert() + time.sleep(3.0) + after = {n.name: n.stats() for n in nodes} + + d_sent = after[tx.name].get("sent", 0) - before[tx.name].get("sent", 0) + d_to = after[tx.name].get("tx_timeout", 0) - before[tx.name].get("tx_timeout", 0) + got = [] + for rx in others: + d = after[rx.name].get("recv", 0) - before[rx.name].get("recv", 0) + if d >= 1: + heard[tx.name][rx.name] += 1 + rs = rx.radio_stats() + if rs: + rssi[tx.name][rx.name] = (rs.get("last_rssi"), rs.get("last_snr")) + got.append(f"{rx.name}{'+' if d >= 1 else '-'}") + rep.note(f"kolo {rnd+1}: {tx.name} vysila -> sent +{d_sent} " + f"timeout +{d_to} | slyseli: {' '.join(got)}") + + for tx in nodes: + misses = [r for r, c in heard[tx.name].items() if c < rounds] + rep.add("matrix", f"{tx.name} slyseli vsichni ({rounds}/{rounds})", not misses, + "ok" if not misses else + f"neslyseli/ne vzdy: {', '.join(f'{r} {heard[tx.name][r]}/{rounds}' for r in misses)}") + for tx in nodes: + for rx, v in rssi[tx.name].items(): + if v[0] is not None: + rep.note(f"{tx.name} -> {rx}: RSSI {v[0]} dBm, SNR {v[1]} dB") + return heard + + +def check_hygiene(nodes, base, rep): + print("\n== 4. countery chyb behem behu", flush=True) + for n in nodes: + a, b = n.stats(), base[n.name] + bad = {k: a.get(k, 0) - b.get(k, 0) + for k in ("tx_timeout", "tx_start_fail", "recv_errors") + if a.get(k, 0) - b.get(k, 0) > 0} + rep.add("hygiene", f"{n.name} bez chybovych counteru", not bad, + "ok" if not bad else str(bad)) + + +# Rok, pod kterym je jasne, ze hodinam nikdo cas nenastavil: VolatileRTCClock +# startuje v kvetnu 2024 a jinak jen tika z millis(). +CLOCK_FLOOR = 1735689600 # 2025-01-01 UTC + + +def check_clock(nodes, rep): + print("\n== 6. hodiny desek", flush=True) + for n in nodes: + if n.kind != "console": + rep.note(f"{n.name}: companion build, `clock` neexistuje -- preskoceno") + continue + out = n.cmd("clock") + m = re.search(r"epoch\s+(\d+)", out) + if m: + node_epoch = int(m.group(1)) + else: + m = re.search(r"\b(\d{1,2}):(\d{2})\s*-\s*(\d{1,2})/(\d{1,2})/(\d{4})", out) + if not m: + rep.add("clock", f"{n.name} odpovida na clock", False, out.strip()[:60]) + continue + hh, mm, day, mon, year = (int(g) for g in m.groups()) + try: + node_epoch = int(datetime(year, mon, day, hh, mm, + tzinfo=timezone.utc).timestamp()) + except ValueError: + rep.add("clock", f"{n.name} odpovida na clock", False, out.strip()[:60]) + continue + skew = int(time.time()) - node_epoch + # Deska, ktere nikdo cas nenastavil, je vada konfigurace, ne vada desky -- + # ale prave proto se to musi hlasit. Na x3 to uniklo 811 dni a na teto + # lavici to 7. 8. 2026 platilo pro KAZDOU desku. Spatny cas neni kosmetika: + # RTC stampuje kazdy vyslany advert a prijemce stary timestamp zahodi jako + # replay. Srovnat: `tools/ble_cli.py "time {epoch}"` nebo pres USB. + rep.add("clock", f"{n.name} ma nastavene hodiny", node_epoch > CLOCK_FLOOR, + f"{datetime.fromtimestamp(node_epoch, timezone.utc).isoformat()}" + f" (skew {skew:+d} s = {skew / 86400:.1f} dni)") + + +# Commands every repeater/analyzer build must answer. `dfu` is deliberately NOT +# probed -- it reboots into the bootloader. +MUST_HAVE = ["ver", "advert.zerohop", "stats-packets", "blink", "txpwr"] +OPTIONAL = ["nodes", "rxlog 999999", "pktlog 999999", "bot", "dio1", "bleconn"] + + +def check_commands(nodes, rep): + print("\n== 5. povrch prikazu (jen console buildy)", flush=True) + for n in nodes: + if n.kind != "console": + rep.note(f"{n.name}: companion build, textova konzole neexistuje -- preskoceno") + continue + missing = [c for c in MUST_HAVE if "Unknown command" in n.cmd(c)] + rep.add("commands", f"{n.name} ma zakladni prikazy", not missing, + "ok" if not missing else f"chybi: {missing}") + have = [c.split()[0] for c in OPTIONAL if "Unknown command" not in n.cmd(c)] + rep.note(f"{n.name} volitelne: {' '.join(have) if have else '(zadne)'}") + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--boards", help="cisla desek, napr. 0,1,2,4 (vychozi: vse na USB)") + ap.add_argument("--rounds", type=int, default=1, help="kol matice (vychozi 1)") + ap.add_argument("--json", help="ulozit vysledek jako JSON") + ap.add_argument("--remote", action="append", default=[], metavar="N=URL", + help="deska na jinem hostu, napr. 1=socket://127.0.0.1:7001 " + "(TCP<->serial proxy na tom hostu + ssh -L); opakovatelne") + a = ap.parse_args() + + wanted = set(a.boards.split(",")) if a.boards else None + found = discover(wanted) + tbl = fleet_table() + for r in a.remote: + no, _, url = r.partition("=") + if not url: + sys.exit(f"--remote {r}: cekam N=URL") + found.append((no, tbl.get(no, "?"), url)) + if not found: + sys.exit("na USB nenalezena zadna XIAO deska") + + print(f"== nalezeno {len(found)} desek", flush=True) + nodes = [] + for no, sn, port in found: + n = open_node(no, sn, port) + if n is None: + # "Neodpovida" je spatna diagnoza, kdyz na desce bezi neco, co ani + # odpovidat nema. 1. 9. 2026 to stalo hodinu a tri zbytecne replugy: + # na x2 skoncil omylem KISS modem (nema textovou konzoli ANI companion + # protokol) a hlaska vypadala jako zaseknuta deska. Doptame se tedy + # jeste KISS ramcem, at je videt, CO tam bezi. + what = "neodpovida ani konzoli, ani companion protokolu" + try: + out = subprocess.run( + [os.path.join(HERE, "board_probe.py"), "--all"], + capture_output=True, text=True, timeout=90).stdout + # Stav, ktery probe NEZJISTIL, se nesmi vydavat za zjistenou + # identitu firmwaru. `visi` znamena, ze deska visela v open(2), + # `obsazeny` ze port drzi nekdo jiny (casto tenhle beh sam), + # `chyba` ze probe spadl -- z zadneho z nich neplyne "neni to + # MeshCore uzel". Takhle to hlasilo presne tu diagnozu, kterou + # nastroj nemel cim podepřít. + for line in out.splitlines(): + f = line.split(None, 2) + if len(f) < 2 or f[0] != sn: + continue + kind = f[1].split("/")[-1] + ver = f[2].strip() if len(f) > 2 else "" + if kind in ("nic", "nedostupny", "modem", "boot"): + what = f"{f[1]} {ver} -- neni to MeshCore uzel, vynechavam" + elif kind in ("visi", "obsazeny", "chyba"): + what = (f"{f[1]} {ver} -- stav se NEPODARILO zjistit," + f" vynechavam (o firmwaru to nic nerika)") + else: + what = f"{f[1]} {ver} -- jiny protokol, vynechavam" + except Exception: + pass + print(f" x{no} ({sn}): {what}", flush=True) + continue + n.identify() + nodes.append(n) + if not nodes: + sys.exit("zadna deska neodpovedela") + + rep = Report() + try: + check_identity(nodes, rep) + same_radio = check_config(nodes, rep) + if not same_radio: + rep.note("POZOR: desky nejsou na stejnem radiu, matice nize je tim padem " + "test konfigurace, ne hardwaru") + base = {n.name: n.stats() for n in nodes} + check_matrix(nodes, rep, a.rounds) + check_hygiene(nodes, base, rep) + check_commands(nodes, rep) + check_clock(nodes, rep) + finally: + for n in nodes: + n.close() + + print("\n===== SOUHRN =====") + for _sec, name, ok, _detail in rep.rows: + print(f" {'OK ' if ok else 'FAIL'} {name}") + n_bad = len(rep.failed) + print(f"\n{len(rep.rows) - n_bad}/{len(rep.rows)} proslo") + + if a.json: + with open(a.json, "w") as f: + json.dump({"boards": [{"no": n.no, "sn": n.sn, "kind": n.kind, **n.info} + for n in nodes], + "checks": [{"section": s, "name": nm, "ok": ok, "detail": d} + for s, nm, ok, d in rep.rows]}, f, indent=2) + print(f"JSON: {a.json}") + return 1 if n_bad else 0 + + +# The guard is not decoration: this module TRANSMITS. check_matrix() and the +# `advert.zerohop` probe in check_commands() key the radio on every console board +# found on USB, whatever band each one is tuned to. Without the guard, so much as +# `import fleet_test` to reuse discover() ran the whole suite -- which on +# 7. 8. 2026 put two zero-hop adverts on 869.432 out of a bench board configured +# for the live CZ mesh, before the importing script's own first line had run. +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/fw_room_smoke.py b/tools/fw_room_smoke.py new file mode 100755 index 00000000..ff0e8c8f --- /dev/null +++ b/tools/fw_room_smoke.py @@ -0,0 +1,119 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Smoke test of a FIRMWARE room server (simple_room_server) over the air. + +Two MeshCore companions log in as guests; each posts once and the room must +push that post to the OTHER one (signed message from the room, author prefix +in the signature), never back to its author. That is the room's whole job -- +login, store, push -- end to end, on real radios. + + tools/fw_room_smoke.py --room --password \\ + --a 127.0.0.1:47001 --b 127.0.0.1:47003 + +--a/--b are companions reachable as meshcore TCP (a companion on USB elsewhere +can be exposed with a TCP<->serial bridge; the frames are the same). The room +is added to both as a contact with a flood path, so no advert is needed. + +Run it on the bench preset only (all three on 866.5): it transmits logins and +posts. Exit 0 = every step passed. + +Not the openHop room (tth-room): that one has its own bench, +openhop-repeater/tools/bench/room_delivery.py. +""" + +import argparse +import asyncio +import sys +import time + +if __name__ == "__main__" and any(a in ("-h", "--help") for a in sys.argv[1:]): + print(__doc__) + sys.exit(0) + +from meshcore import EventType, MeshCore # noqa: E402 + +ROOM_TYPE = 3 + + +def room_contact(pubkey, name="room-under-test"): + return { + "public_key": pubkey, "type": ROOM_TYPE, "flags": 0, + "out_path_len": -1, "out_path": "", "out_path_hash_mode": 0, + "adv_name": name, "last_advert": 0, "adv_lat": 0.0, "adv_lon": 0.0, + } + + +async def connect(hostport): + host, port = hostport.rsplit(":", 1) + mc = await MeshCore.create_tcp(host, int(port)) + return mc + + +async def wait_push(mc, room_prefix, needle, timeout): + """Wait for a message from the room whose text contains `needle`.""" + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + ev = await mc.dispatcher.wait_for_event(EventType.CONTACT_MSG_RECV, + timeout=max(0.1, deadline - time.monotonic())) + if ev is None: + break + p = ev.payload + if p.get("pubkey_prefix", "").lower() == room_prefix and needle in p.get("text", ""): + return p + return None + + +async def main(): + ap = argparse.ArgumentParser(description="firmware room server smoke test") + ap.add_argument("--room", required=True, help="room server public key (64 hex)") + ap.add_argument("--password", required=True, help="guest password") + ap.add_argument("--a", required=True, help="companion A host:port") + ap.add_argument("--b", required=True, help="companion B host:port") + ap.add_argument("--push-timeout", type=float, default=120) + args = ap.parse_args() + + room = args.room.lower() + prefix = room[:12] + ok = True + a, b = await connect(args.a), await connect(args.b) + names = {id(a): a.self_info.get("name"), id(b): b.self_info.get("name")} + for mc in (a, b): + await mc.commands.add_contact(room_contact(room)) + await mc.ensure_contacts() + await mc.start_auto_message_fetching() + + for mc in (a, b): + t0 = time.monotonic() + ev = await mc.commands.send_login_sync(room, args.password, min_timeout=20) + good = ev is not None and ev.type == EventType.LOGIN_SUCCESS + print(f"login {names[id(mc)]}: {'OK' if good else 'FAIL'} ({time.monotonic() - t0:.1f} s)") + ok &= good + if not good: + break + + if ok: + for src, dst in ((a, b), (b, a)): + tag = f"smoke-{int(time.time())}-{names[id(src)]}" + res = await src.commands.send_msg_with_retry(room, tag, max_attempts=3) + sent = res is not None and res.type != EventType.ERROR + print(f"post by {names[id(src)]}: {'acked' if sent else 'NOT acked'}") + t0 = time.monotonic() + got = await wait_push(dst, prefix, tag, args.push_timeout) + if got: + print(f"push to {names[id(dst)]}: OK after {time.monotonic() - t0:.1f} s " + f"(author sig {got.get('signature')}, path_len {got.get('path_len')})") + else: + print(f"push to {names[id(dst)]}: FAIL (nothing in {args.push_timeout:.0f} s)") + echo = await wait_push(src, prefix, tag, 5) + if echo: + print(f"author {names[id(src)]} got its own post back: FAIL") + ok &= sent and got is not None and echo is None + + for mc in (a, b): + await mc.disconnect() + print("RESULT:", "PASS" if ok else "FAIL") + return 0 if ok else 1 + + +if __name__ == "__main__": + sys.exit(asyncio.run(main())) diff --git a/tools/gen_node_id.py b/tools/gen_node_id.py new file mode 100755 index 00000000..4abd3629 --- /dev/null +++ b/tools/gen_node_id.py @@ -0,0 +1,177 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Vygeneruje identitu uzlu s NEKOLIZNIM path hashem. + +Proc to nejde nechat na nahode +------------------------------- +Path hash je prosty prefix verejneho klice (`Identity.h:20`) a jeho sirku urcuje +ODESILATEL paketu, ne forwarder -- `Mesh.cpp:346` pripoji `packet->getPathHashSize()` +bajtu, takze do jednobajtoveho paketu pripise jeden bajt i repeater nastaveny na dva. +Kandidatem na hop je proto VZDY cela populace repeateru, ne jen ti nastaveni na tutez +sirku. Zmereno na CZ meshi 5. 8. 2026 (669 repeateru): + + 1 bajt -> 620 repeateru sedi na sdilenem prefixu (253 z 256 hodnot obsazeno) + 2 bajty -> 6 (obsazenost 1,25 %) + 3 bajty -> 0 + +Jednobajtova unikatnost je tedy neziskatelna (pigeonhole: 669 > 256), zato dvoubajtova +je skoro zadarmo. Kolize neni kosmetika: `isHashMatch` porovna prave tyhle bajty, takze +na kolidujici hop reaguje VIC repeateru -- rozbiji to routovani i atribuci v analyzeru. + +Pouziti +------- + tools/gen_node_id.py # 2B prefix volny proti CoreScope + tools/gen_node_id.py --bytes 3 # prisnejsi + tools/gen_node_id.py --first-byte 5f # k tomu konkretni prvni bajt + tools/gen_node_id.py --known klice.txt # offline, misto CoreScope + +Nahrani do uzlu (klic je 64 B = seed32 || pubkey32, viz PRV_KEY_SIZE v MeshCore.h): + meshcore-cli -a set private_key <128 hex znaku> +""" +import argparse +import hashlib +import json +import os +import secrets +import sys +import urllib.request +from cryptography.hazmat.primitives import serialization as ser +from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey + + +def keypair(seed: bytes): + """Vrati (pub32, prv64) ve formatu, ktery ceka MeshCore. + + POZOR: prv NENI seed||pub (konvence libsodium), ale **clampnuty SHA-512(seed)** + -- viz lib/ed25519/keypair.c: + + sha512(seed, 32, private_key); + private_key[0] &= 248; private_key[31] &= 63; private_key[31] |= 64; + ge_scalarmult_base(&A, private_key); + + `set prv.key` jinak odpovi "Error, bad key", protoze validatePrivateKey() + si pubkey odvodi pres ed25519_derive_pub() z prvnich 32 bajtu jako ze skalaru. + Pub pocitame pres standardni Ed25519 ze seedu -- RFC 8032 dela presne tohle. + """ + h = bytearray(hashlib.sha512(seed).digest()) + h[0] &= 248 + h[31] &= 63 + h[31] |= 64 + pub = Ed25519PrivateKey.from_private_bytes(seed).public_key().public_bytes( + ser.Encoding.Raw, ser.PublicFormat.Raw) + return pub, bytes(h) + +# Verejny komunitni analyzer: vidi cely mesh (50 observeru), ne jen to, co slysi +# nase dve. Kolize se musi hledat proti nejuplnejsi populaci, jakou sezeneme. +DEFAULT_SRC = "https://analyzer.meshcore.cz/api/analytics/hash-sizes" + + +def load_known(src): + """Vrati (vsechny_pubkey, pubkey_repeateru) jako lowercase hex.""" + if src.startswith("http"): + with urllib.request.urlopen(src, timeout=20) as r: + d = json.load(r) + # Zdroje se lisi tvarem a API se meni pod rukama (23. 8. 2026 zmizel + # "multiByteCapability" z CoreScope): zkus zname obalky, pak fallback + # na prvni list dictu v odpovedi. Klic pubkeye taky pluje. + nodes = None + for k in ("multiByteCapability", "nodes", "data"): + if isinstance(d, dict) and isinstance(d.get(k), list): + nodes = d[k] + break + if nodes is None: + if isinstance(d, list): + nodes = d + else: + nodes = next((v for v in d.values() if isinstance(v, list)), None) + if not nodes: + sys.exit(f"zdroj {src} nevratil zadny seznam uzlu") + def pk(n): + return (n.get("pubkey") or n.get("public_key") or n.get("publicKey") or "").lower() + rep_types = {"repeater", 2, "2"} + return ([pk(n) for n in nodes if pk(n)], + [pk(n) for n in nodes if pk(n) and ( + n.get("role") in rep_types or n.get("type") in rep_types + or n.get("node_type") in rep_types)]) + keys = [ln.strip().lower() for ln in open(src) if ln.strip()] + return keys, keys + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--bytes", type=int, default=2, + help="kolik bajtu prefixu musi byt volnych (default 2)") + ap.add_argument("--first-byte", metavar="HEX", + help="vynutit konkretni prvni bajt, napr. 5f") + ap.add_argument("--known", default=DEFAULT_SRC, + help="zdroj znamych klicu: URL CoreScope nebo soubor") + ap.add_argument("--max-tries", type=int, default=5_000_000) + ap.add_argument("--derive", metavar="HEX128", + help="jen odvodit pubkey z existujiciho 64B prv.key a skoncit. " + "PAST: prv[32:64] NENI pubkey (je to druha pulka SHA-512) " + "-- pub = ge_scalarmult_base(prv[0:32]). Chce PyNaCl.") + ap.add_argument("--out", metavar="SOUBOR", + help="kam zapsat privatni klic (0600). Bez toho se NEVYPISUJE " + "-- klic nema co delat v scrollbacku terminalu.") + a = ap.parse_args() + + if a.derive: + import nacl.bindings as nb # jen tady, jinak staci `cryptography` + prv = bytes.fromhex(a.derive.strip()) + if len(prv) != 64: + sys.exit(f"prv.key ma mit 64 bajtu (128 hex), ma {len(prv)}") + print(nb.crypto_scalarmult_ed25519_base_noclamp(prv[:32]).hex()) + return + + try: + allk, repk = load_known(a.known) + except Exception as e: + sys.exit(f"nelze nacist zname klice z {a.known}: {e}") + + n = a.bytes * 2 + taken_all = {k[:n] for k in allk} + bucket1 = {} + for k in repk: + bucket1[k[:2]] = bucket1.get(k[:2], 0) + 1 + print(f"znamych uzlu {len(allk)} (z toho repeateru {len(repk)}); " + f"obsazenych {a.bytes}B prefixu: {len(taken_all)}", file=sys.stderr) + + want = a.first_byte.lower() if a.first_byte else None + if want and len(want) != 2: + sys.exit("--first-byte chce prave dva hex znaky") + + if want in ("00", "ff"): + sys.exit("00 a ff nejsou volne, ale ZAKAZANE -- Identity.cpp:56 odmita " + "klic s pub[0] == 0x00 nebo 0xFF jako neplatny") + + for i in range(a.max_tries): + seed = secrets.token_bytes(32) + pub, prv64 = keypair(seed) + h = pub.hex() + if h[:2] in ("00", "ff"): # firmware by takovy klic odmitl + continue + if want and h[:2] != want: + continue + if h[:n] in taken_all: + continue + crowd = bucket1.get(h[:2], 0) + print(f"nalezeno po {i + 1} pokusech", file=sys.stderr) + print(f"pub_key {h}") + print(f"path hash 1B={h[:2]} 2B={h[:4]} 3B={h[:6]}") + print(f"prvni bajt {h[:2]} sdili {crowd} repeateru" + + (" <-- unikatni i na 1 bajt!" if crowd == 0 else "")) + if a.out: + fd = os.open(a.out, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) + with os.fdopen(fd, "w") as f: + f.write(prv64.hex() + "\n") + print(f"\nprivatni klic zapsan do {a.out} (0600). Nahrani do uzlu:") + print(f" repeater po seriove konzoli: set prv.key $(cat {a.out})") + print(f" companion pres meshcore-cli: set private_key $(cat {a.out})") + else: + print("\n(privatni klic se nevypisuje; pouzij --out SOUBOR)") + return + sys.exit("nenalezeno, zvys --max-tries nebo uvolni podminky") + + +if __name__ == "__main__": + main() diff --git a/tools/mctools_config.py b/tools/mctools_config.py new file mode 100755 index 00000000..b246aa31 --- /dev/null +++ b/tools/mctools_config.py @@ -0,0 +1,173 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Local config of the MeshCore tools: which boards and nodes you have. + +The tools in this directory carry no board serial, MAC or host of anyone's +bench. They take them from ONE file beside the repo: + + ~/.config/meshcore-tools/config.ini (or $MESHCORE_TOOLS_CONFIG) + +Copy tools/config.example.ini there and describe your boards. Without the +file every tool still works with full serial numbers, MACs and port paths -- +only names like `b1` need it. No secrets go in here: admin passwords stay in +platformio.local.ini. + +From Python: + + from mctools_config import serial_for, mac_for, boards + serial_for("b1") # -> "0123456789ABCDEF", or the input unchanged + +From shell (the same answers, one per line, exit 1 when there is none): + + tools/mctools_config.py path + tools/mctools_config.py serial b1 # alias, number or serial + tools/mctools_config.py mac b1 # BLE MAC of that board + tools/mctools_config.py get b1 protect # any field of the board + tools/mctools_config.py list [--role bench] [--has protect] [--field serial] + tools/mctools_config.py name 0123456789ABCDEF # board name for a serial or MAC + +Board section, every field optional: + + [board.b1] + serial = 0123456789ABCDEF ; USB serial number (/dev/serial/by-id) + mac = AA:BB:CC:DD:EE:01 ; BLE MAC of the application + aliases = 1 ; other names that mean this board + role = bench ; bench | live | probe -- tools and hooks decide by it + protect = keeps an identity ; flashing tools refuse it unless told to + refuse = an observer radio ; console tools refuse to open it at all + host = lab-pc ; where it is plugged in (informative) +""" + +from __future__ import annotations + +import argparse +import configparser +import os +import re +import shlex +import sys +from pathlib import Path + +ENV = "MESHCORE_TOOLS_CONFIG" +DEFAULT = Path.home() / ".config/meshcore-tools/config.ini" +EXAMPLE = Path(__file__).resolve().parent / "config.example.ini" +FIELDS = ("serial", "mac", "aliases", "role", "protect", "refuse", "host") + + +def path() -> Path: + return Path(os.environ.get(ENV) or DEFAULT) + + +def boards() -> dict[str, dict[str, str]]: + """{name: {field: value}} from the config; empty without a config.""" + cp = configparser.ConfigParser(interpolation=None, inline_comment_prefixes=(";", "#")) + cp.read(path()) + out = {} + for sec in cp.sections(): + if sec.startswith("board."): + out[sec[6:]] = {k: v.strip() for k, v in cp[sec].items()} + return out + + +def find(key: str) -> tuple[str, dict[str, str]] | None: + """The board a name, alias, serial number or MAC belongs to.""" + k = key.strip() + for name, b in boards().items(): + aliases = [a.strip() for a in b.get("aliases", "").split(",") if a.strip()] + if k == name or k in aliases: + return name, b + if b.get("serial") and k.upper() == b["serial"].upper(): + return name, b + if b.get("mac") and k.upper() == b["mac"].upper(): + return name, b + return None + + +def serial_for(key: str) -> str: + """USB serial of a board name/alias, or the input unchanged (a serial or a + port path passes straight through).""" + hit = find(key) + return hit[1].get("serial", key) if hit else key + + +def mac_for(key: str) -> str | None: + hit = find(key) + return hit[1].get("mac") if hit else None + + +def field(key: str, name: str) -> str | None: + hit = find(key) + return hit[1].get(name) if hit else None + + +def by_role(role: str | None = None) -> dict[str, dict[str, str]]: + return {n: b for n, b in boards().items() if role is None or b.get("role") == role} + + +def unknown_alias_hint(key: str) -> str: + return f"{key!r} is no board in {path()} (template: {EXAMPLE})" + + +def main() -> int: + ap = argparse.ArgumentParser( + description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter + ) + sub = ap.add_subparsers(dest="cmd", required=True) + sub.add_parser("path", help="the config file in use") + sub.add_parser("hook-vars", help="shell assignments LIVE_IDS / BENCH_IDS (regexes) for a guard hook") + for c in ("serial", "mac", "name"): + sub.add_parser(c).add_argument("key") + g = sub.add_parser("get") + g.add_argument("key") + g.add_argument("field", choices=FIELDS) + lst = sub.add_parser("list") + lst.add_argument("--role") + lst.add_argument("--has", choices=FIELDS, help="only boards that set this field") + lst.add_argument("--field", choices=FIELDS, help="print only this field (skip boards without it)") + a = ap.parse_args() + + if a.cmd == "path": + print(path()) + return 0 if path().exists() else 1 + if a.cmd == "hook-vars": + # live: MACs and names; bench: serials, MACs and names as whole words + def ere(text: str) -> str: # POSIX ERE (grep -E), not Python re + return re.sub(r"([.^$*+?()\[\]{}|\\])", r"\\\1", text) + + def ids(role: str) -> str: + out = [] + for n, b in by_role(role).items(): + out += [ere(b[k]) for k in ("serial", "mac") if b.get(k)] + out.append(f"(^| ){ere(n)}( |$)") + return "|".join(out) + + print(f"LIVE_IDS={shlex.quote(ids('live'))}") + print(f"BENCH_IDS={shlex.quote(ids('bench'))}") + return 0 + if a.cmd == "list": + for n, b in by_role(a.role).items(): + if a.has and not b.get(a.has): + continue + if a.field: + if b.get(a.field): + print(b[a.field]) + else: + print(n) + return 0 + hit = find(a.key) + if a.cmd == "serial": + val = hit[1].get("serial") if hit else None + elif a.cmd == "mac": + val = hit[1].get("mac") if hit else None + elif a.cmd == "name": + val = hit[0] if hit else None + else: + val = hit[1].get(a.field) if hit else None + if not val: + return 1 + print(val) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/mesh_sniffer.py b/tools/mesh_sniffer.py new file mode 100755 index 00000000..520215db --- /dev/null +++ b/tools/mesh_sniffer.py @@ -0,0 +1,445 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Passive MeshCore sniffer -- every frame the radio hears, decoded on the host. + + tools/mesh_sniffer.py --board 0 --preset cz [--jsonl cap.jsonl] [--pcap cap.pcap] + [--psk ] [--seconds 600] + +Needs a board running the openHop modem firmware (openhop-dev/openhop_modem) and +`pip install openhop-core` -- the Python reimplementation of the MeshCore stack. +The board is a dumb SX1262 PHY: it hands up EVERY frame that passes CRC, tagged +with RSSI/SNR, and all decoding happens here. + +Why this exists, when we already have a node + BLE bridge feeding the analyzer: + + * A companion node only ever surfaces what ITS firmware decided to process -- + its own channels and DMs, adverts, packets addressed to it. Foreign-PSK + channel traffic and DIRECT packets for other destinations are dropped before + the companion protocol ever sees them. The modem has no such opinion, so + "SDR sees twice what the observer decodes" (docs, measured) becomes a + testable claim instead of a mystery: the modem's own rx_count is printed + next to the number of frames we managed to parse. + * No BLE anywhere on the path -- no dock-quiet interaction, no BlueZ holding + the link, no MC_BLE_OFF_INTERVAL windows costing 42 % of the capture. + +RECEIVE ONLY, by construction. There is no call to radio.send() in this file and +no dispatcher/handler is registered, so nothing can answer, ACK or forward. That +matters on 869.432: an unannounced node that starts answering confuses routing. +The modem is left with tx_power at its floor as a second line of defence. + +Two traps that shaped the code, both worth keeping in mind if you extend it: + + * openhop_core's own Dispatcher runs a PacketFilter that swallows byte-identical + frames for 30 s. That is right for a repeater and wrong for a sniffer -- two + neighbours relaying the same flood is exactly the observation we are after. + So this script parses packets itself instead of going through the dispatcher, + and counts duplicates instead of hiding them. + * USBLoRaRadio's rx_callback is handed only the payload; RSSI/SNR live in + radio.last_rssi/last_snr, which the NEXT packet overwrites before a queued + callback runs. So we override _dispatch_frame and take the metadata straight + out of the CMD_RX_PACKET frame, where it is atomic with the bytes. +""" + +from __future__ import annotations + +import argparse +import glob +import hashlib +import hmac +import json +import os +import socket +import struct +import sys +import threading +import time +from collections import Counter + +try: + from openhop_core.hardware.usb_radio import CMD_RX_PACKET, USBLoRaRadio + from openhop_core.protocol import decode_appdata, parse_advert_payload + from openhop_core.protocol.packet import Packet +except ImportError: + # --help má jít i bez závislostí: aspoň hlavička (plné volby až s openhop-core). + if {"-h", "--help"} & set(sys.argv[1:]): + print(__doc__.strip()) + sys.exit(0) + sys.exit( + "chybi openhop-core: python3 -m venv .venv && .venv/bin/pip install openhop-core pyserial" + ) + +# Fleet shorthand, same numbering as tools/xiao_uf2_flash.sh. Keyed on serial +# number because the by-id NAME changes with the firmware: the modem build +# renames the port from usb-Seeed_Studio_XIAO_nRF52840_ to +# usb-Seeed_XIAO-Wio-SX1262_, so anything matching on the name breaks the +# moment the board becomes a modem. +# Tabulka žije v fleet.py, ať se pátá kopie nerozejde s deskami. +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from fleet import FLEET_BARE as FLEET + +# freq_hz, bandwidth_hz, sf, cr -- mirrored from platformio.ini / .local.ini so a +# capture cannot silently run on the wrong parameters. Two boards on different +# spreading factors simply cannot hear each other. +PRESETS = { + "cz": (869_432_000, 62_500, 7, 5), # live CZ mesh, [cz_radio] + "bench": (866_500_000, 62_500, 8, 5), # test band, [test_radio] + committed defaults + "prod": (869_618_000, 62_500, 8, 5), # committed platformio.ini default +} + +ROUTE_TYPES = {0: "TRANSPORT_FLOOD", 1: "FLOOD", 2: "DIRECT", 3: "TRANSPORT_DIRECT"} +PAYLOAD_TYPES = { + 0x00: "REQ", + 0x01: "RESPONSE", + 0x02: "TXT_MSG", + 0x03: "ACK", + 0x04: "ADVERT", + 0x05: "GRP_TXT", + 0x06: "GRP_DATA", + 0x07: "ANON_REQ", + 0x08: "PATH", + 0x09: "TRACE", + 0x0A: "MULTIPART", + 0x0B: "CONTROL", + 0x0F: "RAW_CUSTOM", +} +ADVERT_ROLES = {0x01: "chat", 0x02: "repeater", 0x03: "room", 0x04: "sensor"} + +LINKTYPE_USER0 = 147 # what openhop_core's own wireshark example uses + + +def resolve_port(board: str, port: str | None) -> str: + """Map a fleet number or serial number to a /dev/serial/by-id path.""" + if port: + return port + serial_no = FLEET.get(board, board) + matches = [p for p in glob.glob("/dev/serial/by-id/*") if serial_no in p] + if not matches: + sys.exit(f"zadny port pro sn {serial_no} -- pripojena deska? (ls /dev/serial/by-id/)") + if len(matches) > 1: + sys.exit(f"vic portu pro sn {serial_no}: {matches}") + return matches[0] + + +class SnifferRadio(USBLoRaRadio): + """USBLoRaRadio that hands RX frames straight to a callback, metadata included. + + See the module docstring: the stock rx_callback loses the RSSI/SNR pairing + under load, and it is scheduled onto an asyncio loop we do not want to run. + """ + + def __init__(self, *args, on_frame=None, **kwargs): + super().__init__(*args, **kwargs) + self._on_frame = on_frame + + def _dispatch_frame(self, cmd: int, payload: bytes): + if cmd == CMD_RX_PACKET and len(payload) >= 6: + # Keep the driver's own bookkeeping up to date -- get_status() is our + # honest denominator -- but do NOT delegate to super() here: with no + # rx_callback set it logs "RX packet but no callback registered" for + # every single frame, which is noise in a capture. + rssi, snr_x10, signal_rssi = struct.unpack(" tuple[int, bytes]: + """(channel hash, 32B secret) from a hex PSK, matching the firmware. + + The firmware hashes only the first 16 bytes when the second 16 are zero, so a + 128-bit key written out as 32 hex bytes still derives the right hash. + """ + secret = bytes.fromhex(psk_hex) + if len(secret) >= 32 and secret[16:32] == b"\x00" * 16: + hashed = secret[:16] + else: + hashed = secret[:32] + master = hashlib.sha256(hashed).digest() + secret32 = (secret + b"\x00" * 32)[:32] + return master[0], secret32 + + +def try_decrypt_channel(payload: bytes, keys: dict[int, list[bytes]]) -> dict | None: + """MeshCore group text: hash(1) | mac(2) | AES-128-ECB ciphertext.""" + if len(payload) < 4: + return None + chan_hash, mac, ciphertext = payload[0], payload[1:3], payload[3:] + for secret32 in keys.get(chan_hash, []): + if hmac.new(secret32, ciphertext, hashlib.sha256).digest()[:2] != mac: + continue # 1-byte hash collides; the HMAC is the real test + from Crypto.Cipher import AES # pycryptodome, pulled in by openhop-core + + padded = ciphertext + b"\x00" * (-len(ciphertext) % 16) + plain = AES.new(secret32[:16], AES.MODE_ECB).decrypt(padded)[: len(ciphertext)] + if len(plain) < 5: + return None + return { + "timestamp": int.from_bytes(plain[:4], "little"), + "flags": plain[4], + "text": plain[5:].decode("utf-8", errors="replace").rstrip("\x00"), + } + return None + + +def decode(data: bytes, keys: dict[int, list[bytes]]) -> dict: + """Parse one raw frame into a flat dict. Never raises.""" + out: dict = {"len": len(data), "raw": data.hex()} + pkt = Packet() + try: + pkt.read_from(data) + except Exception as exc: # truncated, bad version, bogus path_len + out["error"] = str(exc) + return out + + hash_size = pkt.get_path_hash_size() + hash_count = pkt.get_path_hash_count() + payload_type = pkt.get_payload_type() + path = bytes(pkt.path) + out.update( + { + "route": ROUTE_TYPES.get(pkt.get_route_type(), "?"), + "type": PAYLOAD_TYPES.get(payload_type, f"0x{payload_type:02X}"), + "ver": pkt.get_payload_ver(), + # Hash width is chosen by the SENDER and carried in bits 6-7 of + # path_len, so a 2B/3B-path-hash node decodes here without a rebuild. + "hash_size": hash_size, + "hops": hash_count, + "path": ":".join( + path[i : i + hash_size].hex() for i in range(0, hash_size * hash_count, hash_size) + ), + } + ) + if pkt.has_transport_codes(): + out["transport_codes"] = list(pkt.transport_codes) + + payload = bytes(pkt.payload) + name = out["type"] + try: + if name == "ADVERT": + adv = parse_advert_payload(payload) + app = decode_appdata(adv["appdata"]) if adv["appdata"] else {} + out["advert"] = { + "pubkey": adv["pubkey"], + "path_hash": adv["pubkey"][: hash_size * 2], + "timestamp": adv["timestamp"], + "name": app.get("node_name"), + "role": ADVERT_ROLES.get(app.get("flags", 0) & 0x0F), + "lat": app.get("latitude"), + "lon": app.get("longitude"), + } + elif name in ("GRP_TXT", "GRP_DATA"): + out["channel_hash"] = f"{payload[0]:02x}" + decrypted = try_decrypt_channel(payload, keys) + if decrypted: + out["channel_msg"] = decrypted + elif name == "ACK": + out["ack_crc"] = payload[:4].hex() + elif name in ("TXT_MSG", "RESPONSE", "REQ"): + # dest hash | src hash | mac | ciphertext, hashes as wide as the sender chose + out["dest"] = payload[:hash_size].hex() + out["src"] = payload[hash_size : hash_size * 2].hex() + elif name == "PATH": + out["dest"] = payload[:hash_size].hex() + elif name == "TRACE": + tag, auth, flags = struct.unpack(" str: + """One packet, one terminal line, most-identifying field last.""" + head = ( + f"{time.strftime('%H:%M:%S', time.localtime(rec['ts']))} " + f"{rec['rssi']:>4}dBm {rec['snr']:>5.1f}dB {rec['len']:>3}B " + f"{rec.get('route', '?'):<15} {rec.get('type', '?'):<9} " + f"{rec.get('hops', 0)}hop/{rec.get('hash_size', 0)}B" + ) + if rec.get("dup"): + head += f" dup#{rec['dup']}" + if "error" in rec: + return f"{head} UNPARSED: {rec['error']} {rec['raw'][:48]}" + tail = [] + if rec.get("path"): + tail.append(f"path={rec['path']}") + adv = rec.get("advert") + if adv: + tail.append(f"{adv.get('role') or 'node'} {adv.get('name') or '?'} [{adv['path_hash']}]") + if adv.get("lat"): + tail.append(f"{adv['lat']:.4f},{adv['lon']:.4f}") + if rec.get("channel_hash"): + tail.append(f"chan={rec['channel_hash']}") + if rec.get("channel_msg"): + tail.append(f"msg={rec['channel_msg']['text']!r}") + for key in ("dest", "src", "ack_crc"): + if rec.get(key): + tail.append(f"{key}={rec[key]}") + if rec.get("trace"): + tail.append(f"trace tag={rec['trace']['tag']}") + return f"{head} " + " ".join(tail) + + +def main() -> int: + ap = argparse.ArgumentParser(description=(__doc__ or "").split("\n")[0]) + ap.add_argument("--board", default="0", help="fleet number or serial number (default 0)") + ap.add_argument("--port", help="explicit /dev/serial/by-id path, overrides --board") + ap.add_argument("--preset", choices=sorted(PRESETS), default="cz") + ap.add_argument("--freq", type=float, help="MHz, overrides preset") + ap.add_argument("--bw", type=float, help="kHz, overrides preset") + ap.add_argument("--sf", type=int, help="overrides preset") + ap.add_argument("--cr", type=int, help="overrides preset") + ap.add_argument("--psk", action="append", default=[], help="channel PSK hex, repeatable") + ap.add_argument("--jsonl", help="append decoded packets here, one JSON per line") + ap.add_argument("--pcap", help="write raw frames as pcap (LINKTYPE_USER0)") + ap.add_argument("--wireshark", help="also stream pcap over UDP, host:port") + ap.add_argument("--seconds", type=float, help="stop after N seconds") + ap.add_argument("--status-interval", type=float, default=60.0, help="0 disables") + ap.add_argument("--quiet", action="store_true", help="no per-packet stdout") + args = ap.parse_args() + + freq, bw, sf, cr = PRESETS[args.preset] + if args.freq: + freq = int(args.freq * 1e6) + if args.bw: + bw = int(args.bw * 1000) + sf, cr = args.sf or sf, args.cr or cr + port = resolve_port(args.board, args.port) + + keys: dict[int, list[bytes]] = {} + for psk in args.psk: + chan_hash, secret32 = channel_keys(psk) + keys.setdefault(chan_hash, []).append(secret32) + + stats: Counter[str] = Counter() + seen: dict[str, int] = {} + lock = threading.Lock() + jsonl = open(args.jsonl, "a") if args.jsonl else None + pcap = PcapWriter(args.pcap, args.wireshark) + + def on_frame(data: bytes, rssi: int, snr: float, signal_rssi: int): + ts = time.time() + with lock: + stats["heard"] += 1 + rec = decode(data, keys) + rec.update({"ts": ts, "rssi": rssi, "snr": snr, "signal_rssi": signal_rssi}) + digest = hashlib.sha256(data).hexdigest()[:16] + seen[digest] = seen.get(digest, 0) + 1 + if seen[digest] > 1: + rec["dup"] = seen[digest] + stats["dup"] += 1 + stats["parsed" if "error" not in rec else "unparsed"] += 1 + stats[f"type:{rec.get('type', 'BAD')}"] += 1 + pcap.write(data, ts) + if jsonl: + jsonl.write(json.dumps(rec, default=str) + "\n") + jsonl.flush() + if not args.quiet: + print(format_line(rec), flush=True) + + print( + f"== port {os.path.basename(port)}\n" + f"== {freq / 1e6:.3f} MHz BW {bw / 1000:g} kHz SF{sf} CR{cr}" + f" ({args.preset}){' +' + str(len(args.psk)) + ' PSK' if args.psk else ''}", + flush=True, + ) + radio = SnifferRadio( + port=port, + frequency=freq, + bandwidth=bw, + spreading_factor=sf, + coding_rate=cr, + tx_power=2, # receive-only tool; keep the floor as a second safety net + lbt_enabled=False, + on_frame=on_frame, + ) + if not radio.begin(): + sys.exit(f"modem na {port} neodpovedel -- bezi na desce openHop modem firmware?") + print("== RX only, nic nevysilam. Ctrl-C ukonci a vypise souhrn.\n", flush=True) + + t0 = time.time() + next_status = t0 + args.status_interval if args.status_interval else None + try: + while True: + time.sleep(0.25) + now = time.time() + if args.seconds and now - t0 >= args.seconds: + break + if next_status and now >= next_status: + next_status = now + args.status_interval + # The modem's own counter is the honest denominator: it counted a + # CRC-clean frame even when nothing here could parse it. + modem = radio.get_status() + with lock: + print( + f"-- {now - t0:6.0f}s modem rx={modem.get('rx_count')} " + f"crc_err={modem.get('crc_errors')} heard={stats['heard']} " + f"parsed={stats['parsed']} unparsed={stats['unparsed']} " + f"dup={stats['dup']}", + flush=True, + ) + except KeyboardInterrupt: + pass + finally: + radio.cleanup() + pcap.close() + if jsonl: + jsonl.close() + + elapsed = time.time() - t0 + print(f"\n== {elapsed:.0f}s, {stats['heard']} frames heard, {stats['dup']} duplicates") + print(f"== parsed {stats['parsed']}, unparsed {stats['unparsed']}") + for key, count in sorted(stats.items()): + if key.startswith("type:"): + print(f" {key[5:]:<10} {count}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/power_ab.py b/tools/power_ab.py new file mode 100755 index 00000000..8cf0ee0e --- /dev/null +++ b/tools/power_ab.py @@ -0,0 +1,461 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""A/B current measurement on a bench node, via the UC96 meter's own exporter. + + tools/power_ab.py --serial 0123456789ABCDEF --minutes 30 \ + --cell "baseline=" --cell "ps=powersaving on" --cell "duty=gps duty" + +Why the exporter and not the meter: `uc96-exporter.service` owns the BLE link to +the UC96. A second central connecting to it takes the link away and the service +reconnect-loops, so this reads http://localhost:9877/metrics instead. Same data, +no contention. (It also lands in Mimir via alloy, so a run stays inspectable +afterwards -- but the exporter is scraped live, which is tighter for timing.) + +**The instantaneous current field is useless here.** The UC96 reports current in +10 mA steps (`meter_current_amps` 0.02 for a node drawing anywhere from 15 to +24 mA), and the deltas worth chasing on a repeater are 1-4 mA. The accumulating +`meter_capacity_ah` counter has 1 mAh resolution, so this integrates that over a +window instead: avg mA = 60 * delta_mAh / minutes. The +-1 mAh quantisation is +printed with every cell as an explicit error bar -- at 20 minutes that is ++-3 mA, which would swallow the whole effect, so short windows are a trap and +the tool says so rather than letting you read noise as a result. + +Two estimators are reported per cell, because the endpoint one alone wastes the +window: `fit` is a least-squares slope through the whole sampled staircase, and +it beats the endpoint difference by using WHEN each 1 mAh step landed instead of +only how many landed. Its residual spread is printed too -- a cell that drifted +(traffic burst, charging, a hand near the antenna) shows up there rather than +quietly biasing the number. When the two estimators disagree by more than the +error bar, do not average them: the cell was not stationary, so re-run it. + +Airtime counters are recorded per cell as CONTEXT, not as the claim: a cell that +happened to relay a flood burns more than an idle one, and without that column a +polluted cell looks like a real regression. +""" + +import argparse +import glob +import json +import re +import sys +import time +import urllib.request + +import serial + +EXPORTER = "http://localhost:9877/metrics" +SETTLE_DEFAULT = 60 + + +def meter_sample(url, meter=None): + """One reading of the exporter: (capacity_mAh, volts, amps, unix_ts).""" + with urllib.request.urlopen(url, timeout=10) as r: + body = r.read().decode() + out = {} + for name in ("meter_capacity_ah", "meter_voltage_volts", "meter_current_amps", + "meter_last_seen_timestamp_seconds", "meter_up"): + for line in body.splitlines(): + if not line.startswith(name + "{"): + continue + if meter and f'meter="{meter}"' not in line: + continue + out[name] = float(line.rsplit(" ", 1)[1]) + break + missing = [k for k in ("meter_capacity_ah", "meter_up") if k not in out] + if missing: + raise SystemExit(f"exporter neposkytl {missing} (jiny meter? --meter )") + if out["meter_up"] != 1.0: + raise SystemExit("meter_up=0 -- exporter nema spojeni s meraakem, meritko by lhalo") + # Frames must be arriving, not just the link be up: a stale series is a + # straight line, and a straight line reads like a perfectly stable load. + age = time.time() - out.get("meter_last_seen_timestamp_seconds", 0.0) + if age > 30: + raise SystemExit(f"posledni ramec pred {age:.0f} s -- serie je zamrzla, ne stabilni") + return (out["meter_capacity_ah"] * 1000.0, out.get("meter_voltage_volts", 0.0), + out.get("meter_current_amps", 0.0), out.get("meter_last_seen_timestamp_seconds", 0.0)) + + +def fit_slope_ma(series): + """Least-squares mA through (seconds, mAh) samples: (mA, residual, std err). + + The counter is a 1 mAh staircase, so the slope carries the timing of every + step, not just the count at the ends. Residuals are returned in mAh: on a + stationary cell they stay under ~0.6 (half a step); much more than that means + the load moved during the window and the average is hiding something. + + CAVEAT on the standard error: it assumes independent residuals, and a + quantised staircase violates that (consecutive samples sit on the same step), + so it reads optimistic. It is still the right order of magnitude, and it is + the honest one to compare deltas against -- unlike the endpoint quantisation, + which the fit is specifically there to beat. Run one cell twice to get the + empirical repeatability; that number outranks this estimate. + """ + n = len(series) + if n < 4: + return None, None, None + tx = sum(t for t, _ in series) / n + ty = sum(c for _, c in series) / n + sxx = sum((t - tx) ** 2 for t, _ in series) + if sxx == 0: + return None, None, None + sxy = sum((t - tx) * (c - ty) for t, c in series) + slope = sxy / sxx # mAh per second + sse = sum((c - (ty + slope * (t - tx))) ** 2 for t, c in series) + resid = (sse / n) ** 0.5 + se = ((sse / (n - 2)) / sxx) ** 0.5 # mAh/s + return slope * 3600.0, resid, se * 3600.0 + + +class Console: + """Text console of a repeater/analyzer build over USB CDC. + + dtr/rts + the settle delay are not optional: nRF52 TinyUSB keeps the CDC + mute until DTR is asserted, and a board opened without it looks dead. + """ + + LOST = "" + + def __init__(self, port_glob): + self.port_glob = port_glob + self.s = None + self._open() + + def _open(self): + path = glob.glob(self.port_glob) + if not path: + raise SystemExit(f"port {self.port_glob} nenalezen") + self.s = serial.Serial(path[0], 115200, timeout=0) + self.s.dtr = True + self.s.rts = True + time.sleep(1.3) + self.s.reset_input_buffer() + + def reopen(self, wait=90.0): + """Wait for the board to come back on USB and re-open it. + + These boards drop off USB on their own (documented flakiness) and return + seconds to minutes later. Losing the console mid-run must not force a + rerun of an hour-long matrix. + """ + try: + if self.s: + self.s.close() + except Exception: + pass + self.s = None + t0 = time.time() + while time.time() - t0 < wait: + if glob.glob(self.port_glob): + try: + self._open() + return True + except (OSError, serial.SerialException, SystemExit): + pass + time.sleep(3) + return False + + def cmd(self, c, timeout=4.0, quiet=0.3): + """Send a command. On a console drop, re-open once and retry. + + Returns LOST if the console could not be recovered. Callers that are + APPLYING a cell setting must treat that as a failed cell — measuring a + treatment that was never applied is worse than no measurement, and it + happened: `gps off` was lost on the wire, the run carried on, and two + cells silently measured `gps on` again. + """ + try: + return self._cmd(c, timeout, quiet) + except (OSError, serial.SerialException): + pass + if self.reopen(): + try: + return self._cmd(c, timeout, quiet) + except (OSError, serial.SerialException): + pass + return self.LOST + + def _cmd(self, c, timeout, quiet): + if self.s is None: + raise serial.SerialException("console not open") + self.s.write((c + "\r").encode()) + buf, last, t0 = b"", time.time(), time.time() + while time.time() - t0 < timeout: + d = self.s.read(256) + if d: + buf += d + last = time.time() + elif buf and time.time() - last > quiet: + break + else: + time.sleep(0.02) + txt = buf.decode(errors="replace") + # echo of the command comes back first; keep the answer only + lines = [ln.strip() for ln in txt.replace("\r", "\n").split("\n") if ln.strip()] + lines = [ln for ln in lines if ln != c] + return " | ".join(ln.lstrip("> ").strip() for ln in lines) + + def air(self): + m = re.search(r'"tx_air_secs":(\d+).*?"rx_air_secs":(\d+)', self.cmd("stats-radio")) + return (int(m.group(1)), int(m.group(2))) if m else (None, None) + + def close(self): + try: + if self.s: + self.s.close() + except Exception: + pass + + +# What a cell's setting command must end up reporting, so "applied" is verified +# on the node rather than assumed from a write that returned no error. Key is the +# command prefix, value is (query, expected substring in the answer). +VERIFY = { + "gps off": ("gps", "off"), + "gps on": ("gps", "on,"), + "gps duty": ("gps", "duty"), + "powersaving on": ("powersaving", "on"), + "powersaving off": ("powersaving", "off"), + "ble on": ("ble", "on"), + "ble off": ("ble", "off"), +} + +# Queried at the start of every cell: the record of what the node actually was, +# and the raw material for VERIFY above. +STATE_QUERIES = ("powersaving", "gps", "ble", "get repeat") + + +def port_glob_for(serial_no): + g = glob.glob(f"/dev/serial/by-id/*{serial_no}*") + if not g: + raise SystemExit(f"port pro seriak {serial_no} nenalezen v /dev/serial/by-id/") + return f"/dev/serial/by-id/*{serial_no}*" + + +def main(): + ap = argparse.ArgumentParser(description="A/B mereni proudu pres UC96 exporter") + ap.add_argument("--serial", help="seriove cislo desky (matchuje se v /dev/serial/by-id/)") + ap.add_argument("--port", help="misto --serial: pevna cesta k portu") + ap.add_argument("--cell", action="append", default=[], metavar="NAME=CMD[;CMD]", + help="jedna bunka: jmeno a prikazy, ktere ji nastavi (prazdne = jen mer)") + ap.add_argument("--minutes", type=float, default=30.0, help="delka okna bunky (vychozi 30)") + ap.add_argument("--settle", type=float, default=SETTLE_DEFAULT, + help="prodleva po aplikaci prikazu pred zacatkem okna (s, vychozi 60)") + ap.add_argument("--poll", type=float, default=10.0, + help="jak casto vzorkovat citac kapacity v okne (s, vychozi 10)") + ap.add_argument("--meter", help="MAC merace bez dvojtecek, kdyz exporter vidi vic meraku") + ap.add_argument("--url", default=EXPORTER) + ap.add_argument("--json", help="ulozit vysledek jako JSON") + args = ap.parse_args() + + if not args.cell: + raise SystemExit("aspon jedna --cell") + + err_ma = 60.0 / args.minutes # +-1 mAh quantisation over the window + print(f"okno {args.minutes:g} min => kvantizace merice je +-{err_ma:.2f} mA na bunku") + if err_ma > 1.5: + print(" POZOR: to je vic, nez kolik ceka vetsina uspor. Delsi --minutes, nebo " + "cti vysledek jako 'nezmereno'.") + + con = None + if args.serial or args.port: + con = Console(args.port or port_glob_for(args.serial)) + print(f"deska: {con.cmd('ver')} / {con.cmd('get name')}") + + results = [] + try: + for spec in args.cell: + name, _, cmds = spec.partition("=") + name = name.strip() or "cell" + cmds = [c.strip() for c in cmds.split(";") if c.strip()] + print(f"\n=== bunka {name}") + + applied = True + for c in cmds: + if not con: + raise SystemExit("bunka ma prikazy, ale neni zadana deska (--serial)") + reply = con.cmd(c) + print(f" {c} -> {reply}") + if reply == Console.LOST or "Unknown command" in reply or "rror" in reply: + applied = False + if cmds: + print(f" usazovani {args.settle:g} s") + time.sleep(args.settle) + + state = {} + tx0 = rx0 = None + if con: + for q in STATE_QUERIES: + state[q] = con.cmd(q) + tx0, rx0 = con.air() + + # Verify on the node that the setting took, then refuse to measure a + # treatment that is not actually in place. The alternative -- what + # this tool did before -- is a plausible-looking number for a state + # the node was never in. + for c in cmds: + for prefix, (query, expect) in VERIFY.items(): + if c.startswith(prefix): + answer = state.get(query, "") + if expect not in answer: + print(f" NEOVERENO: po '{c}' hlasi '{query}' -> " + f"'{answer}' (cekano '{expect}')") + applied = False + if not applied: + print(" CHYBA: zasah se neaplikoval/neoveril -- bunka se NEMERI " + "(merit neaplikovany zasah je horsi nez nemerit)") + results.append({"cell": name, "cmds": cmds, "avg_ma": None, "fit_ma": None, + "resid_mah": None, "se_ma": None, "delta_mah": None, + "minutes": 0.0, "err_ma": err_ma, "volts": None, + "state": state, "tx_air_delta": None, "rx_air_delta": None, + "samples": 0, "invalid": "neaplikovano"}) + continue + cap0, v0, _, _ = meter_sample(args.url, args.meter) + t0 = time.time() + print(f" start: cap={cap0:.0f} mAh, U={v0:.2f} V, stav={state}") + + series = [(0.0, cap0)] + deadline = t0 + args.minutes * 60 + # Heartbeat once a minute. Without it a healthy cell and a hung + # process look identical for ten minutes at a stretch -- which is + # exactly how a good run got killed two minutes before it finished. + next_beat = t0 + 60 + while time.time() < deadline: + time.sleep(min(args.poll, max(0.0, deadline - time.time()))) + cap, v1, i1, _ = meter_sample(args.url, args.meter) + now = time.time() + series.append((now - t0, cap)) + if now >= next_beat: + next_beat += 60 + el = (now - t0) / 60.0 + print(f" ... {el:.0f}/{args.minutes:g} min, +{cap-cap0:.0f} mAh, " + f"zatim {(cap-cap0)/((now-t0)/3600.0):.1f} mA", flush=True) + + cap1, v1, i1, _ = meter_sample(args.url, args.meter) + series.append((time.time() - t0, cap1)) + dt_h = (time.time() - t0) / 3600.0 + tx1, rx1 = con.air() if con else (None, None) + dcap = cap1 - cap0 + fit_ma = resid = se_ma = None + if dcap < 0: + print(" CHYBA: citac kapacity klesl (reset merice) -- bunka je neplatna") + avg = None + elif dcap == 0: + # An instrument reporting a perfectly flat counter is not + # measuring a small load, it is not measuring. Reporting + # "0.00 +-0.00 mA" as a result once sent a whole session chasing + # the wrong thing: the same board read 22 mA on another meter + # while this one sat at zero for 15 minutes. Refuse the cell. + print(f" CHYBA: citac kapacity se za {dt_h*60:.0f} min NEHNUL " + f"(instant {i1*1000:.0f} mA). Merak tuhle zatez nemeri -- " + f"nula NENI vysledek. Zkus jiny merak nebo vetsi zatez.") + avg = None + else: + avg = dcap / dt_h + fit_ma, resid, se_ma = fit_slope_ma(series) + print(f" konec: cap={cap1:.0f} mAh, delta={dcap:.0f} mAh za {dt_h*60:.1f} min, " + f"{len(series)} vzorku") + print(f" ==> endpoint {avg:.2f} +-{err_ma:.2f} mA | fit {fit_ma:.2f} " + f"+-{se_ma:.2f} mA (rezidua {resid:.2f} mAh) @ {v1:.2f} V " + f"(instant {i1*1000:.0f} mA, 10mA krok)") + if abs(fit_ma - avg) > err_ma: + print(" POZOR: estimatory se rozchazi vic nez chyba -- bunka nebyla " + "stacionarni, zopakuj ji") + # stats-radio can fail to parse on either end (busy console); keep the + # cell valid and just report the airtime column as unknown. + d_tx = tx1 - tx0 if (tx0 is not None and tx1 is not None) else None + d_rx = rx1 - rx0 if (rx0 is not None and rx1 is not None) else None + if d_tx is not None: + print(f" airtime v okne: tx +{d_tx} s, rx +{d_rx} s") + results.append({"cell": name, "cmds": cmds, "avg_ma": avg, "fit_ma": fit_ma, + "resid_mah": resid, "se_ma": se_ma, "delta_mah": dcap, + "minutes": dt_h * 60, "err_ma": err_ma, "volts": v1, + "state": state, "tx_air_delta": d_tx, "rx_air_delta": d_rx, + "samples": len(series)}) + finally: + if con: + con.close() + + summarize(results) + + if args.json: + with open(args.json, "w") as f: + json.dump(results, f, indent=2) + print(f"\nJSON -> {args.json}") + return 0 + + +def summarize(results): + """Print the summary. Separate from main() so a finished run's JSON can be + re-analysed (and the analysis tested) without touching hardware.""" + print("\n===== SOUHRN ===== (fit je presnejsi estimator, endpoint v zavorce)") + valid = [r for r in results if r["fit_ma"] is not None] + base = valid[0] if valid else None + + # Spread across repeats of the same cell is repeatability ONLY if the rig is + # stationary. It is not, when something drifts underneath (a charging cell + # tapering: `gps on` cells went 107 -> 92 -> 88 -> 84 mA across one hour). + # Using that spread as a noise floor then buries the very effect being + # measured -- it flagged a real 46 mA GPS delta as "v sumu". + floor = None + groups = {} + for r in valid: + groups.setdefault(tuple(r["cmds"]), []).append(r["fit_ma"]) + for cmds, vals in groups.items(): + if len(vals) > 1: + spread = max(vals) - min(vals) + trend = abs(vals[-1] - vals[0]) + drifting = trend > 0.6 * spread # monotone-ish: most of the spread is trend + label = "drift, NE sum" if drifting else "opakovatelnost" + print(f" {label} ({'+'.join(cmds) or 'bez prikazu'}): rozptyl {spread:.2f} mA " + f"pres {len(vals)} bunky (kraje se lisi o {trend:.2f})") + if not drifting: + floor = spread if floor is None else max(floor, spread) + + # Alternating designs (A B A B ...) are the answer to a drifting rig, so + # analyse them as such: each B against the MEAN OF ITS TWO NEIGHBOURING A + # cells, which cancels a linear trend. This is the number to quote. + sigs = [tuple(r["cmds"]) for r in valid] + distinct = list(dict.fromkeys(sigs)) + if len(distinct) == 2 and len(valid) >= 3: + a_sig, b_sig = distinct + deltas = [] + for i, r in enumerate(valid): + if tuple(r["cmds"]) != b_sig: + continue + before = next((v["fit_ma"] for v in reversed(valid[:i]) + if tuple(v["cmds"]) == a_sig), None) + after = next((v["fit_ma"] for v in valid[i + 1:] + if tuple(v["cmds"]) == a_sig), None) + flank = [x for x in (before, after) if x is not None] + if flank: + deltas.append(sum(flank) / len(flank) - r["fit_ma"]) + if deltas: + mean = sum(deltas) / len(deltas) + print(f"\n PAROVY ODHAD ({'+'.join(a_sig) or 'bez prikazu'} minus " + f"{'+'.join(b_sig) or 'bez prikazu'}): {mean:.2f} mA " + f"(z {len(deltas)} paru, rozptyl {min(deltas):.2f}-{max(deltas):.2f}) " + f"-- drift vykracen, tohle je cislo k citovani") + + for r in valid: + d = "" + if base and r is not base: + diff = r["fit_ma"] - base["fit_ma"] + # Significance against the measured repeatability when we have it, + # otherwise against twice the fit's own standard error. + lim = floor if floor is not None else 2 * (r["se_ma"] or 0) + sig = "" if abs(diff) > lim else " (v sumu!)" + d = f" delta vs {base['cell']}: {diff:+.2f} mA{sig}" + print(f" {r['cell']:12s} {r['fit_ma']:6.2f} +-{r['se_ma']:.2f} mA " + f"(endpoint {r['avg_ma']:.2f} +-{r['err_ma']:.2f}){d}") + for r in results: + if r["fit_ma"] is None: + print(f" {r['cell']:12s} neplatna ({r.get('invalid', 'merak nemeril')})") + + +if __name__ == "__main__": + # Re-analyse a finished run: power_ab.py --reanalyse run.json + if len(sys.argv) == 3 and sys.argv[1] == "--reanalyse": + with open(sys.argv[2]) as f: + summarize(json.load(f)) + sys.exit(0) + sys.exit(main()) diff --git a/tools/preset_trace.py b/tools/preset_trace.py new file mode 100644 index 00000000..7c77f0b3 --- /dev/null +++ b/tools/preset_trace.py @@ -0,0 +1,85 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""TRACE po pevné cestě na zvoleném presetu přes USB companion — měření přímého hopu. + +Companion přepne rádio na preset, pošle N× TRACE po cestě (2B hashe) a vypíše +SNR, které na trase připsal každý hop, a SNR, se kterým odpověď slyšel on sám. +Slouží k měření spoje mezi dvěma repeatery, které jsou mezitím přes `tempradio` +na stejném presetu (sám je nepřelaďuje). + + preset_trace.py /dev/serial/by-id/... 869.525 62.5 12 8 --path 025c,5f14,025c -n 8 + preset_trace.py /dev/serial/by-id/... 866.5 62.5 8 5 --tx 2 --restore # zpět, bez TRACE + +Nastavení rádia companion ukládá do prefs — po měření ho vrať (--restore). +Výstup: jedna JSON řádka na pokus (ok/timeout, hopy se SNR, rtt). +""" +import argparse +import asyncio +import json +import random +import time + + +def parse(): + ap = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("port", help="sériový port companionu (/dev/serial/by-id/...)") + ap.add_argument("freq", type=float, help="MHz") + ap.add_argument("bw", type=float, help="kHz") + ap.add_argument("sf", type=int) + ap.add_argument("cr", type=int, help="5..8 (4/5..4/8)") + ap.add_argument("--tx", type=int, default=22, help="TX výkon dBm (default 22)") + ap.add_argument("--path", default="025c,5f14,025c", help="hopy TRACE, 2B hex, čárkou") + ap.add_argument("-n", type=int, default=8, help="počet TRACE (default 8)") + ap.add_argument("--gap", type=float, default=3.0, help="pauza mezi pokusy, s") + ap.add_argument("--timeout", type=float, default=0, + help="čekání na odpověď, s (0 = odhad firmwaru + 50 %%)") + ap.add_argument("--restore", action="store_true", help="jen nastavit rádio, žádný TRACE") + return ap.parse_args() + + +async def main(a): + from meshcore import EventType, MeshCore + + mc = await MeshCore.create_serial(a.port, 115200) + if mc is None: + raise SystemExit("companion neodpovídá") + r = await mc.commands.set_radio(a.freq, a.bw, a.sf, a.cr) + if r.type == EventType.ERROR: + raise SystemExit("set_radio: %s" % r.payload) + r = await mc.commands.set_tx_power(a.tx) + if r.type == EventType.ERROR: # build caps TX (MAX_LORA_TX_POWER): keep its current power + print(json.dumps({"warn": "set_tx_power %d refused" % a.tx}), flush=True) + await mc.commands.send_appstart() + si = mc.self_info + print(json.dumps({"radio": [si.get("radio_freq"), si.get("radio_bw"), si.get("radio_sf"), + si.get("radio_cr")], "tx": si.get("tx_power")}), flush=True) + if a.restore: + await mc.disconnect() + return + + for i in range(a.n): + tag = random.randint(1, 0xFFFFFFFF) + t0 = time.monotonic() + sent = await mc.commands.send_trace(auth_code=0, tag=tag, flags=1, path=a.path) + if sent.type == EventType.ERROR: + print(json.dumps({"i": i, "error": str(sent.payload)}), flush=True) + await asyncio.sleep(a.gap) + continue + est = (sent.payload or {}).get("suggested_timeout", 0) / 1000 + wait = a.timeout or max(10.0, est * 1.5) + ev = await mc.wait_for_event(EventType.TRACE_DATA, attribute_filters={"tag": tag}, + timeout=wait) + rec = {"i": i, "t": time.strftime("%H:%M:%S"), "wait": round(wait, 1)} + if ev is None: + rec["ok"] = False + else: + rec.update(ok=True, rtt=round(time.monotonic() - t0, 1), + hops=[[h.get("hash", "me"), h["snr"]] for h in ev.payload.get("path", [])]) + print(json.dumps(rec), flush=True) + await asyncio.sleep(a.gap) + await mc.disconnect() + + +if __name__ == "__main__": + asyncio.run(main(parse())) diff --git a/tools/radio_stall_watch.py b/tools/radio_stall_watch.py new file mode 100755 index 00000000..d7f10b1a --- /dev/null +++ b/tools/radio_stall_watch.py @@ -0,0 +1,129 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Watch a RADIO_DIAG node on its USB console until its receiver goes deaf. + +usage: radio_stall_watch.py [--stall-min N] [--log FILE] + +Born 31. 10. 2026: bench-sensor stopped receiving (recv frozen, noise_floor +-120, last_rssi 0) and a reboot revived it. A reboot fixes nothing, it only +destroys the evidence -- so this sits on the console and waits for the next one: + + * every line the node prints (MESH_DEBUG) goes to the log with a UTC stamp + * every 60 s: `radiostat` + `stats-packets` + * no packet read for --stall-min minutes (default 15; the live CZ mesh + normally delivers a flood every 30-60 s) = STALL: + - three `radiostat` snapshots, 10 s apart (is anything still moving?) + - then the recovery ladder, gentlest first, one step at a time: + clrirq -> rx -> standby -> agc. After each step it waits 3 min for a + packet; the FIRST step that brings recv back names the broken layer + (lost DIO1 edge / RX not re-armed / chip out of RX / AGC-analog). + - if nothing helps, it says so and leaves the node deaf for a human. + It does not reboot the node, ever. + +Needs firmware built with -D RADIO_DIAG (radiostat/radiokick). Holds the port +open for as long as it runs, so the node's BLE (dock-quiet) and other console +users are off meanwhile. Nothing is transmitted. +""" + +import re +import sys +import time + +if {"-h", "--help"} & set(sys.argv[1:]): + print(__doc__.strip()) + sys.exit(0) + +import serial # noqa: E402 + +LADDER = ["clrirq", "rx", "standby", "agc"] +RX_RE = re.compile(r"\brx=(\d+)/(\d+)s") + + +def utc(): + return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()) + + +class Node: + def __init__(self, port, log): + self.s = serial.Serial(port, 115200, timeout=0.2) + self.log = log + self.buf = b"" + + def write_log(self, line): + self.log.write(f"{utc()} {line}\n") + self.log.flush() + + def pump(self, secs): + """Log everything the node prints for `secs`; return the lines.""" + out, end = [], time.time() + secs + while time.time() < end: + self.buf += self.s.read(4096) + while b"\n" in self.buf: + raw, self.buf = self.buf.split(b"\n", 1) + line = raw.decode(errors="replace").rstrip("\r") + if line: + self.write_log(line) + out.append(line) + return out + + def cmd(self, c): + self.write_log(f">>> {c}") + self.s.write((c + "\r").encode()) + for line in self.pump(1.0): + if line.startswith(c) and "->" in line: + return line.split("->", 1)[1].strip() + return "" + + def rx_age(self): + m = RX_RE.search(self.cmd("radiostat")) + return (int(m.group(1)), int(m.group(2))) if m else (None, None) + + +def main(port, stall_s, logpath): + with open(logpath, "a") as log: + n = Node(port, log) + n.write_log(f"=== watch start, stall after {stall_s} s, port {port}") + n.cmd("ver") + while True: + n.pump(59) + n.cmd("stats-packets") + rx, age = n.rx_age() + if age is None or age < stall_s: + continue + n.write_log(f"!!! STALL: no packet read for {age} s (rx={rx})") + for _ in range(3): + n.cmd("radiostat") + n.pump(10) + for step in LADDER: + n.cmd(f"radiokick {step}") + end = time.time() + 180 + while time.time() < end: + n.pump(30) + rx2, _ = n.rx_age() + if rx2 is not None and rx2 > rx: + n.write_log(f"!!! RECOVERED by '{step}' (rx {rx} -> {rx2})") + break + else: + n.write_log(f"... '{step}' did not bring RX back") + continue + break + else: + n.write_log("!!! NOTHING on the ladder revived RX -- left deaf for inspection") + n.pump(10**9) + + +stall_min, logfile = 15, "radio_stall_watch.log" +it = iter(sys.argv[1:]) +args = [] +for a in it: + if a == "--stall-min": + stall_min = int(next(it)) + elif a == "--log": + logfile = next(it) + elif a.startswith("--"): + sys.exit(__doc__.strip().splitlines()[2]) + else: + args.append(a) +if len(args) != 1: + sys.exit(__doc__.strip().splitlines()[2]) +main(args[0], stall_min * 60, logfile) diff --git a/tools/serial_cli.py b/tools/serial_cli.py new file mode 100755 index 00000000..c60a4ebf --- /dev/null +++ b/tools/serial_cli.py @@ -0,0 +1,116 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Textova konzole uzlu na USB -- posli prikazy, vypis odpovedi. + + tools/serial_cli.py x4 ver + tools/serial_cli.py x4 "get freq" "get name" "get batt.icon" + tools/serial_cli.py /dev/serial/by-id/usb-Seeed_Studio_XIAO_... ver + tools/serial_cli.py --list + +USB protejsek `ble_cli.py`. Vzniklo 21. 9. 2026: `board_probe.py` umi jen +otisk (posle `ver` a skonci), `fleet_test.py` konzoli pouziva, ale jen na svuj +scenar -- a na kazdy dotaz typu "co ma ta deska ve `get freq`" se pokazde psal +jednorazovy skript znovu. + +Parametry portu jsou prevzate z `board_probe.py::_open()` vcetne dvou veci, +ktere vypadaji jako zbytecnost a nejsou: + + * DTR+RTS nahoru a 0,9 s cekani -- bez toho deska jeste neni pripravena + a prvni prikaz spolkne. + * prazdne CRLF pred prvnim prikazem -- prvni radek po otevreni portu se + casto ztrati uplne. + +PAST (z hlavicky fleet_test.py): nenechavej pripojeneho BLE klienta na desce, +se kterou tady mluvis. USB a BLE konzole sdileji jeden buffer command[160] +(simple_repeater/main.cpp), takze dve zive konzole si michaji znaky do jedne +radky a uzel pak vykona nesmysl. + +Companion buildy textovou konzoli NEMAJI a na vsechno tady odpovi tichem -- +neni to zaseklá deska. Co na ktere desce bezi rekne `board_probe.py --all`. +""" +import argparse +import glob +import os +import sys +import time + +# FLEET ani otevírání portu se tu NEDUPLIKUJE -- viz fleet.py (tabulka) a +# board_probe.py::_open (sekvence dtr/rts + settle + prime, kterou by druhá +# kopie dřív nebo později rozešla). AGENTS.md: "nevymýšlej kolo". +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from board_probe import _open as open_port +from fleet import FLEET, serial_for +from mctools_config import field, unknown_alias_hint + + +def ports(): + return sorted(glob.glob("/dev/serial/by-id/*")) + + +def resolve(target): + """Jmeno z flotily, holé seriove cislo, nebo rovnou cesta k portu.""" + if target.startswith("/"): + return target + sn = serial_for(target) + why = field(sn, "refuse") + if why: + sys.exit(f"{target}: odmitnuto -- {why}") + hits = [p for p in ports() if sn in p] + if not hits: + hint = f"; {unknown_alias_hint(target)}" if sn == target else "" + sys.exit(f"port pro {target!r} (sn {sn}) nenalezen -- viz --list{hint}") + if len(hits) > 1: + sys.exit(f"{target!r} odpovida vic portum: {hits}") + return hits[0] + + +def drain(s, window): + buf, t = b"", time.time() + while time.time() - t < window: + d = s.read(8192) + if d: + buf += d + else: + time.sleep(0.02) + return buf + + +def main(): + ap = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("board", nargs="?", help="jmeno desky z configu (tools/mctools_config.py), seriove cislo, nebo cesta k portu") + ap.add_argument("cmd", nargs="*", help="prikazy konzole") + ap.add_argument("--list", action="store_true", help="vypis porty a konci") + ap.add_argument("--wait", type=float, default=1.5, + help="kolik sekund cekat na odpoved (default 1.5; `nodes` a " + "`rxlog` na plnem uzlu chtou vic)") + ap.add_argument("--raw", action="store_true", help="bez hlavicek, jen odpovedi") + args = ap.parse_args() + + if args.list: + for p in ports(): + tag = next((n for n, sn in FLEET.items() if sn in p), "") + print(f"{tag:4} {p}") + return + if not args.board or not args.cmd: + ap.error("chybi deska nebo prikaz (viz --list)") + + port = resolve(args.board) + s = open_port(port) # dtr/rts + 0,9 s settle + reset_input_buffer + try: + s.write(b"\r\n") + time.sleep(0.4) + s.reset_input_buffer() + + for c in args.cmd: + s.write(c.encode() + b"\r\n") + out = drain(s, args.wait).decode(errors="replace").strip() + if args.raw: + print(out) + else: + print(f"[{args.board}] {c}\n{out}\n") + finally: + s.close() + + +main() diff --git a/tools/serial_tcp_proxy.py b/tools/serial_tcp_proxy.py new file mode 100755 index 00000000..69690515 --- /dev/null +++ b/tools/serial_tcp_proxy.py @@ -0,0 +1,86 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +"""Bridge a bench XIAO's USB console to a localhost TCP port. + + tools/serial_tcp_proxy.py + +Holds the console open with DTR/RTS up (as fleet_test.py does) and serves it +on 127.0.0.1:, one client at a time, so a board on another host +joins a test run here through an SSH tunnel: + + ssh -L 7001:127.0.0.1:7001 lab-pc \\ + 'python3 MeshCore/tools/serial_tcp_proxy.py b1 7001' + tools/fleet_test.py --boards 4 --remote 1=socket://127.0.0.1:7001 + +Localhost only. Matches the board by its USB serial number, never ttyACM*; +a board name/alias is looked up in the local config (tools/mctools_config.py) +of the host it runs on. Refuses a board whose config entry sets `refuse` +(e.g. the radio of an observer, which runs other firmware). +""" + +import glob +import socket +import sys +import threading + +from mctools_config import field, serial_for + + +def serve(ser, srv: socket.socket) -> None: + while True: + conn, _ = srv.accept() + conn.settimeout(0.05) + alive = [True] + + def to_client() -> None: + while alive[0]: + try: + data = ser.read(4096) + if data: + conn.sendall(data) + except OSError: + alive[0] = False + + t = threading.Thread(target=to_client, daemon=True) + t.start() + while alive[0]: + try: + data = conn.recv(4096) + if not data: + break + ser.write(data) + except socket.timeout: + continue + except OSError: + break + alive[0] = False + t.join(1) + conn.close() + + +def main() -> None: + if len(sys.argv) != 3 or sys.argv[1] in ("-h", "--help"): + print(__doc__) + sys.exit(0) + sn, tport = serial_for(sys.argv[1]), int(sys.argv[2]) + why = field(sn, "refuse") + if why: + sys.exit(f"refused: {why}") + ports = [p for p in glob.glob("/dev/serial/by-id/*Seeed_Studio_XIAO*") if sn in p] + if not ports: + sys.exit(f"{sn}: no MeshCore XIAO port") + import serial # after --help: the help works without pyserial + + ser = serial.Serial(ports[0], 115200, timeout=0.05) + ser.dtr = True + ser.rts = True + srv = socket.socket() + srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + srv.bind(("127.0.0.1", tport)) + srv.listen(1) + print(f"{ports[0]} <-> 127.0.0.1:{tport}", flush=True) + serve(ser, srv) + + +if __name__ == "__main__": + main() diff --git a/tools/xiao_serial_dfu.sh b/tools/xiao_serial_dfu.sh new file mode 100755 index 00000000..3d526646 --- /dev/null +++ b/tools/xiao_serial_dfu.sh @@ -0,0 +1,75 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MIT +# Flash a XIAO nRF52840 with a text console (repeater, room server, sensor) +# over USB serial DFU -- no UF2 drive, no mount, no root, no 1200-baud touch. +# +# tools/xiao_serial_dfu.sh +# +# firmware.zip the DFU package (.pio/build//firmware.zip, or a release +# asset *.zip) +# usb-serial the board's USB serial number (matched in /dev/serial/by-id) +# board its name for serial_cli.py (local config, tools/mctools_config.py) +# +# NRF= directory holding tool-adafruit-nrfutil +# (default ~/.platformio/packages) +# PY= interpreter (default python3) +# CLI= serial_cli.py (default: next to this script) +# +# Sends `dfu serial` on the console, waits for the bootloader port +# (XIAO_nRF52840_Sense_) and runs adafruit-nrfutil on it; a board already +# in the bootloader is flashed as it is. Reports success only when the app is +# back on USB -- check `ver` yourself. Companion builds have no console: use +# `pio run -e -t upload` there (touch). Refuses a board whose config +# entry has `refuse` set (e.g. the radio of an observer). Runs on any host that +# has the board on USB and a checkout of this repo -- no PlatformIO project +# build needed there, only the nrfutil package. +set -euo pipefail +case "${1:-}" in -h | --help | "") + sed -n '3,/^[^#]/{/^#/s/^# \{0,1\}//p}' "$0" + exit 0 + ;; +esac +[ $# -eq 3 ] || { + echo "usage: $0 " >&2 + exit 2 +} +ZIP=$1 SN=$2 BOARD=$3 +WHY="$(python3 "$(dirname "$0")/mctools_config.py" get "$SN" refuse 2>/dev/null || true)" +[ -z "$WHY" ] || { + echo "refused: $WHY" >&2 + exit 1 +} +[ -f "$ZIP" ] || { + echo "$ZIP: no such file" >&2 + exit 1 +} +NRF=${NRF:-$HOME/.platformio/packages} +PY=${PY:-python3} +CLI=${CLI:-$(dirname "$(readlink -f "$0")")/serial_cli.py} +port() { compgen -G "/dev/serial/by-id/*$1$SN*" | head -1; } + +if [ -n "$(port Seeed_Studio_XIAO_nRF52840_)" ]; then + timeout 20 "$PY" "$CLI" "$BOARD" "dfu serial" >/dev/null 2>&1 || true +fi +B="" +for _ in $(seq 1 25); do + B=$(port XIAO_nRF52840_Sense_ || true) + [ -n "$B" ] && break + sleep 1 +done +[ -n "$B" ] || { + echo "$BOARD: bootloader port did not appear" >&2 + exit 1 +} +PYTHONPATH="$NRF/tool-adafruit-nrfutil/site-packages" timeout 120 "$PY" \ + "$NRF/tool-adafruit-nrfutil/adafruit-nrfutil.py" dfu serial -pkg "$ZIP" \ + -p "$B" -b 115200 --singlebank 2>&1 | tail -1 +for _ in $(seq 1 30); do + if [ -n "$(port Seeed_Studio_XIAO_nRF52840_)" ]; then + echo "$BOARD: app back on USB" + exit 0 + fi + sleep 2 +done +echo "$BOARD: app did not come back on USB" >&2 +exit 1 diff --git a/tools/xiao_uf2_flash.sh b/tools/xiao_uf2_flash.sh new file mode 100755 index 00000000..b47f49cd --- /dev/null +++ b/tools/xiao_uf2_flash.sh @@ -0,0 +1,314 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MIT +# Flash a XIAO nRF52840 through its UF2 drive -- to a named board, and verified. +# +# tools/xiao_uf2_flash.sh [target] +# +# target USB serial (full or unique suffix), or a board name/alias from the +# local config (tools/mctools_config.py). +# Omit only when exactly one board is plugged in. +# +# XIAO_UF2_WAIT=300 seconds to wait for UF2 mode (default 90). Worth raising +# when the board has to be double-tapped by hand. +# +# Get the board into UF2 mode with 'dfu' on its console (deterministic), or by +# double-tapping its small RESET button. +# +# What it refuses to do, because each of these has actually gone wrong here: +# - flash an image older than the build that produced it (pio run and +# pio run -t create_uf2 refresh different artifacts; x3 silently ended up +# two commits behind the rest of the fleet that way) +# - guess which board to write to when several are in UF2 mode (every drive +# is labelled XIAO-SENSE, in plug order, so the label proves nothing) +# - write to a board other than the one you named +# - report success without reading the version back off the board (the first +# version of this script printed x4's port after flashing x3) +# +# NEVER uses the 1200-baud touch: it only requests the bootloader's SERIAL_ONLY +# mode, so no drive ever appears, and a second touch in one power session wedges +# the board out of USB and BLE with no self-recovery. +set -uo pipefail +case "${1:-}" in -h | --help) + sed -n '3,/^[^#]/{/^#/s/^# \{0,1\}//p}' "$0" + exit 0 + ;; +esac + +die() { + echo "CHYBA: $*" >&2 + exit 1 +} + +UF2="${1:-}" +TARGET="${2:-}" +[ -n "$UF2" ] && [ -f "$UF2" ] || { + echo "usage: $(basename "$0") [serial|board]" >&2 + exit 1 +} + +# Board names/aliases come from the local config (tools/mctools_config.py); +# a serial or its unique suffix passes through. +if [ -n "$TARGET" ] && SN="$(python3 "$(dirname "$0")/mctools_config.py" serial "$TARGET" 2>/dev/null)"; then + TARGET="$SN" +fi + +# A .hex or .zip dropped on a UF2 drive is silently ignored by the bootloader and +# looks like a successful flash, so check the container before trusting it. +# UF2 blocks start with the magic 0x0A324655 ("UF2\n"). +head -c4 "$UF2" | grep -q 'UF2' || die "$UF2 neni UF2 obraz (chybi magic 'UF2\\n')" +echo "== image: $UF2 ($(stat -c%s "$UF2") B)" + +ELF="$(dirname "$UF2")/firmware.elf" +if [ -f "$ELF" ] && [ "$ELF" -nt "$UF2" ]; then + die "$(basename "$UF2") je STARSI nez firmware.elf -- nalil bys stary obraz. + Sprav: pio run -e && pio run -e -t create_uf2" +fi + +# Read the version out of the UF2 PAYLOAD, not the raw file. A UF2 is 512-byte +# blocks of 32 B header + 256 B data, so any string in the image can be cut in +# half by a block boundary -- and then a plain grep over the file finds nothing +# and this script refuses a perfectly good build. That is not hypothetical: it +# happened to SenseCap_mast_rpt on 15. 8. 2026 (the version was in the ELF the +# whole time), and it cost a hand-copied flash and a board that had to be +# replugged. Stitching the payload back together makes the check depend on the +# image rather than on where the linker happened to put the string. +WANT_VER="$( + python3 - "$UF2" <<'PY' 2>/dev/null || true +import re, sys +raw = open(sys.argv[1], "rb").read() +payload = b"".join(raw[i+32:i+288] for i in range(0, len(raw), 512)) +m = re.search(rb"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", payload) +if m: print(m.group(0).decode()) +PY +)" +if [ -z "$WANT_VER" ]; then + die "obraz nema verzi od tools/build_version.py -- po flashi by neslo overit, + co na desce doopravdy je. Zapoj do envu: extra_scripts = \${stamped.extra_scripts}" +fi +echo "== verze v obrazu: $WANT_VER" +[ -n "$TARGET" ] && echo "== cil: $TARGET" + +# Resolve UF2 drives THROUGH SYSFS, never by label: every XIAO drive is called +# XIAO-SENSE (then XIAO-SENSE1, ...) assigned in plug order, so with several +# boards on the bus the label says nothing about which board you are writing to. +find_uf2_boards() { + local d s blk + for d in /sys/bus/usb/devices/*/; do + s="$(cat "$d/serial" 2>/dev/null)" || continue + [ "$(cat "$d/idVendor" 2>/dev/null)" = "2886" ] || continue + blk="$(ls -d "$d"*/host*/target*/*/block/* 2>/dev/null | head -1)" || true + [ -n "$blk" ] && echo "$s /dev/$(basename "$blk")" + done +} + +# Companion builds have no text console, so no `dfu` command: those boards can +# only be double-tapped by hand, and 90 s turned out to be shorter than the round +# trip of asking someone to do it. Overridable rather than just longer, so an +# unattended flash still fails fast. +WAIT="${XIAO_UF2_WAIT:-90}" +echo -n "== cekam na UF2 rezim, ${WAIT}s (\"dfu\" na konzoli, nebo dvojklik RESET) " +SERIAL="" +DISK="" +for _ in $(seq 1 "$WAIT"); do + mapfile -t found < <(find_uf2_boards) + if [ -n "$TARGET" ]; then # keep only the board asked for + mapfile -t found < <(printf '%s\n' "${found[@]:-}" | grep -F "$TARGET" || true) + fi + if [ "${#found[@]}" -gt 1 ]; then + echo + { + echo "${#found[@]} desek v UF2 rezimu -- nevim, ktera je ta tva:" + printf ' %s\n' "${found[@]}" + echo "Zadej cil: $(basename "$0") $UF2 " + } >&2 + exit 1 + fi + if [ "${#found[@]}" -eq 1 ] && [ -n "${found[0]}" ]; then + SERIAL="${found[0]%% *}" + DISK="${found[0]##* }" + break + fi + echo -n "." + sleep 1 +done +echo +[ -n "$DISK" ] || die "do ${WAIT} s se v UF2 rezimu neobjevila${TARGET:+ deska $TARGET}" +echo "== deska: $SERIAL disk: $DISK" + +# Mount with retries: the drive appears a moment before the desktop automounter +# gets to it, and udisksctl can lose that race, so a single attempt fails on a +# board that is perfectly fine. Observed on the very first `dfu`-driven flash. +MNT="" +for _ in $(seq 1 12); do + MNT="$(lsblk -no MOUNTPOINT "$DISK" | head -1)" + [ -n "$MNT" ] && break + udisksctl mount -b "$DISK" >/dev/null 2>&1 || true + sleep 1 +done +[ -n "$MNT" ] || die "disk $DISK se nepodarilo namountovat ani na 12 pokusu + Zkus rucne: udisksctl mount -b $DISK" + +echo "== mount: $MNT -- kopiruju" +# The board resets itself the moment it has all the blocks, so cp/sync failing +# at the very end is normal, not an error. +cp "$UF2" "$MNT/" 2>/dev/null || true +sync 2>/dev/null || true + +echo -n "== cekam, az disk zmizi (= bootloader obraz prevzal) " +GONE=0 +for _ in $(seq 1 30); do + find_uf2_boards | grep -q "^$SERIAL " || { + GONE=1 + break + } + echo -n "." + sleep 1 +done +echo +[ "$GONE" -eq 1 ] || die "disk nezmizel -- flash nejspis neprobehl" + +# Wait for THIS board, matched on its serial. "Some XIAO came back on USB" is +# worthless with four of them plugged in. +echo -n "== cekam na navrat desky $SERIAL " +PORT="" +for _ in $(seq 1 45); do + for d in /sys/bus/usb/devices/*/; do + [ "$(cat "$d/serial" 2>/dev/null)" = "$SERIAL" ] || continue + [ "$(cat "$d/idProduct" 2>/dev/null)" = "8044" ] || continue + PORT="$(ls /dev/serial/by-id/*"$SERIAL"*-if00 2>/dev/null | head -1)" || true + done + [ -n "$PORT" ] && break + echo -n "." + sleep 1 +done +echo +[ -n "$PORT" ] || die "$SERIAL se do 45 s neohlasila jako aplikace" + +# The actual proof: ask the board what it is running. Anything less and a flash +# that quietly did nothing still reports success. +# +# The same trip also SETS THE CLOCK, because this is the one moment when a host +# is provably talking to the board. Every clock in this firmware is volatile +# unless the board has GPS or an I2C RTC: `VolatileRTCClock` starts in May 2024 +# and only ticks from millis(). A node with a wrong clock is not a cosmetic +# problem -- the RTC stamps every advert it transmits, and receivers drop a stale +# timestamp as a replay. Measured 7. 8. 2026: bench-board had been running 811 days +# behind since deployment, and bench board x1 was 812 days behind, both simply +# because nobody ever typed `time `. +GOT="$( + python3 - "$PORT" <<'PY' 2>/dev/null || true +import re, struct, sys, time +try: + import serial +except ImportError: + sys.exit(0) +# Retry: the port enumerates a second or two before the firmware is answering on +# it, so a single attempt calls a perfectly good flash "unverified" -- which is +# worse than no check, because it teaches you to ignore the tool. +for attempt in range(5): + try: + s = serial.Serial(sys.argv[1], 115200, timeout=1); s.dtr = True; s.rts = True + time.sleep(2.5); s.reset_input_buffer() + # Throwaway newline first. The board's own line buffer can still hold a + # fragment from before the reset, and whatever is sent next gets appended + # to it -- so the first real command comes back "Unknown command" and the + # flash is declared unverified even though it landed. Cost this exactly + # one wrong conclusion about x4. + s.write(b"\r\n"); s.flush(); time.sleep(0.5); s.reset_input_buffer() + s.write(b"ver\r\n"); s.flush(); time.sleep(2.0) + out = s.read(s.in_waiting or 1).decode("utf-8", "replace") + m = re.search(r"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", out) + if m: + print("VER\t" + m.group(0)) + # Set the clock, then read it back. The read-back is what decides: + # `time` answers "(ERR: clock cannot go backwards)" when the board is + # already right -- which happens once the build epoch seeds the RTC, + # and is SUCCESS, not failure. Never trust the setter's own reply. + s.reset_input_buffer() + s.write(("time %d\r\n" % int(time.time())).encode()); s.flush() + time.sleep(1.5); s.reset_input_buffer() + s.write(b"clock\r\n"); s.flush(); time.sleep(1.5) + got = s.read(s.in_waiting or 1).decode("utf-8", "replace") + c = re.search(r"\d{1,2}:\d{2} - \d{1,2}/\d{1,2}/\d{4} UTC(?: \(epoch \d+\))?", got) + print("CLOCK\t" + (c.group(0) if c else "?")) + s.close(); break + # No text console means this is a companion_radio build, which has no + # `ver` command at all -- ask in its own language rather than calling a + # perfectly good flash unverified (it did exactly that on x2). + # CMD_DEVICE_QUERY(22) -> RESP_CODE_DEVICE_INFO(13); firmware_version is + # the 20-byte field at offset 60. Framing: '<' + uint16 LE len + payload + # outbound, '>' + len + payload back. + s.reset_input_buffer() + s.write(b"<" + struct.pack("") + if i >= 0 and len(buf) >= i + 3: + ln = struct.unpack("= 80 and f[0] == 13: + v = f[60:80].split(b"\0")[0].decode("utf-8", "replace") + if v: + print("VER\t" + v) + # Companion builds have no `time` command at all -- the app + # sets the clock with CMD_SET_DEVICE_TIME(6). Same guard as + # the console (`secs >= curr`), so an ERR frame here is not a + # failure either; CMD_GET_DEVICE_TIME(5) -> RESP(9) decides. + now = int(time.time()) + s.reset_input_buffer() + fr = bytes([6]) + struct.pack("") + if j >= 0 and len(rb) >= j + 3: + rl = struct.unpack("= 5 and rf[0] == 9: + t = struct.unpack("&2 + exit 2 +fi +if [ "$GOT_VER" != "$WANT_VER" ]; then + die "deska hlasi $GOT_VER, ale v obrazu bylo $WANT_VER -- flash NEPROSEL" +fi +echo "== OK: $SERIAL bezi $GOT_VER ($PORT)" + +# Warn rather than fail: a wrong clock does not mean the flash was bad, and this +# script's contract is "the image landed". But it must not pass silently -- an +# unset clock is exactly what went unnoticed on x3 for 811 days. +# Only the year is checked, because that is what a volatile RTC gets wrong: it +# comes up in 2024 and stays there. (Around midnight on 31 December this warns +# for one minute on a board that is actually right. Non-fatal, once a year.) +case "$GOT_CLOCK" in +"") echo "!! hodiny se necetly zpatky -- nastav je rucne: time \$(date +%s)" >&2 ;; +"?") echo "!! hodiny neodpovedely ve znamem formatu -- zkontroluj 'clock' rucne" >&2 ;; +*"/$(date -u +%Y)"*) + echo "== hodiny: $GOT_CLOCK" + ;; +*) echo "!! hodiny hlasi $GOT_CLOCK -- nesedi rok, nastav je rucne: time \$(date +%s)" >&2 ;; +esac