Traffic Management Module for packet forwarding logic (#9358)

* Add ESP32 Power Management lessons learned document

Documents our experimentation with ESP-IDF DFS and why it doesn't
work well for Meshtastic (RTOS locks, BLE locks, USB issues).

Proposes simpler alternative: manual setCpuFrequencyMhz() control
with explicit triggers for when to go fast vs slow.

* Addition of traffic management module

* Fixing compile issues, but may still need to update protobufs.

* Fixing log2Floor in cuckoo hash function

* Adding support for traffic management in PhoneAPI.

* Making router_preserve_hops work without checking if the previous hop was a router. Also works for CLIENT_BASE.

* Adding station-g2 and portduino varients to be able to use this module.

* Spoofing from address for nodeinfo cache

* Changing name and behavior for zero_hop_telemetry / zero_hop_position

* Name change for exhausting telemetry packets and setting hop_limit to 1 so it will be 0 when sent.

* Updated hop logic, including exhaustRequested flag to bypass some checks later in the code.

* Reducing memory on nrf52 nodes further to 12 bytes per entry, 12KB total using 8 bit hashes with 0.4% collision. Probably ok. Adding portduino to the platforms that don't need to worry about memory as much.

* Fixing hopsAway for nodeinfo responses.

* traffic_management.nodeinfo_direct_response_min_hops -> traffic_management.nodeinfo_direct_response_max_hops

* Removing dry run mode

* Updates to UnifiedCacheEntry to use a common cache, created defaults for some values, reduced a couple bytes per entry by using a resolution-scale time selection based on configuration value.

* Enhance traffic management logging and configuration. Updated log messages in NextHopRouter and Router to include more context. Adjusted traffic management configuration checks in AdminModule and improved cache handling in TrafficManagementModule. Ensured consistent enabling of traffic management across various variants.

* Implement destructor for TrafficManagementModule and improve cache allocation handling. The destructor ensures proper deallocation of cache memory based on its allocation source (PSRAM or heap). Additionally, updated cache allocation logic to log warnings only when PSRAM allocation fails.

* Update TrafficManagementModule with enhanced comments for clarity and improve cache handling logic. Update protobuf submodule to latest commit.

* Creating consistent log messages

* Remove docs/ESP32_Power_Management.md from traffic_module

* Add unit tests for Traffic Management Module functionality

* Fixing compile issues, but may still need to update protobufs.

* Adding support for traffic management in PhoneAPI.

* Making router_preserve_hops work without checking if the previous hop was a router. Also works for CLIENT_BASE.

* Enhance traffic management logging and configuration. Updated log messages in NextHopRouter and Router to include more context. Adjusted traffic management configuration checks in AdminModule and improved cache handling in TrafficManagementModule. Ensured consistent enabling of traffic management across various variants.

* Implement destructor for TrafficManagementModule and improve cache allocation handling. The destructor ensures proper deallocation of cache memory based on its allocation source (PSRAM or heap). Additionally, updated cache allocation logic to log warnings only when PSRAM allocation fails.

* Update TrafficManagementModule with enhanced comments for clarity and improve cache handling logic. Update protobuf submodule to latest commit.

* Add mock classes and unit tests for Traffic Management Module functionality.

* Refactor setup and loop functions in test_main.cpp to include extern "C" linkage

* Update comment to include reduced  memory requirements

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Re-arranging comments for programmers with the attention span of less than 5 lines of code.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update comments in TrafficManagementModule to reflect changes in timestamp epoch handling and memory optimization details.

* bug: Use node-wide config_ok_to_mqtt setting for cached NodeInfo replies.

* Better way to handle clearing the ok_to_mqtt bit

* Add bucketing to cuckoo hashing, allowing for 95% occupied rate before major eviction problems.

* Extend nodeinfo cache for psram devices.

* Refactor traffic management to make hop exhaustion packet-scoped. Nice catch.

* Implement better position precision sanitization in TrafficManagementModule.

* Added logic in TrafficManagementModule to invalidate stale traffic state. Also, added some tests to avoid future me from creating a regression here.

* Fixing tests for native

* Enhance TrafficManagementModule to improve NodeInfo response handling and position deduplication logic. Added tests to ensure local packets bypass transit filters and that NodeInfo requests correctly update the requester information in the cache. Updated deduplication checks to prevent dropping valid position packets under certain conditions.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

src/configuration.h

@@ -499,6 +499,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #define MESHTASTIC_EXCLUDE_REMOTEHARDWARE 1
 #define MESHTASTIC_EXCLUDE_STOREFORWARD 1
 #define MESHTASTIC_EXCLUDE_TEXTMESSAGE 1
+#define MESHTASTIC_EXCLUDE_TRAFFIC_MANAGEMENT 1
 #define MESHTASTIC_EXCLUDE_ATAK 1
 #define MESHTASTIC_EXCLUDE_CANNEDMESSAGES 1
 #define MESHTASTIC_EXCLUDE_NEIGHBORINFO 1

src/graphics/EInkDisplay2.cpp

@@ -143,6 +143,10 @@ bool EInkDisplay::connect()
 #ifdef ELECROW_ThinkNode_M1
     // ThinkNode M1 has a hardware dimmable backlight. Start enabled
     digitalWrite(PIN_EINK_EN, HIGH);
+#elif defined(MINI_EPAPER_S3)
+    // T-Mini Epaper S3 requires panel power rail enabled before SPI transfer.
+    digitalWrite(PIN_EINK_EN, HIGH);
+    delay(10);
 #else
     digitalWrite(PIN_EINK_EN, LOW);
 #endif
@@ -202,7 +206,8 @@ bool EInkDisplay::connect()
     }
 
 #elif defined(HELTEC_WIRELESS_PAPER_V1_0) || defined(HELTEC_VISION_MASTER_E290) || defined(TLORA_T3S3_EPAPER) ||                 \
-    defined(CROWPANEL_ESP32S3_5_EPAPER) || defined(CROWPANEL_ESP32S3_4_EPAPER) || defined(CROWPANEL_ESP32S3_2_EPAPER)
+    defined(CROWPANEL_ESP32S3_5_EPAPER) || defined(CROWPANEL_ESP32S3_4_EPAPER) || defined(CROWPANEL_ESP32S3_2_EPAPER) ||         \
+    defined(MINI_EPAPER_S3)
     {
         // Start HSPI
         hspi = new SPIClass(HSPI);
@@ -216,9 +221,13 @@ bool EInkDisplay::connect()
 
         // Init GxEPD2
         adafruitDisplay->init();
+#if defined(MINI_EPAPER_S3)
+        adafruitDisplay->setRotation(3);
+#else
         adafruitDisplay->setRotation(3);
 #if defined(CROWPANEL_ESP32S3_5_EPAPER) || defined(CROWPANEL_ESP32S3_4_EPAPER)
         adafruitDisplay->setRotation(0);
+#endif
 #endif
     }
 #elif defined(PCA10059) || defined(ME25LS01)
@@ -259,17 +268,6 @@ bool EInkDisplay::connect()
         adafruitDisplay->setRotation(3);
         adafruitDisplay->setPartialWindow(0, 0, EINK_WIDTH, EINK_HEIGHT);
     }
-#elif defined(MINI_EPAPER_S3)
-    spi1 = new SPIClass(HSPI);
-    spi1->begin(PIN_SPI1_SCK, PIN_SPI1_MISO, PIN_SPI1_MOSI, PIN_EINK_CS);
-
-    // Create GxEPD2 objects
-    auto lowLevel = new EINK_DISPLAY_MODEL(PIN_EINK_CS, PIN_EINK_DC, PIN_EINK_RES, PIN_EINK_BUSY, *spi1);
-    adafruitDisplay = new GxEPD2_BW<EINK_DISPLAY_MODEL, EINK_DISPLAY_MODEL::HEIGHT>(*lowLevel);
-
-    // Init GxEPD2
-    adafruitDisplay->init();
-    adafruitDisplay->setRotation(1);
 #elif defined(HELTEC_WIRELESS_PAPER) || defined(HELTEC_VISION_MASTER_E213)
 
     // Detect display model, before starting SPI

src/graphics/EInkDisplay2.h

@@ -89,12 +89,12 @@ class EInkDisplay : public OLEDDisplay
     // If display uses HSPI
 #if defined(HELTEC_WIRELESS_PAPER) || defined(HELTEC_WIRELESS_PAPER_V1_0) || defined(HELTEC_VISION_MASTER_E213) ||               \
     defined(HELTEC_VISION_MASTER_E290) || defined(TLORA_T3S3_EPAPER) || defined(CROWPANEL_ESP32S3_5_EPAPER) ||                   \
-    defined(CROWPANEL_ESP32S3_4_EPAPER) || defined(CROWPANEL_ESP32S3_2_EPAPER) || defined(ELECROW_ThinkNode_M5)
+    defined(CROWPANEL_ESP32S3_4_EPAPER) || defined(CROWPANEL_ESP32S3_2_EPAPER) || defined(ELECROW_ThinkNode_M5) ||               \
+    defined(MINI_EPAPER_S3)
     SPIClass *hspi = NULL;
 #endif
 
-#if defined(HELTEC_MESH_POCKET) || defined(SEEED_WIO_TRACKER_L1_EINK) || defined(HELTEC_MESH_SOLAR_EINK) ||                      \
-    defined(MINI_EPAPER_S3)
+#if defined(HELTEC_MESH_POCKET) || defined(SEEED_WIO_TRACKER_L1_EINK) || defined(HELTEC_MESH_SOLAR_EINK)
     SPIClass *spi1 = NULL;
 #endif
 

src/graphics/niche/Drivers/EInk/GDEW0102T4.cpp

