From 9312fe780a13245fa3e15cdbc9d890c94421cffa Mon Sep 17 00:00:00 2001 From: Quency-D Date: Thu, 26 Feb 2026 17:47:03 +0800 Subject: [PATCH 01/52] add heltec v4.3 --- variants/heltec_v4/HeltecV4Board.cpp | 16 +--- variants/heltec_v4/HeltecV4Board.h | 4 +- variants/heltec_v4/LoRaFEMControl.cpp | 104 ++++++++++++++++++++++++++ variants/heltec_v4/LoRaFEMControl.h | 28 +++++++ variants/heltec_v4/platformio.ini | 8 +- 5 files changed, 143 insertions(+), 17 deletions(-) create mode 100644 variants/heltec_v4/LoRaFEMControl.cpp create mode 100644 variants/heltec_v4/LoRaFEMControl.h diff --git a/variants/heltec_v4/HeltecV4Board.cpp b/variants/heltec_v4/HeltecV4Board.cpp index 92f9343767..fcb5050dc2 100644 --- a/variants/heltec_v4/HeltecV4Board.cpp +++ b/variants/heltec_v4/HeltecV4Board.cpp @@ -7,15 +7,7 @@ void HeltecV4Board::begin() { pinMode(PIN_ADC_CTRL, OUTPUT); digitalWrite(PIN_ADC_CTRL, LOW); // Initially inactive - pinMode(P_LORA_PA_POWER, OUTPUT); - digitalWrite(P_LORA_PA_POWER,HIGH); - - rtc_gpio_hold_dis((gpio_num_t)P_LORA_PA_EN); - pinMode(P_LORA_PA_EN, OUTPUT); - digitalWrite(P_LORA_PA_EN,HIGH); - pinMode(P_LORA_PA_TX_EN, OUTPUT); - digitalWrite(P_LORA_PA_TX_EN,LOW); - + loRaFEMControl.init(); periph_power.begin(); @@ -33,12 +25,12 @@ void HeltecV4Board::begin() { void HeltecV4Board::onBeforeTransmit(void) { digitalWrite(P_LORA_TX_LED, HIGH); // turn TX LED on - digitalWrite(P_LORA_PA_TX_EN,HIGH); + loRaFEMControl.setTxModeEnable(); } void HeltecV4Board::onAfterTransmit(void) { digitalWrite(P_LORA_TX_LED, LOW); // turn TX LED off - digitalWrite(P_LORA_PA_TX_EN,LOW); + loRaFEMControl.setRxModeEnable(); } void HeltecV4Board::enterDeepSleep(uint32_t secs, int pin_wake_btn) { @@ -50,7 +42,7 @@ void HeltecV4Board::begin() { rtc_gpio_hold_en((gpio_num_t)P_LORA_NSS); - rtc_gpio_hold_en((gpio_num_t)P_LORA_PA_EN); //It also needs to be enabled in receive mode + loRaFEMControl.setRxModeEnableWhenMCUSleep();//It also needs to be enabled in receive mode if (pin_wake_btn < 0) { esp_sleep_enable_ext1_wakeup( (1L << P_LORA_DIO_1), ESP_EXT1_WAKEUP_ANY_HIGH); // wake up on: recv LoRa packet diff --git a/variants/heltec_v4/HeltecV4Board.h b/variants/heltec_v4/HeltecV4Board.h index 745e8d8f3d..4d5ee46155 100644 --- a/variants/heltec_v4/HeltecV4Board.h +++ b/variants/heltec_v4/HeltecV4Board.h @@ -4,12 +4,12 @@ #include #include #include - +#include "LoRaFEMControl.h" class HeltecV4Board : public ESP32Board { public: RefCountedDigitalPin periph_power; - + LoRaFEMControl loRaFEMControl; HeltecV4Board() : periph_power(PIN_VEXT_EN,PIN_VEXT_EN_ACTIVE) { } void begin(); diff --git a/variants/heltec_v4/LoRaFEMControl.cpp b/variants/heltec_v4/LoRaFEMControl.cpp new file mode 100644 index 0000000000..c5953b7786 --- /dev/null +++ b/variants/heltec_v4/LoRaFEMControl.cpp @@ -0,0 +1,104 @@ +#include "LoRaFEMControl.h" +#include +#include +#include + +void LoRaFEMControl::init(void) +{ + setLnaCanControl(false);// Default is uncontrollable + rtc_gpio_hold_dis((gpio_num_t)P_LORA_PA_POWER); + rtc_gpio_hold_dis((gpio_num_t)P_LORA_GC1109_PA_EN); + rtc_gpio_hold_dis((gpio_num_t)P_LORA_GC1109_PA_TX_EN); + rtc_gpio_hold_dis((gpio_num_t)P_LORA_KCT8103L_PA_CSD); + rtc_gpio_hold_dis((gpio_num_t)P_LORA_KCT8103L_PA_CTX); + + pinMode(P_LORA_PA_POWER,OUTPUT); + digitalWrite(P_LORA_PA_POWER,HIGH); + delay(1); + pinMode(P_LORA_KCT8103L_PA_CSD,INPUT); // detect which FEM is used + delay(1); + if(digitalRead(P_LORA_KCT8103L_PA_CSD)==HIGH) { + // FEM is KCT8103L + fem_type= KCT8103L_PA; + pinMode(P_LORA_KCT8103L_PA_CSD, OUTPUT); + digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); + pinMode(P_LORA_KCT8103L_PA_CTX, OUTPUT); + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + setLnaCanControl(true); + } else if(digitalRead(P_LORA_KCT8103L_PA_CSD)==LOW) { + // FEM is GC1109 + fem_type= GC1109_PA; + pinMode(P_LORA_GC1109_PA_EN, OUTPUT); + digitalWrite(P_LORA_GC1109_PA_EN, HIGH); + pinMode(P_LORA_GC1109_PA_TX_EN, OUTPUT); + digitalWrite(P_LORA_GC1109_PA_TX_EN, LOW); + } else { + fem_type= OTHER_FEM_TYPES; + } +} + +void LoRaFEMControl::setSleepModeEnable(void) +{ + if(fem_type==GC1109_PA) { + /* + * Do not switch the power on and off frequently. + * After turning off P_LORA_PA_EN, the power consumption has dropped to the uA level. + */ + digitalWrite(P_LORA_GC1109_PA_EN, LOW); + digitalWrite(P_LORA_GC1109_PA_TX_EN, LOW); + } else if(fem_type==KCT8103L_PA) { + // shutdown the PA + digitalWrite(P_LORA_KCT8103L_PA_CSD, LOW); + } +} + +void LoRaFEMControl::setTxModeEnable(void) +{ + if(fem_type==GC1109_PA) { + digitalWrite(P_LORA_GC1109_PA_EN, HIGH); // CSD=1: Chip enabled + digitalWrite(P_LORA_GC1109_PA_TX_EN, HIGH); // CPS: 1=full PA, 0=bypass (for RX, CPS is don't care) + } else if(fem_type==KCT8103L_PA) { + digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + } +} + +void LoRaFEMControl::setRxModeEnable(void) +{ + if(fem_type==GC1109_PA) { + digitalWrite(P_LORA_GC1109_PA_EN, HIGH); // CSD=1: Chip enabled + digitalWrite(P_LORA_GC1109_PA_TX_EN, LOW); + } else if(fem_type==KCT8103L_PA) { + digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); + if(lna_enabled) { + digitalWrite(P_LORA_KCT8103L_PA_CTX, LOW); + } else { + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + } + } +} + +void LoRaFEMControl::setRxModeEnableWhenMCUSleep(void) +{ + digitalWrite(P_LORA_PA_POWER, HIGH); + rtc_gpio_hold_en((gpio_num_t)P_LORA_PA_POWER); + if(fem_type==GC1109_PA) { + digitalWrite(P_LORA_GC1109_PA_EN, HIGH); + rtc_gpio_hold_en((gpio_num_t)P_LORA_GC1109_PA_EN); + gpio_pulldown_en((gpio_num_t)P_LORA_GC1109_PA_TX_EN); + } else if(fem_type==KCT8103L_PA) { + digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); + rtc_gpio_hold_en((gpio_num_t)P_LORA_KCT8103L_PA_CSD); + if(lna_enabled) { + digitalWrite(P_LORA_KCT8103L_PA_CTX, LOW); + } else { + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + } + rtc_gpio_hold_en((gpio_num_t)P_LORA_KCT8103L_PA_CTX); + } +} + +void LoRaFEMControl::setLNAEnable(bool enabled) +{ + lna_enabled = enabled; +} diff --git a/variants/heltec_v4/LoRaFEMControl.h b/variants/heltec_v4/LoRaFEMControl.h new file mode 100644 index 0000000000..349f0ffb84 --- /dev/null +++ b/variants/heltec_v4/LoRaFEMControl.h @@ -0,0 +1,28 @@ +#pragma once +#include + +typedef enum { + GC1109_PA, + KCT8103L_PA, + OTHER_FEM_TYPES +} LoRaFEMType; + +class LoRaFEMControl +{ + public: + LoRaFEMControl(){ } + virtual ~LoRaFEMControl(){ } + void init(void); + void setSleepModeEnable(void); + void setTxModeEnable(void); + void setRxModeEnable(void); + void setRxModeEnableWhenMCUSleep(void); + void setLNAEnable(bool enabled); + bool isLnaCanControl(void) { return lna_can_control; } + void setLnaCanControl(bool can_control) { lna_can_control = can_control; } + private: + LoRaFEMType fem_type; + bool lna_enabled=false; + bool lna_can_control=false; +}; + diff --git a/variants/heltec_v4/platformio.ini b/variants/heltec_v4/platformio.ini index c5011e0e9b..3bec19f5ad 100644 --- a/variants/heltec_v4/platformio.ini +++ b/variants/heltec_v4/platformio.ini @@ -17,9 +17,11 @@ build_flags = -D P_LORA_SCLK=9 -D P_LORA_MISO=11 -D P_LORA_MOSI=10 - -D P_LORA_PA_POWER=7 ; VFEM_Ctrl - Power on GC1109 - -D P_LORA_PA_EN=2 ; PA CSD - Enable GC1109 - -D P_LORA_PA_TX_EN=46 ; PA CPS - GC1109 TX PA full(High) / bypass(Low) + -D P_LORA_PA_POWER=7 ; // VFEM_Ctrl -LDO power enable + -D P_LORA_GC1109_PA_EN=2 ; // CSD - GC1109 chip enable (HIGH=on) + -D P_LORA_GC1109_PA_TX_EN=46 ;// CPS - GC1109 PA mode (HIGH=full PA, LOW=bypass) + -D P_LORA_KCT8103L_PA_CSD=2 + -D P_LORA_KCT8103L_PA_CTX=5 -D PIN_USER_BTN=0 -D PIN_VEXT_EN=36 -D PIN_VEXT_EN_ACTIVE=LOW From f0d37e552d05d4013f516a4a1f0767e0b283645a Mon Sep 17 00:00:00 2001 From: Quency-D Date: Fri, 27 Feb 2026 16:49:00 +0800 Subject: [PATCH 02/52] Added version identification. --- variants/heltec_v4/HeltecV4Board.cpp | 10 +++++----- variants/heltec_v4/LoRaFEMControl.h | 3 ++- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/variants/heltec_v4/HeltecV4Board.cpp b/variants/heltec_v4/HeltecV4Board.cpp index fcb5050dc2..6cad79ab9f 100644 --- a/variants/heltec_v4/HeltecV4Board.cpp +++ b/variants/heltec_v4/HeltecV4Board.cpp @@ -78,9 +78,9 @@ void HeltecV4Board::begin() { } const char* HeltecV4Board::getManufacturerName() const { - #ifdef HELTEC_LORA_V4_TFT - return "Heltec V4 TFT"; - #else - return "Heltec V4 OLED"; - #endif +#ifdef HELTEC_LORA_V4_TFT + return loRaFEMControl.getFEMType() == KCT8103L_PA ? "Heltec V4.3 TFT" : "Heltec V4 TFT"; +#else + return loRaFEMControl.getFEMType() == KCT8103L_PA ? "Heltec V4.3 OLED" : "Heltec V4 OLED"; +#endif } diff --git a/variants/heltec_v4/LoRaFEMControl.h b/variants/heltec_v4/LoRaFEMControl.h index 349f0ffb84..13225bd56b 100644 --- a/variants/heltec_v4/LoRaFEMControl.h +++ b/variants/heltec_v4/LoRaFEMControl.h @@ -20,8 +20,9 @@ class LoRaFEMControl void setLNAEnable(bool enabled); bool isLnaCanControl(void) { return lna_can_control; } void setLnaCanControl(bool can_control) { lna_can_control = can_control; } + LoRaFEMType getFEMType(void) const { return fem_type; } private: - LoRaFEMType fem_type; + LoRaFEMType fem_type=OTHER_FEM_TYPES; bool lna_enabled=false; bool lna_can_control=false; }; From 8b7fed65ded03f00043fd872e2dad94a561a4a79 Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Mon, 2 Mar 2026 11:34:12 +0100 Subject: [PATCH 03/52] default lna_enabled=true --- variants/heltec_v4/LoRaFEMControl.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variants/heltec_v4/LoRaFEMControl.h b/variants/heltec_v4/LoRaFEMControl.h index 13225bd56b..7545296503 100644 --- a/variants/heltec_v4/LoRaFEMControl.h +++ b/variants/heltec_v4/LoRaFEMControl.h @@ -23,7 +23,7 @@ class LoRaFEMControl LoRaFEMType getFEMType(void) const { return fem_type; } private: LoRaFEMType fem_type=OTHER_FEM_TYPES; - bool lna_enabled=false; + bool lna_enabled=true; bool lna_can_control=false; }; From 14f066bed0e1be1a2c0c7b214e16fa12c0d56c5c Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Mon, 2 Mar 2026 11:34:42 +0100 Subject: [PATCH 04/52] Fix sleep --- variants/heltec_v4/LoRaFEMControl.cpp | 42 +++++++++++++++------------ 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/variants/heltec_v4/LoRaFEMControl.cpp b/variants/heltec_v4/LoRaFEMControl.cpp index c5953b7786..168185c31f 100644 --- a/variants/heltec_v4/LoRaFEMControl.cpp +++ b/variants/heltec_v4/LoRaFEMControl.cpp @@ -5,35 +5,39 @@ void LoRaFEMControl::init(void) { - setLnaCanControl(false);// Default is uncontrollable + // Power on FEM LDO — set registers before releasing RTC hold for + // atomic transition (no glitch on deep sleep wake). + pinMode(P_LORA_PA_POWER, OUTPUT); + digitalWrite(P_LORA_PA_POWER, HIGH); rtc_gpio_hold_dis((gpio_num_t)P_LORA_PA_POWER); - rtc_gpio_hold_dis((gpio_num_t)P_LORA_GC1109_PA_EN); - rtc_gpio_hold_dis((gpio_num_t)P_LORA_GC1109_PA_TX_EN); - rtc_gpio_hold_dis((gpio_num_t)P_LORA_KCT8103L_PA_CSD); - rtc_gpio_hold_dis((gpio_num_t)P_LORA_KCT8103L_PA_CTX); - pinMode(P_LORA_PA_POWER,OUTPUT); - digitalWrite(P_LORA_PA_POWER,HIGH); - delay(1); - pinMode(P_LORA_KCT8103L_PA_CSD,INPUT); // detect which FEM is used + esp_reset_reason_t reason = esp_reset_reason(); + if (reason != ESP_RST_DEEPSLEEP) { + delay(1); // FEM startup time after cold power-on + } + + // Auto-detect FEM type via shared GPIO2 default pull level. + // GC1109 CSD: internal pull-down → reads LOW + // KCT8103L CSD: internal pull-up → reads HIGH + rtc_gpio_hold_dis((gpio_num_t)P_LORA_KCT8103L_PA_CSD); + pinMode(P_LORA_KCT8103L_PA_CSD, INPUT); delay(1); if(digitalRead(P_LORA_KCT8103L_PA_CSD)==HIGH) { - // FEM is KCT8103L + // FEM is KCT8103L (V4.3) fem_type= KCT8103L_PA; pinMode(P_LORA_KCT8103L_PA_CSD, OUTPUT); digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); + rtc_gpio_hold_dis((gpio_num_t)P_LORA_KCT8103L_PA_CTX); pinMode(P_LORA_KCT8103L_PA_CTX, OUTPUT); - digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + digitalWrite(P_LORA_KCT8103L_PA_CTX, lna_enabled ? LOW : HIGH); setLnaCanControl(true); - } else if(digitalRead(P_LORA_KCT8103L_PA_CSD)==LOW) { - // FEM is GC1109 + } else { + // FEM is GC1109 (V4.2) fem_type= GC1109_PA; pinMode(P_LORA_GC1109_PA_EN, OUTPUT); digitalWrite(P_LORA_GC1109_PA_EN, HIGH); pinMode(P_LORA_GC1109_PA_TX_EN, OUTPUT); digitalWrite(P_LORA_GC1109_PA_TX_EN, LOW); - } else { - fem_type= OTHER_FEM_TYPES; } } @@ -71,9 +75,9 @@ void LoRaFEMControl::setRxModeEnable(void) } else if(fem_type==KCT8103L_PA) { digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); if(lna_enabled) { - digitalWrite(P_LORA_KCT8103L_PA_CTX, LOW); + digitalWrite(P_LORA_KCT8103L_PA_CTX, LOW); // LNA on } else { - digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); // LNA bypass } } } @@ -90,9 +94,9 @@ void LoRaFEMControl::setRxModeEnableWhenMCUSleep(void) digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); rtc_gpio_hold_en((gpio_num_t)P_LORA_KCT8103L_PA_CSD); if(lna_enabled) { - digitalWrite(P_LORA_KCT8103L_PA_CTX, LOW); + digitalWrite(P_LORA_KCT8103L_PA_CTX, LOW); // LNA on } else { - digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); // LNA bypass } rtc_gpio_hold_en((gpio_num_t)P_LORA_KCT8103L_PA_CTX); } From 70d3b96768274ff9ffe06c854fbefd0cecc2f0b7 Mon Sep 17 00:00:00 2001 From: Quency-D <55523105+Quency-D@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:06:58 +0800 Subject: [PATCH 05/52] Update variants/heltec_v4/LoRaFEMControl.cpp init function Co-authored-by: Wessel --- variants/heltec_v4/LoRaFEMControl.cpp | 34 +++++++++++++++------------ 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/variants/heltec_v4/LoRaFEMControl.cpp b/variants/heltec_v4/LoRaFEMControl.cpp index c5953b7786..d369186c07 100644 --- a/variants/heltec_v4/LoRaFEMControl.cpp +++ b/variants/heltec_v4/LoRaFEMControl.cpp @@ -5,35 +5,39 @@ void LoRaFEMControl::init(void) { - setLnaCanControl(false);// Default is uncontrollable + // Power on FEM LDO — set registers before releasing RTC hold for + // atomic transition (no glitch on deep sleep wake). + pinMode(P_LORA_PA_POWER, OUTPUT); + digitalWrite(P_LORA_PA_POWER, HIGH); rtc_gpio_hold_dis((gpio_num_t)P_LORA_PA_POWER); - rtc_gpio_hold_dis((gpio_num_t)P_LORA_GC1109_PA_EN); - rtc_gpio_hold_dis((gpio_num_t)P_LORA_GC1109_PA_TX_EN); - rtc_gpio_hold_dis((gpio_num_t)P_LORA_KCT8103L_PA_CSD); - rtc_gpio_hold_dis((gpio_num_t)P_LORA_KCT8103L_PA_CTX); - pinMode(P_LORA_PA_POWER,OUTPUT); - digitalWrite(P_LORA_PA_POWER,HIGH); - delay(1); - pinMode(P_LORA_KCT8103L_PA_CSD,INPUT); // detect which FEM is used + esp_reset_reason_t reason = esp_reset_reason(); + if (reason != ESP_RST_DEEPSLEEP) { + delay(1); // FEM startup time after cold power-on + } + + // Auto-detect FEM type via shared GPIO2 default pull level. + // GC1109 CSD: internal pull-down → reads LOW + // KCT8103L CSD: internal pull-up → reads HIGH + rtc_gpio_hold_dis((gpio_num_t)P_LORA_KCT8103L_PA_CSD); + pinMode(P_LORA_KCT8103L_PA_CSD, INPUT); delay(1); if(digitalRead(P_LORA_KCT8103L_PA_CSD)==HIGH) { - // FEM is KCT8103L + // FEM is KCT8103L (V4.3) fem_type= KCT8103L_PA; pinMode(P_LORA_KCT8103L_PA_CSD, OUTPUT); digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); + rtc_gpio_hold_dis((gpio_num_t)P_LORA_KCT8103L_PA_CTX); pinMode(P_LORA_KCT8103L_PA_CTX, OUTPUT); - digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + digitalWrite(P_LORA_KCT8103L_PA_CTX, lna_enabled ? LOW : HIGH); setLnaCanControl(true); - } else if(digitalRead(P_LORA_KCT8103L_PA_CSD)==LOW) { - // FEM is GC1109 + } else { + // FEM is GC1109 (V4.2) fem_type= GC1109_PA; pinMode(P_LORA_GC1109_PA_EN, OUTPUT); digitalWrite(P_LORA_GC1109_PA_EN, HIGH); pinMode(P_LORA_GC1109_PA_TX_EN, OUTPUT); digitalWrite(P_LORA_GC1109_PA_TX_EN, LOW); - } else { - fem_type= OTHER_FEM_TYPES; } } From bab650fe61c4f97996b80471650bae928717e644 Mon Sep 17 00:00:00 2001 From: Quency-D <55523105+Quency-D@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:07:56 +0800 Subject: [PATCH 06/52] LNA is enabled by default. Co-authored-by: Wessel --- variants/heltec_v4/LoRaFEMControl.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variants/heltec_v4/LoRaFEMControl.h b/variants/heltec_v4/LoRaFEMControl.h index 13225bd56b..7545296503 100644 --- a/variants/heltec_v4/LoRaFEMControl.h +++ b/variants/heltec_v4/LoRaFEMControl.h @@ -23,7 +23,7 @@ class LoRaFEMControl LoRaFEMType getFEMType(void) const { return fem_type; } private: LoRaFEMType fem_type=OTHER_FEM_TYPES; - bool lna_enabled=false; + bool lna_enabled=true; bool lna_can_control=false; }; From 3b5139a6556a15256c6c9144857e5c18b9ce6271 Mon Sep 17 00:00:00 2001 From: Quency-D <55523105+Quency-D@users.noreply.github.com> Date: Tue, 3 Mar 2026 17:08:32 +0800 Subject: [PATCH 07/52] Update variants/heltec_v4/LoRaFEMControl.cpp Co-authored-by: Wessel --- variants/heltec_v4/LoRaFEMControl.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/variants/heltec_v4/LoRaFEMControl.cpp b/variants/heltec_v4/LoRaFEMControl.cpp index d369186c07..4ec2960fd2 100644 --- a/variants/heltec_v4/LoRaFEMControl.cpp +++ b/variants/heltec_v4/LoRaFEMControl.cpp @@ -94,9 +94,9 @@ void LoRaFEMControl::setRxModeEnableWhenMCUSleep(void) digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); rtc_gpio_hold_en((gpio_num_t)P_LORA_KCT8103L_PA_CSD); if(lna_enabled) { - digitalWrite(P_LORA_KCT8103L_PA_CTX, LOW); + digitalWrite(P_LORA_KCT8103L_PA_CTX, LOW); // LNA on } else { - digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); // LNA bypass } rtc_gpio_hold_en((gpio_num_t)P_LORA_KCT8103L_PA_CTX); } From 241805e8c1374c24d1793f763064f790652ccb57 Mon Sep 17 00:00:00 2001 From: Quency-D Date: Thu, 5 Mar 2026 14:34:12 +0800 Subject: [PATCH 08/52] Fixed the compilation error of HeltecV4Board::begin. --- variants/heltec_v4/HeltecV4Board.cpp | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/variants/heltec_v4/HeltecV4Board.cpp b/variants/heltec_v4/HeltecV4Board.cpp index ce27cfe43c..49580d2ecf 100644 --- a/variants/heltec_v4/HeltecV4Board.cpp +++ b/variants/heltec_v4/HeltecV4Board.cpp @@ -10,11 +10,12 @@ void HeltecV4Board::begin() { loRaFEMControl.init(); periph_power.begin(); + esp_reset_reason_t reason = esp_reset_reason(); if (reason == ESP_RST_DEEPSLEEP) { long wakeup_source = esp_sleep_get_ext1_wakeup_status(); if (wakeup_source & (1 << P_LORA_DIO_1)) { // received a LoRa packet (while in deep sleep) startup_reason = BD_STARTUP_RX_PACKET; - } + } rtc_gpio_hold_dis((gpio_num_t)P_LORA_NSS); rtc_gpio_deinit((gpio_num_t)P_LORA_DIO_1); From f6338430f8bc6a2f1b057b8e38891fad9f830d9f Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Sat, 7 Mar 2026 14:55:14 +0100 Subject: [PATCH 09/52] Add get/set dutycycle command We translate to af internally, it's easier to store and doesn't break stored prefs. Made get/set af command show deprecated, but it still works fine. --- docs/cli_commands.md | 17 ++++++++++++----- docs/terminal_chat_cli.md | 6 ++++-- src/helpers/CommonCLI.cpp | 28 ++++++++++++++++++++++++---- 3 files changed, 40 insertions(+), 11 deletions(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 1d3430db21..0e170a77c3 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -419,15 +419,22 @@ This document provides an overview of CLI commands that can be sent to MeshCore --- -#### View or change the airtime factor (duty cycle limit) +#### View or change the duty cycle limit **Usage:** -- `get af` -- `set af ` +- `get dutycycle` +- `set dutycycle ` **Parameters:** -- `value`: Airtime factor (0-9) +- `value`: Duty cycle percentage (10-100) -**Default:** `1.0` +**Default:** `50%` (equivalent to airtime factor 1.0) + +**Examples:** +- `set dutycycle 100` — no duty cycle limit +- `set dutycycle 50` — 50% duty cycle (default) +- `set dutycycle 10` — 10% duty cycle (strictest EU requirement) + +> **Deprecated:** `get af` / `set af` still work but are deprecated in favour of `dutycycle`. --- diff --git a/docs/terminal_chat_cli.md b/docs/terminal_chat_cli.md index f053e64d81..b1a3af2a6d 100644 --- a/docs/terminal_chat_cli.md +++ b/docs/terminal_chat_cli.md @@ -28,9 +28,11 @@ set lon {longitude} Sets your advertisement map longitude. (decimal degrees) ``` -set af {air-time-factor} +set dutycycle {percent} ``` -Sets the transmit air-time-factor. +Sets the transmit duty cycle limit (10-100%). Example: `set dutycycle 10` for 10%. + +> **Deprecated:** `set af` still works but is deprecated in favour of `set dutycycle`. ``` diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index f3cba4062a..963eb5d90e 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -283,8 +283,13 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch */ } else if (memcmp(command, "get ", 4) == 0) { const char* config = &command[4]; - if (memcmp(config, "af", 2) == 0) { - sprintf(reply, "> %s", StrHelper::ftoa(_prefs->airtime_factor)); + if (memcmp(config, "dutycycle", 8) == 0) { + float dc = 100.0f / (_prefs->airtime_factor + 1.0f); + int dc_int = (int)dc; + int dc_frac = (int)((dc - dc_int) * 10.0f + 0.5f); + sprintf(reply, "> %d.%d%%", dc_int, dc_frac); + } else if (memcmp(config, "af", 2) == 0) { + sprintf(reply, "> %s (deprecated, use 'get dutycycle')", StrHelper::ftoa(_prefs->airtime_factor)); } else if (memcmp(config, "int.thresh", 10) == 0) { sprintf(reply, "> %d", (uint32_t) _prefs->interference_threshold); } else if (memcmp(config, "agc.reset.interval", 18) == 0) { @@ -436,10 +441,25 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch */ } else if (memcmp(command, "set ", 4) == 0) { const char* config = &command[4]; - if (memcmp(config, "af ", 3) == 0) { + if (memcmp(config, "dutycycle ", 9) == 0) { + float dc = atof(&config[9]); + if (dc < 10 || dc > 100) { + strcpy(reply, "ERROR: dutycycle must be 10-100"); + } else { + _prefs->airtime_factor = (100.0f / dc) - 1.0f; + savePrefs(); + float actual = 100.0f / (_prefs->airtime_factor + 1.0f); + int a_int = (int)actual; + int a_frac = (int)((actual - a_int) * 10.0f + 0.5f); + sprintf(reply, "OK - %d.%d%%", a_int, a_frac); + } + } else if (memcmp(config, "af ", 3) == 0) { _prefs->airtime_factor = atof(&config[3]); savePrefs(); - strcpy(reply, "OK"); + float actual = 100.0f / (_prefs->airtime_factor + 1.0f); + int a_int = (int)actual; + int a_frac = (int)((actual - a_int) * 10.0f + 0.5f); + sprintf(reply, "OK - %d.%d%% (deprecated, use 'set dutycycle')", a_int, a_frac); } else if (memcmp(config, "int.thresh ", 11) == 0) { _prefs->interference_threshold = atoi(&config[11]); savePrefs(); From 3c0d1865691abd7c4aeb329b71fd3047e2f5369b Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Wed, 11 Mar 2026 20:08:47 +0100 Subject: [PATCH 10/52] Fix memcp compare length off by one Co-authored-by: ViezeVingertjes --- src/helpers/CommonCLI.cpp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index 963eb5d90e..b3eff17f9d 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -283,7 +283,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch */ } else if (memcmp(command, "get ", 4) == 0) { const char* config = &command[4]; - if (memcmp(config, "dutycycle", 8) == 0) { + if (memcmp(config, "dutycycle", 9) == 0) { float dc = 100.0f / (_prefs->airtime_factor + 1.0f); int dc_int = (int)dc; int dc_frac = (int)((dc - dc_int) * 10.0f + 0.5f); @@ -441,8 +441,8 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch */ } else if (memcmp(command, "set ", 4) == 0) { const char* config = &command[4]; - if (memcmp(config, "dutycycle ", 9) == 0) { - float dc = atof(&config[9]); + if (memcmp(config, "dutycycle ", 10) == 0) { + float dc = atof(&config[10]); if (dc < 10 || dc > 100) { strcpy(reply, "ERROR: dutycycle must be 10-100"); } else { From c994c6206d41d8eef85907cc0d9b6a971b14fa9e Mon Sep 17 00:00:00 2001 From: whywilson Date: Fri, 13 Mar 2026 13:28:15 +0800 Subject: [PATCH 11/52] Add GAT562 Mesh EVB Pro Repeater and Room Server. --- variants/gat562_evb_pro/platformio.ini | 56 +++++ .../gat562_mesh_evb_pro/GAT562EVBProBoard.cpp | 52 +++++ .../gat562_mesh_evb_pro/GAT562EVBProBoard.h | 53 +++++ variants/gat562_mesh_evb_pro/platformio.ini | 58 +++++ variants/gat562_mesh_evb_pro/target.cpp | 58 +++++ variants/gat562_mesh_evb_pro/target.h | 29 +++ variants/gat562_mesh_evb_pro/variant.cpp | 49 ++++ variants/gat562_mesh_evb_pro/variant.h | 216 ++++++++++++++++++ .../gat562_mesh_tracker_pro/platformio.ini | 2 - 9 files changed, 571 insertions(+), 2 deletions(-) create mode 100644 variants/gat562_evb_pro/platformio.ini create mode 100644 variants/gat562_mesh_evb_pro/GAT562EVBProBoard.cpp create mode 100644 variants/gat562_mesh_evb_pro/GAT562EVBProBoard.h create mode 100644 variants/gat562_mesh_evb_pro/platformio.ini create mode 100644 variants/gat562_mesh_evb_pro/target.cpp create mode 100644 variants/gat562_mesh_evb_pro/target.h create mode 100644 variants/gat562_mesh_evb_pro/variant.cpp create mode 100644 variants/gat562_mesh_evb_pro/variant.h diff --git a/variants/gat562_evb_pro/platformio.ini b/variants/gat562_evb_pro/platformio.ini new file mode 100644 index 0000000000..212ef968e0 --- /dev/null +++ b/variants/gat562_evb_pro/platformio.ini @@ -0,0 +1,56 @@ +[GAT562_Mesh_EVB_Pro] +extends = nrf52_base +board = rak4631 +board_check = true +build_flags = ${nrf52_base.build_flags} + ${sensor_base.build_flags} + -I variants/gat562_mesh_evb_pro + -D NRF52_POWER_MANAGEMENT + -D LORA_FREQ=475 + -D LORA_BW=125 + -D LORA_SF=10 + -D LORA_CR=6 + -D PIN_BOARD_SCL=14 + -D PIN_BOARD_SDA=13 + -D RADIO_CLASS=CustomSX1262 + -D WRAPPER_CLASS=CustomSX1262Wrapper + -D LORA_TX_POWER=22 + -D SX126X_CURRENT_LIMIT=140 + -D SX126X_RX_BOOSTED_GAIN=1 +build_src_filter = ${nrf52_base.build_src_filter} + +<../variants/gat562_mesh_evb_pro> + + + + +lib_deps = + ${nrf52_base.lib_deps} + ${sensor_base.lib_deps} + sparkfun/SparkFun u-blox GNSS Arduino Library@^2.2.27 + +[env:GAT562_Mesh_EVB_Pro_repeater] +extends = GAT562_Mesh_EVB_Pro +build_flags = + ${GAT562_Mesh_EVB_Pro.build_flags} + -D ADVERT_NAME='"GAT562 EVB Pro"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + -D MAX_NEIGHBOURS=50 + -D MESH_PACKET_LOGGING=1 + -D MESH_DEBUG=1 +build_src_filter = ${GAT562_Mesh_EVB_Pro.build_src_filter} + +<../examples/simple_repeater> + + +[env:GAT562_Mesh_EVB_Pro_room_server] +extends = GAT562_Mesh_EVB_Pro +build_flags = + ${GAT562_Mesh_EVB_Pro.build_flags} + -D ADVERT_NAME='"GAT562 EVB Pro Room"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + -D ROOM_PASSWORD='"hello"' + -D MESH_PACKET_LOGGING=1 + -D MESH_DEBUG=1 +build_src_filter = ${GAT562_Mesh_EVB_Pro.build_src_filter} + +<../examples/simple_room_server> diff --git a/variants/gat562_mesh_evb_pro/GAT562EVBProBoard.cpp b/variants/gat562_mesh_evb_pro/GAT562EVBProBoard.cpp new file mode 100644 index 0000000000..ef4af8126b --- /dev/null +++ b/variants/gat562_mesh_evb_pro/GAT562EVBProBoard.cpp @@ -0,0 +1,52 @@ +#include +#include + +#include "GAT562EVBProBoard.h" + + +#ifdef NRF52_POWER_MANAGEMENT +// Static configuration for power management +// Values set in variant.h defines +const PowerMgtConfig power_config = { + .lpcomp_ain_channel = PWRMGT_LPCOMP_AIN, + .lpcomp_refsel = PWRMGT_LPCOMP_REFSEL, + .voltage_bootlock = PWRMGT_VOLTAGE_BOOTLOCK +}; + + +void GAT562EVBProBoard::initiateShutdown(uint8_t reason) { + // Disable LoRa module power before shutdown + digitalWrite(SX126X_POWER_EN, LOW); + + if (reason == SHUTDOWN_REASON_LOW_VOLTAGE || + reason == SHUTDOWN_REASON_BOOT_PROTECT) { + configureVoltageWake(power_config.lpcomp_ain_channel, power_config.lpcomp_refsel); + } + + enterSystemOff(reason); +} +#endif // NRF52_POWER_MANAGEMENT + + +void GAT562EVBProBoard::begin() { + NRF52BoardDCDC::begin(); + pinMode(PIN_VBAT_READ, INPUT); + + // Set all button pins to INPUT_PULLUP + pinMode(PIN_BUTTON1, INPUT_PULLUP); + +#if defined(PIN_BOARD_SDA) && defined(PIN_BOARD_SCL) + Wire.setPins(PIN_BOARD_SDA, PIN_BOARD_SCL); +#endif + + Wire.begin(); + + pinMode(SX126X_POWER_EN, OUTPUT); +#ifdef NRF52_POWER_MANAGEMENT + // Boot voltage protection check (may not return if voltage too low) + // We need to call this after we configure SX126X_POWER_EN as output but before we pull high + checkBootVoltage(&power_config); +#endif + digitalWrite(SX126X_POWER_EN, HIGH); + delay(10); // give sx1268 some time to power up +} \ No newline at end of file diff --git a/variants/gat562_mesh_evb_pro/GAT562EVBProBoard.h b/variants/gat562_mesh_evb_pro/GAT562EVBProBoard.h new file mode 100644 index 0000000000..33c3d05fc5 --- /dev/null +++ b/variants/gat562_mesh_evb_pro/GAT562EVBProBoard.h @@ -0,0 +1,53 @@ +#pragma once + +#include +#include +#include + + +class GAT562EVBProBoard : public NRF52BoardDCDC { +protected: +#ifdef NRF52_POWER_MANAGEMENT + void initiateShutdown(uint8_t reason) override; +#endif + +public: + GAT562EVBProBoard() : NRF52Board("GAT562_OTA") {} + void begin(); + + #define BATTERY_SAMPLES 8 + + uint16_t getBattMilliVolts() override { + analogReadResolution(12); + + uint32_t raw = 0; + for (int i = 0; i < BATTERY_SAMPLES; i++) { + raw += analogRead(PIN_VBAT_READ); + } + raw = raw / BATTERY_SAMPLES; + + return (ADC_MULTIPLIER * raw) / 4096; + } + + const char* getManufacturerName() const override { + return "GAT562 EVB Pro"; + } + +#if defined(P_LORA_TX_LED) + void onBeforeTransmit() override { + digitalWrite(P_LORA_TX_LED, HIGH); // turn TX LED on + } + + void onAfterTransmit() override { + digitalWrite(P_LORA_TX_LED, LOW); // turn TX LED off + } +#endif + + void powerOff() override { + uint32_t button_pin = PIN_BUTTON1; + nrf_gpio_cfg_input(button_pin, NRF_GPIO_PIN_PULLUP); + nrf_gpio_cfg_sense_set(button_pin, NRF_GPIO_PIN_SENSE_LOW); + sd_power_system_off(); + } + +}; diff --git a/variants/gat562_mesh_evb_pro/platformio.ini b/variants/gat562_mesh_evb_pro/platformio.ini new file mode 100644 index 0000000000..b6adf3858b --- /dev/null +++ b/variants/gat562_mesh_evb_pro/platformio.ini @@ -0,0 +1,58 @@ +[GAT562_Mesh_EVB_Pro] +extends = nrf52_base +board = rak4631 +board_check = true +build_flags = ${nrf52_base.build_flags} + ${sensor_base.build_flags} + -I variants/gat562_mesh_evb_pro + -D NRF52_POWER_MANAGEMENT + -D LORA_FREQ=475 + -D LORA_BW=125 + -D LORA_SF=10 + -D LORA_CR=6 + -D PIN_BOARD_SCL=14 + -D PIN_BOARD_SDA=13 + -D USB_MANUFACTURER='"GAT562"' + -D USB_PRODUCT='"GAT562 Mesh EVB Pro"' + -D RADIO_CLASS=CustomSX1262 + -D WRAPPER_CLASS=CustomSX1262Wrapper + -D LORA_TX_POWER=22 + -D SX126X_CURRENT_LIMIT=140 + -D SX126X_RX_BOOSTED_GAIN=1 +build_src_filter = ${nrf52_base.build_src_filter} + +<../variants/gat562_mesh_evb_pro> + + + + +lib_deps = + ${nrf52_base.lib_deps} + ${sensor_base.lib_deps} + sparkfun/SparkFun u-blox GNSS Arduino Library@^2.2.27 + +[env:GAT562_Mesh_EVB_Pro_repeater] +extends = GAT562_Mesh_EVB_Pro +build_flags = + ${GAT562_Mesh_EVB_Pro.build_flags} + -D ADVERT_NAME='"GAT562 EVB Pro"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + -D MAX_NEIGHBOURS=50 + -D MESH_PACKET_LOGGING=1 + -D MESH_DEBUG=1 +build_src_filter = ${GAT562_Mesh_EVB_Pro.build_src_filter} + +<../examples/simple_repeater> + + +[env:GAT562_Mesh_EVB_Pro_room_server] +extends = GAT562_Mesh_EVB_Pro +build_flags = + ${GAT562_Mesh_EVB_Pro.build_flags} + -D ADVERT_NAME='"GAT562 EVB Pro Room"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + -D ROOM_PASSWORD='"hello"' + -D MESH_PACKET_LOGGING=1 + -D MESH_DEBUG=1 +build_src_filter = ${GAT562_Mesh_EVB_Pro.build_src_filter} + +<../examples/simple_room_server> diff --git a/variants/gat562_mesh_evb_pro/target.cpp b/variants/gat562_mesh_evb_pro/target.cpp new file mode 100644 index 0000000000..368b5fa19d --- /dev/null +++ b/variants/gat562_mesh_evb_pro/target.cpp @@ -0,0 +1,58 @@ +#include +#include "target.h" +#include + +GAT562EVBProBoard board; + +#ifndef PIN_USER_BTN + #define PIN_USER_BTN (-1) +#endif + + +#ifdef DISPLAY_CLASS + DISPLAY_CLASS display; + MomentaryButton user_btn(PIN_USER_BTN, 1000, true, false, false); + + MomentaryButton back_btn(PIN_BACK_BTN, 1000, true, false, true); +#endif + + +RADIO_CLASS radio = new Module(P_LORA_NSS, P_LORA_DIO_1, P_LORA_RESET, P_LORA_BUSY, SPI); + +WRAPPER_CLASS radio_driver(radio, board); + +VolatileRTCClock fallback_clock; +AutoDiscoverRTCClock rtc_clock(fallback_clock); + +#if ENV_INCLUDE_GPS + #include + MicroNMEALocationProvider nmea = MicroNMEALocationProvider(Serial1, &rtc_clock); + EnvironmentSensorManager sensors = EnvironmentSensorManager(nmea); +#else + EnvironmentSensorManager sensors; +#endif + +bool radio_init() { + rtc_clock.begin(Wire); + return radio.std_init(&SPI); +} + +uint32_t radio_get_rng_seed() { + return radio.random(0x7FFFFFFF); +} + +void radio_set_params(float freq, float bw, uint8_t sf, uint8_t cr) { + radio.setFrequency(freq); + radio.setSpreadingFactor(sf); + radio.setBandwidth(bw); + radio.setCodingRate(cr); +} + +void radio_set_tx_power(int8_t dbm) { + radio.setOutputPower(dbm); +} + +mesh::LocalIdentity radio_new_identity() { + RadioNoiseListener rng(radio); + return mesh::LocalIdentity(&rng); // create new random identity +} diff --git a/variants/gat562_mesh_evb_pro/target.h b/variants/gat562_mesh_evb_pro/target.h new file mode 100644 index 0000000000..2a3c6f87c9 --- /dev/null +++ b/variants/gat562_mesh_evb_pro/target.h @@ -0,0 +1,29 @@ +#pragma once + +#define RADIOLIB_STATIC_ONLY 1 +#include +#include +#include +#include +#include +#include + +#ifdef DISPLAY_CLASS + #include + extern DISPLAY_CLASS display; + #include + extern MomentaryButton user_btn; + + extern MomentaryButton back_btn; +#endif + +extern GAT562EVBProBoard board; +extern WRAPPER_CLASS radio_driver; +extern AutoDiscoverRTCClock rtc_clock; +extern EnvironmentSensorManager sensors; + +bool radio_init(); +uint32_t radio_get_rng_seed(); +void radio_set_params(float freq, float bw, uint8_t sf, uint8_t cr); +void radio_set_tx_power(int8_t dbm); +mesh::LocalIdentity radio_new_identity(); diff --git a/variants/gat562_mesh_evb_pro/variant.cpp b/variants/gat562_mesh_evb_pro/variant.cpp new file mode 100644 index 0000000000..4bbfd78f05 --- /dev/null +++ b/variants/gat562_mesh_evb_pro/variant.cpp @@ -0,0 +1,49 @@ +/* + Copyright (c) 2014-2015 Arduino LLC. All right reserved. + Copyright (c) 2016 Sandeep Mistry All right reserved. + Copyright (c) 2018, Adafruit Industries (adafruit.com) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +*/ + +#include "variant.h" +#include "wiring_constants.h" +#include "wiring_digital.h" +#include "nrf.h" + +const uint32_t g_ADigitalPinMap[] = +{ + // P0 + 0 , 1 , 2 , 3 , 4 , 5 , 6 , 7 , + 8 , 9 , 10, 11, 12, 13, 14, 15, + 16, 17, 18, 19, 20, 21, 22, 23, + 24, 25, 26, 27, 28, 29, 30, 31, + + // P1 + 32, 33, 34, 35, 36, 37, 38, 39, + 40, 41, 42, 43, 44, 45, 46, 47 +}; + + +void initVariant() +{ + // LED1 & LED2 + pinMode(PIN_LED1, OUTPUT); + ledOff(PIN_LED1); + + // pinMode(PIN_LED2, OUTPUT); + // ledOff(PIN_LED2);; +} + diff --git a/variants/gat562_mesh_evb_pro/variant.h b/variants/gat562_mesh_evb_pro/variant.h new file mode 100644 index 0000000000..b0e54a7941 --- /dev/null +++ b/variants/gat562_mesh_evb_pro/variant.h @@ -0,0 +1,216 @@ +/* + Copyright (c) 2014-2015 Arduino LLC. All right reserved. + Copyright (c) 2016 Sandeep Mistry All right reserved. + Copyright (c) 2018, Adafruit Industries (adafruit.com) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU Lesser General Public License for more details. + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +*/ + +#ifndef _VARIANT_RAK4630_ +#define _VARIANT_RAK4630_ + +#define RAK4630 + +/** Master clock frequency */ +#define VARIANT_MCK (64000000ul) + +#define USE_LFXO // Board uses 32khz crystal for LF +// define USE_LFRC // Board uses RC for LF + +/*---------------------------------------------------------------------------- + * Headers + *----------------------------------------------------------------------------*/ + +#include "WVariant.h" + +#ifdef __cplusplus +extern "C" +{ +#endif // __cplusplus + + /* + * WisBlock Base GPIO definitions + */ + static const uint8_t WB_IO1 = 17; // SLOT_A SLOT_B + static const uint8_t WB_IO2 = 34; // SLOT_A SLOT_B + static const uint8_t WB_IO3 = 21; // SLOT_C + static const uint8_t WB_IO4 = 4; // SLOT_C + static const uint8_t WB_IO5 = 9; // SLOT_D + static const uint8_t WB_IO6 = 10; // SLOT_D + static const uint8_t WB_SW1 = 33; // IO_SLOT + static const uint8_t WB_A0 = 5; // IO_SLOT + static const uint8_t WB_A1 = 31; // IO_SLOT + static const uint8_t WB_I2C1_SDA = 13; // SENSOR_SLOT IO_SLOT + static const uint8_t WB_I2C1_SCL = 14; // SENSOR_SLOT IO_SLOT + static const uint8_t WB_I2C2_SDA = 24; // IO_SLOT + static const uint8_t WB_I2C2_SCL = 25; // IO_SLOT + static const uint8_t WB_SPI_CS = 26; // IO_SLOT + static const uint8_t WB_SPI_CLK = 3; // IO_SLOT + static const uint8_t WB_SPI_MISO = 29; // IO_SLOT + static const uint8_t WB_SPI_MOSI = 30; // IO_SLOT + +// Number of pins defined in PinDescription array +#define PINS_COUNT (48) +#define NUM_DIGITAL_PINS (48) +#define NUM_ANALOG_INPUTS (6) +#define NUM_ANALOG_OUTPUTS (0) + +// LEDs +#define PIN_LED1 (35) +#define PIN_LED2 (36) + +#define LED_BUILTIN PIN_LED1 +#define LED_CONN PIN_LED2 + +#define LED_GREEN PIN_LED1 +#define LED_BLUE PIN_LED2 + +#define LED_STATE_ON 1 // State when LED is litted + +// #define P_LORA_TX_LED LED_GREEN + + +/* + * Buttons + */ +#define PIN_BUTTON1 (9) // Menu / User Button +#define PIN_BACK_BTN PIN_BUTTON1 +#define PIN_USER_BTN PIN_BUTTON1 + + +// Analog pins +#define PIN_VBAT_READ (5) +#define ADC_MULTIPLIER (3 * 1.75 * 1.187 * 1000) + + +/* + * Analog pins + */ +#define PIN_A0 (5) //(3) +#define PIN_A1 (31) //(4) +#define PIN_A2 (28) +#define PIN_A3 (29) +#define PIN_A4 (30) +#define PIN_A5 (31) +#define PIN_A6 (0xff) +#define PIN_A7 (0xff) + + static const uint8_t A0 = PIN_A0; + static const uint8_t A1 = PIN_A1; + static const uint8_t A2 = PIN_A2; + static const uint8_t A3 = PIN_A3; + static const uint8_t A4 = PIN_A4; + static const uint8_t A5 = PIN_A5; + static const uint8_t A6 = PIN_A6; + static const uint8_t A7 = PIN_A7; +#define ADC_RESOLUTION 14 + +// Power management boot protection threshold (millivolts) +// Set to 0 to disable boot protection +#define PWRMGT_VOLTAGE_BOOTLOCK 3300 // Won't boot below this voltage (mV) +// LPCOMP wake configuration (voltage recovery from SYSTEMOFF) +// AIN3 = P0.05 = PIN_A0 / PIN_VBAT_READ +#define PWRMGT_LPCOMP_AIN 3 +#define PWRMGT_LPCOMP_REFSEL 4 // 5/8 VDD (~3.13-3.44V) + +// Other pins +#define PIN_AREF (2) +#define PIN_NFC1 (9) +#define PIN_NFC2 (10) + + static const uint8_t AREF = PIN_AREF; + +/* + * Serial interfaces + */ +// TXD1 RXD1 on Base Board +#define PIN_SERIAL1_RX (15) +#define PIN_SERIAL1_TX (16) + +// TXD0 RXD0 on Base Board +#define PIN_SERIAL2_RX (19) +#define PIN_SERIAL2_TX (20) + +/* + * SPI Interfaces + */ +#define SPI_INTERFACES_COUNT 1 + +#define PIN_SPI_MISO (29) +#define PIN_SPI_MOSI (30) +#define PIN_SPI_SCK (3) + + static const uint8_t SS = 26; + static const uint8_t MOSI = PIN_SPI_MOSI; + static const uint8_t MISO = PIN_SPI_MISO; + static const uint8_t SCK = PIN_SPI_SCK; + +// LoRa radio module pins for RAK4631 + +#define SX126X_POWER_EN (37) +#define P_LORA_RESET (38) +#define P_LORA_NSS (42) +#define P_LORA_SCLK (43) +#define P_LORA_MOSI (44) +#define P_LORA_MISO (45) +#define P_LORA_BUSY (46) +#define P_LORA_DIO_1 (47) + +#define SX126X_DIO2_AS_RF_SWITCH true +#define SX126X_DIO3_TCXO_VOLTAGE 1.8 + +/* + * Wire Interfaces + */ +#define WIRE_INTERFACES_COUNT 2 + +#define PIN_WIRE_SDA (13) +#define PIN_WIRE_SCL (14) + +#define PIN_WIRE1_SDA (24) +#define PIN_WIRE1_SCL (25) + +// QSPI Pins +// QSPI occupied by GPIO's +#define PIN_QSPI_SCK 3 // 19 +#define PIN_QSPI_CS 26 // 17 +#define PIN_QSPI_IO0 30 // 20 +#define PIN_QSPI_IO1 29 // 21 +#define PIN_QSPI_IO2 28 // 22 +#define PIN_QSPI_IO3 2 // 23 + +// On-board QSPI Flash +// No onboard flash +#define EXTERNAL_FLASH_DEVICES IS25LP080D +#define EXTERNAL_FLASH_USE_QSPI + +#define GPS_ADDRESS 0x42 //i2c address for GPS + + +// GPS L76KB +#define GPS_BAUD_RATE 9600 +#define GPS_THREAD_INTERVAL 50 +#define PIN_GPS_TX PIN_SERIAL1_RX +#define PIN_GPS_RX PIN_SERIAL1_TX +#define PIN_GPS_EN (33) +#define PIN_GPS_PPS (17) + +#ifdef __cplusplus +} +#endif + +/*---------------------------------------------------------------------------- + * Arduino objects - C++ only + *----------------------------------------------------------------------------*/ + +#endif diff --git a/variants/gat562_mesh_tracker_pro/platformio.ini b/variants/gat562_mesh_tracker_pro/platformio.ini index afe62c9843..f442a8608b 100644 --- a/variants/gat562_mesh_tracker_pro/platformio.ini +++ b/variants/gat562_mesh_tracker_pro/platformio.ini @@ -5,8 +5,6 @@ board_check = true build_flags = ${nrf52_base.build_flags} ${sensor_base.build_flags} -I variants/gat562_mesh_tracker_pro - -D RAK_4631 - -D RAK_BOARD -D NRF52_POWER_MANAGEMENT -D LORA_FREQ=475 -D LORA_BW=125 From 69123ca056de2ef3343f9b4194dd44825f5c0561 Mon Sep 17 00:00:00 2001 From: whywilson Date: Tue, 17 Mar 2026 19:45:56 +0800 Subject: [PATCH 12/52] Update GAT562_Mesh_EVB_Pro Config and remove LoRa Specification and change Repeater name. --- variants/gat562_mesh_evb_pro/platformio.ini | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/variants/gat562_mesh_evb_pro/platformio.ini b/variants/gat562_mesh_evb_pro/platformio.ini index b6adf3858b..e7d9ac267a 100644 --- a/variants/gat562_mesh_evb_pro/platformio.ini +++ b/variants/gat562_mesh_evb_pro/platformio.ini @@ -6,10 +6,6 @@ build_flags = ${nrf52_base.build_flags} ${sensor_base.build_flags} -I variants/gat562_mesh_evb_pro -D NRF52_POWER_MANAGEMENT - -D LORA_FREQ=475 - -D LORA_BW=125 - -D LORA_SF=10 - -D LORA_CR=6 -D PIN_BOARD_SCL=14 -D PIN_BOARD_SDA=13 -D USB_MANUFACTURER='"GAT562"' @@ -32,13 +28,13 @@ lib_deps = extends = GAT562_Mesh_EVB_Pro build_flags = ${GAT562_Mesh_EVB_Pro.build_flags} - -D ADVERT_NAME='"GAT562 EVB Pro"' + -D ADVERT_NAME='"GAT562 EVB Pro Repeater"' -D ADVERT_LAT=0.0 -D ADVERT_LON=0.0 -D ADMIN_PASSWORD='"password"' -D MAX_NEIGHBOURS=50 - -D MESH_PACKET_LOGGING=1 - -D MESH_DEBUG=1 +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 build_src_filter = ${GAT562_Mesh_EVB_Pro.build_src_filter} +<../examples/simple_repeater> @@ -47,12 +43,12 @@ build_src_filter = ${GAT562_Mesh_EVB_Pro.build_src_filter} extends = GAT562_Mesh_EVB_Pro build_flags = ${GAT562_Mesh_EVB_Pro.build_flags} - -D ADVERT_NAME='"GAT562 EVB Pro Room"' + -D ADVERT_NAME='"GAT562 EVB Pro Room Server"' -D ADVERT_LAT=0.0 -D ADVERT_LON=0.0 -D ADMIN_PASSWORD='"password"' -D ROOM_PASSWORD='"hello"' - -D MESH_PACKET_LOGGING=1 - -D MESH_DEBUG=1 +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 build_src_filter = ${GAT562_Mesh_EVB_Pro.build_src_filter} +<../examples/simple_room_server> From 9b842786079da41efd7e8c23dc1bdf482872f11b Mon Sep 17 00:00:00 2001 From: Janez T Date: Thu, 5 Mar 2026 13:23:23 +0100 Subject: [PATCH 13/52] feat: Add support for PAYLOAD_TYPE_GRP_DATA Docs changes are to reflect how it is currently in fw This adds ability to send datagram data to everyone in channel --- docs/companion_protocol.md | 67 +++++++++++++++++++++------- examples/companion_radio/MyMesh.cpp | 68 ++++++++++++++++++++++++++--- examples/companion_radio/MyMesh.h | 2 + src/helpers/BaseChatMesh.cpp | 28 +++++++++++- src/helpers/BaseChatMesh.h | 3 ++ src/helpers/TxtDataHelpers.h | 1 + 6 files changed, 148 insertions(+), 21 deletions(-) diff --git a/docs/companion_protocol.md b/docs/companion_protocol.md index 11ba0ab24c..0b83fddbe2 100644 --- a/docs/companion_protocol.md +++ b/docs/companion_protocol.md @@ -257,31 +257,56 @@ Bytes 34-49: Secret (16 bytes) --- -### 5. Send Channel Message +### 5. Send Channel Text Message -**Purpose**: Send a text message to a channel. +**Purpose**: Send a plain text message to a channel. **Command Format**: ``` Byte 0: 0x03 -Byte 1: 0x00 +Byte 1: Text Type Byte 2: Channel Index (0-7) Bytes 3-6: Timestamp (32-bit little-endian Unix timestamp, seconds) -Bytes 7+: Message Text (UTF-8, variable length) +Bytes 7+: UTF-8 text bytes (variable length) ``` **Timestamp**: Unix timestamp in seconds (32-bit unsigned integer, little-endian) +**Text Type**: +- Must be `0x00` (`TXT_TYPE_PLAIN`) for this command. + **Example** (send "Hello" to channel 1 at timestamp 1234567890): ``` 03 00 01 D2 02 96 49 48 65 6C 6C 6F ``` -**Response**: `PACKET_MSG_SENT` (0x06) on success +**Response**: `PACKET_OK` (0x00) on success + +--- + +### 6. Send Channel Data Datagram + +**Purpose**: Send binary datagram data to a channel. + +**Command Format**: +``` +Byte 0: 0x3E +Byte 1: Data Type (`txt_type`) +Byte 2: Channel Index (0-7) +Bytes 3-6: Timestamp (32-bit little-endian Unix timestamp, seconds) +Bytes 7+: Binary payload bytes (variable length) +``` + +**Data Type / Transport Mapping**: +- `0xFF` (`TXT_TYPE_CUSTOM_BINARY`) is the custom-app binary type. +- `0x00` (`TXT_TYPE_PLAIN`) is invalid for this command. +- Values other than `0xFF` are reserved for official protocol extensions. + +**Response**: `PACKET_OK` (0x00) on success --- -### 6. Get Message +### 7. Get Message **Purpose**: Request the next queued message from the device. @@ -304,7 +329,7 @@ Byte 0: 0x0A --- -### 7. Get Battery and Storage +### 8. Get Battery and Storage **Purpose**: Query device battery voltage and storage usage. @@ -446,7 +471,7 @@ Byte 1: Channel Index (0-7) Byte 2: Path Length Byte 3: Text Type Bytes 4-7: Timestamp (32-bit little-endian) -Bytes 8+: Message Text (UTF-8) +Bytes 8+: Payload bytes ``` **V3 Format** (`PACKET_CHANNEL_MSG_RECV_V3`, 0x11): @@ -458,9 +483,14 @@ Byte 4: Channel Index (0-7) Byte 5: Path Length Byte 6: Text Type Bytes 7-10: Timestamp (32-bit little-endian) -Bytes 11+: Message Text (UTF-8) +Bytes 11+: Payload bytes ``` +**Payload Meaning**: +- If `txt_type == 0x00`: payload is UTF-8 channel text. +- If `txt_type != 0x00`: payload is binary (for example image/voice fragments) and must be treated as raw bytes. + For custom app datagrams sent via `CMD_SEND_CHANNEL_DATA`, use `txt_type == 0xFF`. + **Parsing Pseudocode**: ```python def parse_channel_message(data): @@ -477,11 +507,17 @@ def parse_channel_message(data): path_len = data[offset + 1] txt_type = data[offset + 2] timestamp = int.from_bytes(data[offset+3:offset+7], 'little') - message = data[offset+7:].decode('utf-8') + payload = data[offset+7:] + if txt_type == 0: + message = payload.decode('utf-8') + else: + message = None return { 'channel_idx': channel_idx, + 'txt_type': txt_type, 'timestamp': timestamp, + 'payload': payload, 'message': message, 'snr': snr if packet_type == 0x11 else None } @@ -489,7 +525,7 @@ def parse_channel_message(data): ### Sending Messages -Use the `SEND_CHANNEL_MESSAGE` command (see [Commands](#commands)). +Use `CMD_SEND_CHANNEL_TXT_MSG` for plain text, and `CMD_SEND_CHANNEL_DATA` for binary datagrams (see [Commands](#commands)). **Important**: - Messages are limited to 133 characters per MeshCore specification @@ -510,7 +546,7 @@ Use the `SEND_CHANNEL_MESSAGE` command (see [Commands](#commands)). | 0x03 | PACKET_CONTACT | Contact information | | 0x04 | PACKET_CONTACT_END | End of contact list | | 0x05 | PACKET_SELF_INFO | Device self-information | -| 0x06 | PACKET_MSG_SENT | Message sent confirmation | +| 0x06 | PACKET_MSG_SENT | Direct message sent confirmation | | 0x07 | PACKET_CONTACT_MSG_RECV | Contact message (standard) | | 0x08 | PACKET_CHANNEL_MSG_RECV | Channel message (standard) | | 0x09 | PACKET_CURRENT_TIME | Current time response | @@ -675,7 +711,7 @@ def parse_self_info(data): return info ``` -**PACKET_MSG_SENT** (0x06): +**PACKET_MSG_SENT** (0x06, used by direct/contact send flows): ``` Byte 0: 0x06 Byte 1: Route Flag (0 = direct, 1 = flood) @@ -737,7 +773,8 @@ BLE implementations enqueue and deliver one protocol frame per BLE write/notific - `DEVICE_QUERY` → `PACKET_DEVICE_INFO` - `GET_CHANNEL` → `PACKET_CHANNEL_INFO` - `SET_CHANNEL` → `PACKET_OK` or `PACKET_ERROR` - - `SEND_CHANNEL_MESSAGE` → `PACKET_MSG_SENT` + - `CMD_SEND_CHANNEL_TXT_MSG` → `PACKET_OK` or `PACKET_ERROR` + - `CMD_SEND_CHANNEL_DATA` → `PACKET_OK` or `PACKET_ERROR` - `GET_MESSAGE` → `PACKET_CHANNEL_MSG_RECV`, `PACKET_CONTACT_MSG_RECV`, or `PACKET_NO_MORE_MSGS` - `GET_BATTERY` → `PACKET_BATTERY` @@ -809,7 +846,7 @@ command = build_channel_message(channel_index, message, timestamp) # 2. Send command send_command(rx_char, command) -response = wait_for_response(PACKET_MSG_SENT) +response = wait_for_response(PACKET_OK) ``` ### Receiving Messages diff --git a/examples/companion_radio/MyMesh.cpp b/examples/companion_radio/MyMesh.cpp index 1f71a9bc6c..85df464fc1 100644 --- a/examples/companion_radio/MyMesh.cpp +++ b/examples/companion_radio/MyMesh.cpp @@ -58,6 +58,7 @@ #define CMD_GET_AUTOADD_CONFIG 59 #define CMD_GET_ALLOWED_REPEAT_FREQ 60 #define CMD_SET_PATH_HASH_MODE 61 +#define CMD_SEND_CHANNEL_DATA 62 // Stats sub-types for CMD_GET_STATS #define STATS_TYPE_CORE 0 @@ -564,6 +565,41 @@ void MyMesh::onChannelMessageRecv(const mesh::GroupChannel &channel, mesh::Packe #endif } +void MyMesh::onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, uint8_t txt_type, + const uint8_t *data, size_t data_len) { + int i = 0; + if (app_target_ver >= 3) { + out_frame[i++] = RESP_CODE_CHANNEL_MSG_RECV_V3; + out_frame[i++] = (int8_t)(pkt->getSNR() * 4); + out_frame[i++] = 0; // reserved1 + out_frame[i++] = 0; // reserved2 + } else { + out_frame[i++] = RESP_CODE_CHANNEL_MSG_RECV; + } + + uint8_t channel_idx = findChannelIdx(channel); + out_frame[i++] = channel_idx; + out_frame[i++] = pkt->isRouteFlood() ? pkt->path_len : 0xFF; + out_frame[i++] = txt_type; + memcpy(&out_frame[i], ×tamp, 4); + i += 4; + + size_t available = MAX_FRAME_SIZE - i; + if (data_len > available) data_len = available; + int copy_len = (int)data_len; + if (copy_len > 0) { + memcpy(&out_frame[i], data, copy_len); + i += copy_len; + } + addToOfflineQueue(out_frame, i); + + if (_serial->isConnected()) { + uint8_t frame[1]; + frame[0] = PUSH_CODE_MSG_WAITING; // send push 'tickle' + _serial->writeFrame(frame, 1); + } +} + uint8_t MyMesh::onContactRequest(const ContactInfo &contact, uint32_t sender_timestamp, const uint8_t *data, uint8_t len, uint8_t *reply) { if (data[0] == REQ_TYPE_GET_TELEMETRY_DATA) { @@ -1031,26 +1067,48 @@ void MyMesh::handleCmdFrame(size_t len) { ? ERR_CODE_NOT_FOUND : ERR_CODE_UNSUPPORTED_CMD); // unknown recipient, or unsuported TXT_TYPE_* } - } else if (cmd_frame[0] == CMD_SEND_CHANNEL_TXT_MSG) { // send GroupChannel msg + } else if (cmd_frame[0] == CMD_SEND_CHANNEL_TXT_MSG) { // send GroupChannel text msg int i = 1; - uint8_t txt_type = cmd_frame[i++]; // should be TXT_TYPE_PLAIN + uint8_t txt_type = cmd_frame[i++]; uint8_t channel_idx = cmd_frame[i++]; uint32_t msg_timestamp; memcpy(&msg_timestamp, &cmd_frame[i], 4); i += 4; const char *text = (char *)&cmd_frame[i]; + int text_len = (len > (size_t)i) ? (int)(len - i) : 0; if (txt_type != TXT_TYPE_PLAIN) { writeErrFrame(ERR_CODE_UNSUPPORTED_CMD); } else { ChannelDetails channel; - bool success = getChannel(channel_idx, channel); - if (success && sendGroupMessage(msg_timestamp, channel.channel, _prefs.node_name, text, len - i)) { + if (!getChannel(channel_idx, channel)) { + writeErrFrame(ERR_CODE_NOT_FOUND); // bad channel_idx + } else if (sendGroupMessage(msg_timestamp, channel.channel, _prefs.node_name, text, text_len)) { writeOKFrame(); } else { - writeErrFrame(ERR_CODE_NOT_FOUND); // bad channel_idx + writeErrFrame(ERR_CODE_TABLE_FULL); } } + } else if (cmd_frame[0] == CMD_SEND_CHANNEL_DATA) { // send GroupChannel datagram + int i = 1; + uint8_t txt_type = cmd_frame[i++]; + uint8_t channel_idx = cmd_frame[i++]; + uint32_t msg_timestamp; + memcpy(&msg_timestamp, &cmd_frame[i], 4); + i += 4; + const uint8_t *payload = &cmd_frame[i]; + int payload_len = (len > (size_t)i) ? (int)(len - i) : 0; + + ChannelDetails channel; + if (!getChannel(channel_idx, channel)) { + writeErrFrame(ERR_CODE_NOT_FOUND); // bad channel_idx + } else if (txt_type != TXT_TYPE_CUSTOM_BINARY) { + writeErrFrame(ERR_CODE_UNSUPPORTED_CMD); + } else if (sendGroupData(msg_timestamp, channel.channel, txt_type, payload, payload_len)) { + writeOKFrame(); + } else { + writeErrFrame(ERR_CODE_TABLE_FULL); + } } else if (cmd_frame[0] == CMD_GET_CONTACTS) { // get Contact list if (_iter_started) { writeErrFrame(ERR_CODE_BAD_STATE); // iterator is currently busy diff --git a/examples/companion_radio/MyMesh.h b/examples/companion_radio/MyMesh.h index 4d77b5ab7a..0e11264761 100644 --- a/examples/companion_radio/MyMesh.h +++ b/examples/companion_radio/MyMesh.h @@ -137,6 +137,8 @@ class MyMesh : public BaseChatMesh, public DataStoreHost { const uint8_t *sender_prefix, const char *text) override; void onChannelMessageRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, const char *text) override; + void onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, uint8_t txt_type, + const uint8_t *data, size_t data_len) override; uint8_t onContactRequest(const ContactInfo &contact, uint32_t sender_timestamp, const uint8_t *data, uint8_t len, uint8_t *reply) override; diff --git a/src/helpers/BaseChatMesh.cpp b/src/helpers/BaseChatMesh.cpp index 33d7edbee4..e6f59a50b0 100644 --- a/src/helpers/BaseChatMesh.cpp +++ b/src/helpers/BaseChatMesh.cpp @@ -353,8 +353,10 @@ int BaseChatMesh::searchChannelsByHash(const uint8_t* hash, mesh::GroupChannel d #endif void BaseChatMesh::onGroupDataRecv(mesh::Packet* packet, uint8_t type, const mesh::GroupChannel& channel, uint8_t* data, size_t len) { + if (len < 5) return; + uint8_t txt_type = data[4]; - if (type == PAYLOAD_TYPE_GRP_TXT && len > 5 && (txt_type >> 2) == 0) { // 0 = plain text msg + if (type == PAYLOAD_TYPE_GRP_TXT && (txt_type >> 2) == 0) { // 0 = plain text msg uint32_t timestamp; memcpy(×tamp, data, 4); @@ -363,6 +365,10 @@ void BaseChatMesh::onGroupDataRecv(mesh::Packet* packet, uint8_t type, const mes // notify UI of this new message onChannelMessageRecv(channel, packet, timestamp, (const char *) &data[5]); // let UI know + } else if (type == PAYLOAD_TYPE_GRP_DATA) { + uint32_t timestamp; + memcpy(×tamp, data, 4); + onChannelDataRecv(channel, packet, timestamp, txt_type, &data[5], len - 5); } } @@ -454,6 +460,26 @@ bool BaseChatMesh::sendGroupMessage(uint32_t timestamp, mesh::GroupChannel& chan return false; } +bool BaseChatMesh::sendGroupData(uint32_t timestamp, mesh::GroupChannel& channel, uint8_t txt_type, const uint8_t* data, int data_len) { + if (data_len < 0) return false; + // createGroupDatagram() accepts at most (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE) + // plaintext bytes; subtract our 5-byte {timestamp, txt_type} header. + const int max_group_data_len = (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE) - 5; + if (data_len > max_group_data_len) data_len = max_group_data_len; + + uint8_t temp[MAX_PACKET_PAYLOAD]; + memcpy(temp, ×tamp, 4); + temp[4] = txt_type; + if (data_len > 0) memcpy(&temp[5], data, data_len); + + auto pkt = createGroupDatagram(PAYLOAD_TYPE_GRP_DATA, channel, temp, 5 + data_len); + if (pkt) { + sendFloodScoped(channel, pkt); + return true; + } + return false; +} + bool BaseChatMesh::shareContactZeroHop(const ContactInfo& contact) { int plen = getBlobByKey(contact.id.pub_key, PUB_KEY_SIZE, temp_buf); // retrieve last raw advert packet if (plen == 0) return false; // not found diff --git a/src/helpers/BaseChatMesh.h b/src/helpers/BaseChatMesh.h index ab90d581be..02b2dfabb2 100644 --- a/src/helpers/BaseChatMesh.h +++ b/src/helpers/BaseChatMesh.h @@ -111,6 +111,8 @@ class BaseChatMesh : public mesh::Mesh { virtual uint32_t calcDirectTimeoutMillisFor(uint32_t pkt_airtime_millis, uint8_t path_len) const = 0; virtual void onSendTimeout() = 0; virtual void onChannelMessageRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t timestamp, const char *text) = 0; + virtual void onChannelDataRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t timestamp, uint8_t txt_type, + const uint8_t* data, size_t data_len) {} virtual uint8_t onContactRequest(const ContactInfo& contact, uint32_t sender_timestamp, const uint8_t* data, uint8_t len, uint8_t* reply) = 0; virtual void onContactResponse(const ContactInfo& contact, const uint8_t* data, uint8_t len) = 0; virtual void handleReturnPathRetry(const ContactInfo& contact, const uint8_t* path, uint8_t path_len); @@ -148,6 +150,7 @@ class BaseChatMesh : public mesh::Mesh { int sendMessage(const ContactInfo& recipient, uint32_t timestamp, uint8_t attempt, const char* text, uint32_t& expected_ack, uint32_t& est_timeout); int sendCommandData(const ContactInfo& recipient, uint32_t timestamp, uint8_t attempt, const char* text, uint32_t& est_timeout); bool sendGroupMessage(uint32_t timestamp, mesh::GroupChannel& channel, const char* sender_name, const char* text, int text_len); + bool sendGroupData(uint32_t timestamp, mesh::GroupChannel& channel, uint8_t txt_type, const uint8_t* data, int data_len); int sendLogin(const ContactInfo& recipient, const char* password, uint32_t& est_timeout); int sendAnonReq(const ContactInfo& recipient, const uint8_t* data, uint8_t len, uint32_t& tag, uint32_t& est_timeout); int sendRequest(const ContactInfo& recipient, uint8_t req_type, uint32_t& tag, uint32_t& est_timeout); diff --git a/src/helpers/TxtDataHelpers.h b/src/helpers/TxtDataHelpers.h index 6ab84d3975..0fbbd25357 100644 --- a/src/helpers/TxtDataHelpers.h +++ b/src/helpers/TxtDataHelpers.h @@ -6,6 +6,7 @@ #define TXT_TYPE_PLAIN 0 // a plain text message #define TXT_TYPE_CLI_DATA 1 // a CLI command #define TXT_TYPE_SIGNED_PLAIN 2 // plain text, signed by sender +#define TXT_TYPE_CUSTOM_BINARY 0xFF // custom app binary payload (group/channel datagrams) class StrHelper { public: From 0e98939987a8f825c1f853d3ac1f7e2589d7929f Mon Sep 17 00:00:00 2001 From: Janez T Date: Thu, 5 Mar 2026 14:05:29 +0100 Subject: [PATCH 14/52] feat: Require 0xFF for custom payloads ref: --- docs/companion_protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/companion_protocol.md b/docs/companion_protocol.md index 0b83fddbe2..bf030bfa50 100644 --- a/docs/companion_protocol.md +++ b/docs/companion_protocol.md @@ -298,7 +298,7 @@ Bytes 7+: Binary payload bytes (variable length) ``` **Data Type / Transport Mapping**: -- `0xFF` (`TXT_TYPE_CUSTOM_BINARY`) is the custom-app binary type. +- `0xFF` (`TXT_TYPE_CUSTOM_BINARY`) must be used for custom-protocol binary datagrams. - `0x00` (`TXT_TYPE_PLAIN`) is invalid for this command. - Values other than `0xFF` are reserved for official protocol extensions. @@ -489,7 +489,7 @@ Bytes 11+: Payload bytes **Payload Meaning**: - If `txt_type == 0x00`: payload is UTF-8 channel text. - If `txt_type != 0x00`: payload is binary (for example image/voice fragments) and must be treated as raw bytes. - For custom app datagrams sent via `CMD_SEND_CHANNEL_DATA`, use `txt_type == 0xFF`. + For custom app datagrams sent via `CMD_SEND_CHANNEL_DATA`, `txt_type` must be `0xFF`. **Parsing Pseudocode**: ```python From a21b83b1271884e6f08507d4734440a0349f71d1 Mon Sep 17 00:00:00 2001 From: Janez T Date: Sun, 8 Mar 2026 14:14:26 +0100 Subject: [PATCH 15/52] fix: address comments ref: --- docs/companion_protocol.md | 65 ++++++++++++++++++++++------- examples/companion_radio/MyMesh.cpp | 37 +++++++++------- examples/companion_radio/MyMesh.h | 2 +- src/MeshCore.h | 3 +- src/helpers/BaseChatMesh.cpp | 44 ++++++++++++------- src/helpers/BaseChatMesh.h | 4 +- src/helpers/TxtDataHelpers.h | 2 +- 7 files changed, 107 insertions(+), 50 deletions(-) diff --git a/docs/companion_protocol.md b/docs/companion_protocol.md index bf030bfa50..c00be4a202 100644 --- a/docs/companion_protocol.md +++ b/docs/companion_protocol.md @@ -291,17 +291,21 @@ Bytes 7+: UTF-8 text bytes (variable length) **Command Format**: ``` Byte 0: 0x3E -Byte 1: Data Type (`txt_type`) +Byte 1: Data Type (`data_type`) Byte 2: Channel Index (0-7) Bytes 3-6: Timestamp (32-bit little-endian Unix timestamp, seconds) Bytes 7+: Binary payload bytes (variable length) ``` **Data Type / Transport Mapping**: -- `0xFF` (`TXT_TYPE_CUSTOM_BINARY`) must be used for custom-protocol binary datagrams. +- `0xFF` (`DATA_TYPE_CUSTOM`) must be used for custom-protocol binary datagrams. - `0x00` (`TXT_TYPE_PLAIN`) is invalid for this command. - Values other than `0xFF` are reserved for official protocol extensions. +**Limits**: +- Maximum payload length is `163` bytes (`MAX_GROUP_DATA_LENGTH`). +- Larger payloads are rejected with `PACKET_ERROR` / `ERR_CODE_ILLEGAL_ARG`. + **Response**: `PACKET_OK` (0x00) on success --- @@ -322,6 +326,7 @@ Byte 0: 0x0A **Response**: - `PACKET_CHANNEL_MSG_RECV` (0x08) or `PACKET_CHANNEL_MSG_RECV_V3` (0x11) for channel messages +- `PACKET_CHANNEL_DATA_RECV` (0x1B) or `PACKET_CHANNEL_DATA_RECV_V3` (0x1C) for channel data - `PACKET_CONTACT_MSG_RECV` (0x07) or `PACKET_CONTACT_MSG_RECV_V3` (0x10) for contact messages - `PACKET_NO_MORE_MSGS` (0x0A) if no messages available @@ -391,11 +396,15 @@ Messages are received via the TX characteristic (notifications). The device send - `PACKET_CHANNEL_MSG_RECV` (0x08) - Standard format - `PACKET_CHANNEL_MSG_RECV_V3` (0x11) - Version 3 with SNR -2. **Contact Messages**: +2. **Channel Data**: + - `PACKET_CHANNEL_DATA_RECV` (0x1B) - Standard format + - `PACKET_CHANNEL_DATA_RECV_V3` (0x1C) - Version 3 with SNR + +3. **Contact Messages**: - `PACKET_CONTACT_MSG_RECV` (0x07) - Standard format - `PACKET_CONTACT_MSG_RECV_V3` (0x10) - Version 3 with SNR -3. **Notifications**: +4. **Notifications**: - `PACKET_MESSAGES_WAITING` (0x83) - Indicates messages are queued ### Contact Message Format @@ -489,37 +498,62 @@ Bytes 11+: Payload bytes **Payload Meaning**: - If `txt_type == 0x00`: payload is UTF-8 channel text. - If `txt_type != 0x00`: payload is binary (for example image/voice fragments) and must be treated as raw bytes. - For custom app datagrams sent via `CMD_SEND_CHANNEL_DATA`, `txt_type` must be `0xFF`. + For custom app datagrams sent via `CMD_SEND_CHANNEL_DATA`, `data_type` must be `0xFF`. + +### Channel Data Format + +**Standard Format** (`PACKET_CHANNEL_DATA_RECV`, 0x1B): +``` +Byte 0: 0x1B (packet type) +Byte 1: Channel Index (0-7) +Byte 2: Path Length +Byte 3: Data Type +Bytes 4-7: Timestamp (32-bit little-endian) +Bytes 8+: Payload bytes +``` + +**V3 Format** (`PACKET_CHANNEL_DATA_RECV_V3`, 0x1C): +``` +Byte 0: 0x1C (packet type) +Byte 1: SNR (signed byte, multiplied by 4) +Bytes 2-3: Reserved +Byte 4: Channel Index (0-7) +Byte 5: Path Length +Byte 6: Data Type +Bytes 7-10: Timestamp (32-bit little-endian) +Bytes 11+: Payload bytes +``` **Parsing Pseudocode**: ```python -def parse_channel_message(data): +def parse_channel_frame(data): packet_type = data[0] offset = 1 # Check for V3 format - if packet_type == 0x11: # V3 + if packet_type in (0x11, 0x1C): # V3 snr_byte = data[offset] snr = ((snr_byte if snr_byte < 128 else snr_byte - 256) / 4.0) offset += 3 # Skip SNR + reserved channel_idx = data[offset] path_len = data[offset + 1] - txt_type = data[offset + 2] + item_type = data[offset + 2] timestamp = int.from_bytes(data[offset+3:offset+7], 'little') payload = data[offset+7:] - if txt_type == 0: + is_text = packet_type in (0x08, 0x11) + if is_text and item_type == 0: message = payload.decode('utf-8') else: message = None return { 'channel_idx': channel_idx, - 'txt_type': txt_type, + 'item_type': item_type, 'timestamp': timestamp, 'payload': payload, 'message': message, - 'snr': snr if packet_type == 0x11 else None + 'snr': snr if packet_type in (0x11, 0x1C) else None } ``` @@ -556,6 +590,8 @@ Use `CMD_SEND_CHANNEL_TXT_MSG` for plain text, and `CMD_SEND_CHANNEL_DATA` for b | 0x10 | PACKET_CONTACT_MSG_RECV_V3 | Contact message (V3 with SNR) | | 0x11 | PACKET_CHANNEL_MSG_RECV_V3 | Channel message (V3 with SNR) | | 0x12 | PACKET_CHANNEL_INFO | Channel information | +| 0x1B | PACKET_CHANNEL_DATA_RECV | Channel data (standard) | +| 0x1C | PACKET_CHANNEL_DATA_RECV_V3| Channel data (V3 with SNR) | | 0x80 | PACKET_ADVERTISEMENT | Advertisement packet | | 0x82 | PACKET_ACK | Acknowledgment | | 0x83 | PACKET_MESSAGES_WAITING | Messages waiting notification | @@ -775,7 +811,7 @@ BLE implementations enqueue and deliver one protocol frame per BLE write/notific - `SET_CHANNEL` → `PACKET_OK` or `PACKET_ERROR` - `CMD_SEND_CHANNEL_TXT_MSG` → `PACKET_OK` or `PACKET_ERROR` - `CMD_SEND_CHANNEL_DATA` → `PACKET_OK` or `PACKET_ERROR` - - `GET_MESSAGE` → `PACKET_CHANNEL_MSG_RECV`, `PACKET_CONTACT_MSG_RECV`, or `PACKET_NO_MORE_MSGS` + - `GET_MESSAGE` → `PACKET_CHANNEL_MSG_RECV`, `PACKET_CHANNEL_DATA_RECV`, `PACKET_CONTACT_MSG_RECV`, or `PACKET_NO_MORE_MSGS` - `GET_BATTERY` → `PACKET_BATTERY` 4. **Timeout Handling**: @@ -855,8 +891,9 @@ response = wait_for_response(PACKET_OK) def on_notification_received(data): packet_type = data[0] - if packet_type == PACKET_CHANNEL_MSG_RECV or packet_type == PACKET_CHANNEL_MSG_RECV_V3: - message = parse_channel_message(data) + if packet_type in (PACKET_CHANNEL_MSG_RECV, PACKET_CHANNEL_MSG_RECV_V3, + PACKET_CHANNEL_DATA_RECV, PACKET_CHANNEL_DATA_RECV_V3): + message = parse_channel_frame(data) handle_channel_message(message) elif packet_type == PACKET_MESSAGES_WAITING: # Poll for messages diff --git a/examples/companion_radio/MyMesh.cpp b/examples/companion_radio/MyMesh.cpp index 85df464fc1..490f34a134 100644 --- a/examples/companion_radio/MyMesh.cpp +++ b/examples/companion_radio/MyMesh.cpp @@ -92,6 +92,8 @@ #define RESP_CODE_STATS 24 // v8+, second byte is stats type #define RESP_CODE_AUTOADD_CONFIG 25 #define RESP_ALLOWED_REPEAT_FREQ 26 +#define RESP_CODE_CHANNEL_DATA_RECV 27 +#define RESP_CODE_CHANNEL_DATA_RECV_V3 28 #define SEND_TIMEOUT_BASE_MILLIS 500 #define FLOOD_SEND_TIMEOUT_FACTOR 16.0f @@ -205,7 +207,8 @@ void MyMesh::updateContactFromFrame(ContactInfo &contact, uint32_t& last_mod, co } bool MyMesh::Frame::isChannelMsg() const { - return buf[0] == RESP_CODE_CHANNEL_MSG_RECV || buf[0] == RESP_CODE_CHANNEL_MSG_RECV_V3; + return buf[0] == RESP_CODE_CHANNEL_MSG_RECV || buf[0] == RESP_CODE_CHANNEL_MSG_RECV_V3 || + buf[0] == RESP_CODE_CHANNEL_DATA_RECV || buf[0] == RESP_CODE_CHANNEL_DATA_RECV_V3; } void MyMesh::addToOfflineQueue(const uint8_t frame[], int len) { @@ -565,27 +568,30 @@ void MyMesh::onChannelMessageRecv(const mesh::GroupChannel &channel, mesh::Packe #endif } -void MyMesh::onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, uint8_t txt_type, +void MyMesh::onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, uint8_t data_type, const uint8_t *data, size_t data_len) { int i = 0; if (app_target_ver >= 3) { - out_frame[i++] = RESP_CODE_CHANNEL_MSG_RECV_V3; + out_frame[i++] = RESP_CODE_CHANNEL_DATA_RECV_V3; out_frame[i++] = (int8_t)(pkt->getSNR() * 4); out_frame[i++] = 0; // reserved1 out_frame[i++] = 0; // reserved2 } else { - out_frame[i++] = RESP_CODE_CHANNEL_MSG_RECV; + out_frame[i++] = RESP_CODE_CHANNEL_DATA_RECV; } uint8_t channel_idx = findChannelIdx(channel); out_frame[i++] = channel_idx; out_frame[i++] = pkt->isRouteFlood() ? pkt->path_len : 0xFF; - out_frame[i++] = txt_type; + out_frame[i++] = data_type; memcpy(&out_frame[i], ×tamp, 4); i += 4; size_t available = MAX_FRAME_SIZE - i; - if (data_len > available) data_len = available; + if (data_len > available) { + MESH_DEBUG_PRINTLN("onChannelDataRecv(): payload_len=%d exceeds frame space=%d, truncating", (uint32_t)data_len, (uint32_t)available); + data_len = available; + } int copy_len = (int)data_len; if (copy_len > 0) { memcpy(&out_frame[i], data, copy_len); @@ -1069,29 +1075,27 @@ void MyMesh::handleCmdFrame(size_t len) { } } else if (cmd_frame[0] == CMD_SEND_CHANNEL_TXT_MSG) { // send GroupChannel text msg int i = 1; - uint8_t txt_type = cmd_frame[i++]; + uint8_t txt_type = cmd_frame[i++]; // should be TXT_TYPE_PLAIN uint8_t channel_idx = cmd_frame[i++]; uint32_t msg_timestamp; memcpy(&msg_timestamp, &cmd_frame[i], 4); i += 4; const char *text = (char *)&cmd_frame[i]; - int text_len = (len > (size_t)i) ? (int)(len - i) : 0; if (txt_type != TXT_TYPE_PLAIN) { writeErrFrame(ERR_CODE_UNSUPPORTED_CMD); } else { ChannelDetails channel; - if (!getChannel(channel_idx, channel)) { - writeErrFrame(ERR_CODE_NOT_FOUND); // bad channel_idx - } else if (sendGroupMessage(msg_timestamp, channel.channel, _prefs.node_name, text, text_len)) { + bool success = getChannel(channel_idx, channel); + if (success && sendGroupMessage(msg_timestamp, channel.channel, _prefs.node_name, text, len - i)) { writeOKFrame(); } else { - writeErrFrame(ERR_CODE_TABLE_FULL); + writeErrFrame(ERR_CODE_NOT_FOUND); // bad channel_idx } } } else if (cmd_frame[0] == CMD_SEND_CHANNEL_DATA) { // send GroupChannel datagram int i = 1; - uint8_t txt_type = cmd_frame[i++]; + uint8_t data_type = cmd_frame[i++]; uint8_t channel_idx = cmd_frame[i++]; uint32_t msg_timestamp; memcpy(&msg_timestamp, &cmd_frame[i], 4); @@ -1102,9 +1106,12 @@ void MyMesh::handleCmdFrame(size_t len) { ChannelDetails channel; if (!getChannel(channel_idx, channel)) { writeErrFrame(ERR_CODE_NOT_FOUND); // bad channel_idx - } else if (txt_type != TXT_TYPE_CUSTOM_BINARY) { + } else if (data_type != DATA_TYPE_CUSTOM) { writeErrFrame(ERR_CODE_UNSUPPORTED_CMD); - } else if (sendGroupData(msg_timestamp, channel.channel, txt_type, payload, payload_len)) { + } else if (payload_len > MAX_GROUP_DATA_LENGTH) { + MESH_DEBUG_PRINTLN("CMD_SEND_CHANNEL_DATA payload too long: %d > %d", payload_len, MAX_GROUP_DATA_LENGTH); + writeErrFrame(ERR_CODE_ILLEGAL_ARG); + } else if (sendGroupData(msg_timestamp, channel.channel, data_type, payload, payload_len)) { writeOKFrame(); } else { writeErrFrame(ERR_CODE_TABLE_FULL); diff --git a/examples/companion_radio/MyMesh.h b/examples/companion_radio/MyMesh.h index 0e11264761..78ea6414e1 100644 --- a/examples/companion_radio/MyMesh.h +++ b/examples/companion_radio/MyMesh.h @@ -137,7 +137,7 @@ class MyMesh : public BaseChatMesh, public DataStoreHost { const uint8_t *sender_prefix, const char *text) override; void onChannelMessageRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, const char *text) override; - void onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, uint8_t txt_type, + void onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, uint8_t data_type, const uint8_t *data, size_t data_len) override; uint8_t onContactRequest(const ContactInfo &contact, uint32_t sender_timestamp, const uint8_t *data, diff --git a/src/MeshCore.h b/src/MeshCore.h index 70cd0f0672..3eb4f9354e 100644 --- a/src/MeshCore.h +++ b/src/MeshCore.h @@ -17,6 +17,7 @@ #define PATH_HASH_SIZE 1 #define MAX_PACKET_PAYLOAD 184 +#define MAX_GROUP_DATA_LENGTH (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 5) #define MAX_PATH_SIZE 64 #define MAX_TRANS_UNIT 255 @@ -100,4 +101,4 @@ class RTCClock { } }; -} \ No newline at end of file +} diff --git a/src/helpers/BaseChatMesh.cpp b/src/helpers/BaseChatMesh.cpp index e6f59a50b0..d8e089d545 100644 --- a/src/helpers/BaseChatMesh.cpp +++ b/src/helpers/BaseChatMesh.cpp @@ -353,10 +353,18 @@ int BaseChatMesh::searchChannelsByHash(const uint8_t* hash, mesh::GroupChannel d #endif void BaseChatMesh::onGroupDataRecv(mesh::Packet* packet, uint8_t type, const mesh::GroupChannel& channel, uint8_t* data, size_t len) { - if (len < 5) return; + if (len < 5) { + MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping short group payload len=%d", (uint32_t)len); + return; + } + + uint8_t data_type = data[4]; + if (type == PAYLOAD_TYPE_GRP_TXT) { + if ((data_type >> 2) != 0) { + MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping unsupported group text type=%d", (uint32_t)data_type); + return; + } - uint8_t txt_type = data[4]; - if (type == PAYLOAD_TYPE_GRP_TXT && (txt_type >> 2) == 0) { // 0 = plain text msg uint32_t timestamp; memcpy(×tamp, data, 4); @@ -368,7 +376,7 @@ void BaseChatMesh::onGroupDataRecv(mesh::Packet* packet, uint8_t type, const mes } else if (type == PAYLOAD_TYPE_GRP_DATA) { uint32_t timestamp; memcpy(×tamp, data, 4); - onChannelDataRecv(channel, packet, timestamp, txt_type, &data[5], len - 5); + onChannelDataRecv(channel, packet, timestamp, data_type, &data[5], len - 5); } } @@ -460,24 +468,28 @@ bool BaseChatMesh::sendGroupMessage(uint32_t timestamp, mesh::GroupChannel& chan return false; } -bool BaseChatMesh::sendGroupData(uint32_t timestamp, mesh::GroupChannel& channel, uint8_t txt_type, const uint8_t* data, int data_len) { - if (data_len < 0) return false; - // createGroupDatagram() accepts at most (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE) - // plaintext bytes; subtract our 5-byte {timestamp, txt_type} header. - const int max_group_data_len = (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE) - 5; - if (data_len > max_group_data_len) data_len = max_group_data_len; +bool BaseChatMesh::sendGroupData(uint32_t timestamp, mesh::GroupChannel& channel, uint8_t data_type, const uint8_t* data, int data_len) { + if (data_len < 0) { + MESH_DEBUG_PRINTLN("sendGroupData: invalid negative data_len=%d", data_len); + return false; + } + if (data_len > MAX_GROUP_DATA_LENGTH) { + MESH_DEBUG_PRINTLN("sendGroupData: data_len=%d exceeds max=%d", data_len, MAX_GROUP_DATA_LENGTH); + return false; + } - uint8_t temp[MAX_PACKET_PAYLOAD]; + uint8_t temp[5 + MAX_GROUP_DATA_LENGTH]; memcpy(temp, ×tamp, 4); - temp[4] = txt_type; + temp[4] = data_type; if (data_len > 0) memcpy(&temp[5], data, data_len); auto pkt = createGroupDatagram(PAYLOAD_TYPE_GRP_DATA, channel, temp, 5 + data_len); - if (pkt) { - sendFloodScoped(channel, pkt); - return true; + if (pkt == NULL) { + MESH_DEBUG_PRINTLN("sendGroupData: unable to create group datagram, data_len=%d", data_len); + return false; } - return false; + sendFloodScoped(channel, pkt); + return true; } bool BaseChatMesh::shareContactZeroHop(const ContactInfo& contact) { diff --git a/src/helpers/BaseChatMesh.h b/src/helpers/BaseChatMesh.h index 02b2dfabb2..12fcb95719 100644 --- a/src/helpers/BaseChatMesh.h +++ b/src/helpers/BaseChatMesh.h @@ -111,7 +111,7 @@ class BaseChatMesh : public mesh::Mesh { virtual uint32_t calcDirectTimeoutMillisFor(uint32_t pkt_airtime_millis, uint8_t path_len) const = 0; virtual void onSendTimeout() = 0; virtual void onChannelMessageRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t timestamp, const char *text) = 0; - virtual void onChannelDataRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t timestamp, uint8_t txt_type, + virtual void onChannelDataRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t timestamp, uint8_t data_type, const uint8_t* data, size_t data_len) {} virtual uint8_t onContactRequest(const ContactInfo& contact, uint32_t sender_timestamp, const uint8_t* data, uint8_t len, uint8_t* reply) = 0; virtual void onContactResponse(const ContactInfo& contact, const uint8_t* data, uint8_t len) = 0; @@ -150,7 +150,7 @@ class BaseChatMesh : public mesh::Mesh { int sendMessage(const ContactInfo& recipient, uint32_t timestamp, uint8_t attempt, const char* text, uint32_t& expected_ack, uint32_t& est_timeout); int sendCommandData(const ContactInfo& recipient, uint32_t timestamp, uint8_t attempt, const char* text, uint32_t& est_timeout); bool sendGroupMessage(uint32_t timestamp, mesh::GroupChannel& channel, const char* sender_name, const char* text, int text_len); - bool sendGroupData(uint32_t timestamp, mesh::GroupChannel& channel, uint8_t txt_type, const uint8_t* data, int data_len); + bool sendGroupData(uint32_t timestamp, mesh::GroupChannel& channel, uint8_t data_type, const uint8_t* data, int data_len); int sendLogin(const ContactInfo& recipient, const char* password, uint32_t& est_timeout); int sendAnonReq(const ContactInfo& recipient, const uint8_t* data, uint8_t len, uint32_t& tag, uint32_t& est_timeout); int sendRequest(const ContactInfo& recipient, uint8_t req_type, uint32_t& tag, uint32_t& est_timeout); diff --git a/src/helpers/TxtDataHelpers.h b/src/helpers/TxtDataHelpers.h index 0fbbd25357..a853a64db3 100644 --- a/src/helpers/TxtDataHelpers.h +++ b/src/helpers/TxtDataHelpers.h @@ -6,7 +6,7 @@ #define TXT_TYPE_PLAIN 0 // a plain text message #define TXT_TYPE_CLI_DATA 1 // a CLI command #define TXT_TYPE_SIGNED_PLAIN 2 // plain text, signed by sender -#define TXT_TYPE_CUSTOM_BINARY 0xFF // custom app binary payload (group/channel datagrams) +#define DATA_TYPE_CUSTOM 0xFF // custom app binary payload (group/channel datagrams) class StrHelper { public: From f25d7a882ad5d99540fb9da3fa8f0f84ea85d0bd Mon Sep 17 00:00:00 2001 From: Janez T Date: Wed, 18 Mar 2026 20:14:22 +0100 Subject: [PATCH 16/52] fix: Align channel data framing ref: #1928 --- docs/companion_protocol.md | 42 ++++++++++++----------------- examples/companion_radio/MyMesh.cpp | 33 +++++++++++------------ src/MeshCore.h | 2 +- src/Packet.h | 2 +- src/helpers/BaseChatMesh.cpp | 40 ++++++++++++++++++--------- 5 files changed, 63 insertions(+), 56 deletions(-) diff --git a/docs/companion_protocol.md b/docs/companion_protocol.md index c00be4a202..a8c09bef3e 100644 --- a/docs/companion_protocol.md +++ b/docs/companion_protocol.md @@ -303,7 +303,7 @@ Bytes 7+: Binary payload bytes (variable length) - Values other than `0xFF` are reserved for official protocol extensions. **Limits**: -- Maximum payload length is `163` bytes (`MAX_GROUP_DATA_LENGTH`). +- Maximum payload length is `160` bytes. - Larger payloads are rejected with `PACKET_ERROR` / `ERR_CODE_ILLEGAL_ARG`. **Response**: `PACKET_OK` (0x00) on success @@ -326,7 +326,7 @@ Byte 0: 0x0A **Response**: - `PACKET_CHANNEL_MSG_RECV` (0x08) or `PACKET_CHANNEL_MSG_RECV_V3` (0x11) for channel messages -- `PACKET_CHANNEL_DATA_RECV` (0x1B) or `PACKET_CHANNEL_DATA_RECV_V3` (0x1C) for channel data +- `PACKET_CHANNEL_DATA_RECV` (0x1B) for channel data - `PACKET_CONTACT_MSG_RECV` (0x07) or `PACKET_CONTACT_MSG_RECV_V3` (0x10) for contact messages - `PACKET_NO_MORE_MSGS` (0x0A) if no messages available @@ -397,8 +397,7 @@ Messages are received via the TX characteristic (notifications). The device send - `PACKET_CHANNEL_MSG_RECV_V3` (0x11) - Version 3 with SNR 2. **Channel Data**: - - `PACKET_CHANNEL_DATA_RECV` (0x1B) - Standard format - - `PACKET_CHANNEL_DATA_RECV_V3` (0x1C) - Version 3 with SNR + - `PACKET_CHANNEL_DATA_RECV` (0x1B) - Includes SNR and reserved bytes 3. **Contact Messages**: - `PACKET_CONTACT_MSG_RECV` (0x07) - Standard format @@ -502,26 +501,17 @@ Bytes 11+: Payload bytes ### Channel Data Format -**Standard Format** (`PACKET_CHANNEL_DATA_RECV`, 0x1B): +**Format** (`PACKET_CHANNEL_DATA_RECV`, 0x1B): ``` Byte 0: 0x1B (packet type) -Byte 1: Channel Index (0-7) -Byte 2: Path Length -Byte 3: Data Type -Bytes 4-7: Timestamp (32-bit little-endian) -Bytes 8+: Payload bytes -``` - -**V3 Format** (`PACKET_CHANNEL_DATA_RECV_V3`, 0x1C): -``` -Byte 0: 0x1C (packet type) Byte 1: SNR (signed byte, multiplied by 4) Bytes 2-3: Reserved Byte 4: Channel Index (0-7) Byte 5: Path Length Byte 6: Data Type -Bytes 7-10: Timestamp (32-bit little-endian) -Bytes 11+: Payload bytes +Byte 7: Data Length +Bytes 8-11: Timestamp (32-bit little-endian) +Bytes 12+: Payload bytes ``` **Parsing Pseudocode**: @@ -529,9 +519,10 @@ Bytes 11+: Payload bytes def parse_channel_frame(data): packet_type = data[0] offset = 1 + snr = None - # Check for V3 format - if packet_type in (0x11, 0x1C): # V3 + # Formats with explicit SNR/reserved bytes + if packet_type in (0x11, 0x1B): snr_byte = data[offset] snr = ((snr_byte if snr_byte < 128 else snr_byte - 256) / 4.0) offset += 3 # Skip SNR + reserved @@ -539,8 +530,10 @@ def parse_channel_frame(data): channel_idx = data[offset] path_len = data[offset + 1] item_type = data[offset + 2] - timestamp = int.from_bytes(data[offset+3:offset+7], 'little') - payload = data[offset+7:] + data_len = data[offset + 3] if packet_type == 0x1B else None + timestamp = int.from_bytes(data[offset+4:offset+8], 'little') if packet_type == 0x1B else int.from_bytes(data[offset+3:offset+7], 'little') + payload_offset = offset + 8 if packet_type == 0x1B else offset + 7 + payload = data[payload_offset:payload_offset + data_len] if packet_type == 0x1B else data[payload_offset:] is_text = packet_type in (0x08, 0x11) if is_text and item_type == 0: message = payload.decode('utf-8') @@ -553,7 +546,7 @@ def parse_channel_frame(data): 'timestamp': timestamp, 'payload': payload, 'message': message, - 'snr': snr if packet_type in (0x11, 0x1C) else None + 'snr': snr } ``` @@ -590,8 +583,7 @@ Use `CMD_SEND_CHANNEL_TXT_MSG` for plain text, and `CMD_SEND_CHANNEL_DATA` for b | 0x10 | PACKET_CONTACT_MSG_RECV_V3 | Contact message (V3 with SNR) | | 0x11 | PACKET_CHANNEL_MSG_RECV_V3 | Channel message (V3 with SNR) | | 0x12 | PACKET_CHANNEL_INFO | Channel information | -| 0x1B | PACKET_CHANNEL_DATA_RECV | Channel data (standard) | -| 0x1C | PACKET_CHANNEL_DATA_RECV_V3| Channel data (V3 with SNR) | +| 0x1B | PACKET_CHANNEL_DATA_RECV | Channel data (includes SNR) | | 0x80 | PACKET_ADVERTISEMENT | Advertisement packet | | 0x82 | PACKET_ACK | Acknowledgment | | 0x83 | PACKET_MESSAGES_WAITING | Messages waiting notification | @@ -892,7 +884,7 @@ def on_notification_received(data): packet_type = data[0] if packet_type in (PACKET_CHANNEL_MSG_RECV, PACKET_CHANNEL_MSG_RECV_V3, - PACKET_CHANNEL_DATA_RECV, PACKET_CHANNEL_DATA_RECV_V3): + PACKET_CHANNEL_DATA_RECV): message = parse_channel_frame(data) handle_channel_message(message) elif packet_type == PACKET_MESSAGES_WAITING: diff --git a/examples/companion_radio/MyMesh.cpp b/examples/companion_radio/MyMesh.cpp index 490f34a134..2a540c5be7 100644 --- a/examples/companion_radio/MyMesh.cpp +++ b/examples/companion_radio/MyMesh.cpp @@ -93,7 +93,8 @@ #define RESP_CODE_AUTOADD_CONFIG 25 #define RESP_ALLOWED_REPEAT_FREQ 26 #define RESP_CODE_CHANNEL_DATA_RECV 27 -#define RESP_CODE_CHANNEL_DATA_RECV_V3 28 + +#define MAX_CHANNEL_DATA_LENGTH (MAX_FRAME_SIZE - 12) #define SEND_TIMEOUT_BASE_MILLIS 500 #define FLOOD_SEND_TIMEOUT_FACTOR 16.0f @@ -208,7 +209,7 @@ void MyMesh::updateContactFromFrame(ContactInfo &contact, uint32_t& last_mod, co bool MyMesh::Frame::isChannelMsg() const { return buf[0] == RESP_CODE_CHANNEL_MSG_RECV || buf[0] == RESP_CODE_CHANNEL_MSG_RECV_V3 || - buf[0] == RESP_CODE_CHANNEL_DATA_RECV || buf[0] == RESP_CODE_CHANNEL_DATA_RECV_V3; + buf[0] == RESP_CODE_CHANNEL_DATA_RECV; } void MyMesh::addToOfflineQueue(const uint8_t frame[], int len) { @@ -570,28 +571,26 @@ void MyMesh::onChannelMessageRecv(const mesh::GroupChannel &channel, mesh::Packe void MyMesh::onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, uint8_t data_type, const uint8_t *data, size_t data_len) { - int i = 0; - if (app_target_ver >= 3) { - out_frame[i++] = RESP_CODE_CHANNEL_DATA_RECV_V3; - out_frame[i++] = (int8_t)(pkt->getSNR() * 4); - out_frame[i++] = 0; // reserved1 - out_frame[i++] = 0; // reserved2 - } else { - out_frame[i++] = RESP_CODE_CHANNEL_DATA_RECV; + if (data_len > MAX_CHANNEL_DATA_LENGTH) { + MESH_DEBUG_PRINTLN("onChannelDataRecv: dropping payload_len=%d exceeds frame limit=%d", + (uint32_t)data_len, (uint32_t)MAX_CHANNEL_DATA_LENGTH); + return; } + int i = 0; + out_frame[i++] = RESP_CODE_CHANNEL_DATA_RECV; + out_frame[i++] = (int8_t)(pkt->getSNR() * 4); + out_frame[i++] = 0; // reserved1 + out_frame[i++] = 0; // reserved2 + uint8_t channel_idx = findChannelIdx(channel); out_frame[i++] = channel_idx; out_frame[i++] = pkt->isRouteFlood() ? pkt->path_len : 0xFF; out_frame[i++] = data_type; + out_frame[i++] = (uint8_t)data_len; memcpy(&out_frame[i], ×tamp, 4); i += 4; - size_t available = MAX_FRAME_SIZE - i; - if (data_len > available) { - MESH_DEBUG_PRINTLN("onChannelDataRecv(): payload_len=%d exceeds frame space=%d, truncating", (uint32_t)data_len, (uint32_t)available); - data_len = available; - } int copy_len = (int)data_len; if (copy_len > 0) { memcpy(&out_frame[i], data, copy_len); @@ -1108,8 +1107,8 @@ void MyMesh::handleCmdFrame(size_t len) { writeErrFrame(ERR_CODE_NOT_FOUND); // bad channel_idx } else if (data_type != DATA_TYPE_CUSTOM) { writeErrFrame(ERR_CODE_UNSUPPORTED_CMD); - } else if (payload_len > MAX_GROUP_DATA_LENGTH) { - MESH_DEBUG_PRINTLN("CMD_SEND_CHANNEL_DATA payload too long: %d > %d", payload_len, MAX_GROUP_DATA_LENGTH); + } else if (payload_len > MAX_CHANNEL_DATA_LENGTH) { + MESH_DEBUG_PRINTLN("CMD_SEND_CHANNEL_DATA payload too long: %d > %d", payload_len, MAX_CHANNEL_DATA_LENGTH); writeErrFrame(ERR_CODE_ILLEGAL_ARG); } else if (sendGroupData(msg_timestamp, channel.channel, data_type, payload, payload_len)) { writeOKFrame(); diff --git a/src/MeshCore.h b/src/MeshCore.h index 3eb4f9354e..cf8f949e66 100644 --- a/src/MeshCore.h +++ b/src/MeshCore.h @@ -17,7 +17,7 @@ #define PATH_HASH_SIZE 1 #define MAX_PACKET_PAYLOAD 184 -#define MAX_GROUP_DATA_LENGTH (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 5) +#define MAX_GROUP_DATA_LENGTH (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 6) #define MAX_PATH_SIZE 64 #define MAX_TRANS_UNIT 255 diff --git a/src/Packet.h b/src/Packet.h index 7861954618..c5c5ab0084 100644 --- a/src/Packet.h +++ b/src/Packet.h @@ -22,7 +22,7 @@ namespace mesh { #define PAYLOAD_TYPE_ACK 0x03 // a simple ack #define PAYLOAD_TYPE_ADVERT 0x04 // a node advertising its Identity #define PAYLOAD_TYPE_GRP_TXT 0x05 // an (unverified) group text message (prefixed with channel hash, MAC) (enc data: timestamp, "name: msg") -#define PAYLOAD_TYPE_GRP_DATA 0x06 // an (unverified) group datagram (prefixed with channel hash, MAC) (enc data: timestamp, blob) +#define PAYLOAD_TYPE_GRP_DATA 0x06 // an (unverified) group datagram (prefixed with channel hash, MAC) (enc data: timestamp, data_type, data_len, blob) #define PAYLOAD_TYPE_ANON_REQ 0x07 // generic request (prefixed with dest_hash, ephemeral pub_key, MAC) (enc data: ...) #define PAYLOAD_TYPE_PATH 0x08 // returned path (prefixed with dest/src hashes, MAC) (enc data: path, extra) #define PAYLOAD_TYPE_TRACE 0x09 // trace a path, collecting SNI for each hop diff --git a/src/helpers/BaseChatMesh.cpp b/src/helpers/BaseChatMesh.cpp index d8e089d545..5f4e0d4da9 100644 --- a/src/helpers/BaseChatMesh.cpp +++ b/src/helpers/BaseChatMesh.cpp @@ -353,15 +353,15 @@ int BaseChatMesh::searchChannelsByHash(const uint8_t* hash, mesh::GroupChannel d #endif void BaseChatMesh::onGroupDataRecv(mesh::Packet* packet, uint8_t type, const mesh::GroupChannel& channel, uint8_t* data, size_t len) { - if (len < 5) { - MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping short group payload len=%d", (uint32_t)len); - return; - } - - uint8_t data_type = data[4]; if (type == PAYLOAD_TYPE_GRP_TXT) { - if ((data_type >> 2) != 0) { - MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping unsupported group text type=%d", (uint32_t)data_type); + if (len < 5) { + MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping short group text payload len=%d", (uint32_t)len); + return; + } + + uint8_t txt_type = data[4]; + if ((txt_type >> 2) != 0) { + MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping unsupported group text type=%d", (uint32_t)txt_type); return; } @@ -374,9 +374,24 @@ void BaseChatMesh::onGroupDataRecv(mesh::Packet* packet, uint8_t type, const mes // notify UI of this new message onChannelMessageRecv(channel, packet, timestamp, (const char *) &data[5]); // let UI know } else if (type == PAYLOAD_TYPE_GRP_DATA) { + if (len < 6) { + MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping short group data payload len=%d", (uint32_t)len); + return; + } + uint32_t timestamp; memcpy(×tamp, data, 4); - onChannelDataRecv(channel, packet, timestamp, data_type, &data[5], len - 5); + uint8_t data_type = data[4]; + uint8_t data_len = data[5]; + size_t available_len = len - 6; + + if (data_len > available_len) { + MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping malformed group data type=%d len=%d available=%d", + (uint32_t)data_type, (uint32_t)data_len, (uint32_t)available_len); + return; + } + + onChannelDataRecv(channel, packet, timestamp, data_type, &data[6], data_len); } } @@ -478,12 +493,13 @@ bool BaseChatMesh::sendGroupData(uint32_t timestamp, mesh::GroupChannel& channel return false; } - uint8_t temp[5 + MAX_GROUP_DATA_LENGTH]; + uint8_t temp[6 + MAX_GROUP_DATA_LENGTH]; memcpy(temp, ×tamp, 4); temp[4] = data_type; - if (data_len > 0) memcpy(&temp[5], data, data_len); + temp[5] = (uint8_t)data_len; + if (data_len > 0) memcpy(&temp[6], data, data_len); - auto pkt = createGroupDatagram(PAYLOAD_TYPE_GRP_DATA, channel, temp, 5 + data_len); + auto pkt = createGroupDatagram(PAYLOAD_TYPE_GRP_DATA, channel, temp, 6 + data_len); if (pkt == NULL) { MESH_DEBUG_PRINTLN("sendGroupData: unable to create group datagram, data_len=%d", data_len); return false; From 37b72ffc17ad5875ac53ec10946001dc81c3dcfc Mon Sep 17 00:00:00 2001 From: Janez T Date: Wed, 18 Mar 2026 20:29:49 +0100 Subject: [PATCH 17/52] fix: Scope group data docs ref: #1928 --- docs/companion_protocol.md | 281 +++++++++++++++++++++++-------------- 1 file changed, 174 insertions(+), 107 deletions(-) diff --git a/docs/companion_protocol.md b/docs/companion_protocol.md index a8c09bef3e..ffb4f84c50 100644 --- a/docs/companion_protocol.md +++ b/docs/companion_protocol.md @@ -1,6 +1,6 @@ # Companion Protocol -- **Last Updated**: 2026-03-08 +- **Last Updated**: 2026-01-03 - **Protocol Version**: Companion Firmware v1.12.0+ > NOTE: This document is still in development. Some information may be inaccurate. @@ -100,7 +100,7 @@ When writing commands to the RX characteristic, specify the write type: ### MTU (Maximum Transmission Unit) -The default BLE MTU is 23 bytes (20 bytes payload). For larger commands like `SET_CHANNEL` (50 bytes), you may need to: +The default BLE MTU is 23 bytes (20 bytes payload). For larger commands like `SET_CHANNEL` (66 bytes), you may need to: 1. **Request Larger MTU**: Request MTU of 512 bytes if supported - Android: `gatt.requestMtu(512)` @@ -167,16 +167,16 @@ The first byte indicates the packet type (see [Response Parsing](#response-parsi **Command Format**: ``` Byte 0: 0x01 -Bytes 1-7: Reserved (currently ignored by firmware) -Bytes 8+: Application name (UTF-8, optional) +Byte 1: 0x03 +Bytes 2-10: "mccli" (ASCII, null-padded to 9 bytes) ``` **Example** (hex): ``` -01 00 00 00 00 00 00 00 6d 63 63 6c 69 +01 03 6d 63 63 6c 69 00 00 00 00 ``` -**Response**: `PACKET_SELF_INFO` (0x05) +**Response**: `PACKET_OK` (0x00) --- @@ -216,6 +216,8 @@ Byte 1: Channel Index (0-7) **Response**: `PACKET_CHANNEL_INFO` (0x12) with channel details +**Note**: The device does not return channel secrets for security reasons. Store secrets locally when creating channels. + --- ### 4. Set Channel @@ -227,10 +229,10 @@ Byte 1: Channel Index (0-7) Byte 0: 0x20 Byte 1: Channel Index (0-7) Bytes 2-33: Channel Name (32 bytes, UTF-8, null-padded) -Bytes 34-49: Secret (16 bytes) +Bytes 34-65: Secret (32 bytes) ``` -**Total Length**: 50 bytes +**Total Length**: 66 bytes **Channel Index**: - Index 0: Reserved for public channels (no secret) @@ -241,46 +243,41 @@ Bytes 34-49: Secret (16 bytes) - Maximum 32 bytes - Padded with null bytes (0x00) if shorter -**Secret Field** (16 bytes): -- For **private channels**: 16-byte secret +**Secret Field** (32 bytes): +- For **private channels**: 32-byte secret - For **public channels**: All zeros (0x00) **Example** (create channel "YourChannelName" at index 1 with secret): ``` 20 01 53 4D 53 00 00 ... (name padded to 32 bytes) - [16 bytes of secret] + [32 bytes of secret] ``` -**Note**: The 32-byte secret variant is unsupported and returns `PACKET_ERROR`. - **Response**: `PACKET_OK` (0x00) on success, `PACKET_ERROR` (0x01) on failure --- -### 5. Send Channel Text Message +### 5. Send Channel Message -**Purpose**: Send a plain text message to a channel. +**Purpose**: Send a text message to a channel. **Command Format**: ``` Byte 0: 0x03 -Byte 1: Text Type +Byte 1: 0x00 Byte 2: Channel Index (0-7) Bytes 3-6: Timestamp (32-bit little-endian Unix timestamp, seconds) -Bytes 7+: UTF-8 text bytes (variable length) +Bytes 7+: Message Text (UTF-8, variable length) ``` **Timestamp**: Unix timestamp in seconds (32-bit unsigned integer, little-endian) -**Text Type**: -- Must be `0x00` (`TXT_TYPE_PLAIN`) for this command. - **Example** (send "Hello" to channel 1 at timestamp 1234567890): ``` 03 00 01 D2 02 96 49 48 65 6C 6C 6F ``` -**Response**: `PACKET_OK` (0x00) on success +**Response**: `PACKET_MSG_SENT` (0x06) on success --- @@ -299,12 +296,12 @@ Bytes 7+: Binary payload bytes (variable length) **Data Type / Transport Mapping**: - `0xFF` (`DATA_TYPE_CUSTOM`) must be used for custom-protocol binary datagrams. -- `0x00` (`TXT_TYPE_PLAIN`) is invalid for this command. +- `0x00` is invalid for this command. - Values other than `0xFF` are reserved for official protocol extensions. **Limits**: - Maximum payload length is `160` bytes. -- Larger payloads are rejected with `PACKET_ERROR` / `ERR_CODE_ILLEGAL_ARG`. +- Larger payloads are rejected with `PACKET_ERROR`. **Response**: `PACKET_OK` (0x00) on success @@ -334,9 +331,9 @@ Byte 0: 0x0A --- -### 8. Get Battery and Storage +### 8. Get Battery -**Purpose**: Query device battery voltage and storage usage. +**Purpose**: Query device battery level. **Command Format**: ``` @@ -348,7 +345,7 @@ Byte 0: 0x14 14 ``` -**Response**: `PACKET_BATTERY` (0x0C) with battery millivolts and storage information +**Response**: `PACKET_BATTERY` (0x0C) with battery percentage --- @@ -376,7 +373,7 @@ Byte 0: 0x14 1. **Set Channel**: - Fetch all channel slots, and find one with empty name and all-zero secret - Generate or provide a 16-byte secret - - Send `CMD_SET_CHANNEL` with name and a 16-byte secret + - Send `CMD_SET_CHANNEL` with name and secret 2. **Get Channel**: - Send `CMD_GET_CHANNEL` with channel index - Parse `RESP_CODE_CHANNEL_INFO` response @@ -390,7 +387,7 @@ Byte 0: 0x14 ### Receiving Messages -Messages are received via the TX characteristic (notifications). The device sends: +Messages are received via the RX characteristic (notifications). The device sends: 1. **Channel Messages**: - `PACKET_CHANNEL_MSG_RECV` (0x08) - Standard format @@ -479,7 +476,7 @@ Byte 1: Channel Index (0-7) Byte 2: Path Length Byte 3: Text Type Bytes 4-7: Timestamp (32-bit little-endian) -Bytes 8+: Payload bytes +Bytes 8+: Message Text (UTF-8) ``` **V3 Format** (`PACKET_CHANNEL_MSG_RECV_V3`, 0x11): @@ -491,13 +488,34 @@ Byte 4: Channel Index (0-7) Byte 5: Path Length Byte 6: Text Type Bytes 7-10: Timestamp (32-bit little-endian) -Bytes 11+: Payload bytes +Bytes 11+: Message Text (UTF-8) ``` -**Payload Meaning**: -- If `txt_type == 0x00`: payload is UTF-8 channel text. -- If `txt_type != 0x00`: payload is binary (for example image/voice fragments) and must be treated as raw bytes. - For custom app datagrams sent via `CMD_SEND_CHANNEL_DATA`, `data_type` must be `0xFF`. +**Parsing Pseudocode**: +```python +def parse_channel_message(data): + packet_type = data[0] + offset = 1 + + # Check for V3 format + if packet_type == 0x11: # V3 + snr_byte = data[offset] + snr = ((snr_byte if snr_byte < 128 else snr_byte - 256) / 4.0) + offset += 3 # Skip SNR + reserved + + channel_idx = data[offset] + path_len = data[offset + 1] + txt_type = data[offset + 2] + timestamp = int.from_bytes(data[offset+3:offset+7], 'little') + message = data[offset+7:].decode('utf-8') + + return { + 'channel_idx': channel_idx, + 'timestamp': timestamp, + 'message': message, + 'snr': snr if packet_type == 0x11 else None + } +``` ### Channel Data Format @@ -516,43 +534,29 @@ Bytes 12+: Payload bytes **Parsing Pseudocode**: ```python -def parse_channel_frame(data): - packet_type = data[0] - offset = 1 - snr = None - - # Formats with explicit SNR/reserved bytes - if packet_type in (0x11, 0x1B): - snr_byte = data[offset] - snr = ((snr_byte if snr_byte < 128 else snr_byte - 256) / 4.0) - offset += 3 # Skip SNR + reserved - - channel_idx = data[offset] - path_len = data[offset + 1] - item_type = data[offset + 2] - data_len = data[offset + 3] if packet_type == 0x1B else None - timestamp = int.from_bytes(data[offset+4:offset+8], 'little') if packet_type == 0x1B else int.from_bytes(data[offset+3:offset+7], 'little') - payload_offset = offset + 8 if packet_type == 0x1B else offset + 7 - payload = data[payload_offset:payload_offset + data_len] if packet_type == 0x1B else data[payload_offset:] - is_text = packet_type in (0x08, 0x11) - if is_text and item_type == 0: - message = payload.decode('utf-8') - else: - message = None - +def parse_channel_data(data): + snr_byte = data[1] + snr = ((snr_byte if snr_byte < 128 else snr_byte - 256) / 4.0) + channel_idx = data[4] + path_len = data[5] + data_type = data[6] + data_len = data[7] + timestamp = int.from_bytes(data[8:12], 'little') + payload = data[12:12 + data_len] + return { 'channel_idx': channel_idx, - 'item_type': item_type, + 'path_len': path_len, + 'data_type': data_type, 'timestamp': timestamp, 'payload': payload, - 'message': message, - 'snr': snr + 'snr': snr, } ``` ### Sending Messages -Use `CMD_SEND_CHANNEL_TXT_MSG` for plain text, and `CMD_SEND_CHANNEL_DATA` for binary datagrams (see [Commands](#commands)). +Use the `SEND_CHANNEL_MESSAGE` command for plain text messages. Use `CMD_SEND_CHANNEL_DATA` for binary datagrams (see [Commands](#commands)). **Important**: - Messages are limited to 133 characters per MeshCore specification @@ -573,7 +577,7 @@ Use `CMD_SEND_CHANNEL_TXT_MSG` for plain text, and `CMD_SEND_CHANNEL_DATA` for b | 0x03 | PACKET_CONTACT | Contact information | | 0x04 | PACKET_CONTACT_END | End of contact list | | 0x05 | PACKET_SELF_INFO | Device self-information | -| 0x06 | PACKET_MSG_SENT | Direct message sent confirmation | +| 0x06 | PACKET_MSG_SENT | Message sent confirmation | | 0x07 | PACKET_CONTACT_MSG_RECV | Contact message (standard) | | 0x08 | PACKET_CHANNEL_MSG_RECV | Channel message (standard) | | 0x09 | PACKET_CURRENT_TIME | Current time response | @@ -608,10 +612,10 @@ Byte 1: Error code (optional) Byte 0: 0x12 Byte 1: Channel Index Bytes 2-33: Channel Name (32 bytes, null-terminated) -Bytes 34-49: Secret (16 bytes) +Bytes 34-65: Secret (32 bytes, but device typically only returns 20 bytes total) ``` -**Note**: The device returns the 16-byte channel secret in this response. +**Note**: The device may not return the full 66-byte packet. Parse what is available. The secret field is typically not returned for security reasons. **PACKET_DEVICE_INFO** (0x0D): ``` @@ -626,8 +630,6 @@ Bytes 4-7: BLE PIN (32-bit little-endian) Bytes 8-19: Firmware Build (12 bytes, UTF-8, null-padded) Bytes 20-59: Model (40 bytes, UTF-8, null-padded) Bytes 60-79: Version (20 bytes, UTF-8, null-padded) -Byte 80: Client repeat enabled/preferred (firmware v9+) -Byte 81: Path hash mode (firmware v10+) ``` **Parsing Pseudocode**: @@ -653,7 +655,9 @@ def parse_device_info(data): **PACKET_BATTERY** (0x0C): ``` Byte 0: 0x0C -Bytes 1-2: Battery Voltage (16-bit little-endian, millivolts) +Bytes 1-2: Battery Level (16-bit little-endian, percentage 0-100) + +Optional (if data size > 3): Bytes 3-6: Used Storage (32-bit little-endian, KB) Bytes 7-10: Total Storage (32-bit little-endian, KB) ``` @@ -664,12 +668,14 @@ def parse_battery(data): if len(data) < 3: return None - mv = int.from_bytes(data[1:3], 'little') - info = {'battery_mv': mv} + level = int.from_bytes(data[1:3], 'little') + info = {'level': level} - if len(data) >= 11: - info['used_kb'] = int.from_bytes(data[3:7], 'little') - info['total_kb'] = int.from_bytes(data[7:11], 'little') + if len(data) > 3: + used_kb = int.from_bytes(data[3:7], 'little') + total_kb = int.from_bytes(data[7:11], 'little') + info['used_kb'] = used_kb + info['total_kb'] = total_kb return info ``` @@ -691,7 +697,7 @@ Bytes 48-51: Radio Frequency (32-bit little-endian, divided by 1000.0) Bytes 52-55: Radio Bandwidth (32-bit little-endian, divided by 1000.0) Byte 56: Radio Spreading Factor Byte 57: Radio Coding Rate -Bytes 58+: Device Name (UTF-8, variable length, no null terminator required) +Bytes 58+: Device Name (UTF-8, variable length, null-terminated) ``` **Parsing Pseudocode**: @@ -739,12 +745,12 @@ def parse_self_info(data): return info ``` -**PACKET_MSG_SENT** (0x06, used by direct/contact send flows): +**PACKET_MSG_SENT** (0x06): ``` Byte 0: 0x06 -Byte 1: Route Flag (0 = direct, 1 = flood) -Bytes 2-5: Tag / Expected ACK (4 bytes, little-endian) -Bytes 6-9: Suggested Timeout (32-bit little-endian, milliseconds) +Byte 1: Message Type +Bytes 2-5: Expected ACK (4 bytes, hex) +Bytes 6-9: Suggested Timeout (32-bit little-endian, seconds) ``` **PACKET_ACK** (0x82): @@ -772,36 +778,93 @@ Bytes 1-6: ACK Code (6 bytes, hex) **Note**: Error codes may vary by firmware version. Always check byte 1 of `PACKET_ERROR` response. -### Frame Handling +### Partial Packet Handling -BLE implementations enqueue and deliver one protocol frame per BLE write/notification at the firmware layer. +BLE notifications may arrive in chunks, especially for larger packets. Implement buffering: -- Apps should treat each characteristic write/notification as exactly one companion protocol frame -- Apps should still validate frame lengths before parsing -- Future transports or firmware revisions may differ, so avoid assuming fixed payload sizes for variable-length responses +**Implementation**: +```python +class PacketBuffer: + def __init__(self): + self.buffer = bytearray() + self.expected_length = None + + def add_data(self, data): + self.buffer.extend(data) + + # Check if we have a complete packet + if len(self.buffer) >= 1: + packet_type = self.buffer[0] + + # Determine expected length based on packet type + expected = self.get_expected_length(packet_type) + + if expected is not None and len(self.buffer) >= expected: + # Complete packet + packet = bytes(self.buffer[:expected]) + self.buffer = self.buffer[expected:] + return packet + elif expected is None: + # Variable length packet - try to parse what we have + # Some packets have minimum length requirements + if self.can_parse_partial(packet_type): + return self.try_parse_partial() + + return None # Incomplete packet + + def get_expected_length(self, packet_type): + # Fixed-length packets + fixed_lengths = { + 0x00: 5, # PACKET_OK (minimum) + 0x01: 2, # PACKET_ERROR (minimum) + 0x0A: 1, # PACKET_NO_MORE_MSGS + 0x14: 3, # PACKET_BATTERY (minimum) + } + return fixed_lengths.get(packet_type) + + def can_parse_partial(self, packet_type): + # Some packets can be parsed partially + return packet_type in [0x12, 0x08, 0x11, 0x1B, 0x07, 0x10, 0x05, 0x0D] + + def try_parse_partial(self): + # Try to parse with available data + # Return packet if successfully parsed, None otherwise + # This is packet-type specific + pass +``` + +**Usage**: +```python +buffer = PacketBuffer() + +def on_notification_received(data): + packet = buffer.add_data(data) + if packet: + parse_and_handle_packet(packet) +``` ### Response Handling 1. **Command-Response Pattern**: - - Send command via RX characteristic - - Wait for response via TX characteristic (notification) + - Send command via TX characteristic + - Wait for response via RX characteristic (notification) - Match response to command using sequence numbers or command type - Handle timeout (typically 5 seconds) - Use command queue to prevent concurrent commands 2. **Asynchronous Messages**: - - Device may send messages at any time via TX characteristic + - Device may send messages at any time via RX characteristic - Handle `PACKET_MESSAGES_WAITING` (0x83) by polling `GET_MESSAGE` command - Parse incoming messages and route to appropriate handlers - - Validate frame length before decoding + - Buffer partial packets until complete 3. **Response Matching**: - Match responses to commands by expected packet type: - - `APP_START` → `PACKET_SELF_INFO` + - `APP_START` → `PACKET_OK` - `DEVICE_QUERY` → `PACKET_DEVICE_INFO` - `GET_CHANNEL` → `PACKET_CHANNEL_INFO` - `SET_CHANNEL` → `PACKET_OK` or `PACKET_ERROR` - - `CMD_SEND_CHANNEL_TXT_MSG` → `PACKET_OK` or `PACKET_ERROR` + - `SEND_CHANNEL_MESSAGE` → `PACKET_MSG_SENT` - `CMD_SEND_CHANNEL_DATA` → `PACKET_OK` or `PACKET_ERROR` - `GET_MESSAGE` → `PACKET_CHANNEL_MSG_RECV`, `PACKET_CHANNEL_DATA_RECV`, `PACKET_CONTACT_MSG_RECV`, or `PACKET_NO_MORE_MSGS` - `GET_BATTERY` → `PACKET_BATTERY` @@ -831,16 +894,16 @@ device = scan_for_device("MeshCore") gatt = connect_to_device(device) # 3. Discover services and characteristics -service = discover_service(gatt, "6E400001-B5A3-F393-E0A9-E50E24DCCA9E") -rx_char = discover_characteristic(service, "6E400002-B5A3-F393-E0A9-E50E24DCCA9E") -tx_char = discover_characteristic(service, "6E400003-B5A3-F393-E0A9-E50E24DCCA9E") +service = discover_service(gatt, "0000ff00-0000-1000-8000-00805f9b34fb") +rx_char = discover_characteristic(service, "0000ff01-0000-1000-8000-00805f9b34fb") +tx_char = discover_characteristic(service, "0000ff02-0000-1000-8000-00805f9b34fb") -# 4. Enable notifications on TX characteristic -enable_notifications(tx_char, on_notification_received) +# 4. Enable notifications on RX characteristic +enable_notifications(rx_char, on_notification_received) # 5. Send AppStart command -send_command(rx_char, build_app_start()) -wait_for_response(PACKET_SELF_INFO) +send_command(tx_char, build_app_start()) +wait_for_response(PACKET_OK) ``` ### Creating a Private Channel @@ -850,16 +913,21 @@ wait_for_response(PACKET_SELF_INFO) secret_16_bytes = generate_secret(16) # Use CSPRNG secret_hex = secret_16_bytes.hex() -# 2. Build SET_CHANNEL command +# 2. Expand secret to 32 bytes using SHA-512 +import hashlib +sha512_hash = hashlib.sha512(secret_16_bytes).digest() +secret_32_bytes = sha512_hash[:32] + +# 3. Build SET_CHANNEL command channel_name = "YourChannelName" channel_index = 1 # Use 1-7 for private channels -command = build_set_channel(channel_index, channel_name, secret_16_bytes) +command = build_set_channel(channel_index, channel_name, secret_32_bytes) -# 3. Send command -send_command(rx_char, command) +# 4. Send command +send_command(tx_char, command) response = wait_for_response(PACKET_OK) -# 4. Store secret locally +# 5. Store secret locally (device won't return it) store_channel_secret(channel_index, secret_hex) ``` @@ -873,8 +941,8 @@ timestamp = int(time.time()) command = build_channel_message(channel_index, message, timestamp) # 2. Send command -send_command(rx_char, command) -response = wait_for_response(PACKET_OK) +send_command(tx_char, command) +response = wait_for_response(PACKET_MSG_SENT) ``` ### Receiving Messages @@ -883,13 +951,12 @@ response = wait_for_response(PACKET_OK) def on_notification_received(data): packet_type = data[0] - if packet_type in (PACKET_CHANNEL_MSG_RECV, PACKET_CHANNEL_MSG_RECV_V3, - PACKET_CHANNEL_DATA_RECV): - message = parse_channel_frame(data) + if packet_type == PACKET_CHANNEL_MSG_RECV or packet_type == PACKET_CHANNEL_MSG_RECV_V3: + message = parse_channel_message(data) handle_channel_message(message) elif packet_type == PACKET_MESSAGES_WAITING: # Poll for messages - send_command(rx_char, build_get_message()) + send_command(tx_char, build_get_message()) ``` --- From 896d60c02610a237c06475d0d8155976b5b8d4bf Mon Sep 17 00:00:00 2001 From: Janez T Date: Wed, 18 Mar 2026 20:32:47 +0100 Subject: [PATCH 18/52] fix: Keep data docs only ref: #1928 --- docs/companion_protocol.md | 57 +++++--------------------------------- 1 file changed, 7 insertions(+), 50 deletions(-) diff --git a/docs/companion_protocol.md b/docs/companion_protocol.md index ffb4f84c50..e74c527469 100644 --- a/docs/companion_protocol.md +++ b/docs/companion_protocol.md @@ -307,7 +307,7 @@ Bytes 7+: Binary payload bytes (variable length) --- -### 7. Get Message +### 6. Get Message **Purpose**: Request the next queued message from the device. @@ -323,7 +323,6 @@ Byte 0: 0x0A **Response**: - `PACKET_CHANNEL_MSG_RECV` (0x08) or `PACKET_CHANNEL_MSG_RECV_V3` (0x11) for channel messages -- `PACKET_CHANNEL_DATA_RECV` (0x1B) for channel data - `PACKET_CONTACT_MSG_RECV` (0x07) or `PACKET_CONTACT_MSG_RECV_V3` (0x10) for contact messages - `PACKET_NO_MORE_MSGS` (0x0A) if no messages available @@ -331,7 +330,7 @@ Byte 0: 0x0A --- -### 8. Get Battery +### 7. Get Battery **Purpose**: Query device battery level. @@ -393,14 +392,11 @@ Messages are received via the RX characteristic (notifications). The device send - `PACKET_CHANNEL_MSG_RECV` (0x08) - Standard format - `PACKET_CHANNEL_MSG_RECV_V3` (0x11) - Version 3 with SNR -2. **Channel Data**: - - `PACKET_CHANNEL_DATA_RECV` (0x1B) - Includes SNR and reserved bytes - -3. **Contact Messages**: +2. **Contact Messages**: - `PACKET_CONTACT_MSG_RECV` (0x07) - Standard format - `PACKET_CONTACT_MSG_RECV_V3` (0x10) - Version 3 with SNR -4. **Notifications**: +3. **Notifications**: - `PACKET_MESSAGES_WAITING` (0x83) - Indicates messages are queued ### Contact Message Format @@ -517,46 +513,9 @@ def parse_channel_message(data): } ``` -### Channel Data Format - -**Format** (`PACKET_CHANNEL_DATA_RECV`, 0x1B): -``` -Byte 0: 0x1B (packet type) -Byte 1: SNR (signed byte, multiplied by 4) -Bytes 2-3: Reserved -Byte 4: Channel Index (0-7) -Byte 5: Path Length -Byte 6: Data Type -Byte 7: Data Length -Bytes 8-11: Timestamp (32-bit little-endian) -Bytes 12+: Payload bytes -``` - -**Parsing Pseudocode**: -```python -def parse_channel_data(data): - snr_byte = data[1] - snr = ((snr_byte if snr_byte < 128 else snr_byte - 256) / 4.0) - channel_idx = data[4] - path_len = data[5] - data_type = data[6] - data_len = data[7] - timestamp = int.from_bytes(data[8:12], 'little') - payload = data[12:12 + data_len] - - return { - 'channel_idx': channel_idx, - 'path_len': path_len, - 'data_type': data_type, - 'timestamp': timestamp, - 'payload': payload, - 'snr': snr, - } -``` - ### Sending Messages -Use the `SEND_CHANNEL_MESSAGE` command for plain text messages. Use `CMD_SEND_CHANNEL_DATA` for binary datagrams (see [Commands](#commands)). +Use the `SEND_CHANNEL_MESSAGE` command (see [Commands](#commands)). **Important**: - Messages are limited to 133 characters per MeshCore specification @@ -587,7 +546,6 @@ Use the `SEND_CHANNEL_MESSAGE` command for plain text messages. Use `CMD_SEND_CH | 0x10 | PACKET_CONTACT_MSG_RECV_V3 | Contact message (V3 with SNR) | | 0x11 | PACKET_CHANNEL_MSG_RECV_V3 | Channel message (V3 with SNR) | | 0x12 | PACKET_CHANNEL_INFO | Channel information | -| 0x1B | PACKET_CHANNEL_DATA_RECV | Channel data (includes SNR) | | 0x80 | PACKET_ADVERTISEMENT | Advertisement packet | | 0x82 | PACKET_ACK | Acknowledgment | | 0x83 | PACKET_MESSAGES_WAITING | Messages waiting notification | @@ -824,7 +782,7 @@ class PacketBuffer: def can_parse_partial(self, packet_type): # Some packets can be parsed partially - return packet_type in [0x12, 0x08, 0x11, 0x1B, 0x07, 0x10, 0x05, 0x0D] + return packet_type in [0x12, 0x08, 0x11, 0x07, 0x10, 0x05, 0x0D] def try_parse_partial(self): # Try to parse with available data @@ -865,8 +823,7 @@ def on_notification_received(data): - `GET_CHANNEL` → `PACKET_CHANNEL_INFO` - `SET_CHANNEL` → `PACKET_OK` or `PACKET_ERROR` - `SEND_CHANNEL_MESSAGE` → `PACKET_MSG_SENT` - - `CMD_SEND_CHANNEL_DATA` → `PACKET_OK` or `PACKET_ERROR` - - `GET_MESSAGE` → `PACKET_CHANNEL_MSG_RECV`, `PACKET_CHANNEL_DATA_RECV`, `PACKET_CONTACT_MSG_RECV`, or `PACKET_NO_MORE_MSGS` + - `GET_MESSAGE` → `PACKET_CHANNEL_MSG_RECV`, `PACKET_CONTACT_MSG_RECV`, or `PACKET_NO_MORE_MSGS` - `GET_BATTERY` → `PACKET_BATTERY` 4. **Timeout Handling**: From 2fe3c36b8fc249db6cf78f4ed3f852e425f68029 Mon Sep 17 00:00:00 2001 From: Janez T Date: Wed, 18 Mar 2026 20:34:15 +0100 Subject: [PATCH 19/52] fix: Trim grp docs ref: #1928 --- docs/companion_protocol.md | 176 ++++++++++++------------------------- 1 file changed, 56 insertions(+), 120 deletions(-) diff --git a/docs/companion_protocol.md b/docs/companion_protocol.md index e74c527469..917df1df83 100644 --- a/docs/companion_protocol.md +++ b/docs/companion_protocol.md @@ -1,6 +1,6 @@ # Companion Protocol -- **Last Updated**: 2026-01-03 +- **Last Updated**: 2026-03-08 - **Protocol Version**: Companion Firmware v1.12.0+ > NOTE: This document is still in development. Some information may be inaccurate. @@ -100,7 +100,7 @@ When writing commands to the RX characteristic, specify the write type: ### MTU (Maximum Transmission Unit) -The default BLE MTU is 23 bytes (20 bytes payload). For larger commands like `SET_CHANNEL` (66 bytes), you may need to: +The default BLE MTU is 23 bytes (20 bytes payload). For larger commands like `SET_CHANNEL` (50 bytes), you may need to: 1. **Request Larger MTU**: Request MTU of 512 bytes if supported - Android: `gatt.requestMtu(512)` @@ -167,16 +167,16 @@ The first byte indicates the packet type (see [Response Parsing](#response-parsi **Command Format**: ``` Byte 0: 0x01 -Byte 1: 0x03 -Bytes 2-10: "mccli" (ASCII, null-padded to 9 bytes) +Bytes 1-7: Reserved (currently ignored by firmware) +Bytes 8+: Application name (UTF-8, optional) ``` **Example** (hex): ``` -01 03 6d 63 63 6c 69 00 00 00 00 +01 00 00 00 00 00 00 00 6d 63 63 6c 69 ``` -**Response**: `PACKET_OK` (0x00) +**Response**: `PACKET_SELF_INFO` (0x05) --- @@ -216,8 +216,6 @@ Byte 1: Channel Index (0-7) **Response**: `PACKET_CHANNEL_INFO` (0x12) with channel details -**Note**: The device does not return channel secrets for security reasons. Store secrets locally when creating channels. - --- ### 4. Set Channel @@ -229,10 +227,10 @@ Byte 1: Channel Index (0-7) Byte 0: 0x20 Byte 1: Channel Index (0-7) Bytes 2-33: Channel Name (32 bytes, UTF-8, null-padded) -Bytes 34-65: Secret (32 bytes) +Bytes 34-49: Secret (16 bytes) ``` -**Total Length**: 66 bytes +**Total Length**: 50 bytes **Channel Index**: - Index 0: Reserved for public channels (no secret) @@ -243,16 +241,18 @@ Bytes 34-65: Secret (32 bytes) - Maximum 32 bytes - Padded with null bytes (0x00) if shorter -**Secret Field** (32 bytes): -- For **private channels**: 32-byte secret +**Secret Field** (16 bytes): +- For **private channels**: 16-byte secret - For **public channels**: All zeros (0x00) **Example** (create channel "YourChannelName" at index 1 with secret): ``` 20 01 53 4D 53 00 00 ... (name padded to 32 bytes) - [32 bytes of secret] + [16 bytes of secret] ``` +**Note**: The 32-byte secret variant is unsupported and returns `PACKET_ERROR`. + **Response**: `PACKET_OK` (0x00) on success, `PACKET_ERROR` (0x01) on failure --- @@ -330,9 +330,9 @@ Byte 0: 0x0A --- -### 7. Get Battery +### 7. Get Battery and Storage -**Purpose**: Query device battery level. +**Purpose**: Query device battery voltage and storage usage. **Command Format**: ``` @@ -344,7 +344,7 @@ Byte 0: 0x14 14 ``` -**Response**: `PACKET_BATTERY` (0x0C) with battery percentage +**Response**: `PACKET_BATTERY` (0x0C) with battery millivolts and storage information --- @@ -372,7 +372,7 @@ Byte 0: 0x14 1. **Set Channel**: - Fetch all channel slots, and find one with empty name and all-zero secret - Generate or provide a 16-byte secret - - Send `CMD_SET_CHANNEL` with name and secret + - Send `CMD_SET_CHANNEL` with name and a 16-byte secret 2. **Get Channel**: - Send `CMD_GET_CHANNEL` with channel index - Parse `RESP_CODE_CHANNEL_INFO` response @@ -386,7 +386,7 @@ Byte 0: 0x14 ### Receiving Messages -Messages are received via the RX characteristic (notifications). The device sends: +Messages are received via the TX characteristic (notifications). The device sends: 1. **Channel Messages**: - `PACKET_CHANNEL_MSG_RECV` (0x08) - Standard format @@ -570,10 +570,10 @@ Byte 1: Error code (optional) Byte 0: 0x12 Byte 1: Channel Index Bytes 2-33: Channel Name (32 bytes, null-terminated) -Bytes 34-65: Secret (32 bytes, but device typically only returns 20 bytes total) +Bytes 34-49: Secret (16 bytes) ``` -**Note**: The device may not return the full 66-byte packet. Parse what is available. The secret field is typically not returned for security reasons. +**Note**: The device returns the 16-byte channel secret in this response. **PACKET_DEVICE_INFO** (0x0D): ``` @@ -588,6 +588,8 @@ Bytes 4-7: BLE PIN (32-bit little-endian) Bytes 8-19: Firmware Build (12 bytes, UTF-8, null-padded) Bytes 20-59: Model (40 bytes, UTF-8, null-padded) Bytes 60-79: Version (20 bytes, UTF-8, null-padded) +Byte 80: Client repeat enabled/preferred (firmware v9+) +Byte 81: Path hash mode (firmware v10+) ``` **Parsing Pseudocode**: @@ -613,9 +615,7 @@ def parse_device_info(data): **PACKET_BATTERY** (0x0C): ``` Byte 0: 0x0C -Bytes 1-2: Battery Level (16-bit little-endian, percentage 0-100) - -Optional (if data size > 3): +Bytes 1-2: Battery Voltage (16-bit little-endian, millivolts) Bytes 3-6: Used Storage (32-bit little-endian, KB) Bytes 7-10: Total Storage (32-bit little-endian, KB) ``` @@ -626,14 +626,12 @@ def parse_battery(data): if len(data) < 3: return None - level = int.from_bytes(data[1:3], 'little') - info = {'level': level} + mv = int.from_bytes(data[1:3], 'little') + info = {'battery_mv': mv} - if len(data) > 3: - used_kb = int.from_bytes(data[3:7], 'little') - total_kb = int.from_bytes(data[7:11], 'little') - info['used_kb'] = used_kb - info['total_kb'] = total_kb + if len(data) >= 11: + info['used_kb'] = int.from_bytes(data[3:7], 'little') + info['total_kb'] = int.from_bytes(data[7:11], 'little') return info ``` @@ -655,7 +653,7 @@ Bytes 48-51: Radio Frequency (32-bit little-endian, divided by 1000.0) Bytes 52-55: Radio Bandwidth (32-bit little-endian, divided by 1000.0) Byte 56: Radio Spreading Factor Byte 57: Radio Coding Rate -Bytes 58+: Device Name (UTF-8, variable length, null-terminated) +Bytes 58+: Device Name (UTF-8, variable length, no null terminator required) ``` **Parsing Pseudocode**: @@ -706,9 +704,9 @@ def parse_self_info(data): **PACKET_MSG_SENT** (0x06): ``` Byte 0: 0x06 -Byte 1: Message Type -Bytes 2-5: Expected ACK (4 bytes, hex) -Bytes 6-9: Suggested Timeout (32-bit little-endian, seconds) +Byte 1: Route Flag (0 = direct, 1 = flood) +Bytes 2-5: Tag / Expected ACK (4 bytes, little-endian) +Bytes 6-9: Suggested Timeout (32-bit little-endian, milliseconds) ``` **PACKET_ACK** (0x82): @@ -736,89 +734,32 @@ Bytes 1-6: ACK Code (6 bytes, hex) **Note**: Error codes may vary by firmware version. Always check byte 1 of `PACKET_ERROR` response. -### Partial Packet Handling - -BLE notifications may arrive in chunks, especially for larger packets. Implement buffering: - -**Implementation**: -```python -class PacketBuffer: - def __init__(self): - self.buffer = bytearray() - self.expected_length = None - - def add_data(self, data): - self.buffer.extend(data) - - # Check if we have a complete packet - if len(self.buffer) >= 1: - packet_type = self.buffer[0] - - # Determine expected length based on packet type - expected = self.get_expected_length(packet_type) - - if expected is not None and len(self.buffer) >= expected: - # Complete packet - packet = bytes(self.buffer[:expected]) - self.buffer = self.buffer[expected:] - return packet - elif expected is None: - # Variable length packet - try to parse what we have - # Some packets have minimum length requirements - if self.can_parse_partial(packet_type): - return self.try_parse_partial() - - return None # Incomplete packet - - def get_expected_length(self, packet_type): - # Fixed-length packets - fixed_lengths = { - 0x00: 5, # PACKET_OK (minimum) - 0x01: 2, # PACKET_ERROR (minimum) - 0x0A: 1, # PACKET_NO_MORE_MSGS - 0x14: 3, # PACKET_BATTERY (minimum) - } - return fixed_lengths.get(packet_type) - - def can_parse_partial(self, packet_type): - # Some packets can be parsed partially - return packet_type in [0x12, 0x08, 0x11, 0x07, 0x10, 0x05, 0x0D] - - def try_parse_partial(self): - # Try to parse with available data - # Return packet if successfully parsed, None otherwise - # This is packet-type specific - pass -``` +### Frame Handling -**Usage**: -```python -buffer = PacketBuffer() +BLE implementations enqueue and deliver one protocol frame per BLE write/notification at the firmware layer. -def on_notification_received(data): - packet = buffer.add_data(data) - if packet: - parse_and_handle_packet(packet) -``` +- Apps should treat each characteristic write/notification as exactly one companion protocol frame +- Apps should still validate frame lengths before parsing +- Future transports or firmware revisions may differ, so avoid assuming fixed payload sizes for variable-length responses ### Response Handling 1. **Command-Response Pattern**: - - Send command via TX characteristic - - Wait for response via RX characteristic (notification) + - Send command via RX characteristic + - Wait for response via TX characteristic (notification) - Match response to command using sequence numbers or command type - Handle timeout (typically 5 seconds) - Use command queue to prevent concurrent commands 2. **Asynchronous Messages**: - - Device may send messages at any time via RX characteristic + - Device may send messages at any time via TX characteristic - Handle `PACKET_MESSAGES_WAITING` (0x83) by polling `GET_MESSAGE` command - Parse incoming messages and route to appropriate handlers - - Buffer partial packets until complete + - Validate frame length before decoding 3. **Response Matching**: - Match responses to commands by expected packet type: - - `APP_START` → `PACKET_OK` + - `APP_START` → `PACKET_SELF_INFO` - `DEVICE_QUERY` → `PACKET_DEVICE_INFO` - `GET_CHANNEL` → `PACKET_CHANNEL_INFO` - `SET_CHANNEL` → `PACKET_OK` or `PACKET_ERROR` @@ -851,16 +792,16 @@ device = scan_for_device("MeshCore") gatt = connect_to_device(device) # 3. Discover services and characteristics -service = discover_service(gatt, "0000ff00-0000-1000-8000-00805f9b34fb") -rx_char = discover_characteristic(service, "0000ff01-0000-1000-8000-00805f9b34fb") -tx_char = discover_characteristic(service, "0000ff02-0000-1000-8000-00805f9b34fb") +service = discover_service(gatt, "6E400001-B5A3-F393-E0A9-E50E24DCCA9E") +rx_char = discover_characteristic(service, "6E400002-B5A3-F393-E0A9-E50E24DCCA9E") +tx_char = discover_characteristic(service, "6E400003-B5A3-F393-E0A9-E50E24DCCA9E") -# 4. Enable notifications on RX characteristic -enable_notifications(rx_char, on_notification_received) +# 4. Enable notifications on TX characteristic +enable_notifications(tx_char, on_notification_received) # 5. Send AppStart command -send_command(tx_char, build_app_start()) -wait_for_response(PACKET_OK) +send_command(rx_char, build_app_start()) +wait_for_response(PACKET_SELF_INFO) ``` ### Creating a Private Channel @@ -870,21 +811,16 @@ wait_for_response(PACKET_OK) secret_16_bytes = generate_secret(16) # Use CSPRNG secret_hex = secret_16_bytes.hex() -# 2. Expand secret to 32 bytes using SHA-512 -import hashlib -sha512_hash = hashlib.sha512(secret_16_bytes).digest() -secret_32_bytes = sha512_hash[:32] - -# 3. Build SET_CHANNEL command +# 2. Build SET_CHANNEL command channel_name = "YourChannelName" channel_index = 1 # Use 1-7 for private channels -command = build_set_channel(channel_index, channel_name, secret_32_bytes) +command = build_set_channel(channel_index, channel_name, secret_16_bytes) -# 4. Send command -send_command(tx_char, command) +# 3. Send command +send_command(rx_char, command) response = wait_for_response(PACKET_OK) -# 5. Store secret locally (device won't return it) +# 4. Store secret locally store_channel_secret(channel_index, secret_hex) ``` @@ -898,7 +834,7 @@ timestamp = int(time.time()) command = build_channel_message(channel_index, message, timestamp) # 2. Send command -send_command(tx_char, command) +send_command(rx_char, command) response = wait_for_response(PACKET_MSG_SENT) ``` @@ -913,7 +849,7 @@ def on_notification_received(data): handle_channel_message(message) elif packet_type == PACKET_MESSAGES_WAITING: # Poll for messages - send_command(tx_char, build_get_message()) + send_command(rx_char, build_get_message()) ``` --- From 1f48d2b8698c3702baf2b548bc8e987bdfe20b17 Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Wed, 18 Mar 2026 22:06:23 +0100 Subject: [PATCH 20/52] Address comments --- docs/cli_commands.md | 21 ++++++++++++++++++--- docs/terminal_chat_cli.md | 7 +++++-- src/helpers/CommonCLI.cpp | 11 ++++------- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 0e170a77c3..f248e4f33f 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -425,16 +425,31 @@ This document provides an overview of CLI commands that can be sent to MeshCore - `set dutycycle ` **Parameters:** -- `value`: Duty cycle percentage (10-100) +- `value`: Duty cycle percentage (1-100) **Default:** `50%` (equivalent to airtime factor 1.0) **Examples:** - `set dutycycle 100` — no duty cycle limit - `set dutycycle 50` — 50% duty cycle (default) -- `set dutycycle 10` — 10% duty cycle (strictest EU requirement) +- `set dutycycle 10` — 10% duty cycle +- `set dutycycle 1` — 1% duty cycle (strictest EU requirement) -> **Deprecated:** `get af` / `set af` still work but are deprecated in favour of `dutycycle`. +> **Note:** Added in firmware v1.15.0 + +--- + +#### View or change the airtime factor (duty cycle limit) +> **Deprecated** as of firmware v1.15.0. Use [`get/set dutycycle`](#view-or-change-the-duty-cycle-limit) instead. + +**Usage:** +- `get af` +- `set af ` + +**Parameters:** +- `value`: Airtime factor (0-9) + +**Default:** `1.0` --- diff --git a/docs/terminal_chat_cli.md b/docs/terminal_chat_cli.md index b1a3af2a6d..c889da9672 100644 --- a/docs/terminal_chat_cli.md +++ b/docs/terminal_chat_cli.md @@ -30,9 +30,12 @@ Sets your advertisement map longitude. (decimal degrees) ``` set dutycycle {percent} ``` -Sets the transmit duty cycle limit (10-100%). Example: `set dutycycle 10` for 10%. +Sets the transmit duty cycle limit (1-100%). Example: `set dutycycle 10` for 10%. -> **Deprecated:** `set af` still works but is deprecated in favour of `set dutycycle`. +``` +set af {air-time-factor} +``` +Sets the transmit air-time-factor. Deprecated — use `set dutycycle` instead. ``` diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index b3eff17f9d..cf6d471276 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -289,7 +289,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch int dc_frac = (int)((dc - dc_int) * 10.0f + 0.5f); sprintf(reply, "> %d.%d%%", dc_int, dc_frac); } else if (memcmp(config, "af", 2) == 0) { - sprintf(reply, "> %s (deprecated, use 'get dutycycle')", StrHelper::ftoa(_prefs->airtime_factor)); + sprintf(reply, "> %s", StrHelper::ftoa(_prefs->airtime_factor)); } else if (memcmp(config, "int.thresh", 10) == 0) { sprintf(reply, "> %d", (uint32_t) _prefs->interference_threshold); } else if (memcmp(config, "agc.reset.interval", 18) == 0) { @@ -443,8 +443,8 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch const char* config = &command[4]; if (memcmp(config, "dutycycle ", 10) == 0) { float dc = atof(&config[10]); - if (dc < 10 || dc > 100) { - strcpy(reply, "ERROR: dutycycle must be 10-100"); + if (dc < 1 || dc > 100) { + strcpy(reply, "ERROR: dutycycle must be 1-100"); } else { _prefs->airtime_factor = (100.0f / dc) - 1.0f; savePrefs(); @@ -456,10 +456,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch } else if (memcmp(config, "af ", 3) == 0) { _prefs->airtime_factor = atof(&config[3]); savePrefs(); - float actual = 100.0f / (_prefs->airtime_factor + 1.0f); - int a_int = (int)actual; - int a_frac = (int)((actual - a_int) * 10.0f + 0.5f); - sprintf(reply, "OK - %d.%d%% (deprecated, use 'set dutycycle')", a_int, a_frac); + strcpy(reply, "OK"); } else if (memcmp(config, "int.thresh ", 11) == 0) { _prefs->interference_threshold = atoi(&config[11]); savePrefs(); From 1fb26e76235754ff203b4de7ef5072f47936e745 Mon Sep 17 00:00:00 2001 From: Janez T Date: Thu, 19 Mar 2026 09:22:12 +0100 Subject: [PATCH 21/52] fix: Drop grp data timestamp ref: #1928 --- docs/companion_protocol.md | 7 ++++--- examples/companion_radio/MyMesh.cpp | 11 +++-------- examples/companion_radio/MyMesh.h | 2 +- src/MeshCore.h | 2 +- src/Packet.h | 2 +- src/helpers/BaseChatMesh.cpp | 25 +++++++++++-------------- src/helpers/BaseChatMesh.h | 4 ++-- 7 files changed, 23 insertions(+), 30 deletions(-) diff --git a/docs/companion_protocol.md b/docs/companion_protocol.md index 917df1df83..2ec9a51288 100644 --- a/docs/companion_protocol.md +++ b/docs/companion_protocol.md @@ -290,8 +290,7 @@ Bytes 7+: Message Text (UTF-8, variable length) Byte 0: 0x3E Byte 1: Data Type (`data_type`) Byte 2: Channel Index (0-7) -Bytes 3-6: Timestamp (32-bit little-endian Unix timestamp, seconds) -Bytes 7+: Binary payload bytes (variable length) +Bytes 3+: Binary payload bytes (variable length) ``` **Data Type / Transport Mapping**: @@ -299,8 +298,10 @@ Bytes 7+: Binary payload bytes (variable length) - `0x00` is invalid for this command. - Values other than `0xFF` are reserved for official protocol extensions. +**Note**: Applications that need a timestamp should encode it inside the binary payload. + **Limits**: -- Maximum payload length is `160` bytes. +- Maximum payload length is `166` bytes. - Larger payloads are rejected with `PACKET_ERROR`. **Response**: `PACKET_OK` (0x00) on success diff --git a/examples/companion_radio/MyMesh.cpp b/examples/companion_radio/MyMesh.cpp index 2a540c5be7..ac5afe243b 100644 --- a/examples/companion_radio/MyMesh.cpp +++ b/examples/companion_radio/MyMesh.cpp @@ -94,7 +94,7 @@ #define RESP_ALLOWED_REPEAT_FREQ 26 #define RESP_CODE_CHANNEL_DATA_RECV 27 -#define MAX_CHANNEL_DATA_LENGTH (MAX_FRAME_SIZE - 12) +#define MAX_CHANNEL_DATA_LENGTH (MAX_FRAME_SIZE - 8) #define SEND_TIMEOUT_BASE_MILLIS 500 #define FLOOD_SEND_TIMEOUT_FACTOR 16.0f @@ -569,7 +569,7 @@ void MyMesh::onChannelMessageRecv(const mesh::GroupChannel &channel, mesh::Packe #endif } -void MyMesh::onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, uint8_t data_type, +void MyMesh::onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint8_t data_type, const uint8_t *data, size_t data_len) { if (data_len > MAX_CHANNEL_DATA_LENGTH) { MESH_DEBUG_PRINTLN("onChannelDataRecv: dropping payload_len=%d exceeds frame limit=%d", @@ -588,8 +588,6 @@ void MyMesh::onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet * out_frame[i++] = pkt->isRouteFlood() ? pkt->path_len : 0xFF; out_frame[i++] = data_type; out_frame[i++] = (uint8_t)data_len; - memcpy(&out_frame[i], ×tamp, 4); - i += 4; int copy_len = (int)data_len; if (copy_len > 0) { @@ -1096,9 +1094,6 @@ void MyMesh::handleCmdFrame(size_t len) { int i = 1; uint8_t data_type = cmd_frame[i++]; uint8_t channel_idx = cmd_frame[i++]; - uint32_t msg_timestamp; - memcpy(&msg_timestamp, &cmd_frame[i], 4); - i += 4; const uint8_t *payload = &cmd_frame[i]; int payload_len = (len > (size_t)i) ? (int)(len - i) : 0; @@ -1110,7 +1105,7 @@ void MyMesh::handleCmdFrame(size_t len) { } else if (payload_len > MAX_CHANNEL_DATA_LENGTH) { MESH_DEBUG_PRINTLN("CMD_SEND_CHANNEL_DATA payload too long: %d > %d", payload_len, MAX_CHANNEL_DATA_LENGTH); writeErrFrame(ERR_CODE_ILLEGAL_ARG); - } else if (sendGroupData(msg_timestamp, channel.channel, data_type, payload, payload_len)) { + } else if (sendGroupData(channel.channel, data_type, payload, payload_len)) { writeOKFrame(); } else { writeErrFrame(ERR_CODE_TABLE_FULL); diff --git a/examples/companion_radio/MyMesh.h b/examples/companion_radio/MyMesh.h index 78ea6414e1..485b8af1ca 100644 --- a/examples/companion_radio/MyMesh.h +++ b/examples/companion_radio/MyMesh.h @@ -137,7 +137,7 @@ class MyMesh : public BaseChatMesh, public DataStoreHost { const uint8_t *sender_prefix, const char *text) override; void onChannelMessageRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, const char *text) override; - void onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, uint8_t data_type, + void onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint8_t data_type, const uint8_t *data, size_t data_len) override; uint8_t onContactRequest(const ContactInfo &contact, uint32_t sender_timestamp, const uint8_t *data, diff --git a/src/MeshCore.h b/src/MeshCore.h index cf8f949e66..5613599583 100644 --- a/src/MeshCore.h +++ b/src/MeshCore.h @@ -17,7 +17,7 @@ #define PATH_HASH_SIZE 1 #define MAX_PACKET_PAYLOAD 184 -#define MAX_GROUP_DATA_LENGTH (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 6) +#define MAX_GROUP_DATA_LENGTH (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 2) #define MAX_PATH_SIZE 64 #define MAX_TRANS_UNIT 255 diff --git a/src/Packet.h b/src/Packet.h index c5c5ab0084..60f6526af5 100644 --- a/src/Packet.h +++ b/src/Packet.h @@ -22,7 +22,7 @@ namespace mesh { #define PAYLOAD_TYPE_ACK 0x03 // a simple ack #define PAYLOAD_TYPE_ADVERT 0x04 // a node advertising its Identity #define PAYLOAD_TYPE_GRP_TXT 0x05 // an (unverified) group text message (prefixed with channel hash, MAC) (enc data: timestamp, "name: msg") -#define PAYLOAD_TYPE_GRP_DATA 0x06 // an (unverified) group datagram (prefixed with channel hash, MAC) (enc data: timestamp, data_type, data_len, blob) +#define PAYLOAD_TYPE_GRP_DATA 0x06 // an (unverified) group datagram (prefixed with channel hash, MAC) (enc data: data_type, data_len, blob) #define PAYLOAD_TYPE_ANON_REQ 0x07 // generic request (prefixed with dest_hash, ephemeral pub_key, MAC) (enc data: ...) #define PAYLOAD_TYPE_PATH 0x08 // returned path (prefixed with dest/src hashes, MAC) (enc data: path, extra) #define PAYLOAD_TYPE_TRACE 0x09 // trace a path, collecting SNI for each hop diff --git a/src/helpers/BaseChatMesh.cpp b/src/helpers/BaseChatMesh.cpp index 5f4e0d4da9..2a4290edcb 100644 --- a/src/helpers/BaseChatMesh.cpp +++ b/src/helpers/BaseChatMesh.cpp @@ -374,16 +374,14 @@ void BaseChatMesh::onGroupDataRecv(mesh::Packet* packet, uint8_t type, const mes // notify UI of this new message onChannelMessageRecv(channel, packet, timestamp, (const char *) &data[5]); // let UI know } else if (type == PAYLOAD_TYPE_GRP_DATA) { - if (len < 6) { + if (len < 2) { MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping short group data payload len=%d", (uint32_t)len); return; } - uint32_t timestamp; - memcpy(×tamp, data, 4); - uint8_t data_type = data[4]; - uint8_t data_len = data[5]; - size_t available_len = len - 6; + uint8_t data_type = data[0]; + uint8_t data_len = data[1]; + size_t available_len = len - 2; if (data_len > available_len) { MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping malformed group data type=%d len=%d available=%d", @@ -391,7 +389,7 @@ void BaseChatMesh::onGroupDataRecv(mesh::Packet* packet, uint8_t type, const mes return; } - onChannelDataRecv(channel, packet, timestamp, data_type, &data[6], data_len); + onChannelDataRecv(channel, packet, data_type, &data[2], data_len); } } @@ -483,7 +481,7 @@ bool BaseChatMesh::sendGroupMessage(uint32_t timestamp, mesh::GroupChannel& chan return false; } -bool BaseChatMesh::sendGroupData(uint32_t timestamp, mesh::GroupChannel& channel, uint8_t data_type, const uint8_t* data, int data_len) { +bool BaseChatMesh::sendGroupData(mesh::GroupChannel& channel, uint8_t data_type, const uint8_t* data, int data_len) { if (data_len < 0) { MESH_DEBUG_PRINTLN("sendGroupData: invalid negative data_len=%d", data_len); return false; @@ -493,13 +491,12 @@ bool BaseChatMesh::sendGroupData(uint32_t timestamp, mesh::GroupChannel& channel return false; } - uint8_t temp[6 + MAX_GROUP_DATA_LENGTH]; - memcpy(temp, ×tamp, 4); - temp[4] = data_type; - temp[5] = (uint8_t)data_len; - if (data_len > 0) memcpy(&temp[6], data, data_len); + uint8_t temp[2 + MAX_GROUP_DATA_LENGTH]; + temp[0] = data_type; + temp[1] = (uint8_t)data_len; + if (data_len > 0) memcpy(&temp[2], data, data_len); - auto pkt = createGroupDatagram(PAYLOAD_TYPE_GRP_DATA, channel, temp, 6 + data_len); + auto pkt = createGroupDatagram(PAYLOAD_TYPE_GRP_DATA, channel, temp, 2 + data_len); if (pkt == NULL) { MESH_DEBUG_PRINTLN("sendGroupData: unable to create group datagram, data_len=%d", data_len); return false; diff --git a/src/helpers/BaseChatMesh.h b/src/helpers/BaseChatMesh.h index 12fcb95719..08a5500525 100644 --- a/src/helpers/BaseChatMesh.h +++ b/src/helpers/BaseChatMesh.h @@ -111,7 +111,7 @@ class BaseChatMesh : public mesh::Mesh { virtual uint32_t calcDirectTimeoutMillisFor(uint32_t pkt_airtime_millis, uint8_t path_len) const = 0; virtual void onSendTimeout() = 0; virtual void onChannelMessageRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t timestamp, const char *text) = 0; - virtual void onChannelDataRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t timestamp, uint8_t data_type, + virtual void onChannelDataRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint8_t data_type, const uint8_t* data, size_t data_len) {} virtual uint8_t onContactRequest(const ContactInfo& contact, uint32_t sender_timestamp, const uint8_t* data, uint8_t len, uint8_t* reply) = 0; virtual void onContactResponse(const ContactInfo& contact, const uint8_t* data, uint8_t len) = 0; @@ -150,7 +150,7 @@ class BaseChatMesh : public mesh::Mesh { int sendMessage(const ContactInfo& recipient, uint32_t timestamp, uint8_t attempt, const char* text, uint32_t& expected_ack, uint32_t& est_timeout); int sendCommandData(const ContactInfo& recipient, uint32_t timestamp, uint8_t attempt, const char* text, uint32_t& est_timeout); bool sendGroupMessage(uint32_t timestamp, mesh::GroupChannel& channel, const char* sender_name, const char* text, int text_len); - bool sendGroupData(uint32_t timestamp, mesh::GroupChannel& channel, uint8_t data_type, const uint8_t* data, int data_len); + bool sendGroupData(mesh::GroupChannel& channel, uint8_t data_type, const uint8_t* data, int data_len); int sendLogin(const ContactInfo& recipient, const char* password, uint32_t& est_timeout); int sendAnonReq(const ContactInfo& recipient, const uint8_t* data, uint8_t len, uint32_t& tag, uint32_t& est_timeout); int sendRequest(const ContactInfo& recipient, uint8_t req_type, uint32_t& tag, uint32_t& est_timeout); From 2f68769185ba5a1d0a22afd2b9c7f50387f189be Mon Sep 17 00:00:00 2001 From: Janez T Date: Thu, 19 Mar 2026 09:25:42 +0100 Subject: [PATCH 22/52] fix: Widen grp data type ref: #1928 --- docs/companion_protocol.md | 14 +++++++------- docs/faq.md | 2 +- examples/companion_radio/MyMesh.cpp | 18 ++++++++++++------ examples/companion_radio/MyMesh.h | 2 +- src/MeshCore.h | 2 +- src/Packet.h | 2 +- src/helpers/BaseChatMesh.cpp | 23 ++++++++++++----------- src/helpers/BaseChatMesh.h | 4 ++-- src/helpers/TxtDataHelpers.h | 8 ++++---- 9 files changed, 41 insertions(+), 34 deletions(-) diff --git a/docs/companion_protocol.md b/docs/companion_protocol.md index 2ec9a51288..ce3953ec58 100644 --- a/docs/companion_protocol.md +++ b/docs/companion_protocol.md @@ -288,20 +288,20 @@ Bytes 7+: Message Text (UTF-8, variable length) **Command Format**: ``` Byte 0: 0x3E -Byte 1: Data Type (`data_type`) -Byte 2: Channel Index (0-7) -Bytes 3+: Binary payload bytes (variable length) +Bytes 1-2: Data Type (`data_type`, 16-bit little-endian) +Byte 3: Channel Index (0-7) +Bytes 4+: Binary payload bytes (variable length) ``` **Data Type / Transport Mapping**: -- `0xFF` (`DATA_TYPE_CUSTOM`) must be used for custom-protocol binary datagrams. -- `0x00` is invalid for this command. -- Values other than `0xFF` are reserved for official protocol extensions. +- `0x0000` is invalid for this command. +- `0xFFFF` (`DATA_TYPE_CUSTOM`) is the generic custom-app namespace. +- Other non-zero values can be used as assigned application/community namespaces. **Note**: Applications that need a timestamp should encode it inside the binary payload. **Limits**: -- Maximum payload length is `166` bytes. +- Maximum payload length is `163` bytes. - Larger payloads are rejected with `PACKET_ERROR`. **Response**: `PACKET_OK` (0x00) on success diff --git a/docs/faq.md b/docs/faq.md index 530f97013b..560e3f629b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -386,7 +386,7 @@ https://github.com/meshcore-dev/MeshCore/blob/main/src/Packet.h#L19 #define PAYLOAD_TYPE_TXT_MSG 0x02 // a plain text message (prefixed with dest/src hashes, MAC) (enc data: timestamp, text) #define PAYLOAD_TYPE_ACK 0x03 // a simple ack #define PAYLOAD_TYPE_ADVERT 0x04 // a node advertising its Identity #define PAYLOAD_TYPE_GRP_TXT 0x05 // an (unverified) group text message (prefixed with channel hash, MAC) (enc data: timestamp, "name: msg") - #define PAYLOAD_TYPE_GRP_DATA 0x06 // an (unverified) group datagram (prefixed with channel hash, MAC) (enc data: timestamp, blob) + #define PAYLOAD_TYPE_GRP_DATA 0x06 // an (unverified) group datagram (prefixed with channel hash, MAC) (enc data: data_type, data_len, blob) #define PAYLOAD_TYPE_ANON_REQ 0x07 // generic request (prefixed with dest_hash, ephemeral pub_key, MAC) (enc data: ...) #define PAYLOAD_TYPE_PATH 0x08 // returned path (prefixed with dest/src hashes, MAC) (enc data: path, extra) diff --git a/examples/companion_radio/MyMesh.cpp b/examples/companion_radio/MyMesh.cpp index ac5afe243b..cb82c954e6 100644 --- a/examples/companion_radio/MyMesh.cpp +++ b/examples/companion_radio/MyMesh.cpp @@ -94,7 +94,7 @@ #define RESP_ALLOWED_REPEAT_FREQ 26 #define RESP_CODE_CHANNEL_DATA_RECV 27 -#define MAX_CHANNEL_DATA_LENGTH (MAX_FRAME_SIZE - 8) +#define MAX_CHANNEL_DATA_LENGTH (MAX_FRAME_SIZE - 9) #define SEND_TIMEOUT_BASE_MILLIS 500 #define FLOOD_SEND_TIMEOUT_FACTOR 16.0f @@ -569,7 +569,7 @@ void MyMesh::onChannelMessageRecv(const mesh::GroupChannel &channel, mesh::Packe #endif } -void MyMesh::onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint8_t data_type, +void MyMesh::onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint16_t data_type, const uint8_t *data, size_t data_len) { if (data_len > MAX_CHANNEL_DATA_LENGTH) { MESH_DEBUG_PRINTLN("onChannelDataRecv: dropping payload_len=%d exceeds frame limit=%d", @@ -586,7 +586,8 @@ void MyMesh::onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet * uint8_t channel_idx = findChannelIdx(channel); out_frame[i++] = channel_idx; out_frame[i++] = pkt->isRouteFlood() ? pkt->path_len : 0xFF; - out_frame[i++] = data_type; + out_frame[i++] = (uint8_t)(data_type & 0xFF); + out_frame[i++] = (uint8_t)(data_type >> 8); out_frame[i++] = (uint8_t)data_len; int copy_len = (int)data_len; @@ -1091,8 +1092,13 @@ void MyMesh::handleCmdFrame(size_t len) { } } } else if (cmd_frame[0] == CMD_SEND_CHANNEL_DATA) { // send GroupChannel datagram + if (len < 4) { + writeErrFrame(ERR_CODE_ILLEGAL_ARG); + return; + } int i = 1; - uint8_t data_type = cmd_frame[i++]; + uint16_t data_type = ((uint16_t)cmd_frame[i]) | (((uint16_t)cmd_frame[i + 1]) << 8); + i += 2; uint8_t channel_idx = cmd_frame[i++]; const uint8_t *payload = &cmd_frame[i]; int payload_len = (len > (size_t)i) ? (int)(len - i) : 0; @@ -1100,8 +1106,8 @@ void MyMesh::handleCmdFrame(size_t len) { ChannelDetails channel; if (!getChannel(channel_idx, channel)) { writeErrFrame(ERR_CODE_NOT_FOUND); // bad channel_idx - } else if (data_type != DATA_TYPE_CUSTOM) { - writeErrFrame(ERR_CODE_UNSUPPORTED_CMD); + } else if (data_type == 0) { + writeErrFrame(ERR_CODE_ILLEGAL_ARG); } else if (payload_len > MAX_CHANNEL_DATA_LENGTH) { MESH_DEBUG_PRINTLN("CMD_SEND_CHANNEL_DATA payload too long: %d > %d", payload_len, MAX_CHANNEL_DATA_LENGTH); writeErrFrame(ERR_CODE_ILLEGAL_ARG); diff --git a/examples/companion_radio/MyMesh.h b/examples/companion_radio/MyMesh.h index 485b8af1ca..33d615d504 100644 --- a/examples/companion_radio/MyMesh.h +++ b/examples/companion_radio/MyMesh.h @@ -137,7 +137,7 @@ class MyMesh : public BaseChatMesh, public DataStoreHost { const uint8_t *sender_prefix, const char *text) override; void onChannelMessageRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint32_t timestamp, const char *text) override; - void onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint8_t data_type, + void onChannelDataRecv(const mesh::GroupChannel &channel, mesh::Packet *pkt, uint16_t data_type, const uint8_t *data, size_t data_len) override; uint8_t onContactRequest(const ContactInfo &contact, uint32_t sender_timestamp, const uint8_t *data, diff --git a/src/MeshCore.h b/src/MeshCore.h index 5613599583..2db1d4c3ec 100644 --- a/src/MeshCore.h +++ b/src/MeshCore.h @@ -17,7 +17,7 @@ #define PATH_HASH_SIZE 1 #define MAX_PACKET_PAYLOAD 184 -#define MAX_GROUP_DATA_LENGTH (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 2) +#define MAX_GROUP_DATA_LENGTH (MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 3) #define MAX_PATH_SIZE 64 #define MAX_TRANS_UNIT 255 diff --git a/src/Packet.h b/src/Packet.h index 60f6526af5..0886a06c4e 100644 --- a/src/Packet.h +++ b/src/Packet.h @@ -22,7 +22,7 @@ namespace mesh { #define PAYLOAD_TYPE_ACK 0x03 // a simple ack #define PAYLOAD_TYPE_ADVERT 0x04 // a node advertising its Identity #define PAYLOAD_TYPE_GRP_TXT 0x05 // an (unverified) group text message (prefixed with channel hash, MAC) (enc data: timestamp, "name: msg") -#define PAYLOAD_TYPE_GRP_DATA 0x06 // an (unverified) group datagram (prefixed with channel hash, MAC) (enc data: data_type, data_len, blob) +#define PAYLOAD_TYPE_GRP_DATA 0x06 // an (unverified) group datagram (prefixed with channel hash, MAC) (enc data: data_type(uint16), data_len, blob) #define PAYLOAD_TYPE_ANON_REQ 0x07 // generic request (prefixed with dest_hash, ephemeral pub_key, MAC) (enc data: ...) #define PAYLOAD_TYPE_PATH 0x08 // returned path (prefixed with dest/src hashes, MAC) (enc data: path, extra) #define PAYLOAD_TYPE_TRACE 0x09 // trace a path, collecting SNI for each hop diff --git a/src/helpers/BaseChatMesh.cpp b/src/helpers/BaseChatMesh.cpp index 2a4290edcb..78e197bee2 100644 --- a/src/helpers/BaseChatMesh.cpp +++ b/src/helpers/BaseChatMesh.cpp @@ -374,14 +374,14 @@ void BaseChatMesh::onGroupDataRecv(mesh::Packet* packet, uint8_t type, const mes // notify UI of this new message onChannelMessageRecv(channel, packet, timestamp, (const char *) &data[5]); // let UI know } else if (type == PAYLOAD_TYPE_GRP_DATA) { - if (len < 2) { + if (len < 3) { MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping short group data payload len=%d", (uint32_t)len); return; } - uint8_t data_type = data[0]; - uint8_t data_len = data[1]; - size_t available_len = len - 2; + uint16_t data_type = ((uint16_t)data[0]) | (((uint16_t)data[1]) << 8); + uint8_t data_len = data[2]; + size_t available_len = len - 3; if (data_len > available_len) { MESH_DEBUG_PRINTLN("onGroupDataRecv: dropping malformed group data type=%d len=%d available=%d", @@ -389,7 +389,7 @@ void BaseChatMesh::onGroupDataRecv(mesh::Packet* packet, uint8_t type, const mes return; } - onChannelDataRecv(channel, packet, data_type, &data[2], data_len); + onChannelDataRecv(channel, packet, data_type, &data[3], data_len); } } @@ -481,7 +481,7 @@ bool BaseChatMesh::sendGroupMessage(uint32_t timestamp, mesh::GroupChannel& chan return false; } -bool BaseChatMesh::sendGroupData(mesh::GroupChannel& channel, uint8_t data_type, const uint8_t* data, int data_len) { +bool BaseChatMesh::sendGroupData(mesh::GroupChannel& channel, uint16_t data_type, const uint8_t* data, int data_len) { if (data_len < 0) { MESH_DEBUG_PRINTLN("sendGroupData: invalid negative data_len=%d", data_len); return false; @@ -491,12 +491,13 @@ bool BaseChatMesh::sendGroupData(mesh::GroupChannel& channel, uint8_t data_type, return false; } - uint8_t temp[2 + MAX_GROUP_DATA_LENGTH]; - temp[0] = data_type; - temp[1] = (uint8_t)data_len; - if (data_len > 0) memcpy(&temp[2], data, data_len); + uint8_t temp[3 + MAX_GROUP_DATA_LENGTH]; + temp[0] = (uint8_t)(data_type & 0xFF); + temp[1] = (uint8_t)(data_type >> 8); + temp[2] = (uint8_t)data_len; + if (data_len > 0) memcpy(&temp[3], data, data_len); - auto pkt = createGroupDatagram(PAYLOAD_TYPE_GRP_DATA, channel, temp, 2 + data_len); + auto pkt = createGroupDatagram(PAYLOAD_TYPE_GRP_DATA, channel, temp, 3 + data_len); if (pkt == NULL) { MESH_DEBUG_PRINTLN("sendGroupData: unable to create group datagram, data_len=%d", data_len); return false; diff --git a/src/helpers/BaseChatMesh.h b/src/helpers/BaseChatMesh.h index 08a5500525..c2f9d9154a 100644 --- a/src/helpers/BaseChatMesh.h +++ b/src/helpers/BaseChatMesh.h @@ -111,7 +111,7 @@ class BaseChatMesh : public mesh::Mesh { virtual uint32_t calcDirectTimeoutMillisFor(uint32_t pkt_airtime_millis, uint8_t path_len) const = 0; virtual void onSendTimeout() = 0; virtual void onChannelMessageRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint32_t timestamp, const char *text) = 0; - virtual void onChannelDataRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint8_t data_type, + virtual void onChannelDataRecv(const mesh::GroupChannel& channel, mesh::Packet* pkt, uint16_t data_type, const uint8_t* data, size_t data_len) {} virtual uint8_t onContactRequest(const ContactInfo& contact, uint32_t sender_timestamp, const uint8_t* data, uint8_t len, uint8_t* reply) = 0; virtual void onContactResponse(const ContactInfo& contact, const uint8_t* data, uint8_t len) = 0; @@ -150,7 +150,7 @@ class BaseChatMesh : public mesh::Mesh { int sendMessage(const ContactInfo& recipient, uint32_t timestamp, uint8_t attempt, const char* text, uint32_t& expected_ack, uint32_t& est_timeout); int sendCommandData(const ContactInfo& recipient, uint32_t timestamp, uint8_t attempt, const char* text, uint32_t& est_timeout); bool sendGroupMessage(uint32_t timestamp, mesh::GroupChannel& channel, const char* sender_name, const char* text, int text_len); - bool sendGroupData(mesh::GroupChannel& channel, uint8_t data_type, const uint8_t* data, int data_len); + bool sendGroupData(mesh::GroupChannel& channel, uint16_t data_type, const uint8_t* data, int data_len); int sendLogin(const ContactInfo& recipient, const char* password, uint32_t& est_timeout); int sendAnonReq(const ContactInfo& recipient, const uint8_t* data, uint8_t len, uint32_t& tag, uint32_t& est_timeout); int sendRequest(const ContactInfo& recipient, uint8_t req_type, uint32_t& tag, uint32_t& est_timeout); diff --git a/src/helpers/TxtDataHelpers.h b/src/helpers/TxtDataHelpers.h index a853a64db3..ad845b40ea 100644 --- a/src/helpers/TxtDataHelpers.h +++ b/src/helpers/TxtDataHelpers.h @@ -3,10 +3,10 @@ #include #include -#define TXT_TYPE_PLAIN 0 // a plain text message -#define TXT_TYPE_CLI_DATA 1 // a CLI command -#define TXT_TYPE_SIGNED_PLAIN 2 // plain text, signed by sender -#define DATA_TYPE_CUSTOM 0xFF // custom app binary payload (group/channel datagrams) +#define TXT_TYPE_PLAIN 0 // a plain text message +#define TXT_TYPE_CLI_DATA 1 // a CLI command +#define TXT_TYPE_SIGNED_PLAIN 2 // plain text, signed by sender +#define DATA_TYPE_CUSTOM 0xFFFF // generic custom app namespace for group/channel datagrams class StrHelper { public: From ae9fcb3c0bb5a9a8d8bf7006b8c8a747450bd1dd Mon Sep 17 00:00:00 2001 From: Janez T Date: Thu, 19 Mar 2026 09:35:02 +0100 Subject: [PATCH 23/52] fix: Rename grp dev type ref: #1928 --- docs/companion_protocol.md | 2 +- src/helpers/TxtDataHelpers.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/companion_protocol.md b/docs/companion_protocol.md index ce3953ec58..bbad1e40f0 100644 --- a/docs/companion_protocol.md +++ b/docs/companion_protocol.md @@ -295,7 +295,7 @@ Bytes 4+: Binary payload bytes (variable length) **Data Type / Transport Mapping**: - `0x0000` is invalid for this command. -- `0xFFFF` (`DATA_TYPE_CUSTOM`) is the generic custom-app namespace. +- `0xFFFF` (`DATA_TYPE_DEV`) is the developer namespace for experimenting and developing apps. - Other non-zero values can be used as assigned application/community namespaces. **Note**: Applications that need a timestamp should encode it inside the binary payload. diff --git a/src/helpers/TxtDataHelpers.h b/src/helpers/TxtDataHelpers.h index ad845b40ea..47bbc0ded9 100644 --- a/src/helpers/TxtDataHelpers.h +++ b/src/helpers/TxtDataHelpers.h @@ -6,7 +6,7 @@ #define TXT_TYPE_PLAIN 0 // a plain text message #define TXT_TYPE_CLI_DATA 1 // a CLI command #define TXT_TYPE_SIGNED_PLAIN 2 // plain text, signed by sender -#define DATA_TYPE_CUSTOM 0xFFFF // generic custom app namespace for group/channel datagrams +#define DATA_TYPE_DEV 0xFFFF // developer namespace for experimenting with group/channel datagrams and building apps class StrHelper { public: From f6cfed66b35da802c003daf45fec6d4007f11316 Mon Sep 17 00:00:00 2001 From: Quency-D Date: Fri, 20 Mar 2026 15:56:09 +0800 Subject: [PATCH 24/52] add heltec_mesh_node_t096 board. --- boards/heltec_t096.json | 61 ++++++++++ src/helpers/ui/ST7735Display.cpp | 15 ++- variants/heltec_t096/LoRaFEMControl.cpp | 51 ++++++++ variants/heltec_t096/LoRaFEMControl.h | 21 ++++ variants/heltec_t096/T096Board.cpp | 126 ++++++++++++++++++++ variants/heltec_t096/T096Board.h | 28 +++++ variants/heltec_t096/platformio.ini | 148 ++++++++++++++++++++++++ variants/heltec_t096/target.cpp | 64 ++++++++++ variants/heltec_t096/target.h | 33 ++++++ variants/heltec_t096/variant.cpp | 15 +++ variants/heltec_t096/variant.h | 132 +++++++++++++++++++++ 11 files changed, 690 insertions(+), 4 deletions(-) create mode 100644 boards/heltec_t096.json create mode 100644 variants/heltec_t096/LoRaFEMControl.cpp create mode 100644 variants/heltec_t096/LoRaFEMControl.h create mode 100644 variants/heltec_t096/T096Board.cpp create mode 100644 variants/heltec_t096/T096Board.h create mode 100644 variants/heltec_t096/platformio.ini create mode 100644 variants/heltec_t096/target.cpp create mode 100644 variants/heltec_t096/target.h create mode 100644 variants/heltec_t096/variant.cpp create mode 100644 variants/heltec_t096/variant.h diff --git a/boards/heltec_t096.json b/boards/heltec_t096.json new file mode 100644 index 0000000000..9d4f3037e7 --- /dev/null +++ b/boards/heltec_t096.json @@ -0,0 +1,61 @@ +{ + "build": { + "arduino": { + "ldscript": "nrf52840_s140_v6.ld" + }, + "core": "nRF5", + "cpu": "cortex-m4", + "extra_flags": "-DARDUINO_NRF52840_FEATHER -DNRF52840_XXAA", + "f_cpu": "64000000L", + "hwids": [ + ["0x239A","0x8029"], + ["0x239A","0x0029"], + ["0x239A","0x002A"], + ["0x239A","0x802A"] + ], + "usb_product": "HT-n5262G", + "mcu": "nrf52840", + "variant": "Heltec_T096_Board", + "bsp": { + "name": "adafruit" + }, + "softdevice": { + "sd_flags": "-DS140", + "sd_name": "s140", + "sd_version": "6.1.1", + "sd_fwid": "0x00B6" + }, + "bootloader": { + "settings_addr": "0xFF000" + } + }, + "connectivity": [ + "bluetooth" + ], + "debug": { + "jlink_device": "nRF52840_xxAA", + "svd_path": "nrf52840.svd", + "openocd_target": "nrf52.cfg" + }, + "frameworks": [ + "arduino" + ], + "name": "Heltec T096 Board", + "upload": { + "maximum_ram_size": 235520, + "maximum_size": 815104, + "speed": 115200, + "protocol": "nrfutil", + "protocols": [ + "jlink", + "nrfjprog", + "nrfutil", + "stlink" + ], + "use_1200bps_touch": true, + "require_upload_port": true, + "wait_for_upload_port": true + }, + "url": "https://heltec.org/", + "vendor": "Heltec" +} \ No newline at end of file diff --git a/src/helpers/ui/ST7735Display.cpp b/src/helpers/ui/ST7735Display.cpp index 0a28077c06..3eb4521cca 100644 --- a/src/helpers/ui/ST7735Display.cpp +++ b/src/helpers/ui/ST7735Display.cpp @@ -21,10 +21,14 @@ bool ST7735Display::begin() { if (_peripher_power) _peripher_power->claim(); pinMode(PIN_TFT_LEDA_CTL, OUTPUT); - digitalWrite(PIN_TFT_LEDA_CTL, HIGH); +#if defined(PIN_TFT_LEDA_CTL_ACTIVE) + digitalWrite(PIN_TFT_LEDA_CTL, PIN_TFT_LEDA_CTL_ACTIVE); +#else + digitalWrite(PIN_TFT_LEDA_CTL, HIGH); +#endif digitalWrite(PIN_TFT_RST, HIGH); -#if defined(HELTEC_TRACKER_V2) +#if defined(HELTEC_TRACKER_V2) || defined(HELTEC_T096) display.initR(INITR_MINI160x80); display.setRotation(DISPLAY_ROTATION); uint8_t madctl = ST77XX_MADCTL_MY | ST77XX_MADCTL_MV |ST7735_MADCTL_BGR;//Adjust color to BGR @@ -50,9 +54,12 @@ void ST7735Display::turnOn() { void ST7735Display::turnOff() { if (_isOn) { - digitalWrite(PIN_TFT_LEDA_CTL, HIGH); digitalWrite(PIN_TFT_RST, LOW); - digitalWrite(PIN_TFT_LEDA_CTL, LOW); +#if defined(PIN_TFT_LEDA_CTL_ACTIVE) + digitalWrite(PIN_TFT_LEDA_CTL, !PIN_TFT_LEDA_CTL_ACTIVE); +#else + digitalWrite(PIN_TFT_LEDA_CTL, LOW); +#endif _isOn = false; if (_peripher_power) _peripher_power->release(); diff --git a/variants/heltec_t096/LoRaFEMControl.cpp b/variants/heltec_t096/LoRaFEMControl.cpp new file mode 100644 index 0000000000..9aeb83852b --- /dev/null +++ b/variants/heltec_t096/LoRaFEMControl.cpp @@ -0,0 +1,51 @@ +#include "LoRaFEMControl.h" +#include + +void LoRaFEMControl::init(void) +{ + pinMode(P_LORA_PA_POWER, OUTPUT); + digitalWrite(P_LORA_PA_POWER, HIGH); + delay(1); + pinMode(P_LORA_KCT8103L_PA_CSD, OUTPUT); + digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); + pinMode(P_LORA_KCT8103L_PA_CTX, OUTPUT); + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + setLnaCanControl(true); +} + +void LoRaFEMControl::setSleepModeEnable(void) +{ + // shutdown the PA + digitalWrite(P_LORA_KCT8103L_PA_CSD, LOW); +} + +void LoRaFEMControl::setTxModeEnable(void) +{ + digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); +} + +void LoRaFEMControl::setRxModeEnable(void) +{ + digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); + if (lna_enabled) { + digitalWrite(P_LORA_KCT8103L_PA_CTX, LOW); + } else { + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + } +} + +void LoRaFEMControl::setRxModeEnableWhenMCUSleep(void) +{ + digitalWrite(P_LORA_KCT8103L_PA_CSD, HIGH); + if (lna_enabled) { + digitalWrite(P_LORA_KCT8103L_PA_CTX, LOW); + } else { + digitalWrite(P_LORA_KCT8103L_PA_CTX, HIGH); + } +} + +void LoRaFEMControl::setLNAEnable(bool enabled) +{ + lna_enabled = enabled; +} diff --git a/variants/heltec_t096/LoRaFEMControl.h b/variants/heltec_t096/LoRaFEMControl.h new file mode 100644 index 0000000000..2c50b74289 --- /dev/null +++ b/variants/heltec_t096/LoRaFEMControl.h @@ -0,0 +1,21 @@ +#pragma once +#include + +class LoRaFEMControl +{ + public: + LoRaFEMControl() {} + virtual ~LoRaFEMControl() {} + void init(void); + void setSleepModeEnable(void); + void setTxModeEnable(void); + void setRxModeEnable(void); + void setRxModeEnableWhenMCUSleep(void); + void setLNAEnable(bool enabled); + bool isLnaCanControl(void) { return lna_can_control; } + void setLnaCanControl(bool can_control) { lna_can_control = can_control; } + + private: + bool lna_enabled = false; + bool lna_can_control = false; +}; diff --git a/variants/heltec_t096/T096Board.cpp b/variants/heltec_t096/T096Board.cpp new file mode 100644 index 0000000000..550131571f --- /dev/null +++ b/variants/heltec_t096/T096Board.cpp @@ -0,0 +1,126 @@ +#include "T096Board.h" + +#include +#include + +#ifdef NRF52_POWER_MANAGEMENT +// Static configuration for power management +// Values come from variant.h defines +const PowerMgtConfig power_config = { + .lpcomp_ain_channel = PWRMGT_LPCOMP_AIN, + .lpcomp_refsel = PWRMGT_LPCOMP_REFSEL, + .voltage_bootlock = PWRMGT_VOLTAGE_BOOTLOCK +}; + +void T096Board::initiateShutdown(uint8_t reason) { +#if ENV_INCLUDE_GPS == 1 + pinMode(PIN_GPS_EN, OUTPUT); + digitalWrite(PIN_GPS_EN, !PIN_GPS_EN_ACTIVE); +#endif + variant_shutdown(); + + bool enable_lpcomp = (reason == SHUTDOWN_REASON_LOW_VOLTAGE || + reason == SHUTDOWN_REASON_BOOT_PROTECT); + pinMode(PIN_BAT_CTL, OUTPUT); + digitalWrite(PIN_BAT_CTL, enable_lpcomp ? HIGH : LOW); + + if (enable_lpcomp) { + configureVoltageWake(power_config.lpcomp_ain_channel, power_config.lpcomp_refsel); + } + + enterSystemOff(reason); +} +#endif // NRF52_POWER_MANAGEMENT + +void T096Board::begin() { + NRF52Board::begin(); + +#ifdef NRF52_POWER_MANAGEMENT + // Boot voltage protection check (may not return if voltage too low) + checkBootVoltage(&power_config); +#endif + +#if defined(PIN_BOARD_SDA) && defined(PIN_BOARD_SCL) + Wire.setPins(PIN_BOARD_SDA, PIN_BOARD_SCL); +#endif + + Wire.begin(); + + pinMode(P_LORA_TX_LED, OUTPUT); + digitalWrite(P_LORA_TX_LED, LOW); + + periph_power.begin(); + loRaFEMControl.init(); + delay(1); +} + +void T096Board::onBeforeTransmit() { + digitalWrite(P_LORA_TX_LED, HIGH); // turn TX LED on + loRaFEMControl.setTxModeEnable(); +} + +void T096Board::onAfterTransmit() { + digitalWrite(P_LORA_TX_LED, LOW); //turn TX LED off + loRaFEMControl.setRxModeEnable(); +} + +uint16_t T096Board::getBattMilliVolts() { + int adcvalue = 0; + analogReadResolution(12); + analogReference(AR_INTERNAL_3_0); + pinMode(PIN_VBAT_READ, INPUT); + pinMode(PIN_BAT_CTL, OUTPUT); + digitalWrite(PIN_BAT_CTL, 1); + + delay(10); + adcvalue = analogRead(PIN_VBAT_READ); + digitalWrite(PIN_BAT_CTL, 0); + + return (uint16_t)((float)adcvalue * MV_LSB * 4.9); +} +void T096Board::variant_shutdown() { + nrf_gpio_cfg_default(PIN_VEXT_EN); + nrf_gpio_cfg_default(PIN_TFT_CS); + nrf_gpio_cfg_default(PIN_TFT_DC); + nrf_gpio_cfg_default(PIN_TFT_SDA); + nrf_gpio_cfg_default(PIN_TFT_SCL); + nrf_gpio_cfg_default(PIN_TFT_RST); + nrf_gpio_cfg_default(PIN_TFT_LEDA_CTL); + + nrf_gpio_cfg_default(PIN_LED); + + nrf_gpio_cfg_default(P_LORA_KCT8103L_PA_CSD); + nrf_gpio_cfg_default(P_LORA_KCT8103L_PA_CTX); + pinMode(P_LORA_PA_POWER, OUTPUT); + digitalWrite(P_LORA_PA_POWER, LOW); + + digitalWrite(PIN_BAT_CTL, LOW); + nrf_gpio_cfg_default(LORA_CS); + nrf_gpio_cfg_default(SX126X_DIO1); + nrf_gpio_cfg_default(SX126X_BUSY); + nrf_gpio_cfg_default(SX126X_RESET); + + nrf_gpio_cfg_default(PIN_SPI_MISO); + nrf_gpio_cfg_default(PIN_SPI_MOSI); + nrf_gpio_cfg_default(PIN_SPI_SCK); + + // nrf_gpio_cfg_default(PIN_GPS_PPS); + nrf_gpio_cfg_default(PIN_GPS_RESET); + nrf_gpio_cfg_default(PIN_GPS_EN); + nrf_gpio_cfg_default(PIN_GPS_RX); + nrf_gpio_cfg_default(PIN_GPS_TX); +} + +void T096Board::powerOff() { +#if ENV_INCLUDE_GPS == 1 + pinMode(PIN_GPS_EN, OUTPUT); + digitalWrite(PIN_GPS_EN, !PIN_GPS_EN_ACTIVE); +#endif + loRaFEMControl.setSleepModeEnable(); + variant_shutdown(); + sd_power_system_off(); +} + +const char* T096Board::getManufacturerName() const { + return "Heltec T096"; +} \ No newline at end of file diff --git a/variants/heltec_t096/T096Board.h b/variants/heltec_t096/T096Board.h new file mode 100644 index 0000000000..d1e3bdfdee --- /dev/null +++ b/variants/heltec_t096/T096Board.h @@ -0,0 +1,28 @@ +#pragma once + +#include +#include +#include +#include +#include "LoRaFEMControl.h" + +class T096Board : public NRF52BoardDCDC { +protected: +#ifdef NRF52_POWER_MANAGEMENT + void initiateShutdown(uint8_t reason) override; +#endif + void variant_shutdown(); + +public: + RefCountedDigitalPin periph_power; + LoRaFEMControl loRaFEMControl; + + T096Board() :periph_power(PIN_VEXT_EN,PIN_VEXT_EN_ACTIVE), NRF52Board("T096_OTA") {} + void begin(); + + void onBeforeTransmit(void) override; + void onAfterTransmit(void) override; + uint16_t getBattMilliVolts() override; + const char* getManufacturerName() const override ; + void powerOff() override; +}; diff --git a/variants/heltec_t096/platformio.ini b/variants/heltec_t096/platformio.ini new file mode 100644 index 0000000000..19b05f3ce4 --- /dev/null +++ b/variants/heltec_t096/platformio.ini @@ -0,0 +1,148 @@ +[Heltec_t096] +extends = nrf52_base +board = heltec_t096 +board_build.ldscript = boards/nrf52840_s140_v6.ld +build_flags = ${nrf52_base.build_flags} + ${sensor_base.build_flags} + -I lib/nrf52/s140_nrf52_6.1.1_API/include + -I lib/nrf52/s140_nrf52_6.1.1_API/include/nrf52 + -I variants/heltec_t096 + -I src/helpers/ui + -D HELTEC_T096 + -D NRF52_POWER_MANAGEMENT + -D P_LORA_DIO_1=21 + -D P_LORA_NSS=5 + -D P_LORA_RESET=16 + -D P_LORA_BUSY=19 + -D P_LORA_SCLK=40 + -D P_LORA_MISO=14 + -D P_LORA_MOSI=11 + -D P_LORA_TX_LED=28 + -D P_LORA_PA_POWER=30 ;VFEM_Ctrl -LDO power enable + -D P_LORA_KCT8103L_PA_CSD=12 + -D P_LORA_KCT8103L_PA_CTX=41 + -D LORA_TX_POWER=9 ; 9dBm + ~13dB KCT8103L gain = ~22dBm output + -D MAX_LORA_TX_POWER=22 ; Max SX1262 output -> ~28dBm at antenna + -D RADIO_CLASS=CustomSX1262 + -D WRAPPER_CLASS=CustomSX1262Wrapper + -D SX126X_DIO2_AS_RF_SWITCH=true + -D SX126X_DIO3_TCXO_VOLTAGE=1.8 + -D SX126X_CURRENT_LIMIT=140 + -D SX126X_RX_BOOSTED_GAIN=1 + -D PIN_VEXT_EN=26 ; Vext is connected to VDD which is also connected to TFT & GPS + -D PIN_VEXT_EN_ACTIVE=HIGH + -D PIN_GPS_RX=25 + -D PIN_GPS_TX=23 + -D PIN_GPS_EN=GPS_EN + -D PIN_GPS_EN_ACTIVE=LOW + -D PIN_GPS_RESET=GPS_RESET + -D PIN_GPS_RESET_ACTIVE=LOW + -D GPS_BAUD_RATE=115200 + -D PIN_VBAT_READ=BATTERY_PIN + -D PIN_BAT_CTL=47 + -D DISPLAY_CLASS=ST7735Display + -D DISPLAY_ROTATION=1 +build_src_filter = ${nrf52_base.build_src_filter} + + + + + +<../variants/heltec_t096> + + + + +lib_deps = + ${nrf52_base.lib_deps} + ${sensor_base.lib_deps} + adafruit/Adafruit ST7735 and ST7789 Library @ ^1.11.0 +debug_tool = jlink +upload_protocol = nrfutil + +[env:Heltec_t096_repeater] +extends = Heltec_t096 +build_src_filter = ${Heltec_t096.build_src_filter} + +<../examples/simple_repeater> + +build_flags = + ${Heltec_t096.build_flags} + -D ADVERT_NAME='"Heltec_t096 Repeater"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + -D MAX_NEIGHBOURS=50 +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 + +[env:Heltec_t096_repeater_bridge_rs232] +extends = Heltec_t096 +build_flags = + ${Heltec_t096.build_flags} + -D ADVERT_NAME='"RS232 Bridge"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + -D MAX_NEIGHBOURS=50 + -D WITH_RS232_BRIDGE=Serial2 + -D WITH_RS232_BRIDGE_RX=9 + -D WITH_RS232_BRIDGE_TX=10 +; -D BRIDGE_DEBUG=1 +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 +build_src_filter = ${Heltec_t096.build_src_filter} + + + +<../examples/simple_repeater> + +[env:Heltec_t096_room_server] +extends = Heltec_t096 +build_src_filter = ${Heltec_t096.build_src_filter} + +<../examples/simple_room_server> +build_flags = + ${Heltec_t096.build_flags} + -D ADVERT_NAME='"Heltec_t096 Room"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + -D ROOM_PASSWORD='"hello"' +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 + +[env:Heltec_t096_companion_radio_ble] +extends = Heltec_t096 +board_build.ldscript = boards/nrf52840_s140_v6_extrafs.ld +board_upload.maximum_size = 712704 +build_flags = + ${Heltec_t096.build_flags} + -I examples/companion_radio/ui-new + -D MAX_CONTACTS=350 + -D MAX_GROUP_CHANNELS=40 + -D BLE_PIN_CODE=123456 + -D ENV_INCLUDE_GPS=1 ; enable the GPS page in UI +; -D BLE_DEBUG_LOGGING=1 + -D OFFLINE_QUEUE_SIZE=256 +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 +build_src_filter = ${Heltec_t096.build_src_filter} + + + +<../examples/companion_radio/*.cpp> + +<../examples/companion_radio/ui-new/*.cpp> +lib_deps = + ${Heltec_t096.lib_deps} + densaugeo/base64 @ ~1.4.0 + +[env:Heltec_t096_companion_radio_usb] +extends = Heltec_t096 +board_build.ldscript = boards/nrf52840_s140_v6_extrafs.ld +board_upload.maximum_size = 712704 +build_flags = + ${Heltec_t096.build_flags} + -I examples/companion_radio/ui-new + -D MAX_CONTACTS=350 + -D MAX_GROUP_CHANNELS=40 +; -D BLE_PIN_CODE=123456 +; -D BLE_DEBUG_LOGGING=1 +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 +build_src_filter = ${Heltec_t096.build_src_filter} + + + +<../examples/companion_radio/*.cpp> + +<../examples/companion_radio/ui-new/*.cpp> +lib_deps = + ${Heltec_t096.lib_deps} + densaugeo/base64 @ ~1.4.0 \ No newline at end of file diff --git a/variants/heltec_t096/target.cpp b/variants/heltec_t096/target.cpp new file mode 100644 index 0000000000..09609b878f --- /dev/null +++ b/variants/heltec_t096/target.cpp @@ -0,0 +1,64 @@ +#include "target.h" + +#include +#include + +#ifdef ENV_INCLUDE_GPS +#include +#endif + +T096Board board; + +#if defined(P_LORA_SCLK) +RADIO_CLASS radio = new Module(P_LORA_NSS, P_LORA_DIO_1, P_LORA_RESET, P_LORA_BUSY, SPI); +#else +RADIO_CLASS radio = new Module(P_LORA_NSS, P_LORA_DIO_1, P_LORA_RESET, P_LORA_BUSY); +#endif + +WRAPPER_CLASS radio_driver(radio, board); + +VolatileRTCClock fallback_clock; +AutoDiscoverRTCClock rtc_clock(fallback_clock); + +#if ENV_INCLUDE_GPS +#include +MicroNMEALocationProvider nmea = MicroNMEALocationProvider(Serial1, &rtc_clock, GPS_RESET, GPS_EN, &board.periph_power); +EnvironmentSensorManager sensors = EnvironmentSensorManager(nmea); +#else +EnvironmentSensorManager sensors; +#endif + +#ifdef DISPLAY_CLASS +DISPLAY_CLASS display(&board.periph_power); +MomentaryButton user_btn(PIN_USER_BTN, 1000, true); +#endif + +bool radio_init() { + rtc_clock.begin(Wire); + +#if defined(P_LORA_SCLK) + return radio.std_init(&SPI); +#else + return radio.std_init(); +#endif +} + +uint32_t radio_get_rng_seed() { + return radio.random(0x7FFFFFFF); +} + +void radio_set_params(float freq, float bw, uint8_t sf, uint8_t cr) { + radio.setFrequency(freq); + radio.setSpreadingFactor(sf); + radio.setBandwidth(bw); + radio.setCodingRate(cr); +} + +void radio_set_tx_power(int8_t dbm) { + radio.setOutputPower(dbm); +} + +mesh::LocalIdentity radio_new_identity() { + RadioNoiseListener rng(radio); + return mesh::LocalIdentity(&rng); // create new random identity +} diff --git a/variants/heltec_t096/target.h b/variants/heltec_t096/target.h new file mode 100644 index 0000000000..8c704b23ac --- /dev/null +++ b/variants/heltec_t096/target.h @@ -0,0 +1,33 @@ +#pragma once + +#define RADIOLIB_STATIC_ONLY 1 +#include +#include +#include +#include +#include +#include +#include + +#ifdef DISPLAY_CLASS +#include +#include +#else +#include "helpers/ui/NullDisplayDriver.h" +#endif + +extern T096Board board; +extern WRAPPER_CLASS radio_driver; +extern AutoDiscoverRTCClock rtc_clock; +extern EnvironmentSensorManager sensors; + +#ifdef DISPLAY_CLASS +extern DISPLAY_CLASS display; +extern MomentaryButton user_btn; +#endif + +bool radio_init(); +uint32_t radio_get_rng_seed(); +void radio_set_params(float freq, float bw, uint8_t sf, uint8_t cr); +void radio_set_tx_power(int8_t dbm); +mesh::LocalIdentity radio_new_identity(); diff --git a/variants/heltec_t096/variant.cpp b/variants/heltec_t096/variant.cpp new file mode 100644 index 0000000000..2bca56a1f9 --- /dev/null +++ b/variants/heltec_t096/variant.cpp @@ -0,0 +1,15 @@ +#include "variant.h" +#include "wiring_constants.h" +#include "wiring_digital.h" + +const uint32_t g_ADigitalPinMap[] = { + 0xff, 0xff, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, + 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, + 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, + 40, 41, 42, 43, 44, 45, 46, 47 +}; + +void initVariant() +{ + pinMode(PIN_USER_BTN, INPUT); +} diff --git a/variants/heltec_t096/variant.h b/variants/heltec_t096/variant.h new file mode 100644 index 0000000000..c240c1f27b --- /dev/null +++ b/variants/heltec_t096/variant.h @@ -0,0 +1,132 @@ +/* + * variant.h + * Copyright (C) 2023 Seeed K.K. + * MIT License + */ + +#pragma once + +#include "WVariant.h" + +//////////////////////////////////////////////////////////////////////////////// +// Low frequency clock source + +#define USE_LFXO // 32.768 kHz crystal oscillator +#define VARIANT_MCK (64000000ul) + +#define WIRE_INTERFACES_COUNT (2) + +//////////////////////////////////////////////////////////////////////////////// +// Power + +#define NRF_APM +#define PIN_3V3_EN (38) + +#define BATTERY_PIN (3) +#define ADC_MULTIPLIER (4.90F) + +#define ADC_RESOLUTION (14) +#define BATTERY_SENSE_RES (12) + +#define AREF_VOLTAGE (3.0) +#define MV_LSB (3000.0F / 4096.0F) // 12-bit ADC with 3.0V input range + +// Power management boot protection threshold (millivolts) +// Set to 0 to disable boot protection +#define PWRMGT_VOLTAGE_BOOTLOCK 3300 // Won't boot below this voltage (mV) +// LPCOMP wake configuration (voltage recovery from SYSTEMOFF) +// AIN1 = P0.03 = BATTERY_PIN / PIN_VBAT_READ +#define PWRMGT_LPCOMP_AIN 1 +#define PWRMGT_LPCOMP_REFSEL 1 // 2/8 VDD (~3.68-4.04V) + +//////////////////////////////////////////////////////////////////////////////// +// Number of pins + +#define PINS_COUNT (48) +#define NUM_DIGITAL_PINS (48) +#define NUM_ANALOG_INPUTS (1) +#define NUM_ANALOG_OUTPUTS (0) + + +// I2C pin definition + +#define PIN_WIRE_SDA (0 + 7) +#define PIN_WIRE_SCL (0 + 8) + +// I2C bus 1 +// Available on header pins, for general use +#define PIN_WIRE1_SDA (0 + 4) +#define PIN_WIRE1_SCL (0 + 27) + +//////////////////////////////////////////////////////////////////////////////// +// Builtin LEDs + +#define LED_BUILTIN (28) +#define PIN_LED LED_BUILTIN +#define LED_RED LED_BUILTIN +#define LED_BLUE (-1) // No blue led, prevents Bluefruit flashing the green LED during advertising +#define LED_PIN LED_BUILTIN + +#define LED_STATE_ON 1 + +// #define PIN_NEOPIXEL (-1) +// #define NEOPIXEL_NUM (2) + +//////////////////////////////////////////////////////////////////////////////// +// Builtin buttons + +#define PIN_BUTTON1 (32 + 10) +#define BUTTON_PIN PIN_BUTTON1 + +// #define PIN_BUTTON2 (11) +// #define BUTTON_PIN2 PIN_BUTTON2 + +#define PIN_USER_BTN BUTTON_PIN + +//////////////////////////////////////////////////////////////////////////////// +// Lora + +#define USE_SX1262 +#define LORA_CS (0 + 5) +#define SX126X_DIO1 (0 + 21) +#define SX126X_BUSY (0 + 19) +#define SX126X_RESET (0 + 16) +#define SX126X_DIO2_AS_RF_SWITCH +#define SX126X_DIO3_TCXO_VOLTAGE 1.8 + +//////////////////////////////////////////////////////////////////////////////// +// SPI pin definition + +#define SPI_INTERFACES_COUNT (2) + +#define PIN_SPI_MISO (0 + 14) +#define PIN_SPI_MOSI (0 + 11) +#define PIN_SPI_SCK (32 + 8) +#define PIN_SPI_NSS LORA_CS + +#define PIN_SPI1_MISO (-1) +#define PIN_SPI1_MOSI (0+17) +#define PIN_SPI1_SCK (0+20) + +//////////////////////////////////////////////////////////////////////////////// +// GPS + +#define GPS_EN (0 + 6) +#define GPS_RESET (32 + 14) + +#define PIN_SERIAL1_RX (0 + 23) +#define PIN_SERIAL1_TX (0 + 25) + +#define PIN_SERIAL2_RX (0 + 9) +#define PIN_SERIAL2_TX (0 + 10) + +//////////////////////////////////////////////////////////////////////////////// +// TFT +#define PIN_TFT_SCL (0 + 20) +#define PIN_TFT_SDA (0 + 17) +#define PIN_TFT_RST (0 + 13) +// #define PIN_TFT_VDD_CTL (0 + 26) +#define PIN_TFT_LEDA_CTL (32 + 12) +#define PIN_TFT_LEDA_CTL_ACTIVE LOW +#define PIN_TFT_CS (0 + 22) +#define PIN_TFT_DC (0 + 15) From dbfc29b06a5f685fd5363cccb5d475f45516efa1 Mon Sep 17 00:00:00 2001 From: Jeroen Vermeulen Date: Fri, 20 Mar 2026 22:46:53 +0100 Subject: [PATCH 25/52] Documented get/set radio.rxgain CLI command Added documentation for RX Boosted Gain Mode commands. --- docs/cli_commands.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 8ae95443ad..1063991a77 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -238,6 +238,22 @@ This document provides an overview of CLI commands that can be sent to MeshCore **Note:** Requires reboot to apply **Serial Only:** `set freq ` +--- + +#### View or change this node's rx boosted gain mode (SX12xx only, v1.14.1+) +**Usage:** +- `get radio.rxgain` +- `set radio.rxgain ` + +**Parameters:** + - `state`: `on`|`off` + +**Default:** `on` + +**Temporary Note:** In release 1.14.1 this setting is `off` by default. + +--- + ### System #### View or change this node's name From 7e6d8dde1342cd0bbb5c75fb1a4da5249a52091c Mon Sep 17 00:00:00 2001 From: Jeroen Vermeulen Date: Fri, 20 Mar 2026 23:54:48 +0100 Subject: [PATCH 26/52] Update note about setting when upgrading Clarified note regarding default setting for upgrades from older versions. See https://github.com/meshcore-dev/MeshCore/pull/1653#issuecomment-4101341378 --- docs/cli_commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 1063991a77..3e590599d3 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -250,7 +250,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore **Default:** `on` -**Temporary Note:** In release 1.14.1 this setting is `off` by default. +**Note:** If you upgraded from an older version to 1.14.1 without erasing flash, this setting is `off`. --- From 0ac33479d3537915840551016492af4d4e17c77a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Br=C3=A1zio?= Date: Sat, 21 Mar 2026 11:47:22 +0000 Subject: [PATCH 27/52] fix: update devcontainer features to use node instead of bun --- .devcontainer/devcontainer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index a806d902f1..3a1c2f0548 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -2,7 +2,7 @@ "name": "MeshCore", "image": "mcr.microsoft.com/devcontainers/python:3-bookworm", "features": { - "ghcr.io/devcontainers-extra/features/bun:1": {}, + "ghcr.io/devcontainers/features/node:1": {}, "ghcr.io/rocker-org/devcontainer-features/apt-packages:1": { "packages": [ "sudo" From b07ab2bc5550564f5518a0e516ad43cfa8e80ed6 Mon Sep 17 00:00:00 2001 From: whywilson Date: Sat, 21 Mar 2026 20:45:29 +0800 Subject: [PATCH 28/52] Remove useless define in GAT562_Mesh_EVB_Pro. --- variants/gat562_evb_pro/platformio.ini | 56 --------------------- variants/gat562_mesh_evb_pro/platformio.ini | 2 - 2 files changed, 58 deletions(-) delete mode 100644 variants/gat562_evb_pro/platformio.ini diff --git a/variants/gat562_evb_pro/platformio.ini b/variants/gat562_evb_pro/platformio.ini deleted file mode 100644 index 212ef968e0..0000000000 --- a/variants/gat562_evb_pro/platformio.ini +++ /dev/null @@ -1,56 +0,0 @@ -[GAT562_Mesh_EVB_Pro] -extends = nrf52_base -board = rak4631 -board_check = true -build_flags = ${nrf52_base.build_flags} - ${sensor_base.build_flags} - -I variants/gat562_mesh_evb_pro - -D NRF52_POWER_MANAGEMENT - -D LORA_FREQ=475 - -D LORA_BW=125 - -D LORA_SF=10 - -D LORA_CR=6 - -D PIN_BOARD_SCL=14 - -D PIN_BOARD_SDA=13 - -D RADIO_CLASS=CustomSX1262 - -D WRAPPER_CLASS=CustomSX1262Wrapper - -D LORA_TX_POWER=22 - -D SX126X_CURRENT_LIMIT=140 - -D SX126X_RX_BOOSTED_GAIN=1 -build_src_filter = ${nrf52_base.build_src_filter} - +<../variants/gat562_mesh_evb_pro> - + - + -lib_deps = - ${nrf52_base.lib_deps} - ${sensor_base.lib_deps} - sparkfun/SparkFun u-blox GNSS Arduino Library@^2.2.27 - -[env:GAT562_Mesh_EVB_Pro_repeater] -extends = GAT562_Mesh_EVB_Pro -build_flags = - ${GAT562_Mesh_EVB_Pro.build_flags} - -D ADVERT_NAME='"GAT562 EVB Pro"' - -D ADVERT_LAT=0.0 - -D ADVERT_LON=0.0 - -D ADMIN_PASSWORD='"password"' - -D MAX_NEIGHBOURS=50 - -D MESH_PACKET_LOGGING=1 - -D MESH_DEBUG=1 -build_src_filter = ${GAT562_Mesh_EVB_Pro.build_src_filter} - +<../examples/simple_repeater> - - -[env:GAT562_Mesh_EVB_Pro_room_server] -extends = GAT562_Mesh_EVB_Pro -build_flags = - ${GAT562_Mesh_EVB_Pro.build_flags} - -D ADVERT_NAME='"GAT562 EVB Pro Room"' - -D ADVERT_LAT=0.0 - -D ADVERT_LON=0.0 - -D ADMIN_PASSWORD='"password"' - -D ROOM_PASSWORD='"hello"' - -D MESH_PACKET_LOGGING=1 - -D MESH_DEBUG=1 -build_src_filter = ${GAT562_Mesh_EVB_Pro.build_src_filter} - +<../examples/simple_room_server> diff --git a/variants/gat562_mesh_evb_pro/platformio.ini b/variants/gat562_mesh_evb_pro/platformio.ini index e7d9ac267a..cede9c97c0 100644 --- a/variants/gat562_mesh_evb_pro/platformio.ini +++ b/variants/gat562_mesh_evb_pro/platformio.ini @@ -8,8 +8,6 @@ build_flags = ${nrf52_base.build_flags} -D NRF52_POWER_MANAGEMENT -D PIN_BOARD_SCL=14 -D PIN_BOARD_SDA=13 - -D USB_MANUFACTURER='"GAT562"' - -D USB_PRODUCT='"GAT562 Mesh EVB Pro"' -D RADIO_CLASS=CustomSX1262 -D WRAPPER_CLASS=CustomSX1262Wrapper -D LORA_TX_POWER=22 From c7b8db55e61ab9098fde53103de78eec9f5f41e0 Mon Sep 17 00:00:00 2001 From: Konstantin <69057532+archef2000@users.noreply.github.com> Date: Sat, 21 Mar 2026 23:09:28 +0100 Subject: [PATCH 29/52] Fix typo for ThinkNode M5 room server environment --- variants/thinknode_m5/platformio.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variants/thinknode_m5/platformio.ini b/variants/thinknode_m5/platformio.ini index 0c64bcef86..75ee380258 100644 --- a/variants/thinknode_m5/platformio.ini +++ b/variants/thinknode_m5/platformio.ini @@ -111,7 +111,7 @@ lib_deps = ${esp32_ota.lib_deps} [env:ThinkNode_M5_room_server] -extends = ThinkNonde_M5 +extends = ThinkNode_M5 build_src_filter = ${ThinkNode_M5.build_src_filter} +<../examples/simple_room_server> build_flags = From ff5aad71a6d96fb5f10e23d140e69ebc6c050f36 Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Sun, 22 Mar 2026 08:35:32 +0100 Subject: [PATCH 30/52] Make radio.rxgain true by default after upgrades --- src/helpers/CommonCLI.cpp | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index 2f7a0fffcb..aa1ef29421 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -55,7 +55,7 @@ void CommonCLI::loadPrefsInt(FILESYSTEM* fs, const char* filename) { file.read((uint8_t *)&_prefs->tx_power_dbm, sizeof(_prefs->tx_power_dbm)); // 76 file.read((uint8_t *)&_prefs->disable_fwd, sizeof(_prefs->disable_fwd)); // 77 file.read((uint8_t *)&_prefs->advert_interval, sizeof(_prefs->advert_interval)); // 78 - file.read((uint8_t *)&_prefs->rx_boosted_gain, sizeof(_prefs->rx_boosted_gain)); // 79 + file.read(pad, 1); // 79 : 1 byte unused (was rx_boosted_gain in v1.14.1, moved to end for upgrade compat) file.read((uint8_t *)&_prefs->rx_delay_base, sizeof(_prefs->rx_delay_base)); // 80 file.read((uint8_t *)&_prefs->tx_delay_factor, sizeof(_prefs->tx_delay_factor)); // 84 file.read((uint8_t *)&_prefs->guest_password[0], sizeof(_prefs->guest_password)); // 88 @@ -87,7 +87,8 @@ void CommonCLI::loadPrefsInt(FILESYSTEM* fs, const char* filename) { file.read((uint8_t *)&_prefs->discovery_mod_timestamp, sizeof(_prefs->discovery_mod_timestamp)); // 162 file.read((uint8_t *)&_prefs->adc_multiplier, sizeof(_prefs->adc_multiplier)); // 166 file.read((uint8_t *)_prefs->owner_info, sizeof(_prefs->owner_info)); // 170 - // next: 290 + file.read((uint8_t *)&_prefs->rx_boosted_gain, sizeof(_prefs->rx_boosted_gain)); // 290 + // next: 291 // sanitise bad pref values _prefs->rx_delay_base = constrain(_prefs->rx_delay_base, 0, 20.0f); @@ -145,7 +146,7 @@ void CommonCLI::savePrefs(FILESYSTEM* fs) { file.write((uint8_t *)&_prefs->tx_power_dbm, sizeof(_prefs->tx_power_dbm)); // 76 file.write((uint8_t *)&_prefs->disable_fwd, sizeof(_prefs->disable_fwd)); // 77 file.write((uint8_t *)&_prefs->advert_interval, sizeof(_prefs->advert_interval)); // 78 - file.write((uint8_t *)&_prefs->rx_boosted_gain, sizeof(_prefs->rx_boosted_gain)); // 79 + file.write(pad, 1); // 79 : 1 byte unused (rx_boosted_gain moved to end) file.write((uint8_t *)&_prefs->rx_delay_base, sizeof(_prefs->rx_delay_base)); // 80 file.write((uint8_t *)&_prefs->tx_delay_factor, sizeof(_prefs->tx_delay_factor)); // 84 file.write((uint8_t *)&_prefs->guest_password[0], sizeof(_prefs->guest_password)); // 88 @@ -177,7 +178,8 @@ void CommonCLI::savePrefs(FILESYSTEM* fs) { file.write((uint8_t *)&_prefs->discovery_mod_timestamp, sizeof(_prefs->discovery_mod_timestamp)); // 162 file.write((uint8_t *)&_prefs->adc_multiplier, sizeof(_prefs->adc_multiplier)); // 166 file.write((uint8_t *)_prefs->owner_info, sizeof(_prefs->owner_info)); // 170 - // next: 290 + file.write((uint8_t *)&_prefs->rx_boosted_gain, sizeof(_prefs->rx_boosted_gain)); // 290 + // next: 291 file.close(); } From 285fc685c5254b2659aa7683e00fc3da0d7df8fa Mon Sep 17 00:00:00 2001 From: Rastislav Vysoky Date: Sun, 22 Mar 2026 13:54:42 +0100 Subject: [PATCH 31/52] allow to set lower LoRa frequency --- examples/companion_radio/MyMesh.cpp | 12 ++++++------ src/helpers/CommonCLI.cpp | 14 +++++++------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/examples/companion_radio/MyMesh.cpp b/examples/companion_radio/MyMesh.cpp index 32e362607f..b94e452674 100644 --- a/examples/companion_radio/MyMesh.cpp +++ b/examples/companion_radio/MyMesh.cpp @@ -292,7 +292,7 @@ bool MyMesh::shouldAutoAddContactType(uint8_t contact_type) const { if ((_prefs.manual_add_contacts & 1) == 0) { return true; } - + uint8_t type_bit = 0; switch (contact_type) { case ADV_TYPE_CHAT: @@ -310,7 +310,7 @@ bool MyMesh::shouldAutoAddContactType(uint8_t contact_type) const { default: return false; // Unknown type, don't auto-add } - + return (_prefs.autoadd_config & type_bit) != 0; } @@ -859,7 +859,7 @@ void MyMesh::begin(bool has_display) { // sanitise bad pref values _prefs.rx_delay_base = constrain(_prefs.rx_delay_base, 0, 20.0f); _prefs.airtime_factor = constrain(_prefs.airtime_factor, 0, 9.0f); - _prefs.freq = constrain(_prefs.freq, 400.0f, 2500.0f); + _prefs.freq = constrain(_prefs.freq, 150.0f, 2500.0f); _prefs.bw = constrain(_prefs.bw, 7.8f, 500.0f); _prefs.sf = constrain(_prefs.sf, 5, 12); _prefs.cr = constrain(_prefs.cr, 5, 8); @@ -1264,7 +1264,7 @@ void MyMesh::handleCmdFrame(size_t len) { if (repeat && !isValidClientRepeatFreq(freq)) { writeErrFrame(ERR_CODE_ILLEGAL_ARG); - } else if (freq >= 300000 && freq <= 2500000 && sf >= 5 && sf <= 12 && cr >= 5 && cr <= 8 && bw >= 7000 && + } else if (freq >= 150000 && freq <= 2500000 && sf >= 5 && sf <= 12 && cr >= 5 && cr <= 8 && bw >= 7000 && bw <= 500000) { _prefs.sf = sf; _prefs.cr = cr; @@ -1620,7 +1620,7 @@ void MyMesh::handleCmdFrame(size_t len) { } else if (cmd_frame[0] == CMD_SEND_TRACE_PATH && len > 10 && len - 10 < MAX_PACKET_PAYLOAD-5) { uint8_t path_len = len - 10; uint8_t flags = cmd_frame[9]; - uint8_t path_sz = flags & 0x03; // NEW v1.11+ + uint8_t path_sz = flags & 0x03; // NEW v1.11+ if ((path_len >> path_sz) > MAX_PATH_SIZE || (path_len % (1 << path_sz)) != 0) { // make sure is multiple of path_sz writeErrFrame(ERR_CODE_ILLEGAL_ARG); } else { @@ -1927,7 +1927,7 @@ void MyMesh::checkCLIRescueCmd() { // get path from command e.g: "cat /contacts3" const char *path = &cli_command[4]; - + bool is_fs2 = false; if (memcmp(path, "UserData/", 9) == 0) { path += 8; // skip "UserData" diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index aa1ef29421..8b097c29fe 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -95,7 +95,7 @@ void CommonCLI::loadPrefsInt(FILESYSTEM* fs, const char* filename) { _prefs->tx_delay_factor = constrain(_prefs->tx_delay_factor, 0, 2.0f); _prefs->direct_tx_delay_factor = constrain(_prefs->direct_tx_delay_factor, 0, 2.0f); _prefs->airtime_factor = constrain(_prefs->airtime_factor, 0, 9.0f); - _prefs->freq = constrain(_prefs->freq, 400.0f, 2500.0f); + _prefs->freq = constrain(_prefs->freq, 150.0f, 2500.0f); _prefs->bw = constrain(_prefs->bw, 7.8f, 500.0f); _prefs->sf = constrain(_prefs->sf, 5, 12); _prefs->cr = constrain(_prefs->cr, 5, 8); @@ -275,7 +275,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch uint8_t sf = num > 2 ? atoi(parts[2]) : 0; uint8_t cr = num > 3 ? atoi(parts[3]) : 0; int temp_timeout_mins = num > 4 ? atoi(parts[4]) : 0; - if (freq >= 300.0f && freq <= 2500.0f && sf >= 5 && sf <= 12 && cr >= 5 && cr <= 8 && bw >= 7.0f && bw <= 500.0f && temp_timeout_mins > 0) { + if (freq >= 150.0f && freq <= 2500.0f && sf >= 5 && sf <= 12 && cr >= 5 && cr <= 8 && bw >= 7.0f && bw <= 500.0f && temp_timeout_mins > 0) { _callbacks->applyTempRadioParams(freq, bw, sf, cr, temp_timeout_mins); sprintf(reply, "OK - temp params for %d mins", temp_timeout_mins); } else { @@ -535,7 +535,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch float bw = num > 1 ? strtof(parts[1], nullptr) : 0.0f; uint8_t sf = num > 2 ? atoi(parts[2]) : 0; uint8_t cr = num > 3 ? atoi(parts[3]) : 0; - if (freq >= 300.0f && freq <= 2500.0f && sf >= 5 && sf <= 12 && cr >= 5 && cr <= 8 && bw >= 7.0f && bw <= 500.0f) { + if (freq >= 150.0f && freq <= 2500.0f && sf >= 5 && sf <= 12 && cr >= 5 && cr <= 8 && bw >= 7.0f && bw <= 500.0f) { _prefs->sf = sf; _prefs->cr = cr; _prefs->freq = freq; @@ -720,7 +720,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch } } else if (memcmp(command, "sensor set ", 11) == 0) { strcpy(tmp, &command[11]); - const char *parts[2]; + const char *parts[2]; int num = mesh::Utils::parseTextParts(tmp, parts, 2, ' '); const char *key = (num > 0) ? parts[0] : ""; const char *value = (num > 1) ? parts[1] : "null"; @@ -743,7 +743,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch dp = strchr(dp, 0); int i; for (i = start; i < end && (dp-reply < 134); i++) { - sprintf(dp, "%s=%s\n", + sprintf(dp, "%s=%s\n", _sensors->getSettingName(i), _sensors->getSettingValue(i)); dp = strchr(dp, 0); @@ -823,8 +823,8 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch bool active = !strcmp(_sensors->getSettingByKey("gps"), "1"); if (enabled) { sprintf(reply, "on, %s, %s, %d sats", - active?"active":"deactivated", - fix?"fix":"no fix", + active?"active":"deactivated", + fix?"fix":"no fix", sats); } else { strcpy(reply, "off"); From 31a08e1de6b053f1e5189b80b1ff14cf0f84adbd Mon Sep 17 00:00:00 2001 From: Jeroen Vermeulen Date: Sun, 22 Mar 2026 21:18:14 +0100 Subject: [PATCH 32/52] Update note for upgrade to version 1.14.1 Clarify note regarding upgrade from older version. --- docs/cli_commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 3e590599d3..85859be6ac 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -250,7 +250,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore **Default:** `on` -**Note:** If you upgraded from an older version to 1.14.1 without erasing flash, this setting is `off`. +**Temporary Note:** If you upgraded from an older version to 1.14.1 without erasing flash, this setting is `off` because of a #2118 --- From f543ba22de7a0eb88498aba2a4babd428200a8e5 Mon Sep 17 00:00:00 2001 From: Jeroen Vermeulen Date: Sun, 22 Mar 2026 21:19:06 +0100 Subject: [PATCH 33/52] Update temporary note with a hyperlink to issue #2118 --- docs/cli_commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 85859be6ac..ac81a35a35 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -250,7 +250,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore **Default:** `on` -**Temporary Note:** If you upgraded from an older version to 1.14.1 without erasing flash, this setting is `off` because of a #2118 +**Temporary Note:** If you upgraded from an older version to 1.14.1 without erasing flash, this setting is `off` because of [#2118](https://github.com/meshcore-dev/MeshCore/issues/2118) --- From 54f6ac49294ed666728735259b1e1ce346a3deb8 Mon Sep 17 00:00:00 2001 From: Jeroen Vermeulen Date: Sun, 22 Mar 2026 21:35:02 +0100 Subject: [PATCH 34/52] Add discover.neighbors command documentation --- docs/cli_commands.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index ac81a35a35..9769d71334 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -106,6 +106,13 @@ This document provides an overview of CLI commands that can be sent to MeshCore --- +### Discover zero hop neighbors + +**Usage:** +- `discover.neighbors` + +--- + ## Statistics ### Clear Stats From ed326255d545af528d734dfb8c821c322b8eeb40 Mon Sep 17 00:00:00 2001 From: liamcottle Date: Mon, 23 Mar 2026 21:46:21 +1300 Subject: [PATCH 35/52] add support for direct paths when sending group data --- examples/companion_radio/MyMesh.cpp | 17 ++++++++++++++++- src/helpers/BaseChatMesh.cpp | 10 ++++++++-- src/helpers/BaseChatMesh.h | 2 +- 3 files changed, 25 insertions(+), 4 deletions(-) diff --git a/examples/companion_radio/MyMesh.cpp b/examples/companion_radio/MyMesh.cpp index a98d4b6a90..f151fb30bb 100644 --- a/examples/companion_radio/MyMesh.cpp +++ b/examples/companion_radio/MyMesh.cpp @@ -1110,6 +1110,21 @@ void MyMesh::handleCmdFrame(size_t len) { uint16_t data_type = ((uint16_t)cmd_frame[i]) | (((uint16_t)cmd_frame[i + 1]) << 8); i += 2; uint8_t channel_idx = cmd_frame[i++]; + uint8_t path_len = cmd_frame[i++]; + + // validate path len, allowing 0xFF for flood + if (!mesh::Packet::isValidPathLen(path_len) && path_len != OUT_PATH_UNKNOWN) { + MESH_DEBUG_PRINTLN("CMD_SEND_CHANNEL_DATA invalid path size: %d", path_len); + writeErrFrame(ERR_CODE_ILLEGAL_ARG); + return; + } + + // parse provided path if not flood + uint8_t path[MAX_PATH_SIZE]; + if (path_len != OUT_PATH_UNKNOWN) { + i += mesh::Packet::writePath(path, &cmd_frame[i], path_len); + } + const uint8_t *payload = &cmd_frame[i]; int payload_len = (len > (size_t)i) ? (int)(len - i) : 0; @@ -1121,7 +1136,7 @@ void MyMesh::handleCmdFrame(size_t len) { } else if (payload_len > MAX_CHANNEL_DATA_LENGTH) { MESH_DEBUG_PRINTLN("CMD_SEND_CHANNEL_DATA payload too long: %d > %d", payload_len, MAX_CHANNEL_DATA_LENGTH); writeErrFrame(ERR_CODE_ILLEGAL_ARG); - } else if (sendGroupData(channel.channel, data_type, payload, payload_len)) { + } else if (sendGroupData(channel.channel, path, path_len, data_type, payload, payload_len)) { writeOKFrame(); } else { writeErrFrame(ERR_CODE_TABLE_FULL); diff --git a/src/helpers/BaseChatMesh.cpp b/src/helpers/BaseChatMesh.cpp index 78e197bee2..7ddc461d29 100644 --- a/src/helpers/BaseChatMesh.cpp +++ b/src/helpers/BaseChatMesh.cpp @@ -481,7 +481,7 @@ bool BaseChatMesh::sendGroupMessage(uint32_t timestamp, mesh::GroupChannel& chan return false; } -bool BaseChatMesh::sendGroupData(mesh::GroupChannel& channel, uint16_t data_type, const uint8_t* data, int data_len) { +bool BaseChatMesh::sendGroupData(mesh::GroupChannel& channel, uint8_t* path, uint8_t path_len, uint16_t data_type, const uint8_t* data, int data_len) { if (data_len < 0) { MESH_DEBUG_PRINTLN("sendGroupData: invalid negative data_len=%d", data_len); return false; @@ -502,7 +502,13 @@ bool BaseChatMesh::sendGroupData(mesh::GroupChannel& channel, uint16_t data_type MESH_DEBUG_PRINTLN("sendGroupData: unable to create group datagram, data_len=%d", data_len); return false; } - sendFloodScoped(channel, pkt); + + if (path_len == OUT_PATH_UNKNOWN) { + sendFloodScoped(channel, pkt); + } else { + sendDirect(pkt, path, path_len); + } + return true; } diff --git a/src/helpers/BaseChatMesh.h b/src/helpers/BaseChatMesh.h index c2f9d9154a..b39e736388 100644 --- a/src/helpers/BaseChatMesh.h +++ b/src/helpers/BaseChatMesh.h @@ -150,7 +150,7 @@ class BaseChatMesh : public mesh::Mesh { int sendMessage(const ContactInfo& recipient, uint32_t timestamp, uint8_t attempt, const char* text, uint32_t& expected_ack, uint32_t& est_timeout); int sendCommandData(const ContactInfo& recipient, uint32_t timestamp, uint8_t attempt, const char* text, uint32_t& est_timeout); bool sendGroupMessage(uint32_t timestamp, mesh::GroupChannel& channel, const char* sender_name, const char* text, int text_len); - bool sendGroupData(mesh::GroupChannel& channel, uint16_t data_type, const uint8_t* data, int data_len); + bool sendGroupData(mesh::GroupChannel& channel, uint8_t* path, uint8_t path_len, uint16_t data_type, const uint8_t* data, int data_len); int sendLogin(const ContactInfo& recipient, const char* password, uint32_t& est_timeout); int sendAnonReq(const ContactInfo& recipient, const uint8_t* data, uint8_t len, uint32_t& tag, uint32_t& est_timeout); int sendRequest(const ContactInfo& recipient, uint8_t req_type, uint32_t& tag, uint32_t& est_timeout); From c78f7133c96315af889c219b9369de029687dcea Mon Sep 17 00:00:00 2001 From: liamcottle Date: Mon, 23 Mar 2026 23:02:24 +1300 Subject: [PATCH 36/52] reorder command args --- examples/companion_radio/MyMesh.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/companion_radio/MyMesh.cpp b/examples/companion_radio/MyMesh.cpp index f151fb30bb..590d689b60 100644 --- a/examples/companion_radio/MyMesh.cpp +++ b/examples/companion_radio/MyMesh.cpp @@ -1107,8 +1107,6 @@ void MyMesh::handleCmdFrame(size_t len) { return; } int i = 1; - uint16_t data_type = ((uint16_t)cmd_frame[i]) | (((uint16_t)cmd_frame[i + 1]) << 8); - i += 2; uint8_t channel_idx = cmd_frame[i++]; uint8_t path_len = cmd_frame[i++]; @@ -1125,6 +1123,8 @@ void MyMesh::handleCmdFrame(size_t len) { i += mesh::Packet::writePath(path, &cmd_frame[i], path_len); } + uint16_t data_type = ((uint16_t)cmd_frame[i]) | (((uint16_t)cmd_frame[i + 1]) << 8); + i += 2; const uint8_t *payload = &cmd_frame[i]; int payload_len = (len > (size_t)i) ? (int)(len - i) : 0; From 1d61df72c3362ad8955752ff343558831aeefa6c Mon Sep 17 00:00:00 2001 From: liamcottle Date: Mon, 23 Mar 2026 23:09:35 +1300 Subject: [PATCH 37/52] add define for reserved group data type --- examples/companion_radio/MyMesh.cpp | 2 +- src/helpers/TxtDataHelpers.h | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/examples/companion_radio/MyMesh.cpp b/examples/companion_radio/MyMesh.cpp index 590d689b60..60a5a75fec 100644 --- a/examples/companion_radio/MyMesh.cpp +++ b/examples/companion_radio/MyMesh.cpp @@ -1131,7 +1131,7 @@ void MyMesh::handleCmdFrame(size_t len) { ChannelDetails channel; if (!getChannel(channel_idx, channel)) { writeErrFrame(ERR_CODE_NOT_FOUND); // bad channel_idx - } else if (data_type == 0) { + } else if (data_type == DATA_TYPE_RESERVED) { writeErrFrame(ERR_CODE_ILLEGAL_ARG); } else if (payload_len > MAX_CHANNEL_DATA_LENGTH) { MESH_DEBUG_PRINTLN("CMD_SEND_CHANNEL_DATA payload too long: %d > %d", payload_len, MAX_CHANNEL_DATA_LENGTH); diff --git a/src/helpers/TxtDataHelpers.h b/src/helpers/TxtDataHelpers.h index 47bbc0ded9..ece494f291 100644 --- a/src/helpers/TxtDataHelpers.h +++ b/src/helpers/TxtDataHelpers.h @@ -6,6 +6,7 @@ #define TXT_TYPE_PLAIN 0 // a plain text message #define TXT_TYPE_CLI_DATA 1 // a CLI command #define TXT_TYPE_SIGNED_PLAIN 2 // plain text, signed by sender +#define DATA_TYPE_RESERVED 0x0000 // reserved for future use #define DATA_TYPE_DEV 0xFFFF // developer namespace for experimenting with group/channel datagrams and building apps class StrHelper { From 7829c51898a620a929a4f9753f93ea66beaca743 Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Mon, 9 Mar 2026 14:31:40 +0100 Subject: [PATCH 38/52] Bump to RadioLib 7.6.0 --- library.json | 2 +- platformio.ini | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/library.json b/library.json index aa37cb6ed0..8504793c23 100644 --- a/library.json +++ b/library.json @@ -4,7 +4,7 @@ "dependencies": { "SPI": "*", "Wire": "*", - "jgromes/RadioLib": "^7.3.0", + "jgromes/RadioLib": "^7.6.0", "rweather/Crypto": "^0.4.0", "adafruit/RTClib": "^2.1.3", "melopero/Melopero RV3028": "^1.1.0", diff --git a/platformio.ini b/platformio.ini index ba601c26cd..f2ef924718 100644 --- a/platformio.ini +++ b/platformio.ini @@ -18,7 +18,7 @@ monitor_speed = 115200 lib_deps = SPI Wire - jgromes/RadioLib @ ^7.3.0 + jgromes/RadioLib @ ^7.6.0 rweather/Crypto @ ^0.4.0 adafruit/RTClib @ ^2.1.3 melopero/Melopero RV3028 @ ^1.1.0 From 0aa0ec1f164bd659f752443f1267d9bb621b3fda Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Sat, 7 Mar 2026 14:55:14 +0100 Subject: [PATCH 39/52] Add get/set dutycycle command We translate to af internally, it's easier to store and doesn't break stored prefs. Made get/set af command show deprecated, but it still works fine. --- docs/cli_commands.md | 22 ++++++++++++---------- docs/terminal_chat_cli.md | 6 ++++-- src/helpers/CommonCLI.cpp | 28 ++++++++++++++++++++++++---- 3 files changed, 40 insertions(+), 16 deletions(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 9769d71334..7f1c93c77e 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -500,20 +500,22 @@ This document provides an overview of CLI commands that can be sent to MeshCore --- -#### View or change the airtime factor (duty cycle limit) +#### View or change the duty cycle limit **Usage:** -- `get af` -- `set af ` +- `get dutycycle` +- `set dutycycle ` **Parameters:** -- `value`: Airtime factor (0-9). After each transmission, the repeater enforces a silent period of approximately the on-air transmission time multiplied by the value. This results in a long-term duty cycle of roughly 1 divided by (1 plus the value). For example: - - `af = 1` → ~50% duty - - `af = 2` → ~33% duty - - `af = 3` → ~25% duty - - `af = 9` → ~10% duty - Yyou are responsible for choosing a value that is appropriate for your jurisdiction and channel plan (for example EU 868 Mhz 10% duty cycle regulation). +- `value`: Duty cycle percentage (10-100) -**Default:** `1.0` +**Default:** `50%` (equivalent to airtime factor 1.0) + +**Examples:** +- `set dutycycle 100` — no duty cycle limit +- `set dutycycle 50` — 50% duty cycle (default) +- `set dutycycle 10` — 10% duty cycle (strictest EU requirement) + +> **Deprecated:** `get af` / `set af` still work but are deprecated in favour of `dutycycle`. --- diff --git a/docs/terminal_chat_cli.md b/docs/terminal_chat_cli.md index f053e64d81..b1a3af2a6d 100644 --- a/docs/terminal_chat_cli.md +++ b/docs/terminal_chat_cli.md @@ -28,9 +28,11 @@ set lon {longitude} Sets your advertisement map longitude. (decimal degrees) ``` -set af {air-time-factor} +set dutycycle {percent} ``` -Sets the transmit air-time-factor. +Sets the transmit duty cycle limit (10-100%). Example: `set dutycycle 10` for 10%. + +> **Deprecated:** `set af` still works but is deprecated in favour of `set dutycycle`. ``` diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index 8b097c29fe..b346e3eae6 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -294,8 +294,13 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch */ } else if (memcmp(command, "get ", 4) == 0) { const char* config = &command[4]; - if (memcmp(config, "af", 2) == 0) { - sprintf(reply, "> %s", StrHelper::ftoa(_prefs->airtime_factor)); + if (memcmp(config, "dutycycle", 8) == 0) { + float dc = 100.0f / (_prefs->airtime_factor + 1.0f); + int dc_int = (int)dc; + int dc_frac = (int)((dc - dc_int) * 10.0f + 0.5f); + sprintf(reply, "> %d.%d%%", dc_int, dc_frac); + } else if (memcmp(config, "af", 2) == 0) { + sprintf(reply, "> %s (deprecated, use 'get dutycycle')", StrHelper::ftoa(_prefs->airtime_factor)); } else if (memcmp(config, "int.thresh", 10) == 0) { sprintf(reply, "> %d", (uint32_t) _prefs->interference_threshold); } else if (memcmp(config, "agc.reset.interval", 18) == 0) { @@ -451,10 +456,25 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch */ } else if (memcmp(command, "set ", 4) == 0) { const char* config = &command[4]; - if (memcmp(config, "af ", 3) == 0) { + if (memcmp(config, "dutycycle ", 9) == 0) { + float dc = atof(&config[9]); + if (dc < 10 || dc > 100) { + strcpy(reply, "ERROR: dutycycle must be 10-100"); + } else { + _prefs->airtime_factor = (100.0f / dc) - 1.0f; + savePrefs(); + float actual = 100.0f / (_prefs->airtime_factor + 1.0f); + int a_int = (int)actual; + int a_frac = (int)((actual - a_int) * 10.0f + 0.5f); + sprintf(reply, "OK - %d.%d%%", a_int, a_frac); + } + } else if (memcmp(config, "af ", 3) == 0) { _prefs->airtime_factor = atof(&config[3]); savePrefs(); - strcpy(reply, "OK"); + float actual = 100.0f / (_prefs->airtime_factor + 1.0f); + int a_int = (int)actual; + int a_frac = (int)((actual - a_int) * 10.0f + 0.5f); + sprintf(reply, "OK - %d.%d%% (deprecated, use 'set dutycycle')", a_int, a_frac); } else if (memcmp(config, "int.thresh ", 11) == 0) { _prefs->interference_threshold = atoi(&config[11]); savePrefs(); From 741392889da728292c8aa3de3c449f742a059f86 Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Wed, 11 Mar 2026 20:08:47 +0100 Subject: [PATCH 40/52] Fix memcp compare length off by one Co-authored-by: ViezeVingertjes --- src/helpers/CommonCLI.cpp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index b346e3eae6..67a59b29eb 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -294,7 +294,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch */ } else if (memcmp(command, "get ", 4) == 0) { const char* config = &command[4]; - if (memcmp(config, "dutycycle", 8) == 0) { + if (memcmp(config, "dutycycle", 9) == 0) { float dc = 100.0f / (_prefs->airtime_factor + 1.0f); int dc_int = (int)dc; int dc_frac = (int)((dc - dc_int) * 10.0f + 0.5f); @@ -456,8 +456,8 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch */ } else if (memcmp(command, "set ", 4) == 0) { const char* config = &command[4]; - if (memcmp(config, "dutycycle ", 9) == 0) { - float dc = atof(&config[9]); + if (memcmp(config, "dutycycle ", 10) == 0) { + float dc = atof(&config[10]); if (dc < 10 || dc > 100) { strcpy(reply, "ERROR: dutycycle must be 10-100"); } else { From 728b586c3aec2478ca7eb6652852aac94d77aed3 Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Wed, 18 Mar 2026 22:06:23 +0100 Subject: [PATCH 41/52] Address comments --- docs/cli_commands.md | 21 ++++++++++++++++++--- docs/terminal_chat_cli.md | 7 +++++-- src/helpers/CommonCLI.cpp | 11 ++++------- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 7f1c93c77e..a6b423876f 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -506,16 +506,31 @@ This document provides an overview of CLI commands that can be sent to MeshCore - `set dutycycle ` **Parameters:** -- `value`: Duty cycle percentage (10-100) +- `value`: Duty cycle percentage (1-100) **Default:** `50%` (equivalent to airtime factor 1.0) **Examples:** - `set dutycycle 100` — no duty cycle limit - `set dutycycle 50` — 50% duty cycle (default) -- `set dutycycle 10` — 10% duty cycle (strictest EU requirement) +- `set dutycycle 10` — 10% duty cycle +- `set dutycycle 1` — 1% duty cycle (strictest EU requirement) -> **Deprecated:** `get af` / `set af` still work but are deprecated in favour of `dutycycle`. +> **Note:** Added in firmware v1.15.0 + +--- + +#### View or change the airtime factor (duty cycle limit) +> **Deprecated** as of firmware v1.15.0. Use [`get/set dutycycle`](#view-or-change-the-duty-cycle-limit) instead. + +**Usage:** +- `get af` +- `set af ` + +**Parameters:** +- `value`: Airtime factor (0-9) + +**Default:** `1.0` --- diff --git a/docs/terminal_chat_cli.md b/docs/terminal_chat_cli.md index b1a3af2a6d..c889da9672 100644 --- a/docs/terminal_chat_cli.md +++ b/docs/terminal_chat_cli.md @@ -30,9 +30,12 @@ Sets your advertisement map longitude. (decimal degrees) ``` set dutycycle {percent} ``` -Sets the transmit duty cycle limit (10-100%). Example: `set dutycycle 10` for 10%. +Sets the transmit duty cycle limit (1-100%). Example: `set dutycycle 10` for 10%. -> **Deprecated:** `set af` still works but is deprecated in favour of `set dutycycle`. +``` +set af {air-time-factor} +``` +Sets the transmit air-time-factor. Deprecated — use `set dutycycle` instead. ``` diff --git a/src/helpers/CommonCLI.cpp b/src/helpers/CommonCLI.cpp index 67a59b29eb..47a2592bc4 100644 --- a/src/helpers/CommonCLI.cpp +++ b/src/helpers/CommonCLI.cpp @@ -300,7 +300,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch int dc_frac = (int)((dc - dc_int) * 10.0f + 0.5f); sprintf(reply, "> %d.%d%%", dc_int, dc_frac); } else if (memcmp(config, "af", 2) == 0) { - sprintf(reply, "> %s (deprecated, use 'get dutycycle')", StrHelper::ftoa(_prefs->airtime_factor)); + sprintf(reply, "> %s", StrHelper::ftoa(_prefs->airtime_factor)); } else if (memcmp(config, "int.thresh", 10) == 0) { sprintf(reply, "> %d", (uint32_t) _prefs->interference_threshold); } else if (memcmp(config, "agc.reset.interval", 18) == 0) { @@ -458,8 +458,8 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch const char* config = &command[4]; if (memcmp(config, "dutycycle ", 10) == 0) { float dc = atof(&config[10]); - if (dc < 10 || dc > 100) { - strcpy(reply, "ERROR: dutycycle must be 10-100"); + if (dc < 1 || dc > 100) { + strcpy(reply, "ERROR: dutycycle must be 1-100"); } else { _prefs->airtime_factor = (100.0f / dc) - 1.0f; savePrefs(); @@ -471,10 +471,7 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, const char* command, ch } else if (memcmp(config, "af ", 3) == 0) { _prefs->airtime_factor = atof(&config[3]); savePrefs(); - float actual = 100.0f / (_prefs->airtime_factor + 1.0f); - int a_int = (int)actual; - int a_frac = (int)((actual - a_int) * 10.0f + 0.5f); - sprintf(reply, "OK - %d.%d%% (deprecated, use 'set dutycycle')", a_int, a_frac); + strcpy(reply, "OK"); } else if (memcmp(config, "int.thresh ", 11) == 0) { _prefs->interference_threshold = atoi(&config[11]); savePrefs(); From da689c8e91f810d903307c34042d769efb53f424 Mon Sep 17 00:00:00 2001 From: Jeroen Vermeulen Date: Mon, 23 Mar 2026 23:06:42 +0100 Subject: [PATCH 42/52] Fix default radio.rxgain for Station G2 As @LitBomb pointed out in his [comment](https://github.com/meshcore-dev/MeshCore/issues/2118#issuecomment-4108168109) on #2118 RX Boosted Gain should not be enabled for the Station G2. This change is a fix for #2124 to make the default of `radio.rxgain` to be OFF on the Station G2. This restores the pre-1.14.1 behaviour with the only change being the user is now able to change the setting in the CLI. --- variants/station_g2/platformio.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variants/station_g2/platformio.ini b/variants/station_g2/platformio.ini index b8fc8786a3..87e77152b8 100644 --- a/variants/station_g2/platformio.ini +++ b/variants/station_g2/platformio.ini @@ -28,7 +28,7 @@ build_flags = -D SX126X_DIO2_AS_RF_SWITCH=true -D SX126X_DIO3_TCXO_VOLTAGE=1.8 -D SX126X_CURRENT_LIMIT=140 -; -D SX126X_RX_BOOSTED_GAIN=1 - DO NOT ENABLE THIS! + -D SX126X_RX_BOOSTED_GAIN=0 ; Default value when 'radio.rxgain' has not been set. Must be OFF for the Station G2, see: ; https://wiki.uniteng.com/en/meshtastic/station-g2#impact-of-lora-node-dense-areashigh-noise-environments-on-rf-performance -D DISPLAY_CLASS=SH1106Display build_src_filter = ${esp32_base.build_src_filter} From fb08fc0b1ea5164b01cc600ec385b09d3f47994b Mon Sep 17 00:00:00 2001 From: Wessel Nieboer Date: Tue, 24 Mar 2026 03:08:18 +0100 Subject: [PATCH 43/52] restore docs --- docs/cli_commands.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/cli_commands.md b/docs/cli_commands.md index f248e4f33f..90c5ab08b2 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -447,7 +447,12 @@ This document provides an overview of CLI commands that can be sent to MeshCore - `set af ` **Parameters:** -- `value`: Airtime factor (0-9) +- `value`: Airtime factor (0-9). After each transmission, the repeater enforces a silent period of approximately the on-air transmission time multiplied by the value. This results in a long-term duty cycle of roughly 1 divided by (1 plus the value). For example: + - `af = 1` → ~50% duty + - `af = 2` → ~33% duty + - `af = 3` → ~25% duty + - `af = 9` → ~10% duty + You are responsible for choosing a value that is appropriate for your jurisdiction and channel plan (for example EU 868 Mhz 10% duty cycle regulation). **Default:** `1.0` From f8dbdce6bb83b42920fb2f6f5a5c58f01b22c85e Mon Sep 17 00:00:00 2001 From: Alejandro Ramirez <4050651+got-root@users.noreply.github.com> Date: Fri, 13 Mar 2026 15:12:59 -0500 Subject: [PATCH 44/52] fix: apply persisted GPS enabled setting on boot for companion radio The companion_radio example was not restoring the GPS enabled/disabled preference from flash after reboot. The preference was being saved correctly when toggled via the mobile app, but on boot, sensors.begin() -> initBasicGPS() unconditionally sets gps_active=false and nothing subsequently restored the persisted state. Added applyGpsPrefs() (matching the pattern in simple_repeater, simple_sensor, and simple_room_server) and call it from main.cpp after sensors.begin() to ensure the GPS hardware is initialized before the saved preference is applied. --- examples/companion_radio/MyMesh.h | 6 ++++++ examples/companion_radio/main.cpp | 4 ++++ 2 files changed, 10 insertions(+) diff --git a/examples/companion_radio/MyMesh.h b/examples/companion_radio/MyMesh.h index e8c81cfd91..2c49510c98 100644 --- a/examples/companion_radio/MyMesh.h +++ b/examples/companion_radio/MyMesh.h @@ -165,6 +165,12 @@ class MyMesh : public BaseChatMesh, public DataStoreHost { public: void savePrefs() { _store->savePrefs(_prefs, sensors.node_lat, sensors.node_lon); } +#if ENV_INCLUDE_GPS == 1 + void applyGpsPrefs() { + sensors.setSettingValue("gps", _prefs.gps_enabled ? "1" : "0"); + } +#endif + private: void writeOKFrame(); void writeErrFrame(uint8_t err_code); diff --git a/examples/companion_radio/main.cpp b/examples/companion_radio/main.cpp index eff9efca47..876dc9c33c 100644 --- a/examples/companion_radio/main.cpp +++ b/examples/companion_radio/main.cpp @@ -213,6 +213,10 @@ void setup() { sensors.begin(); +#if ENV_INCLUDE_GPS == 1 + the_mesh.applyGpsPrefs(); +#endif + #ifdef DISPLAY_CLASS ui_task.begin(disp, &sensors, the_mesh.getNodePrefs()); // still want to pass this in as dependency, as prefs might be moved #endif From 2325973fec4e34636deceb31d428605b2b04f478 Mon Sep 17 00:00:00 2001 From: Scott Powell Date: Wed, 25 Mar 2026 16:26:51 +1100 Subject: [PATCH 45/52] * Companion: applyGPSPrefs() now just in one place (moved out of UITask) --- examples/companion_radio/MyMesh.h | 5 +++++ examples/companion_radio/ui-new/UITask.cpp | 12 ------------ 2 files changed, 5 insertions(+), 12 deletions(-) diff --git a/examples/companion_radio/MyMesh.h b/examples/companion_radio/MyMesh.h index 2c49510c98..3b02f5f69d 100644 --- a/examples/companion_radio/MyMesh.h +++ b/examples/companion_radio/MyMesh.h @@ -168,6 +168,11 @@ class MyMesh : public BaseChatMesh, public DataStoreHost { #if ENV_INCLUDE_GPS == 1 void applyGpsPrefs() { sensors.setSettingValue("gps", _prefs.gps_enabled ? "1" : "0"); + if (_prefs.gps_interval > 0) { + char interval_str[12]; // Max: 24 hours = 86400 seconds (5 digits + null) + sprintf(interval_str, "%u", _prefs.gps_interval); + sensors.setSettingValue("gps_interval", interval_str); + } } #endif diff --git a/examples/companion_radio/ui-new/UITask.cpp b/examples/companion_radio/ui-new/UITask.cpp index 265532be0b..94a8ee3efa 100644 --- a/examples/companion_radio/ui-new/UITask.cpp +++ b/examples/companion_radio/ui-new/UITask.cpp @@ -560,18 +560,6 @@ void UITask::begin(DisplayDriver* display, SensorManager* sensors, NodePrefs* no _node_prefs = node_prefs; -#if ENV_INCLUDE_GPS == 1 - // Apply GPS preferences from stored prefs - if (_sensors != NULL && _node_prefs != NULL) { - _sensors->setSettingValue("gps", _node_prefs->gps_enabled ? "1" : "0"); - if (_node_prefs->gps_interval > 0) { - char interval_str[12]; // Max: 24 hours = 86400 seconds (5 digits + null) - sprintf(interval_str, "%u", _node_prefs->gps_interval); - _sensors->setSettingValue("gps_interval", interval_str); - } - } -#endif - if (_display != NULL) { _display->turnOn(); } From 515af35b13dbf47739962d4376ccdd62a79aa48a Mon Sep 17 00:00:00 2001 From: Scott Powell Date: Sun, 29 Mar 2026 06:33:35 +1100 Subject: [PATCH 46/52] * docs changes for PAYLOAD_TYPE_GRP_DATA --- docs/cli_commands.md | 2 +- docs/number_allocations.md | 16 ++++++++++++++++ docs/payloads.md | 18 +++++++++++++++++- 3 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 docs/number_allocations.md diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 792cf1f027..c662495057 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -557,7 +557,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore - `set agc.reset.interval ` **Parameters:** -- `value`: Interval in seconds rounded down to a multiple of 4 (17 becomes 16) +- `value`: Interval in seconds rounded down to a multiple of 4 (17 becomes 16). 0 to disable. **Default:** `0.0` diff --git a/docs/number_allocations.md b/docs/number_allocations.md new file mode 100644 index 0000000000..ea36f830cc --- /dev/null +++ b/docs/number_allocations.md @@ -0,0 +1,16 @@ +# Number Allocations + +This document lists unique numbers/identifiers used in various MeshCore protcol payloads. + +# Group Data Types + +The `PAYLOAD_TYPE_GRP_DATA` payloads have a 16-bit data-type field, which identifies which application the packet is for. + +To make sure multiple applications can function without interfering with each other, the table below is for reserving various ranges of data-type values. Just modify this table, adding a row, then submit a PR to have it authorised/merged. + +The 16-bit types are allocated in blocks of 16, ie. the lower 4-bits is the range. + +| Data-Type range | App name | Contact | +|-----------------|--------------------------|------------------------------------------------------| +| 000x | -reserved- | | +| FFFx | -reserved- | | diff --git a/docs/payloads.md b/docs/payloads.md index 15fec7578a..7745ac61ba 100644 --- a/docs/payloads.md +++ b/docs/payloads.md @@ -226,7 +226,7 @@ txt_type | reply path | (variable) | reply path | -# Group text message / datagram +# Group text message | Field | Size (bytes) | Description | |--------------|-----------------|--------------------------------------------| @@ -236,6 +236,22 @@ txt_type The plaintext contained in the ciphertext matches the format described in [plain text message](#plain-text-message). Specifically, it consists of a four byte timestamp, a flags byte, and the message. The flags byte will generally be `0x00` because it is a "plain text message". The message will be of the form `: ` (eg., `user123: I'm on my way`). +# Group datagram + +| Field | Size (bytes) | Description | +|--------------|-----------------|--------------------------------------------| +| channel hash | 1 | first byte of SHA256 of channel's shared key | +| cipher MAC | 2 | MAC for encrypted data in next field | +| ciphertext | rest of payload | encrypted data, see below for details | + +The data contained in the ciphertext uses the format below: + +| Field | Size (bytes) | Description | +|--------------|-----------------|--------------------------------------------| +| data type | 2 | Identifier for type of data. (See number_allocations.md) | +| data len | 1 | byte length of data | +| data | rest of payload | (depends on data type) | + # Control data From 6fb8e60b5fc855e391721e74b6e083509ceb1ffc Mon Sep 17 00:00:00 2001 From: Scott Powell Date: Mon, 30 Mar 2026 11:53:27 +1100 Subject: [PATCH 47/52] * number_allocations.md data-type range changes --- docs/number_allocations.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/number_allocations.md b/docs/number_allocations.md index ea36f830cc..7f7e9372e4 100644 --- a/docs/number_allocations.md +++ b/docs/number_allocations.md @@ -8,9 +8,11 @@ The `PAYLOAD_TYPE_GRP_DATA` payloads have a 16-bit data-type field, which identi To make sure multiple applications can function without interfering with each other, the table below is for reserving various ranges of data-type values. Just modify this table, adding a row, then submit a PR to have it authorised/merged. -The 16-bit types are allocated in blocks of 16, ie. the lower 4-bits is the range. +NOTE: the range FF00 - FFFF is for use while you're developing, doing POC, and for these you don't need to request to use/allocate. -| Data-Type range | App name | Contact | -|-----------------|--------------------------|------------------------------------------------------| -| 000x | -reserved- | | -| FFFx | -reserved- | | +(add rows, using the range 0100 - FEFF for custom apps) + +| Data-Type range | App name | Contact | +|-----------------|-----------------------------|------------------------------------------------------| +| 0000 - 00FF | -reserved for internal use- | | +| FF00 - FFFF | -reserved for testing/dev- | | From efc875b1b6701e0b8389f2294755787f6864a667 Mon Sep 17 00:00:00 2001 From: Scott Powell Date: Mon, 30 Mar 2026 13:53:16 +1100 Subject: [PATCH 48/52] * more notes about number_allocations --- docs/number_allocations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/number_allocations.md b/docs/number_allocations.md index 7f7e9372e4..94ad1efda1 100644 --- a/docs/number_allocations.md +++ b/docs/number_allocations.md @@ -10,9 +10,11 @@ To make sure multiple applications can function without interfering with each ot NOTE: the range FF00 - FFFF is for use while you're developing, doing POC, and for these you don't need to request to use/allocate. -(add rows, using the range 0100 - FEFF for custom apps) +Once you have a working app/project, you need to be able to demonstrate it exists/works, and THEN request type IDs. So, just use the testing/dev range while developing, then request IDs before you transition to publishing your project. | Data-Type range | App name | Contact | |-----------------|-----------------------------|------------------------------------------------------| | 0000 - 00FF | -reserved for internal use- | | | FF00 - FFFF | -reserved for testing/dev- | | + +(add rows, inside the range 0100 - FEFF for custom apps) From 4a45b11cd66eca70a271351f61df76653b89dea1 Mon Sep 17 00:00:00 2001 From: MeetTheTree Date: Mon, 30 Mar 2026 23:11:25 +0200 Subject: [PATCH 49/52] Added without_display variant for repeater. Added an variant to use the heltec v3 without display as a repeater. This is intended for those whose display is either broken or who want to use the heltec v3 without the display. --- variants/heltec_v3/platformio.ini | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/variants/heltec_v3/platformio.ini b/variants/heltec_v3/platformio.ini index 803ee683e0..99bff77e27 100644 --- a/variants/heltec_v3/platformio.ini +++ b/variants/heltec_v3/platformio.ini @@ -57,6 +57,31 @@ lib_deps = ${esp32_ota.lib_deps} bakercp/CRC32 @ ^2.0.0 + +[env:Heltec_v3_without_display_repeater] +extends = Heltec_lora32_v3 +build_flags = + ${Heltec_lora32_v3.build_flags} + -D DISPLAY_CLASS=NullDisplayDriver + -D ADVERT_NAME='"Heltec Repeater"' + -D ADVERT_LAT=0.0 + -D ADVERT_LON=0.0 + -D ADMIN_PASSWORD='"password"' + -D MAX_NEIGHBOURS=50 +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 +build_src_filter = ${Heltec_lora32_v3.build_src_filter} + - + - + - + - + +<../examples/simple_repeater> +lib_deps = + ${Heltec_lora32_v3.lib_deps} + ${esp32_ota.lib_deps} + bakercp/CRC32 @ ^2.0.0 + + [env:Heltec_v3_repeater_bridge_rs232] extends = Heltec_lora32_v3 build_flags = @@ -376,4 +401,4 @@ build_flags = build_src_filter = ${Heltec_lora32_v3.build_src_filter} +<../examples/kiss_modem/> lib_deps = - ${Heltec_lora32_v3.lib_deps} \ No newline at end of file + ${Heltec_lora32_v3.lib_deps} From 76f6fbb932c27321a2e4d11bbd9e513146cc0a07 Mon Sep 17 00:00:00 2001 From: MeetTheTree Date: Mon, 30 Mar 2026 23:26:12 +0200 Subject: [PATCH 50/52] Implemented check for conditional loading of display libraries. Implemented check if for conditional loading of display related libraries. If DISPLAY_CLASS is NULL_DISPLAY_DRIVER omit any display related code elsewise include the display. --- variants/heltec_v3/target.h | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/variants/heltec_v3/target.h b/variants/heltec_v3/target.h index 21a209f993..b90655d2e4 100644 --- a/variants/heltec_v3/target.h +++ b/variants/heltec_v3/target.h @@ -8,9 +8,20 @@ #include #include #include -#ifdef DISPLAY_CLASS - #include - #include +// --------------------------------------------------------- +// Display handling +// If DISPLAY_CLASS is defined AND not NullDisplayDriver, +// include display support. +// --------------------------------------------------------- +#if defined(DISPLAY_CLASS) && !defined(NULL_DISPLAY_DRIVER) + #if !defined(DISPLAY_CLASS_IS_NULL) && !defined(DISPLAY_CLASS_NULL) + // Only include display headers if DISPLAY_CLASS is not NullDisplayDriver + #if !defined(DISPLAY_CLASS) || !__has_include() + // Default behavior: SSD1306Display + #include + #endif + #include + #endif #endif extern HeltecV3Board board; @@ -18,9 +29,12 @@ extern WRAPPER_CLASS radio_driver; extern AutoDiscoverRTCClock rtc_clock; extern EnvironmentSensorManager sensors; -#ifdef DISPLAY_CLASS - extern DISPLAY_CLASS display; - extern MomentaryButton user_btn; +// --------------------------------------------------------- +// Display globals only if DISPLAY_CLASS is not NullDisplayDriver +// --------------------------------------------------------- +#if defined(DISPLAY_CLASS) && DISPLAY_CLASS != NullDisplayDriver +extern DISPLAY_CLASS display; +extern MomentaryButton user_btn; #endif bool radio_init(); From 4cd24f297070e92f392ee694b9d29c10a8065af5 Mon Sep 17 00:00:00 2001 From: MeetTheTree Date: Mon, 30 Mar 2026 23:43:36 +0200 Subject: [PATCH 51/52] Update platformio.ini added NO_DISPLAY FLAG --- variants/heltec_v3/platformio.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/variants/heltec_v3/platformio.ini b/variants/heltec_v3/platformio.ini index 99bff77e27..14b9e573de 100644 --- a/variants/heltec_v3/platformio.ini +++ b/variants/heltec_v3/platformio.ini @@ -63,6 +63,7 @@ extends = Heltec_lora32_v3 build_flags = ${Heltec_lora32_v3.build_flags} -D DISPLAY_CLASS=NullDisplayDriver + -D NO_DISPLAY -D ADVERT_NAME='"Heltec Repeater"' -D ADVERT_LAT=0.0 -D ADVERT_LON=0.0 From c4932eb43975f10bbaa551cce45c8cf90e1407a1 Mon Sep 17 00:00:00 2001 From: MeetTheTree Date: Mon, 30 Mar 2026 23:46:13 +0200 Subject: [PATCH 52/52] Update target.h simplified logic for inclusion of display code --- variants/heltec_v3/target.h | 29 ++++++++++------------------- 1 file changed, 10 insertions(+), 19 deletions(-) diff --git a/variants/heltec_v3/target.h b/variants/heltec_v3/target.h index b90655d2e4..1f674ee1e1 100644 --- a/variants/heltec_v3/target.h +++ b/variants/heltec_v3/target.h @@ -8,20 +8,14 @@ #include #include #include -// --------------------------------------------------------- -// Display handling -// If DISPLAY_CLASS is defined AND not NullDisplayDriver, -// include display support. -// --------------------------------------------------------- -#if defined(DISPLAY_CLASS) && !defined(NULL_DISPLAY_DRIVER) - #if !defined(DISPLAY_CLASS_IS_NULL) && !defined(DISPLAY_CLASS_NULL) - // Only include display headers if DISPLAY_CLASS is not NullDisplayDriver - #if !defined(DISPLAY_CLASS) || !__has_include() - // Default behavior: SSD1306Display - #include - #endif - #include + +#ifdef DISPLAY_CLASS + #ifdef NO_DISPLAY + #include + #else + #include #endif + #include #endif extern HeltecV3Board board; @@ -29,12 +23,9 @@ extern WRAPPER_CLASS radio_driver; extern AutoDiscoverRTCClock rtc_clock; extern EnvironmentSensorManager sensors; -// --------------------------------------------------------- -// Display globals only if DISPLAY_CLASS is not NullDisplayDriver -// --------------------------------------------------------- -#if defined(DISPLAY_CLASS) && DISPLAY_CLASS != NullDisplayDriver -extern DISPLAY_CLASS display; -extern MomentaryButton user_btn; +#ifdef DISPLAY_CLASS + extern DISPLAY_CLASS display; + extern MomentaryButton user_btn; #endif bool radio_init();