@@ -0,0 +1,178 @@
+#ifdef MESHTASTIC_INCLUDE_NICHE_GRAPHICS
+
+#include "./GDEW0102T4.h"
+
+#include <cstring>
+
+using namespace NicheGraphics::Drivers;
+
+// LUTs from GxEPD2_102.cpp (GDEW0102T4 / UC8175).
+static const uint8_t LUT_W_FULL[] = {
+    0x60, 0x5A, 0x5A, 0x00, 0x00, 0x01, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+};
+
+static const uint8_t LUT_B_FULL[] = {
+    0x90, 0x5A, 0x5A, 0x00, 0x00, 0x01, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+};
+
+static const uint8_t LUT_W_FAST[] = {
+    0x60, 0x01, 0x01, 0x00, 0x00, 0x01, //
+    0x80, 0x12, 0x00, 0x00, 0x00, 0x01, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+};
+
+static const uint8_t LUT_B_FAST[] = {
+    0x90, 0x01, 0x01, 0x00, 0x00, 0x01, //
+    0x40, 0x14, 0x00, 0x00, 0x00, 0x01, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //
+};
+
+GDEW0102T4::GDEW0102T4() : UC8175(width, height, supported) {}
+
+void GDEW0102T4::setFastConfig(FastConfig cfg)
+{
+    // Clamp out only clearly invalid PLL settings.
+    if (cfg.reg30 < 0x05)
+        cfg.reg30 = 0x05;
+    fastConfig = cfg;
+}
+
+GDEW0102T4::FastConfig GDEW0102T4::getFastConfig() const
+{
+    return fastConfig;
+}
+
+void GDEW0102T4::configCommon()
+{
+    // Init path aligned with GxEPD2_GDEW0102T4 (UC8175 family).
+    sendCommand(0xD2);
+    sendData(0x3F);
+
+    sendCommand(0x00);
+    sendData(0x6F);
+
+    sendCommand(0x01);
+    sendData(0x03);
+    sendData(0x00);
+    sendData(0x2B);
+    sendData(0x2B);
+
+    sendCommand(0x06);
+    sendData(0x3F);
+
+    sendCommand(0x2A);
+    sendData(0x00);
+    sendData(0x00);
+
+    sendCommand(0x30); // PLL / drive clock
+    sendData(0x13);
+
+    sendCommand(0x50); // Last border/data interval; subtle but can affect artifacts
+    sendData(0x57);
+
+    sendCommand(0x60);
+    sendData(0x22);
+
+    sendCommand(0x61);
+    sendData(width);
+    sendData(height);
+
+    sendCommand(0x82); // VCOM DC setting
+    sendData(0x12);
+
+    sendCommand(0xE3);
+    sendData(0x33);
+}
+
+void GDEW0102T4::configFull()
+{
+    sendCommand(0x23);
+    sendData(LUT_W_FULL, sizeof(LUT_W_FULL));
+    sendCommand(0x24);
+    sendData(LUT_B_FULL, sizeof(LUT_B_FULL));
+
+    powerOn();
+}
+
+void GDEW0102T4::configFast()
+{
+    uint8_t lutW[sizeof(LUT_W_FAST)];
+    uint8_t lutB[sizeof(LUT_B_FAST)];
+    memcpy(lutW, LUT_W_FAST, sizeof(LUT_W_FAST));
+    memcpy(lutB, LUT_B_FAST, sizeof(LUT_B_FAST));
+
+    // Second stage duration bytes are the main "darkness vs ghosting" control for this panel.
+    lutW[7] = fastConfig.lutW2;
+    lutB[7] = fastConfig.lutB2;
+
+    sendCommand(0x30);
+    sendData(fastConfig.reg30);
+
+    sendCommand(0x50);
+    sendData(fastConfig.reg50);
+
+    sendCommand(0x82);
+    sendData(fastConfig.reg82);
+
+    sendCommand(0x23);
+    sendData(lutW, sizeof(lutW));
+    sendCommand(0x24);
+    sendData(lutB, sizeof(lutB));
+
+    powerOn();
+}
+
+void GDEW0102T4::writeOldImage()
+{
+    // On this panel, FULL refresh is most reliable when "old image" is all white.
+    if (updateType == FULL) {
+        sendCommand(0x10);
+        // Use buffered writes of 0xFF to avoid per-byte SPI transactions.
+        const uint16_t chunkSize = 64;
+        uint8_t ffBuf[chunkSize];
+        memset(ffBuf, 0xFF, sizeof(ffBuf));
+
+        uint32_t remaining = bufferSize;
+        while (remaining > 0) {
+            uint16_t toSend = remaining > chunkSize ? chunkSize : static_cast<uint16_t>(remaining);
+            sendData(ffBuf, toSend);
+            remaining -= toSend;
+        }
+        return;
+    }
+
+    // FAST refresh uses differential data (previous frame as old image).
+    if (previousBuffer) {
+        writeImage(0x10, previousBuffer);
+    } else {
+        writeImage(0x10, buffer);
+    }
+}
+
+void GDEW0102T4::finalizeUpdate()
+{
+    // Keep panel out of deep-sleep between updates for better reliability of repeated FAST refresh.
+    powerOff();
+}
+
+#endif // MESHTASTIC_INCLUDE_NICHE_GRAPHICS

src/graphics/niche/Drivers/EInk/GDEW0102T4.h

@@ -0,0 +1,55 @@
+/*
+
+E-Ink display driver
+    - GDEW0102T4
+    - Controller: UC8175
+    - Size: 1.02 inch
+    - Resolution: 80px x 128px
+
+*/
+
+#pragma once
+
+#ifdef MESHTASTIC_INCLUDE_NICHE_GRAPHICS
+
+#include "configuration.h"
+
+#include "./UC8175.h"
+
+namespace NicheGraphics::Drivers
+{
+
+class GDEW0102T4 : public UC8175
+{
+  private:
+    static constexpr uint16_t width = 80;
+    static constexpr uint16_t height = 128;
+    static constexpr UpdateTypes supported = (UpdateTypes)(FULL | FAST);
+
+  public:
+    struct FastConfig {
+        uint8_t reg30;
+        uint8_t reg50;
+        uint8_t reg82;
+        uint8_t lutW2;
+        uint8_t lutB2;
+    };
+
+    GDEW0102T4();
+    void setFastConfig(FastConfig cfg);
+    FastConfig getFastConfig() const;
+
+  protected:
+    void configCommon() override;
+    void configFull() override;
+    void configFast() override;
+    void writeOldImage() override;
+    void finalizeUpdate() override;
+
+  private:
+    FastConfig fastConfig = {0x13, 0xF2, 0x12, 0x0E, 0x14};
+};
+
+} // namespace NicheGraphics::Drivers
+
+#endif // MESHTASTIC_INCLUDE_NICHE_GRAPHICS

src/graphics/niche/Drivers/EInk/UC8175.cpp

@@ -0,0 +1,203 @@
+#ifdef MESHTASTIC_INCLUDE_NICHE_GRAPHICS
+
+#include "./UC8175.h"
+
+#include <cstring>
+
+#include "SPILock.h"
+
+using namespace NicheGraphics::Drivers;
+
+UC8175::UC8175(uint16_t width, uint16_t height, UpdateTypes supported) : EInk(width, height, supported)
+{
+    bufferRowSize = ((width - 1) / 8) + 1;
+    bufferSize = bufferRowSize * height;
+}
+
+void UC8175::begin(SPIClass *spi, uint8_t pin_dc, uint8_t pin_cs, uint8_t pin_busy, uint8_t pin_rst)
+{
+    this->spi = spi;
+    this->pin_dc = pin_dc;
+    this->pin_cs = pin_cs;
+    this->pin_busy = pin_busy;
+    this->pin_rst = pin_rst;
+
+    pinMode(pin_dc, OUTPUT);
+    pinMode(pin_cs, OUTPUT);
+    pinMode(pin_busy, INPUT);
+
+    // Reset is active LOW, hold HIGH when idle.
+    if (pin_rst != (uint8_t)-1) {
+        pinMode(pin_rst, OUTPUT);
+        digitalWrite(pin_rst, HIGH);
+    }
+
+    if (!previousBuffer) {
+        previousBuffer = new uint8_t[bufferSize];
+        if (previousBuffer)
+            memset(previousBuffer, 0xFF, bufferSize);
+    }
+}
+
+void UC8175::update(uint8_t *imageData, UpdateTypes type)
+{
+    buffer = imageData;
+    updateType = (type == UpdateTypes::UNSPECIFIED) ? UpdateTypes::FULL : type;
+
+    if (updateType == FAST && hasPreviousBuffer && previousBuffer && memcmp(previousBuffer, buffer, bufferSize) == 0)
+        return;
+
+    reset();
+    configCommon();
+
+    if (updateType == FAST)
+        configFast();
+    else
+        configFull();
+
+    writeOldImage();
+    writeNewImage();
+    sendCommand(0x12); // Display refresh.
+
+    if (previousBuffer) {
+        memcpy(previousBuffer, buffer, bufferSize);
+        hasPreviousBuffer = true;
+    }
+
+    detachFromUpdate();
+}
+
+void UC8175::wait(uint32_t timeoutMs)
+{
+    if (failed)
+        return;
+
+    uint32_t started = millis();
+    while (digitalRead(pin_busy) == BUSY_ACTIVE) {
+        if ((millis() - started) > timeoutMs) {
+            failed = true;
+            break;
+        }
+        yield();
+    }
+}
+
+void UC8175::reset()
+{
+    if (pin_rst != (uint8_t)-1) {
+        digitalWrite(pin_rst, LOW);
+        delay(20);
+        digitalWrite(pin_rst, HIGH);
+        delay(20);
+    } else {
+        sendCommand(0x12); // Software reset.
+        delay(10);
+    }
+
+    wait(3000);
+}
+
+void UC8175::sendCommand(uint8_t command)
+{
+    if (failed)
+        return;
+
+    spiLock->lock();
+    spi->beginTransaction(spiSettings);
+    digitalWrite(pin_dc, LOW);
+    digitalWrite(pin_cs, LOW);
+    spi->transfer(command);
+    digitalWrite(pin_cs, HIGH);
+    digitalWrite(pin_dc, HIGH);
+    spi->endTransaction();
+    spiLock->unlock();
+}
+
+void UC8175::sendData(uint8_t data)
+{
+    sendData(&data, 1);
+}
+
+void UC8175::sendData(const uint8_t *data, uint32_t size)
+{
+    if (failed)
+        return;
+
+    spiLock->lock();
+    spi->beginTransaction(spiSettings);
+    digitalWrite(pin_dc, HIGH);
+    digitalWrite(pin_cs, LOW);
+
+#if defined(ARCH_ESP32)
+    spi->transferBytes(data, NULL, size);
+#elif defined(ARCH_NRF52)
+    spi->transfer(data, NULL, size);
+#else
+    for (uint32_t i = 0; i < size; ++i)
+        spi->transfer(data[i]);
+#endif
+
+    digitalWrite(pin_cs, HIGH);
+    digitalWrite(pin_dc, HIGH);
+    spi->endTransaction();
+    spiLock->unlock();
+}
+
+void UC8175::powerOn()
+{
+    sendCommand(0x04);
+    wait(2000);
+}
+
+void UC8175::powerOff()
+{
+    sendCommand(0x02); // Power off.
+    wait(1500);
+}
+
+void UC8175::writeImage(uint8_t command, const uint8_t *image)
+{
+    sendCommand(command);
+    sendData(image, bufferSize);
+}
+
+void UC8175::writeOldImage()
+{
+    if (updateType == FAST && previousBuffer)
+        writeImage(0x10, previousBuffer);
+    else
+        writeImage(0x10, buffer);
+}
+
+void UC8175::writeNewImage()
+{
+    writeImage(0x13, buffer);
+}
+
+void UC8175::detachFromUpdate()
+{
+    switch (updateType) {
+    case FAST:
+        return beginPolling(50, 400);
+    case FULL:
+    default:
+        return beginPolling(100, 2000);
+    }
+}
+
+bool UC8175::isUpdateDone()
+{
+    return digitalRead(pin_busy) != BUSY_ACTIVE;
+}
+
+void UC8175::finalizeUpdate()
+{
+    powerOff();
+
+    if (pin_rst != (uint8_t)-1) {
+        sendCommand(0x07); // Deep sleep.
+        sendData(0xA5);
+    }
+}
+
+#endif // MESHTASTIC_INCLUDE_NICHE_GRAPHICS

src/graphics/niche/Drivers/EInk/UC8175.h

@@ -0,0 +1,62 @@
+// E-Ink base class for displays based on UC8175 / UC8176 style controller ICs.
+
+#pragma once
+
+#ifdef MESHTASTIC_INCLUDE_NICHE_GRAPHICS
+
+#include "configuration.h"
+
+#include "./EInk.h"
+
+namespace NicheGraphics::Drivers
+{
+
+class UC8175 : public EInk
+{
+  public:
+    UC8175(uint16_t width, uint16_t height, UpdateTypes supported);
+    void begin(SPIClass *spi, uint8_t pin_dc, uint8_t pin_cs, uint8_t pin_busy, uint8_t pin_rst = -1) override;
+    void update(uint8_t *imageData, UpdateTypes type) override;
+
+  protected:
+    virtual void wait(uint32_t timeoutMs = 1000);
+    virtual void reset();
+    virtual void sendCommand(uint8_t command);
+    virtual void sendData(uint8_t data);
+    virtual void sendData(const uint8_t *data, uint32_t size);
+
+    virtual void configCommon() = 0; // Always run
+    virtual void configFull() = 0;   // Run when updateType == FULL
+    virtual void configFast() = 0;   // Run when updateType == FAST
+
+    virtual void powerOn();
+    virtual void powerOff();
+    virtual void writeOldImage();
+    virtual void writeNewImage();
+    virtual void writeImage(uint8_t command, const uint8_t *image);
+
+    virtual void detachFromUpdate();
+    virtual bool isUpdateDone() override;
+    virtual void finalizeUpdate() override;
+
+  protected:
+    static constexpr uint8_t BUSY_ACTIVE = LOW;
+
+    uint16_t bufferRowSize = 0;
+    uint32_t bufferSize = 0;
+    uint8_t *buffer = nullptr;
+    uint8_t *previousBuffer = nullptr;
+    bool hasPreviousBuffer = false;
+    UpdateTypes updateType = UpdateTypes::UNSPECIFIED;
+
+    uint8_t pin_dc = (uint8_t)-1;
+    uint8_t pin_cs = (uint8_t)-1;
+    uint8_t pin_busy = (uint8_t)-1;
+    uint8_t pin_rst = (uint8_t)-1;
+    SPIClass *spi = nullptr;
+    SPISettings spiSettings = SPISettings(8000000, MSBFIRST, SPI_MODE0);
+};
+
+} // namespace NicheGraphics::Drivers
+
+#endif // MESHTASTIC_INCLUDE_NICHE_GRAPHICS

src/graphics/niche/InkHUD/Applets/System/Menu/MenuApplet.cpp

@@ -349,13 +349,13 @@ void InkHUD::MenuApplet::execute(MenuItem item)
         handleFreeText = true;
         cm.freeTextItem.rawText.erase(); // clear the previous freetext message
         freeTextMode = true;             // render input field instead of normal menu
-        // Open the on-screen keyboard if the joystick is enabled
-        if (settings->joystick.enabled)
+        // Open the on-screen keyboard only for full joystick devices
+        if (settings->joystick.enabled && !inkhud->twoWayRocker)
             inkhud->openKeyboard();
         break;
 
     case STORE_CANNEDMESSAGE_SELECTION:
-        if (!settings->joystick.enabled)
+        if (!settings->joystick.enabled || inkhud->twoWayRocker)
             cm.selectedMessageItem = &cm.messageItems.at(cursor - 1); // Minus one: offset for the initial "Send Ping" entry
         else
             cm.selectedMessageItem = &cm.messageItems.at(cursor - 2); // Minus two: offset for the "Send Ping" and free text entry
@@ -922,7 +922,7 @@ void InkHUD::MenuApplet::showPage(MenuPage page)
         if (settings->userTiles.maxCount > 1)
             items.push_back(MenuItem("Layout", MenuAction::LAYOUT, MenuPage::OPTIONS));
         items.push_back(MenuItem("Rotate", MenuAction::ROTATE, MenuPage::OPTIONS));
-        if (settings->joystick.enabled)
+        if (settings->joystick.enabled && !inkhud->twoWayRocker)
             items.push_back(MenuItem("Align Joystick", MenuAction::ALIGN_JOYSTICK, MenuPage::EXIT));
         items.push_back(MenuItem("Notifications", MenuAction::TOGGLE_NOTIFICATIONS, MenuPage::OPTIONS,
                                  &settings->optionalFeatures.notifications));
@@ -1751,7 +1751,7 @@ void InkHUD::MenuApplet::populateSendPage()
     items.push_back(MenuItem("Ping", MenuAction::SEND_PING, MenuPage::EXIT));
 
     // If joystick is available, include the Free Text option
-    if (settings->joystick.enabled)
+    if (settings->joystick.enabled && !inkhud->twoWayRocker)
         items.push_back(MenuItem("Free Text", MenuAction::FREE_TEXT, MenuPage::SEND));
 
     // One menu item for each canned message

src/graphics/niche/InkHUD/Applets/System/Tips/TipsApplet.cpp

@@ -152,6 +152,11 @@ void InkHUD::TipsApplet::onRender(bool full)
             drawBullet("User Button");
             drawBullet("- short press: next");
             drawBullet("- long press: select or open menu");
+        } else if (inkhud->twoWayRocker) {
+            drawBullet("Rocker + Button");
+            drawBullet("- center press: open menu or select");
+            drawBullet("- left/right: applet nav");
+            drawBullet("- in menu: up/down");
         } else {
             drawBullet("Joystick");
             drawBullet("- press: open menu or select");

src/graphics/niche/InkHUD/InkHUD.h

@@ -88,6 +88,9 @@ class InkHUD
     // Used by TipsApplet to force menu to start on Region selection
     bool forceRegionMenu = false;
 
+    // Input mode hint for devices that use a left/right rocker plus center button
+    bool twoWayRocker = false;
+
     // Updating the display
     // - called by various InkHUD components
 
@@ -130,4 +133,4 @@ class InkHUD
 
 } // namespace NicheGraphics::InkHUD
 
-#endif
+#endif

src/graphics/niche/InkHUD/WindowManager.cpp

@@ -143,7 +143,7 @@ void InkHUD::WindowManager::openMenu()
 // Bring the AlignStick applet to the foreground
 void InkHUD::WindowManager::openAlignStick()
 {
-    if (settings->joystick.enabled) {
+    if (settings->joystick.enabled && !inkhud->twoWayRocker) {
         AlignStickApplet *alignStick = (AlignStickApplet *)inkhud->getSystemApplet("AlignStick");
         alignStick->bringToForeground();
     }
@@ -151,6 +151,9 @@ void InkHUD::WindowManager::openAlignStick()
 
 void InkHUD::WindowManager::openKeyboard()
 {
+    if (!settings->joystick.enabled || inkhud->twoWayRocker)
+        return;
+
     KeyboardApplet *keyboard = (KeyboardApplet *)inkhud->getSystemApplet("Keyboard");
 
     if (keyboard) {
@@ -162,6 +165,9 @@ void InkHUD::WindowManager::openKeyboard()
 
 void InkHUD::WindowManager::closeKeyboard()
 {
+    if (!settings->joystick.enabled || inkhud->twoWayRocker)
+        return;
+
     KeyboardApplet *keyboard = (KeyboardApplet *)inkhud->getSystemApplet("Keyboard");
 
     if (keyboard) {
@@ -477,7 +483,7 @@ void InkHUD::WindowManager::createSystemApplets()
     addSystemApplet("Logo", new LogoApplet, new Tile);
     addSystemApplet("Pairing", new PairingApplet, new Tile);
     addSystemApplet("Tips", new TipsApplet, new Tile);
-    if (settings->joystick.enabled) {
+    if (settings->joystick.enabled && !inkhud->twoWayRocker) {
         addSystemApplet("AlignStick", new AlignStickApplet, new Tile);
         addSystemApplet("Keyboard", new KeyboardApplet, new Tile);
     }
@@ -503,7 +509,7 @@ void InkHUD::WindowManager::placeSystemTiles()
     inkhud->getSystemApplet("Logo")->getTile()->setRegion(0, 0, inkhud->width(), inkhud->height());
     inkhud->getSystemApplet("Pairing")->getTile()->setRegion(0, 0, inkhud->width(), inkhud->height());
     inkhud->getSystemApplet("Tips")->getTile()->setRegion(0, 0, inkhud->width(), inkhud->height());
-    if (settings->joystick.enabled) {
+    if (settings->joystick.enabled && !inkhud->twoWayRocker) {
         inkhud->getSystemApplet("AlignStick")->getTile()->setRegion(0, 0, inkhud->width(), inkhud->height());
         const uint16_t keyboardHeight = KeyboardApplet::getKeyboardHeight();
         inkhud->getSystemApplet("Keyboard")

src/graphics/niche/Inputs/TwoButtonExtended.cpp

@@ -156,6 +156,24 @@ void TwoButtonExtended::setJoystickWiring(uint8_t uPin, uint8_t dPin, uint8_t lP
     pinMode(joystick[Direction::RIGHT].pin, internalPullup ? INPUT_PULLUP : INPUT);
 }
 
+// Configures only left/right joystick directions for a two-way rocker
+void TwoButtonExtended::setTwoWayRockerWiring(uint8_t leftPin, uint8_t rightPin, bool internalPullup)
+{
+    if (leftPin == rightPin) {
+        LOG_WARN("Attempted reuse of TwoWayRocker GPIO. Ignoring assignment");
+        return;
+    }
+
+    joystick[Direction::UP].pin = 0xFF;
+    joystick[Direction::DOWN].pin = 0xFF;
+    joystick[Direction::LEFT].pin = leftPin;
+    joystick[Direction::RIGHT].pin = rightPin;
+    joystickActiveLogic = LOW;
+
+    pinMode(joystick[Direction::LEFT].pin, internalPullup ? INPUT_PULLUP : INPUT);
+    pinMode(joystick[Direction::RIGHT].pin, internalPullup ? INPUT_PULLUP : INPUT);
+}
+
 void TwoButtonExtended::setTiming(uint8_t whichButton, uint32_t debounceMs, uint32_t longpressMs)
 {
     assert(whichButton < 2);
@@ -229,6 +247,13 @@ void TwoButtonExtended::setJoystickPressHandlers(Callback uPress, Callback dPres
     joystick[Direction::RIGHT].onPress = rPress;
 }
 
+// Set press handlers for a two-way rocker mapped to left/right directions
+void TwoButtonExtended::setTwoWayRockerPressHandlers(Callback lPress, Callback rPress)
+{
+    joystick[Direction::LEFT].onPress = lPress;
+    joystick[Direction::RIGHT].onPress = rPress;
+}
+
 // Handle the start of a press to the primary button
 // Wakes our button thread
 void TwoButtonExtended::isrPrimary()

src/graphics/niche/Inputs/TwoButtonExtended.h

@@ -45,6 +45,7 @@ class TwoButtonExtended : protected concurrency::OSThread
     void stop();                             // Stop handling button input (disconnect ISRs for sleep)
     void setWiring(uint8_t whichButton, uint8_t pin, bool internalPullup = false);
     void setJoystickWiring(uint8_t uPin, uint8_t dPin, uint8_t lPin, uint8_t rPin, bool internalPullup = false);
+    void setTwoWayRockerWiring(uint8_t leftPin, uint8_t rightPin, bool internalPullup = false);
     void setTiming(uint8_t whichButton, uint32_t debounceMs, uint32_t longpressMs);
     void setJoystickDebounce(uint32_t debounceMs);
     void setHandlerDown(uint8_t whichButton, Callback onDown);
@@ -54,6 +55,7 @@ class TwoButtonExtended : protected concurrency::OSThread
     void setJoystickDownHandlers(Callback uDown, Callback dDown, Callback ldown, Callback rDown);
     void setJoystickUpHandlers(Callback uUp, Callback dUp, Callback lUp, Callback rUp);
     void setJoystickPressHandlers(Callback uPress, Callback dPress, Callback lPress, Callback rPress);
+    void setTwoWayRockerPressHandlers(Callback lPress, Callback rPress);
 
     // Disconnect and reconnect interrupts for light sleep
 #ifdef ARCH_ESP32

src/input/UpDownInterruptImpl1.cpp

@@ -8,6 +8,14 @@ UpDownInterruptImpl1::UpDownInterruptImpl1() : UpDownInterruptBase("upDown1") {}
 
 bool UpDownInterruptImpl1::init()
 {
+#if defined(INPUTDRIVER_TWO_WAY_ROCKER) && defined(INPUTDRIVER_TWO_WAY_ROCKER_LEFT) && defined(INPUTDRIVER_TWO_WAY_ROCKER_RIGHT)
+    moduleConfig.canned_message.updown1_enabled = true;
+    moduleConfig.canned_message.inputbroker_pin_a = INPUTDRIVER_TWO_WAY_ROCKER_LEFT;
+    moduleConfig.canned_message.inputbroker_pin_b = INPUTDRIVER_TWO_WAY_ROCKER_RIGHT;
+#if defined(INPUTDRIVER_TWO_WAY_ROCKER_BTN)
+    moduleConfig.canned_message.inputbroker_pin_press = INPUTDRIVER_TWO_WAY_ROCKER_BTN;
+#endif
+#endif
 
     if (!moduleConfig.canned_message.updown1_enabled) {
         // Input device is disabled.
@@ -46,4 +54,4 @@ void UpDownInterruptImpl1::handleIntUp()
 void UpDownInterruptImpl1::handleIntPressed()
 {
     upDownInterruptImpl1->intPressHandler();
-}
+}

src/mesh/Default.h

@@ -30,6 +30,11 @@
 #define min_node_info_broadcast_secs 60 * 60 // No regular broadcasts of more than once an hour
 #define min_neighbor_info_broadcast_secs 4 * 60 * 60
 #define default_map_publish_interval_secs 60 * 60
+
+// Traffic management defaults
+#define default_traffic_mgmt_position_precision_bits 24         // ~10m grid cells
+#define default_traffic_mgmt_position_min_interval_secs ONE_DAY // 1 day between identical positions
+
 #ifdef USERPREFS_RINGTONE_NAG_SECS
 #define default_ringtone_nag_secs USERPREFS_RINGTONE_NAG_SECS
 #else

src/mesh/NextHopRouter.cpp

@@ -4,6 +4,9 @@
 #if !MESHTASTIC_EXCLUDE_TRACEROUTE
 #include "modules/TraceRouteModule.h"
 #endif
+#if HAS_TRAFFIC_MANAGEMENT
+#include "modules/TrafficManagementModule.h"
+#endif
 #include "NodeDB.h"
 
 NextHopRouter::NextHopRouter() {}
@@ -126,15 +129,28 @@ void NextHopRouter::sniffReceived(const meshtastic_MeshPacket *p, const meshtast
 /* Check if we should be rebroadcasting this packet if so, do so. */
 bool NextHopRouter::perhapsRebroadcast(const meshtastic_MeshPacket *p)
 {
-    if (!isToUs(p) && !isFromUs(p) && p->hop_limit > 0) {
+    // Check if traffic management wants to exhaust this packet's hops
+    bool exhaustHops = false;
+#if HAS_TRAFFIC_MANAGEMENT
+    if (trafficManagementModule && trafficManagementModule->shouldExhaustHops(*p)) {
+        exhaustHops = true;
+    }
+#endif
+
+    // Allow rebroadcast if hop_limit > 0 OR if we're exhausting hops (which sets hop_limit = 0 but still needs one relay)
+    if (!isToUs(p) && !isFromUs(p) && (p->hop_limit > 0 || exhaustHops)) {
         if (p->id != 0) {
             if (isRebroadcaster()) {
                 if (p->next_hop == NO_NEXT_HOP_PREFERENCE || p->next_hop == nodeDB->getLastByteOfNodeNum(getNodeNum())) {
                     meshtastic_MeshPacket *tosend = packetPool.allocCopy(*p); // keep a copy because we will be sending it
                     LOG_INFO("Rebroadcast received message coming from %x", p->relay_node);
 
-                    // Use shared logic to determine if hop_limit should be decremented
-                    if (shouldDecrementHopLimit(p)) {
+                    // If exhausting hops, force hop_limit = 0 regardless of other logic
+                    if (exhaustHops) {
+                        tosend->hop_limit = 0;
+                        LOG_INFO("Traffic management: exhausting hops for 0x%08x, setting hop_limit=0", getFrom(p));
+                    } else if (shouldDecrementHopLimit(p)) {
+                        // Use shared logic to determine if hop_limit should be decremented
                         tosend->hop_limit--; // bump down the hop count
                     } else {
                         LOG_INFO("favorite-ROUTER/CLIENT_BASE-to-ROUTER/CLIENT_BASE rebroadcast: preserving hop_limit");

src/mesh/PhoneAPI.cpp

@@ -449,6 +449,11 @@ size_t PhoneAPI::getFromRadio(uint8_t *buf)
             fromRadioScratch.moduleConfig.which_payload_variant = meshtastic_ModuleConfig_paxcounter_tag;
             fromRadioScratch.moduleConfig.payload_variant.paxcounter = moduleConfig.paxcounter;
             break;
+        case meshtastic_ModuleConfig_traffic_management_tag:
+            LOG_DEBUG("Send module config: traffic management");
+            fromRadioScratch.moduleConfig.which_payload_variant = meshtastic_ModuleConfig_traffic_management_tag;
+            fromRadioScratch.moduleConfig.payload_variant.traffic_management = moduleConfig.traffic_management;
+            break;
         default:
             LOG_ERROR("Unknown module config type %d", config_state);
         }

src/mesh/Router.cpp

@@ -11,6 +11,9 @@
 #include "mesh-pb-constants.h"
 #include "meshUtils.h"
 #include "modules/RoutingModule.h"
+#if HAS_TRAFFIC_MANAGEMENT
+#include "modules/TrafficManagementModule.h"
+#endif
 #if !MESHTASTIC_EXCLUDE_MQTT
 #include "mqtt/MQTT.h"
 #endif
@@ -95,6 +98,20 @@ bool Router::shouldDecrementHopLimit(const meshtastic_MeshPacket *p)
         return true;
     }
 
+#if HAS_TRAFFIC_MANAGEMENT
+    // When router_preserve_hops is enabled, preserve hops for decoded packets that are not
+    // position or telemetry (those have their own exhaust_hop controls).
+    if (moduleConfig.has_traffic_management && moduleConfig.traffic_management.enabled &&
+        moduleConfig.traffic_management.router_preserve_hops && p->which_payload_variant == meshtastic_MeshPacket_decoded_tag &&
+        p->decoded.portnum != meshtastic_PortNum_POSITION_APP && p->decoded.portnum != meshtastic_PortNum_TELEMETRY_APP) {
+        LOG_DEBUG("Router hop preserved: port=%d from=0x%08x (traffic_management)", p->decoded.portnum, getFrom(p));
+        if (trafficManagementModule) {
+            trafficManagementModule->recordRouterHopPreserved();
+        }
+        return false;
+    }
+#endif
+
     // For subsequent hops, check if previous relay is a favorite router
     // Optimized search for favorite routers with matching last byte
     // Check ordering optimized for IoT devices (cheapest checks first)

src/mesh/mesh-pb-constants.h

@@ -69,6 +69,22 @@ static inline int get_max_num_nodes()
 /// Max number of channels allowed
 #define MAX_NUM_CHANNELS (member_size(meshtastic_ChannelFile, channels) / member_size(meshtastic_ChannelFile, channels[0]))
 
+// Traffic Management module configuration
+// Enable per-variant by defining HAS_TRAFFIC_MANAGEMENT=1 in variant.h
+#ifndef HAS_TRAFFIC_MANAGEMENT
+#define HAS_TRAFFIC_MANAGEMENT 0
+#endif
+
+// Cache size for traffic management (number of nodes to track)
+// Can be overridden per-variant based on available memory
+#ifndef TRAFFIC_MANAGEMENT_CACHE_SIZE
+#if HAS_TRAFFIC_MANAGEMENT
+#define TRAFFIC_MANAGEMENT_CACHE_SIZE 1000
+#else
+#define TRAFFIC_MANAGEMENT_CACHE_SIZE 0
+#endif
+#endif
+
 /// helper function for encoding a record as a protobuf, any failures to encode are fatal and we will panic
 /// returns the encoded packet size
 size_t pb_encode_to_bytes(uint8_t *destbuf, size_t destbufsize, const pb_msgdesc_t *fields, const void *src_struct);
@@ -90,4 +106,4 @@ bool writecb(pb_ostream_t *stream, const uint8_t *buf, size_t count);
  */
 bool is_in_helper(uint32_t n, const uint32_t *array, pb_size_t count);
 
-#define is_in_repeated(name, n) is_in_helper(n, name, name##_count)
+#define is_in_repeated(name, n) is_in_helper(n, name, name##_count)

src/modules/AdminModule.cpp

@@ -1008,6 +1008,11 @@ bool AdminModule::handleSetModuleConfig(const meshtastic_ModuleConfig &c)
         moduleConfig.statusmessage = c.payload_variant.statusmessage;
         shouldReboot = false;
         break;
+    case meshtastic_ModuleConfig_traffic_management_tag:
+        LOG_INFO("Set module config: Traffic Management");
+        moduleConfig.has_traffic_management = true;
+        moduleConfig.traffic_management = c.payload_variant.traffic_management;
+        break;
     }
     saveChanges(SEGMENT_MODULECONFIG, shouldReboot);
     return true;
@@ -1193,6 +1198,11 @@ void AdminModule::handleGetModuleConfig(const meshtastic_MeshPacket &req, const
             res.get_module_config_response.which_payload_variant = meshtastic_ModuleConfig_statusmessage_tag;
             res.get_module_config_response.payload_variant.statusmessage = moduleConfig.statusmessage;
             break;
+        case meshtastic_AdminMessage_ModuleConfigType_TRAFFICMANAGEMENT_CONFIG:
+            LOG_INFO("Get module config: Traffic Management");
+            res.get_module_config_response.which_payload_variant = meshtastic_ModuleConfig_traffic_management_tag;
+            res.get_module_config_response.payload_variant.traffic_management = moduleConfig.traffic_management;
+            break;
         }
 
         // NOTE: The phone app needs to know the ls_secsvalue so it can properly expect sleep behavior.

src/modules/Modules.cpp

@@ -38,6 +38,9 @@
 #include "modules/PowerStressModule.h"
 #endif
 #include "modules/RoutingModule.h"
+#if HAS_TRAFFIC_MANAGEMENT && !MESHTASTIC_EXCLUDE_TRAFFIC_MANAGEMENT
+#include "modules/TrafficManagementModule.h"
+#endif
 #include "modules/TextMessageModule.h"
 #if !MESHTASTIC_EXCLUDE_TRACEROUTE
 #include "modules/TraceRouteModule.h"
@@ -120,6 +123,14 @@ void setupModules()
 #if !MESHTASTIC_EXCLUDE_REPLYBOT
     new ReplyBotModule();
 #endif
+
+#if HAS_TRAFFIC_MANAGEMENT && !MESHTASTIC_EXCLUDE_TRAFFIC_MANAGEMENT
+    // Instantiate only when enabled to avoid extra memory use and background work.
+    if (moduleConfig.has_traffic_management && moduleConfig.traffic_management.enabled) {
+        trafficManagementModule = new TrafficManagementModule();
+    }
+#endif
+
 #if !MESHTASTIC_EXCLUDE_ADMIN
     adminModule = new AdminModule();
 #endif

src/modules/TrafficManagementModule.h

@@ -0,0 +1,434 @@
+#pragma once
+
+#include "MeshModule.h"
+#include "concurrency/Lock.h"
+#include "concurrency/OSThread.h"
+#include "mesh/generated/meshtastic/mesh.pb.h"
+#include "mesh/generated/meshtastic/telemetry.pb.h"
+
+#if HAS_TRAFFIC_MANAGEMENT
+
+/**
+ * TrafficManagementModule - Packet inspection and traffic shaping for mesh networks.
+ *
+ * This module provides:
+ * - Position deduplication (drop redundant position broadcasts)
+ * - Per-node rate limiting (throttle chatty nodes)
+ * - Unknown packet filtering (drop undecoded packets from repeat offenders)
+ * - NodeInfo direct response (answer queries from cache to reduce mesh chatter)
+ * - Local-only telemetry/position (exhaust hop_limit for local broadcasts)
+ * - Router hop preservation (maintain hop_limit for router-to-router traffic)
+ *
+ * Memory Optimization:
+ * Uses a unified cache with cuckoo hashing for O(1) lookups and 56% memory reduction
+ * compared to separate per-feature caches. Timestamps are stored as 8-bit relative
+ * offsets from a rolling epoch to further reduce memory footprint.
+ */
+class TrafficManagementModule : public MeshModule, private concurrency::OSThread
+{
+  public:
+    TrafficManagementModule();
+    ~TrafficManagementModule();
+
+    // Singleton — no copying or moving
+    TrafficManagementModule(const TrafficManagementModule &) = delete;
+    TrafficManagementModule &operator=(const TrafficManagementModule &) = delete;
+
+    meshtastic_TrafficManagementStats getStats() const;
+    void resetStats();
+    void recordRouterHopPreserved();
+
+    /**
+     * Check if this packet should have its hops exhausted.
+     * Called from perhapsRebroadcast() to force hop_limit = 0 regardless of
+     * router_preserve_hops or favorite node logic.
+     */
+    bool shouldExhaustHops(const meshtastic_MeshPacket &mp) const
+    {
+        return exhaustRequested && exhaustRequestedFrom == getFrom(&mp) && exhaustRequestedId == mp.id;
+    }
+
+  protected:
+    ProcessMessage handleReceived(const meshtastic_MeshPacket &mp) override;
+    bool wantPacket(const meshtastic_MeshPacket *p) override { return true; }
+    void alterReceived(meshtastic_MeshPacket &mp) override;
+    int32_t runOnce() override;
+    // Protected so test shims can force epoch rollover behavior.
+    void resetEpoch(uint32_t nowMs);
+
+  private:
+    // =========================================================================
+    // Unified Cache Entry (10 bytes) - Same for ALL platforms
+    // =========================================================================
+    //
+    // A single compact structure used across ESP32, NRF52, and all other platforms.
+    // Memory: 10 bytes × 2048 entries = 20KB
+    //
+    // Position Fingerprinting:
+    //   Instead of storing full coordinates (8 bytes) or a computed hash,
+    //   we store an 8-bit fingerprint derived deterministically from the
+    //   truncated lat/lon. This extracts the lower 4 significant bits from
+    //   each coordinate: fingerprint = (lat_low4 << 4) | lon_low4
+    //
+    //   Benefits over hash:
+    //   - Adjacent grid cells have sequential fingerprints (no collision)
+    //   - Two positions only collide if 16+ grid cells apart in BOTH dimensions
+    //   - Deterministic: same input always produces same output
+    //
+    // Adaptive Timestamp Resolution:
+    //   All timestamps use 8-bit values with adaptive resolution calculated
+    //   from config at startup. Resolution = max(60, min(339, interval/2)).
+    //   - Min 60 seconds ensures reasonable precision
+    //   - Max 339 seconds allows ~24 hour range (255 * 339 = 86445 sec)
+    //   - interval/2 ensures at least 2 ticks per configured interval
+    //
+    // Layout:
+    //   [0-3]   node            - NodeNum (4 bytes)
+    //   [4]     pos_fingerprint - 4 bits lat + 4 bits lon (1 byte)
+    //   [5]     rate_count      - Packets in current window (1 byte)
+    //   [6]     unknown_count   - Unknown packets count (1 byte)
+    //   [7]     pos_time        - Position timestamp (1 byte, adaptive resolution)
+    //   [8]     rate_time       - Rate window start (1 byte, adaptive resolution)
+    //   [9]     unknown_time    - Unknown tracking start (1 byte, adaptive resolution)
+    //
+    struct __attribute__((packed)) UnifiedCacheEntry {
+        NodeNum node;            // 4 bytes - Node identifier (0 = empty slot)
+        uint8_t pos_fingerprint; // 1 byte  - Lower 4 bits of lat + lon
+        uint8_t rate_count;      // 1 byte  - Packet count (saturates at 255)
+        uint8_t unknown_count;   // 1 byte  - Unknown packet count (saturates at 255)
+        uint8_t pos_time;        // 1 byte  - Position timestamp (adaptive resolution)
+        uint8_t rate_time;       // 1 byte  - Rate window start (adaptive resolution)
+        uint8_t unknown_time;    // 1 byte  - Unknown tracking start (adaptive resolution)
+    };
+    static_assert(sizeof(UnifiedCacheEntry) == 10, "UnifiedCacheEntry should be 10 bytes");
+
+    // =========================================================================
+    // Cuckoo Hash Table Implementation
+    // =========================================================================
+    //
+    // Cuckoo hashing provides O(1) worst-case lookup time using two hash functions.
+    // Each key can be in one of two possible locations (h1 or h2). On collision,
+    // the existing entry is "kicked" to its alternate location.
+    //
+    // Benefits over linear scan:
+    // - O(1) lookup vs O(n) - critical at packet processing rates
+    // - O(1) insertion (amortized) with simple eviction on cycles
+    // - ~95% load factor achievable
+    //
+    // Cache size rounds to power-of-2 for fast modulo via bitmask.
+    // TRAFFIC_MANAGEMENT_CACHE_SIZE=2000 → cacheSize()=2048
+    //
+    static constexpr uint16_t cacheSize();
+    static constexpr uint16_t cacheMask();
+
+    // Hash functions for cuckoo hashing
+    inline uint16_t cuckooHash1(NodeNum node) const { return node & cacheMask(); }
+    inline uint16_t cuckooHash2(NodeNum node) const { return ((node * 2654435769u) >> (32 - cuckooHashBits())) & cacheMask(); }
+    static constexpr uint8_t cuckooHashBits();
+
+    // NodeInfo cache configuration (PSRAM path):
+    // - Payload lives in PSRAM
+    // - DRAM keeps packed 12-bit tags with 4-way bucketed cuckoo hashing
+    //   (Fan et al., CoNEXT 2014). Tag value 0 is reserved as "empty".
+    static constexpr uint16_t kNodeInfoIndexMetadataBudgetBytes = 3072; // 3KB DRAM tag store
+    static constexpr uint8_t kNodeInfoTargetOccupancyPercent = 95;
+    static constexpr uint8_t kNodeInfoBucketSize = 4;
+    static constexpr uint8_t kNodeInfoTagBits = 12;
+    static constexpr uint16_t kNodeInfoTagMask = static_cast<uint16_t>((1u << kNodeInfoTagBits) - 1u);
+    static constexpr uint16_t kNodeInfoIndexSlotsRaw =
+        static_cast<uint16_t>((kNodeInfoIndexMetadataBudgetBytes * 8u) / kNodeInfoTagBits);
+    static constexpr uint16_t kNodeInfoIndexSlots =
+        static_cast<uint16_t>(kNodeInfoIndexSlotsRaw - (kNodeInfoIndexSlotsRaw % kNodeInfoBucketSize));
+    static constexpr uint16_t kNodeInfoTargetEntries =
+        static_cast<uint16_t>((kNodeInfoIndexSlots * kNodeInfoTargetOccupancyPercent) / 100u);
+    static_assert((kNodeInfoIndexSlots % kNodeInfoBucketSize) == 0, "NodeInfo slot count must align to bucket size");
+    static_assert(kNodeInfoTargetEntries < (1u << kNodeInfoTagBits), "NodeInfo tag bits must encode payload index");
+
+    static constexpr uint16_t nodeInfoTargetEntries();
+    static constexpr uint16_t nodeInfoIndexMetadataBudgetBytes();
+    static constexpr uint8_t nodeInfoTargetOccupancyPercent();
+    static constexpr uint8_t nodeInfoBucketSize();
+    static constexpr uint8_t nodeInfoTagBits();
+    static constexpr uint16_t nodeInfoTagMask();
+    static constexpr uint16_t nodeInfoIndexSlots();
+    static constexpr uint16_t nodeInfoBucketCount();
+    static constexpr uint16_t nodeInfoBucketMask();
+    static constexpr uint8_t nodeInfoBucketHashBits();
+    inline uint16_t nodeInfoHash1(NodeNum node) const { return node & nodeInfoBucketMask(); }
+    inline uint16_t nodeInfoHash2(NodeNum node) const
+    {
+        return ((node * 2246822519u) >> (32 - nodeInfoBucketHashBits())) & nodeInfoBucketMask();
+    }
+
+    // =========================================================================
+    // Adaptive Timestamp Resolution
+    // =========================================================================
+    //
+    // All timestamps use 8-bit values with adaptive resolution calculated from
+    // config at startup. This allows ~24 hour range while maintaining precision.
+    //
+    // Resolution formula: max(60, min(339, interval/2))
+    //   - 60 sec minimum ensures reasonable precision
+    //   - 339 sec maximum allows 24 hour range (255 * 339 ≈ 86400 sec)
+    //   - interval/2 ensures at least 2 ticks per configured interval
+    //
+    // Since config changes require reboot, resolution is calculated once.
+    //
+    uint32_t cacheEpochMs = 0;
+    uint16_t posTimeResolution = 60;     // Seconds per tick for position
+    uint16_t rateTimeResolution = 60;    // Seconds per tick for rate limiting
+    uint16_t unknownTimeResolution = 60; // Seconds per tick for unknown tracking
+
+    // Calculate resolution from configured interval (called once at startup)
+    static uint16_t calcTimeResolution(uint32_t intervalSecs)
+    {
+        // Resolution = interval/2 to ensure at least 2 ticks per interval
+        // Clamped to [60, 339] for min precision and max 24h range
+        uint32_t res = (intervalSecs > 0) ? (intervalSecs / 2) : 60;
+        if (res < 60)
+            res = 60;
+        if (res > 339)
+            res = 339;
+        return static_cast<uint16_t>(res);
+    }
+
+    // Convert to/from 8-bit relative timestamps with given resolution
+    uint8_t toRelativeTime(uint32_t nowMs, uint16_t resolutionSecs) const
+    {
+        uint32_t ticks = (nowMs - cacheEpochMs) / (resolutionSecs * 1000UL);
+        return (ticks > UINT8_MAX) ? UINT8_MAX : static_cast<uint8_t>(ticks);
+    }
+    uint32_t fromRelativeTime(uint8_t ticks, uint16_t resolutionSecs) const
+    {
+        return cacheEpochMs + (static_cast<uint32_t>(ticks) * resolutionSecs * 1000UL);
+    }
+
+    // Convenience wrappers for each timestamp type
+    uint8_t toRelativePosTime(uint32_t nowMs) const { return toRelativeTime(nowMs, posTimeResolution); }
+    uint32_t fromRelativePosTime(uint8_t t) const { return fromRelativeTime(t, posTimeResolution); }
+
+    uint8_t toRelativeRateTime(uint32_t nowMs) const { return toRelativeTime(nowMs, rateTimeResolution); }
+    uint32_t fromRelativeRateTime(uint8_t t) const { return fromRelativeTime(t, rateTimeResolution); }
+
+    uint8_t toRelativeUnknownTime(uint32_t nowMs) const { return toRelativeTime(nowMs, unknownTimeResolution); }
+    uint32_t fromRelativeUnknownTime(uint8_t t) const { return fromRelativeTime(t, unknownTimeResolution); }
+
+    // Epoch reset when any timestamp approaches overflow
+    // With max resolution of 339 sec, 200 ticks = ~19 hours (safe margin for 24h max)
+    bool needsEpochReset(uint32_t nowMs) const
+    {
+        uint16_t maxRes = posTimeResolution;
+        if (rateTimeResolution > maxRes)
+            maxRes = rateTimeResolution;
+        if (unknownTimeResolution > maxRes)
+            maxRes = unknownTimeResolution;
+        return (nowMs - cacheEpochMs) > (200UL * maxRes * 1000UL);
+    }
+    // =========================================================================
+    // Position Fingerprint
+    // =========================================================================
+    //
+    // Computes 8-bit fingerprint from truncated lat/lon coordinates.
+    // Extracts lower 4 significant bits from each coordinate.
+    //
+    // fingerprint = (lat_low4 << 4) | lon_low4
+    //
+    // Unlike a hash, adjacent grid cells have sequential fingerprints,
+    // so nearby positions never collide. Collisions only occur for
+    // positions 16+ grid cells apart in both dimensions.
+    //
+    // Guards: If precision < 4 bits, uses min(precision, 4) bits.
+    //
+    static uint8_t computePositionFingerprint(int32_t lat_truncated, int32_t lon_truncated, uint8_t precision);
+
+    // =========================================================================
+    // Cache Storage
+    // =========================================================================
+
+    mutable concurrency::Lock cacheLock; // Protects all cache access
+    UnifiedCacheEntry *cache = nullptr;  // Cuckoo hash table (unified for all platforms)
+    bool cacheFromPsram = false;         // Tracks allocator for correct deallocation
+
+    struct NodeInfoPayloadEntry {
+        // Node identifier associated with this payload slot.
+        // 0 means the slot is currently unused.
+        NodeNum node;
+
+        // Cached NODEINFO_APP payload body. This is separate from NodeDB and is only
+        // used by the PSRAM-backed direct-response path in this module.
+        meshtastic_User user;
+
+        // Extra response metadata captured from the latest observed NODEINFO_APP
+        // packet for this node. shouldRespondToNodeInfo() uses this metadata when
+        // building spoofed replies for requesting clients.
+
+        // Last local uptime tick (millis) when this entry was refreshed.
+        uint32_t lastObservedMs;
+
+        // Last RTC/packet timestamp (seconds) observed for this NodeInfo frame.
+        // If unavailable in packet, remains 0.
+        uint32_t lastObservedRxTime;
+
+        // Channel where we most recently heard this node's NodeInfo.
+        uint8_t sourceChannel;
+
+        // Cached decoded bitfield metadata from the source packet.
+        // We preserve non-OK_TO_MQTT bits in direct replies when available.
+        bool hasDecodedBitfield;
+        uint8_t decodedBitfield;
+    };
+
+    NodeInfoPayloadEntry *nodeInfoPayload = nullptr; // NodeInfo payloads in PSRAM
+    bool nodeInfoPayloadFromPsram = false;           // Tracks allocator for correct deallocation
+    uint8_t *nodeInfoIndex = nullptr;                // Packed 12-bit NodeInfo tags in DRAM
+    uint16_t nodeInfoAllocHint = 0;
+    uint16_t nodeInfoEvictCursor = 0;
+
+    meshtastic_TrafficManagementStats stats;
+
+    // Flag set during alterReceived() when packet should be exhausted.
+    // Checked by perhapsRebroadcast() to force hop_limit = 0 only for the
+    // matching packet key (from + id). Reset at start of handleReceived().
+    bool exhaustRequested = false;
+    NodeNum exhaustRequestedFrom = 0;
+    PacketId exhaustRequestedId = 0;
+
+    // =========================================================================
+    // Cache Operations
+    // =========================================================================
+
+    // Find or create entry for node using cuckoo hashing
+    // Returns nullptr if cache is full and eviction fails
+    UnifiedCacheEntry *findOrCreateEntry(NodeNum node, bool *isNew);
+
+    // Find existing entry (no creation)
+    UnifiedCacheEntry *findEntry(NodeNum node);
+
+    // NodeInfo cache operations (bucketed cuckoo index + PSRAM payloads)
+    const NodeInfoPayloadEntry *findNodeInfoEntry(NodeNum node) const;
+    NodeInfoPayloadEntry *findOrCreateNodeInfoEntry(NodeNum node, bool *usedEmptySlot);
+    uint16_t findNodeInfoPayloadIndex(NodeNum node) const;
+    bool removeNodeInfoIndexEntry(NodeNum node, uint16_t payloadIndex);
+    uint16_t allocateNodeInfoPayloadSlot();
+    uint16_t evictNodeInfoPayloadSlot();
+    bool tryInsertNodeInfoEntryInBucket(uint16_t bucket, uint16_t tag);
+    uint16_t encodeNodeInfoTag(uint16_t payloadIndex) const;
+    uint16_t decodeNodeInfoPayloadIndex(uint16_t tag) const;
+    uint16_t getNodeInfoTag(uint16_t slot) const;
+    void setNodeInfoTag(uint16_t slot, uint16_t tag);
+    uint16_t countNodeInfoEntriesLocked() const;
+    void cacheNodeInfoPacket(const meshtastic_MeshPacket &mp);
+
+    // =========================================================================
+    // Traffic Management Logic
+    // =========================================================================
+
+    bool shouldDropPosition(const meshtastic_MeshPacket *p, const meshtastic_Position *pos, uint32_t nowMs);
+    bool shouldRespondToNodeInfo(const meshtastic_MeshPacket *p, bool sendResponse);
+    bool isMinHopsFromRequestor(const meshtastic_MeshPacket *p) const;
+    bool isRateLimited(NodeNum from, uint32_t nowMs);
+    bool shouldDropUnknown(const meshtastic_MeshPacket *p, uint32_t nowMs);
+
+    void logAction(const char *action, const meshtastic_MeshPacket *p, const char *reason) const;
+    void incrementStat(uint32_t *field);
+};
+
+// =========================================================================
+// Compile-time Cache Size Calculations
+// =========================================================================
+//
+// Round TRAFFIC_MANAGEMENT_CACHE_SIZE up to next power of 2 for efficient
+// cuckoo hash indexing (allows bitmask instead of modulo).
+//
+// These use C++11-compatible constexpr (single return statement).
+//
+
+namespace detail
+{
+// Helper: round up to next power of 2 using bit manipulation
+constexpr uint16_t nextPow2(uint16_t n)
+{
+    return n == 0 ? 0 : (((n - 1) | ((n - 1) >> 1) | ((n - 1) >> 2) | ((n - 1) >> 4) | ((n - 1) >> 8)) + 1);
+}
+
+// Helper: floor(log2(n)) for n >= 0, C++11-compatible constexpr.
+constexpr uint8_t log2Floor(uint16_t n)
+{
+    return n <= 1 ? 0 : static_cast<uint8_t>(1 + log2Floor(static_cast<uint16_t>(n >> 1)));
+}
+
+// Helper: ceil(log2(n)) for n >= 1, C++11-compatible constexpr.
+constexpr uint8_t log2Ceil(uint16_t n)
+{
+    return n <= 1 ? 0 : static_cast<uint8_t>(1 + log2Floor(static_cast<uint16_t>(n - 1)));
+}
+} // namespace detail
+
+constexpr uint16_t TrafficManagementModule::cacheSize()
+{
+    return detail::nextPow2(TRAFFIC_MANAGEMENT_CACHE_SIZE);
+}
+
+constexpr uint16_t TrafficManagementModule::cacheMask()
+{
+    return cacheSize() > 0 ? cacheSize() - 1 : 0;
+}
+
+constexpr uint8_t TrafficManagementModule::cuckooHashBits()
+{
+    return detail::log2Floor(cacheSize());
+}
+
+constexpr uint16_t TrafficManagementModule::nodeInfoTargetEntries()
+{
+    return kNodeInfoTargetEntries;
+}
+
+constexpr uint16_t TrafficManagementModule::nodeInfoIndexMetadataBudgetBytes()
+{
+    return kNodeInfoIndexMetadataBudgetBytes;
+}
+
+constexpr uint8_t TrafficManagementModule::nodeInfoTargetOccupancyPercent()
+{
+    return kNodeInfoTargetOccupancyPercent;
+}
+
+constexpr uint8_t TrafficManagementModule::nodeInfoBucketSize()
+{
+    return kNodeInfoBucketSize;
+}
+
+constexpr uint8_t TrafficManagementModule::nodeInfoTagBits()
+{
+    return kNodeInfoTagBits;
+}
+
+constexpr uint16_t TrafficManagementModule::nodeInfoTagMask()
+{
+    return kNodeInfoTagMask;
+}
+
+constexpr uint16_t TrafficManagementModule::nodeInfoIndexSlots()
+{
+    return kNodeInfoIndexSlots;
+}
+
+constexpr uint16_t TrafficManagementModule::nodeInfoBucketCount()
+{
+    return static_cast<uint16_t>(nodeInfoIndexSlots() / nodeInfoBucketSize());
+}
+
+constexpr uint16_t TrafficManagementModule::nodeInfoBucketMask()
+{
+    return nodeInfoBucketCount() > 0 ? nodeInfoBucketCount() - 1 : 0;
+}
+
+constexpr uint8_t TrafficManagementModule::nodeInfoBucketHashBits()
+{
+    return detail::log2Floor(nodeInfoBucketCount());
+}
+
+extern TrafficManagementModule *trafficManagementModule;
+
+#endif

src/sleep.cpp

@@ -429,8 +429,13 @@ esp_sleep_wakeup_cause_t doLightSleep(uint64_t sleepMsec) // FIXME, use a more r
     gpio_num_t pin = (gpio_num_t)(config.device.button_gpio ? config.device.button_gpio : BUTTON_PIN);
     gpio_wakeup_enable(pin, GPIO_INTR_LOW_LEVEL);
 #endif
-#ifdef INPUTDRIVER_ENCODER_BTN
-    gpio_wakeup_enable((gpio_num_t)INPUTDRIVER_ENCODER_BTN, GPIO_INTR_LOW_LEVEL);
+#if defined(INPUTDRIVER_TWO_WAY_ROCKER_BTN) || defined(INPUTDRIVER_ENCODER_BTN)
+#if defined(INPUTDRIVER_TWO_WAY_ROCKER_BTN)
+#define INPUTDRIVER_WAKE_BTN_PIN INPUTDRIVER_TWO_WAY_ROCKER_BTN
+#else
+#define INPUTDRIVER_WAKE_BTN_PIN INPUTDRIVER_ENCODER_BTN
+#endif
+    gpio_wakeup_enable((gpio_num_t)INPUTDRIVER_WAKE_BTN_PIN, GPIO_INTR_LOW_LEVEL);
 #endif
 #if defined(WAKE_ON_TOUCH)
     gpio_wakeup_enable((gpio_num_t)SCREEN_TOUCH_INT, GPIO_INTR_LOW_LEVEL);
@@ -471,8 +476,9 @@ esp_sleep_wakeup_cause_t doLightSleep(uint64_t sleepMsec) // FIXME, use a more r
     // Disable wake-on-button interrupt. Re-attach normal button-interrupts
     gpio_wakeup_disable(pin);
 #endif
-#if defined(INPUTDRIVER_ENCODER_BTN)
-    gpio_wakeup_disable((gpio_num_t)INPUTDRIVER_ENCODER_BTN);
+#ifdef INPUTDRIVER_WAKE_BTN_PIN
+    gpio_wakeup_disable((gpio_num_t)INPUTDRIVER_WAKE_BTN_PIN);
+#undef INPUTDRIVER_WAKE_BTN_PIN
 #endif
 #if defined(WAKE_ON_TOUCH)
     gpio_wakeup_disable((gpio_num_t)SCREEN_TOUCH_INT);

variants/esp32s3/heltec_v4/platformio.ini

@@ -8,6 +8,7 @@ build_flags =
   -D HELTEC_V4
   -D HAS_LORA_FEM=1
   -I variants/esp32s3/heltec_v4
+  -ULED_BUILTIN
 
 
 [env:heltec-v4]

variants/esp32s3/heltec_v4/variant.h

@@ -29,6 +29,14 @@
 #define SX126X_DIO2_AS_RF_SWITCH
 #define SX126X_DIO3_TCXO_VOLTAGE 1.8
 
+// Enable Traffic Management Module for Heltec V4
+#ifndef HAS_TRAFFIC_MANAGEMENT
+#define HAS_TRAFFIC_MANAGEMENT 1
+#endif
+#ifndef TRAFFIC_MANAGEMENT_CACHE_SIZE
+#define TRAFFIC_MANAGEMENT_CACHE_SIZE 2048
+#endif
+
 // ---- GC1109 RF FRONT END CONFIGURATION ----
 // The Heltec V4.2 uses a GC1109 FEM chip with integrated PA and LNA
 // RF path: SX1262 -> Pi attenuator -> GC1109 PA -> Antenna
@@ -89,4 +97,4 @@
 // Seems to be missing on this new board
 #define GPS_TX_PIN (38) // This is for bits going TOWARDS the CPU
 #define GPS_RX_PIN (39) // This is for bits going TOWARDS the GPS
-#define GPS_THREAD_INTERVAL 50
+#define GPS_THREAD_INTERVAL 50

variants/esp32s3/mini-epaper-s3/nicheGraphics.h

@@ -0,0 +1,131 @@
+#pragma once
+
+#include "configuration.h"
+
+#ifdef MESHTASTIC_INCLUDE_NICHE_GRAPHICS
+
+// InkHUD-specific components
+#include "graphics/niche/InkHUD/InkHUD.h"
+
+// Applets
+#include "graphics/niche/InkHUD/Applet.h"
+#include "graphics/niche/InkHUD/Applets/User/AllMessage/AllMessageApplet.h"
+#include "graphics/niche/InkHUD/Applets/User/DM/DMApplet.h"
+#include "graphics/niche/InkHUD/Applets/User/FavoritesMap/FavoritesMapApplet.h"
+#include "graphics/niche/InkHUD/Applets/User/Heard/HeardApplet.h"
+#include "graphics/niche/InkHUD/Applets/User/Positions/PositionsApplet.h"
+#include "graphics/niche/InkHUD/Applets/User/RecentsList/RecentsListApplet.h"
+#include "graphics/niche/InkHUD/Applets/User/ThreadedMessage/ThreadedMessageApplet.h"
+#include "graphics/niche/InkHUD/SystemApplet.h"
+
+// Shared NicheGraphics components
+#include "graphics/niche/Drivers/EInk/GDEW0102T4.h"
+#include "graphics/niche/Inputs/TwoButtonExtended.h"
+
+void setupNicheGraphics()
+{
+    using namespace NicheGraphics;
+
+    // Power-enable the E-Ink panel on this board before any SPI traffic.
+    pinMode(PIN_EINK_EN, OUTPUT);
+    digitalWrite(PIN_EINK_EN, HIGH);
+    delay(10);
+
+    // Display uses HSPI on this board
+    SPIClass *hspi = new SPIClass(HSPI);
+    hspi->begin(PIN_EINK_SCLK, -1, PIN_EINK_MOSI, PIN_EINK_CS);
+
+    Drivers::GDEW0102T4 *displayDriver = new Drivers::GDEW0102T4;
+    displayDriver->begin(hspi, PIN_EINK_DC, PIN_EINK_CS, PIN_EINK_BUSY, PIN_EINK_RES);
+    // Tuned fast-refresh values reg30 reg50 reg82 lutW2 lutB2 = 11 F2 04 11 0D
+    displayDriver->setFastConfig({0x11, 0xF2, 0x04, 0x11, 0x0D});
+    Drivers::EInk *driver = displayDriver;
+
+    InkHUD::InkHUD *inkhud = InkHUD::InkHUD::getInstance();
+    inkhud->setDriver(driver);
+    // Slightly stricter FAST/FULL
+    inkhud->setDisplayResilience(5, 1.5);
+    inkhud->twoWayRocker = true;
+
+    // Fonts
+    InkHUD::Applet::fontLarge = FREESANS_9PT_WIN1252;
+    InkHUD::Applet::fontMedium = FREESANS_6PT_WIN1252;
+    InkHUD::Applet::fontSmall = FREESANS_6PT_WIN1252;
+
+    // Small display defaults
+    inkhud->persistence->settings.rotation = 0;
+    inkhud->persistence->settings.userTiles.maxCount = 1;
+    inkhud->persistence->settings.userTiles.count = 1;
+    inkhud->persistence->settings.joystick.enabled = true;
+    inkhud->persistence->settings.joystick.aligned = true;
+    inkhud->persistence->settings.optionalMenuItems.nextTile = false;
+
+    // Pick applets
+    // Note: order of applets determines priority of "auto-show" feature
+    inkhud->addApplet("All Messages", new InkHUD::AllMessageApplet, false, false);      // -
+    inkhud->addApplet("DMs", new InkHUD::DMApplet, true, false);                        // Activated, not autoshown
+    inkhud->addApplet("Channel 0", new InkHUD::ThreadedMessageApplet(0), true, true);   // Activated, Autoshown
+    inkhud->addApplet("Channel 1", new InkHUD::ThreadedMessageApplet(1), false, false); // -
+    inkhud->addApplet("Positions", new InkHUD::PositionsApplet, true);                  // Activated
+    inkhud->addApplet("Favorites Map", new InkHUD::FavoritesMapApplet, false, false);   // -
+    inkhud->addApplet("Recents List", new InkHUD::RecentsListApplet, false, false);     // -
+    inkhud->addApplet("Heard", new InkHUD::HeardApplet, true, false, 0); // Activated, not autoshown, default on tile 0
+    // Start running InkHUD
+    inkhud->begin();
+
+    // Enforce two-way rocker behavior regardless of persisted settings.
+    inkhud->persistence->settings.joystick.enabled = true;
+    inkhud->persistence->settings.joystick.aligned = true;
+    inkhud->persistence->settings.optionalMenuItems.nextTile = false;
+
+    // Inputs
+    Inputs::TwoButtonExtended *buttons = Inputs::TwoButtonExtended::getInstance();
+
+    // Center press (boot button)
+    buttons->setWiring(0, INPUTDRIVER_TWO_WAY_ROCKER_BTN, true);
+    // Match baseUI encoder long-press feel.
+    buttons->setTiming(0, 75, 300);
+    buttons->setHandlerShortPress(0, [inkhud]() { inkhud->shortpress(); });
+    buttons->setHandlerLongPress(0, [inkhud]() { inkhud->longpress(); });
+
+    // LEFT rocker pin is IO4; RIGHT rocker pin is IO3.
+    buttons->setTwoWayRockerWiring(INPUTDRIVER_TWO_WAY_ROCKER_LEFT, INPUTDRIVER_TWO_WAY_ROCKER_RIGHT, true);
+    buttons->setJoystickDebounce(50);
+
+    // Two-way rocker behavior:
+    // - when a system applet is handling input (menu, tips, etc): LEFT=up, RIGHT=down
+    // - otherwise: LEFT=previous applet, RIGHT=next applet
+    buttons->setTwoWayRockerPressHandlers(
+        [inkhud]() {
+            bool systemHandlingInput = false;
+            for (InkHUD::SystemApplet *sa : inkhud->systemApplets) {
+                if (sa->handleInput) {
+                    systemHandlingInput = true;
+                    break;
+                }
+            }
+
+            if (systemHandlingInput)
+                inkhud->navUp();
+            else
+                inkhud->prevApplet();
+        },
+        [inkhud]() {
+            bool systemHandlingInput = false;
+            for (InkHUD::SystemApplet *sa : inkhud->systemApplets) {
+                if (sa->handleInput) {
+                    systemHandlingInput = true;
+                    break;
+                }
+            }
+
+            if (systemHandlingInput)
+                inkhud->navDown();
+            else
+                inkhud->nextApplet();
+        });
+
+    buttons->start();
+}
+
+#endif

variants/esp32s3/mini-epaper-s3/pins_arduino.h

@@ -3,24 +3,23 @@
 
 #include <stdint.h>
 
-#define USB_VID 0x303a
+#define USB_VID 0x303A
 #define USB_PID 0x1001
 
 // The default Wire will be mapped to PMU and RTC
 static const uint8_t SDA = 18;
 static const uint8_t SCL = 9;
 
-// Default SPI will be mapped to Radio
+// Default SPI (LoRa bus)
 static const uint8_t SS = -1;
 static const uint8_t MOSI = 17;
 static const uint8_t MISO = 6;
 static const uint8_t SCK = 8;
 
+// SD card SPI bus
 #define SPI_MOSI (39)
 #define SPI_SCK (41)
 #define SPI_MISO (38)
 #define SPI_CS (40)
 
-#define SDCARD_CS SPI_CS
-
 #endif /* Pins_Arduino_h */

variants/esp32s3/mini-epaper-s3/platformio.ini

@@ -17,11 +17,15 @@ upload_protocol = esptool
 build_flags = 
   ${esp32s3_base.build_flags}
   -I variants/esp32s3/mini-epaper-s3
-  -DMINI_EPAPER_S3
-  -DUSE_EINK
-  -DEINK_DISPLAY_MODEL=GxEPD2_102
-  -DEINK_WIDTH=128
-  -DEINK_HEIGHT=80
+  -D MINI_EPAPER_S3
+  -D USE_EINK
+  -D EINK_DISPLAY_MODEL=GxEPD2_102
+  -D EINK_WIDTH=128
+  -D EINK_HEIGHT=80
+  -D USE_EINK_DYNAMICDISPLAY
+  -D EINK_LIMIT_FASTREFRESH=3
+  -D EINK_BACKGROUND_USES_FAST
+  -D EINK_HASQUIRK_GHOSTING
 
 lib_deps =
   ${esp32s3_base.lib_deps}
@@ -29,3 +33,22 @@ lib_deps =
   https://github.com/meshtastic/GxEPD2/archive/c7eb4c3c167cf396ef4f541cc5d4c6aa42f3c46b.zip
   # renovate: datasource=custom.pio depName=SensorLib packageName=lewisxhe/library/SensorLib
   lewisxhe/SensorLib@0.3.4
+
+[env:mini-epaper-s3-inkhud]
+extends = esp32s3_base, inkhud
+board = mini-epaper-s3
+board_check = true
+upload_protocol = esptool
+build_src_filter =
+  ${esp32s3_base.build_src_filter}
+  ${inkhud.build_src_filter}
+build_flags =
+  ${esp32s3_base.build_flags}
+  ${inkhud.build_flags}
+  -I variants/esp32s3/mini-epaper-s3
+  -D MINI_EPAPER_S3
+lib_deps =
+  ${inkhud.lib_deps} ; InkHUD libs first, so we get GFXRoot instead of AdafruitGFX
+  ${esp32s3_base.lib_deps}
+  # renovate: datasource=custom.pio depName=SensorLib packageName=lewisxhe/library/SensorLib
+  lewisxhe/SensorLib@0.3.4

variants/esp32s3/mini-epaper-s3/variant.h

@@ -1,46 +1,46 @@
-// Display (E-Ink)
+#pragma once
 
-#define PIN_EINK_CS 13
-#define PIN_EINK_BUSY 10
-#define PIN_EINK_RES 11
-#define PIN_EINK_SCLK 14
-#define PIN_EINK_MOSI 15
-#define PIN_EINK_DC 12
-#define PIN_EINK_EN 42
+#define GPS_DEFAULT_NOT_PRESENT 1
 
-#define SPI_INTERFACES_COUNT 2
-#define PIN_SPI1_MISO -1
-#define PIN_SPI1_MOSI PIN_EINK_MOSI
-#define PIN_SPI1_SCK PIN_EINK_SCLK
-#define DISPLAY_FORCE_SMALL_FONTS
+// SD card (TF)
+#define HAS_SDCARD
+#define SDCARD_USE_SPI1
+#define SDCARD_CS 40
+#define SD_SPI_FREQUENCY 25000000U
 
+// Built-in RTC (I2C)
+#define PCF8563_RTC 0x51
+#define HAS_RTC 1
 #define I2C_SDA SDA
 #define I2C_SCL SCL
 
+// Battery voltage monitoring
 #define BATTERY_PIN 2 // A battery voltage measurement pin, voltage divider connected here to
 // measure battery voltage ratio of voltage divider = 2.0 (assumption)
 #define ADC_MULTIPLIER 2.11 // 2.0 + 10% for correction of display undervoltage.
 #define ADC_CHANNEL ADC1_GPIO2_CHANNEL
 
-#define HAS_GPS 0
-#undef GPS_RX_PIN
-#undef GPS_TX_PIN
+// Display (E-Ink)
+#define PIN_EINK_EN 42
+#define PIN_EINK_CS 13
+#define PIN_EINK_BUSY 10
+#define PIN_EINK_DC 12
+#define PIN_EINK_RES 11
+#define PIN_EINK_SCLK 14
+#define PIN_EINK_MOSI 15
+#define DISPLAY_FORCE_SMALL_FONTS
 
-#define BUTTON_PIN 3
-#define BUTTON_NEED_PULLUP
-#define ALT_BUTTON_PIN 4
-#define ALT_BUTTON_ACTIVE_LOW true
-#define ALT_BUTTON_ACTIVE_PULLUP true
-#define PIN_BUTTON3 0
-
-// #define HAS_SDCARD 1
-// #define SDCARD_USE_SOFT_SPI
-
-// PCF85063 RTC Module
-#define PCF85063_RTC 0x51
-#define HAS_RTC 1
+// Two-Way Rocker input (left/right + boot as press)
+#define INPUTDRIVER_TWO_WAY_ROCKER
+#define INPUTDRIVER_ENCODER_TYPE 2
+#define INPUTDRIVER_TWO_WAY_ROCKER_RIGHT 3
+#define INPUTDRIVER_TWO_WAY_ROCKER_LEFT 4
+#define INPUTDRIVER_TWO_WAY_ROCKER_BTN 0
+#define UPDOWN_LONG_PRESS_REPEAT_INTERVAL 150
 
+// LoRa (SX1262)
 #define USE_SX1262
+
 #define LORA_DIO1 5
 #define LORA_SCK 8
 #define LORA_MISO 6

variants/esp32s3/station-g2/variant.h

@@ -40,6 +40,14 @@ Board Information: https://wiki.uniteng.com/en/meshtastic/station-g2
 #define SX126X_MAX_POWER 19
 #endif
 
+// Enable Traffic Management Module for Station G2
+#ifndef HAS_TRAFFIC_MANAGEMENT
+#define HAS_TRAFFIC_MANAGEMENT 1
+#endif
+#ifndef TRAFFIC_MANAGEMENT_CACHE_SIZE
+#define TRAFFIC_MANAGEMENT_CACHE_SIZE 2048
+#endif
+
 /*
 #define BATTERY_PIN 4 // A battery voltage measurement pin, voltage divider connected here to measure battery voltage
 #define ADC_CHANNEL ADC1_GPIO4_CHANNEL

variants/native/portduino/variant.h

@@ -8,3 +8,11 @@
 
 // RAK12002 RTC Module
 #define RV3028_RTC (uint8_t)0b1010010
+
+// Enable Traffic Management Module for native/portduino
+#ifndef HAS_TRAFFIC_MANAGEMENT
+#define HAS_TRAFFIC_MANAGEMENT 1
+#endif
+#ifndef TRAFFIC_MANAGEMENT_CACHE_SIZE
+#define TRAFFIC_MANAGEMENT_CACHE_SIZE 2048
+#endif

variants/nrf52840/tracker-t1000-e/variant.h

@@ -154,6 +154,15 @@ extern "C" {
 
 #define HAS_SCREEN 0
 
+// Enable Traffic Management Module for testing on T1000-E
+// NRF52840 has 256KB RAM - 1024 entries uses ~10KB
+#ifndef HAS_TRAFFIC_MANAGEMENT
+#define HAS_TRAFFIC_MANAGEMENT 1
+#endif
+#ifndef TRAFFIC_MANAGEMENT_CACHE_SIZE
+#define TRAFFIC_MANAGEMENT_CACHE_SIZE 1024
+#endif
+
 #ifdef __cplusplus
 }
 #endif