From fa18757f2c8a4fd160b903d8ecc982f69e7e018c Mon Sep 17 00:00:00 2001 From: agessaman Date: Wed, 23 Sep 2026 15:43:01 -0700 Subject: [PATCH 01/10] kiss_modem: add AGC reset interval and FEM gain control (protocol v2) Add SetHardware sub-commands so a host can probe and configure per-board RF front-end settings: - GetCapabilities (0x1B): uint32 feature bits (AGC, FEM RX, FEM TX) - Set/GetAgcResetInterval (0x1C/0x1D): 0-1020 s, 4 s resolution, 0 disables; default stays 30 s - Set/GetFemState (0x1E/0x1F): apply/value masks for FEM RX (LNA) and TX (PA) gain; all-or-nothing, Unsupported (0x08) if any requested bit is not controllable on this board The AGC scheduler moves from main.cpp into KissModem so it is configurable and unit-tested. FEM changes that arrive mid-TX are deferred until the packet ends, since board setters drive FEM pins directly. MainBoard gains virtual FEM hooks (canControl/set/is for LNA and PA gain). Boards that already implemented these methods privately now expose them as overrides: Heltec V4, V4 R8, T096, Tracker V2, Station G3 and Wio Tracker L1 1W. KISS_FIRMWARE_VERSION bumped to 2. --- docs/kiss_modem_protocol.md | 70 ++++- examples/kiss_modem/KissModem.cpp | 134 +++++++++ examples/kiss_modem/KissModem.h | 37 ++- examples/kiss_modem/main.cpp | 9 - src/MeshCore.h | 8 + test/mocks/Mesh.h | 7 + test/test_kiss_modem/test_hw_controls.cpp | 278 ++++++++++++++++++ variants/heltec_t096/T096Board.h | 6 +- .../heltec_tracker_v2/HeltecTrackerV2Board.h | 6 +- variants/heltec_v4/HeltecV4Board.h | 6 +- variants/heltec_v4_r8/HeltecV4R8Board.h | 5 +- variants/heltec_v4_r8/LoRaFEMControl.h | 2 +- variants/station_g3_esp32/StationG3Board.h | 10 +- .../wio-tracker-l1-1w/WioTrackerL1Board.h | 6 +- 14 files changed, 553 insertions(+), 31 deletions(-) create mode 100644 test/test_kiss_modem/test_hw_controls.cpp diff --git a/docs/kiss_modem_protocol.md b/docs/kiss_modem_protocol.md index 3f4dbf9c..9b8aaa4b 100644 --- a/docs/kiss_modem_protocol.md +++ b/docs/kiss_modem_protocol.md @@ -118,10 +118,15 @@ MeshCore-specific functionality uses the standard KISS SetHardware command. The | Reboot | `0x18` | - | | SetSignalReport | `0x19` | Enable (1): 0x00=disable, nonzero=enable | | GetSignalReport | `0x1A` | - | +| GetCapabilities | `0x1B` | - | +| SetAgcResetInterval | `0x1C` | Seconds (2): 0=disable, 0-1020 | +| GetAgcResetInterval | `0x1D` | - | +| SetFemState | `0x1E` | Apply mask (1) + Value mask (1) | +| GetFemState | `0x1F` | - | ### Response Sub-commands (TNC to Host) -Response codes use the high-bit convention: `response = command | 0x80`. Generic and unsolicited responses use the `0xF0`+ range. +Response codes use the high-bit convention: `response = command | 0x80`. Generic and unsolicited responses use the `0xF0`+ range. Set commands that report state (SetSignalReport, SetAgcResetInterval, SetFemState) reply with the matching Get response, so `0x9C` and `0x9E` are never sent. | Sub-command | Value | Data | |--------------|--------|-----------------------------------------| @@ -147,6 +152,9 @@ Response codes use the high-bit convention: `response = command | 0x80`. Generic | DeviceName | `0x96` | Name (variable, UTF-8) | | Pong | `0x97` | - | | SignalReport | `0x9A` | Status (1): 0x00=disabled, 0x01=enabled | +| Capabilities | `0x9B` | Feature bits (4) | +| AgcResetInterval | `0x9D` | Effective seconds (2) | +| FemState | `0x9F` | Capability mask (1) + Value mask (1) | | OK | `0xF0` | - | | Error | `0xF1` | Error code (1) | | TxDone | `0xF8` | Result (1): 0x00=failed, 0x01=success | @@ -163,6 +171,7 @@ Response codes use the high-bit convention: `response = command | 0x80`. Generic | UnknownCmd | `0x05` | Unknown sub-command | | EncryptFailed | `0x06` | Encryption failed | | TxBusy | `0x07` | Radio TX busy, or host output queue full | +| Unsupported | `0x08` | Command known, but not supported by this board | ### Unsolicited Events @@ -215,7 +224,64 @@ All values little-endian. |-------------|---------|-----------------------| | Noise floor | 2 bytes | int16_t, dBm (signed) | -The modem recalibrates the noise floor every 2 seconds with an AGC reset every 30 seconds. +The modem recalibrates the noise floor every 2 seconds. AGC resets follow the configured AGC reset interval (default 30 seconds). + +### Capabilities (Capabilities response) + +All values little-endian. Hosts should probe capabilities rather than infer them from the firmware version: boards running the same version expose different hardware controls. Firmware older than version 2 answers GetCapabilities with `UnknownCmd`; treat that as no capabilities. + +| Field | Size | Description | +|--------------|---------|--------------------| +| Feature bits | 4 bytes | uint32_t, see below | + +| Bit | Value | Description | +|-----|--------|-------------------------------------------| +| 0 | `0x01` | AGC reset interval control (always set) | +| 1 | `0x02` | External FEM RX (LNA) gain control | +| 2 | `0x04` | External FEM TX (PA) gain control | + +Remaining bits are reserved and sent as 0. + +### AGC Reset Interval (SetAgcResetInterval / AgcResetInterval response) + +All values little-endian. + +| Field | Size | Description | +|---------|---------|-------------------------------------------| +| Seconds | 2 bytes | uint16_t, 0 = disabled, maximum 1020 | + +The modem periodically resets the radio's AGC while idle (no transmission in progress and host output not backed up). The interval has 4-second resolution, matching the MeshCore `agc.reset.interval` setting: requested values are rounded down to a multiple of 4, so 1-3 disable the reset. Values above 1020 return `InvalidParam`. SetAgcResetInterval replies with the AgcResetInterval response carrying the effective value, and restarts the countdown from the time of the request. + +The default is 30 seconds. The setting is not persisted; hosts should re-send it after reconnecting or rebooting the modem. + +### FEM State (SetFemState / FemState response) + +Controls the board's external LoRa front-end module gain. This is separate from the radio chip's own RX boosted gain. TX/RX switching of the FEM is handled by the board and is not affected by these settings. + +| Bit | Value | Description | +|-----|--------|---------------------------------| +| 0 | `0x01` | RX gain (LNA enabled) | +| 1 | `0x02` | TX gain (PA high gain enabled) | + +SetFemState data: + +| Field | Size | Description | +|------------|--------|------------------------------------------------| +| Apply mask | 1 byte | Bits to change; bits not set are left as-is | +| Value mask | 1 byte | New value for each bit in the apply mask | + +FemState response data: + +| Field | Size | Description | +|-----------------|--------|---------------------------------------------------| +| Capability mask | 1 byte | Bits this board can control | +| Value mask | 1 byte | Current state; always 0 for uncontrollable bits | + +Example: enable RX gain without changing TX gain: apply `0x01`, value `0x01`. + +If any bit in the apply mask is not in the board's capability mask (including reserved bits), the modem replies `Unsupported` and changes nothing. On success, SetFemState replies with the FemState response carrying the new state. A request received while a packet is on air is applied as soon as that transmission ends, and the FemState response is sent then; a second request during the same transmission returns `TxBusy`. Capabilities come from the board, so a board with a fixed, board-managed FEM (for example RAK3401) reports none. + +The setting is not persisted; the board's power-on default applies after reboot. ### Stats (Stats response) diff --git a/examples/kiss_modem/KissModem.cpp b/examples/kiss_modem/KissModem.cpp index 7dcfc8d7..5b61e83c 100644 --- a/examples/kiss_modem/KissModem.cpp +++ b/examples/kiss_modem/KissModem.cpp @@ -22,6 +22,11 @@ KissModem::KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& r _getStatsCallback = nullptr; _config = {0, 0, 0, 0, 0}; _signal_report_enabled = true; + _agc_reset_interval_sec = KISS_AGC_RESET_DEFAULT_SEC; + _next_agc_reset_ms = 0; + _fem_deferred = false; + _fem_deferred_apply = 0; + _fem_deferred_value = 0; resetOutputQueue(); } @@ -31,6 +36,8 @@ void KissModem::begin() { _rx_active = false; _has_pending_tx = false; _tx_state = TX_IDLE; + _fem_deferred = false; + _next_agc_reset_ms = millis() + (uint32_t)_agc_reset_interval_sec * 1000; resetOutputQueue(); } @@ -240,10 +247,24 @@ void KissModem::loop() { } processTx(); + processDeferredFem(); + maybeResetAgc(); tryFlushFrames(); queuePendingBusyError(); } +void KissModem::maybeResetAgc() { + if (_agc_reset_interval_sec == 0) return; + // same guard as the RX path in main.cpp, so receive is restarted right after the reset + if (_tx_state != TX_IDLE || isHostOutputBackedUp()) return; + + uint32_t now = millis(); + if ((int32_t)(now - _next_agc_reset_ms) >= 0) { + _radio.resetAGC(); + _next_agc_reset_ms = now + (uint32_t)_agc_reset_interval_sec * 1000; + } +} + void KissModem::processFrame() { if (_rx_len < 1) return; @@ -381,6 +402,21 @@ void KissModem::handleHardwareCommand(uint8_t sub_cmd, const uint8_t* data, uint case HW_CMD_GET_SIGNAL_REPORT: handleGetSignalReport(); break; + case HW_CMD_GET_CAPABILITIES: + handleGetCapabilities(); + break; + case HW_CMD_SET_AGC_RESET_INTERVAL: + handleSetAgcResetInterval(data, len); + break; + case HW_CMD_GET_AGC_RESET_INTERVAL: + handleGetAgcResetInterval(); + break; + case HW_CMD_SET_FEM_STATE: + handleSetFemState(data, len); + break; + case HW_CMD_GET_FEM_STATE: + handleGetFemState(); + break; default: writeHardwareError(HW_ERR_UNKNOWN_CMD); break; @@ -732,3 +768,101 @@ void KissModem::handleGetSignalReport() { uint8_t val = _signal_report_enabled ? 0x01 : 0x00; writeHardwareFrame(HW_RESP(HW_CMD_GET_SIGNAL_REPORT), &val, 1); } + +void KissModem::handleGetCapabilities() { + uint32_t caps = HW_CAP_AGC_RESET; + if (_board.canControlLoRaFemLna()) caps |= HW_CAP_FEM_RX_GAIN; + if (_board.canControlLoRaFemPaGain()) caps |= HW_CAP_FEM_TX_GAIN; + uint8_t buf[4] = { (uint8_t)caps, (uint8_t)(caps >> 8), (uint8_t)(caps >> 16), (uint8_t)(caps >> 24) }; + writeHardwareFrame(HW_RESP(HW_CMD_GET_CAPABILITIES), buf, 4); +} + +void KissModem::handleSetAgcResetInterval(const uint8_t* data, uint16_t len) { + if (len < 2) { + writeHardwareError(HW_ERR_INVALID_LENGTH); + return; + } + uint16_t secs = (uint16_t)(data[0] | (data[1] << 8)); + if (secs > KISS_AGC_RESET_MAX_SEC) { + writeHardwareError(HW_ERR_INVALID_PARAM); + return; + } + _agc_reset_interval_sec = secs - (secs % KISS_AGC_RESET_STEP_SEC); + _next_agc_reset_ms = millis() + (uint32_t)_agc_reset_interval_sec * 1000; + handleGetAgcResetInterval(); +} + +void KissModem::handleGetAgcResetInterval() { + uint8_t buf[2] = { (uint8_t)_agc_reset_interval_sec, (uint8_t)(_agc_reset_interval_sec >> 8) }; + writeHardwareFrame(HW_RESP(HW_CMD_GET_AGC_RESET_INTERVAL), buf, 2); +} + +uint8_t KissModem::femCapabilityMask() const { + uint8_t mask = 0; + if (_board.canControlLoRaFemLna()) mask |= HW_FEM_RX_GAIN; + if (_board.canControlLoRaFemPaGain()) mask |= HW_FEM_TX_GAIN; + return mask; +} + +uint8_t KissModem::femValueMask() const { + uint8_t mask = 0; + if (_board.canControlLoRaFemLna() && _board.isLoRaFemLnaEnabled()) mask |= HW_FEM_RX_GAIN; + if (_board.canControlLoRaFemPaGain() && _board.isLoRaFemPaGainEnabled()) mask |= HW_FEM_TX_GAIN; + return mask; +} + +void KissModem::writeFemState() { + uint8_t buf[2] = { femCapabilityMask(), femValueMask() }; + writeHardwareFrame(HW_RESP(HW_CMD_GET_FEM_STATE), buf, 2); +} + +void KissModem::applyFemState(uint8_t apply_mask, uint8_t value_mask) { + bool ok = true; + if (apply_mask & HW_FEM_RX_GAIN) { + ok &= _board.setLoRaFemLnaEnabled((value_mask & HW_FEM_RX_GAIN) != 0); + } + if (apply_mask & HW_FEM_TX_GAIN) { + ok &= _board.setLoRaFemPaGainEnabled((value_mask & HW_FEM_TX_GAIN) != 0); + } + if (ok) { + writeFemState(); + } else { + writeHardwareError(HW_ERR_UNSUPPORTED); + } +} + +void KissModem::processDeferredFem() { + if (!_fem_deferred || _tx_state == TX_SENDING) return; + _fem_deferred = false; + applyFemState(_fem_deferred_apply, _fem_deferred_value); +} + +void KissModem::handleSetFemState(const uint8_t* data, uint16_t len) { + if (len < 2) { + writeHardwareError(HW_ERR_INVALID_LENGTH); + return; + } + uint8_t apply_mask = data[0]; + uint8_t value_mask = data[1]; + // validate every requested bit before touching hardware so a request is all-or-nothing + if (apply_mask & ~femCapabilityMask()) { + writeHardwareError(HW_ERR_UNSUPPORTED); + return; + } + if (_tx_state == TX_SENDING) { + // board setters drive FEM pins directly; changing them mid-packet would corrupt the TX + if (_fem_deferred) { + writeHardwareError(HW_ERR_TX_BUSY); + return; + } + _fem_deferred = true; + _fem_deferred_apply = apply_mask; + _fem_deferred_value = value_mask; + return; + } + applyFemState(apply_mask, value_mask); +} + +void KissModem::handleGetFemState() { + writeFemState(); +} diff --git a/examples/kiss_modem/KissModem.h b/examples/kiss_modem/KissModem.h index a23e459b..751fb336 100644 --- a/examples/kiss_modem/KissModem.h +++ b/examples/kiss_modem/KissModem.h @@ -62,6 +62,11 @@ #define HW_CMD_REBOOT 0x18 #define HW_CMD_SET_SIGNAL_REPORT 0x19 #define HW_CMD_GET_SIGNAL_REPORT 0x1A +#define HW_CMD_GET_CAPABILITIES 0x1B +#define HW_CMD_SET_AGC_RESET_INTERVAL 0x1C +#define HW_CMD_GET_AGC_RESET_INTERVAL 0x1D +#define HW_CMD_SET_FEM_STATE 0x1E +#define HW_CMD_GET_FEM_STATE 0x1F /* Response code = command code | 0x80. Generic / unsolicited use 0xF0+. */ #define HW_RESP(cmd) ((cmd) | 0x80) @@ -81,8 +86,22 @@ #define HW_ERR_UNKNOWN_CMD 0x05 #define HW_ERR_ENCRYPT_FAILED 0x06 #define HW_ERR_TX_BUSY 0x07 +#define HW_ERR_UNSUPPORTED 0x08 -#define KISS_FIRMWARE_VERSION 1 +/* GetCapabilities feature bits */ +#define HW_CAP_AGC_RESET (1UL << 0) +#define HW_CAP_FEM_RX_GAIN (1UL << 1) +#define HW_CAP_FEM_TX_GAIN (1UL << 2) + +/* SetFemState / GetFemState mask bits */ +#define HW_FEM_RX_GAIN (1 << 0) +#define HW_FEM_TX_GAIN (1 << 1) + +#define KISS_AGC_RESET_DEFAULT_SEC 30 +#define KISS_AGC_RESET_MAX_SEC 1020 +#define KISS_AGC_RESET_STEP_SEC 4 + +#define KISS_FIRMWARE_VERSION 2 typedef void (*SetRadioCallback)(float freq, float bw, uint8_t sf, uint8_t cr); typedef void (*SetTxPowerCallback)(uint8_t power); @@ -139,6 +158,11 @@ class KissModem { RadioConfig _config; bool _signal_report_enabled; + uint16_t _agc_reset_interval_sec; + uint32_t _next_agc_reset_ms; + bool _fem_deferred; + uint8_t _fem_deferred_apply; + uint8_t _fem_deferred_value; uint8_t _tx_frame_buf[KISS_TX_FRAME_QUEUE_DEPTH][KISS_MAX_ENCODED_FRAME_SIZE]; uint16_t _tx_frame_len[KISS_TX_FRAME_QUEUE_DEPTH]; uint16_t _tx_frame_written[KISS_TX_FRAME_QUEUE_DEPTH]; @@ -165,6 +189,12 @@ class KissModem { void processFrame(); void handleHardwareCommand(uint8_t sub_cmd, const uint8_t* data, uint16_t len); void processTx(); + void maybeResetAgc(); + uint8_t femCapabilityMask() const; + uint8_t femValueMask() const; + void writeFemState(); + void applyFemState(uint8_t apply_mask, uint8_t value_mask); + void processDeferredFem(); void handleGetIdentity(); void handleGetRandom(const uint8_t* data, uint16_t len); @@ -192,6 +222,11 @@ class KissModem { void handleGetDeviceName(); void handleSetSignalReport(const uint8_t* data, uint16_t len); void handleGetSignalReport(); + void handleGetCapabilities(); + void handleSetAgcResetInterval(const uint8_t* data, uint16_t len); + void handleGetAgcResetInterval(); + void handleSetFemState(const uint8_t* data, uint16_t len); + void handleGetFemState(); public: KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& rng, diff --git a/examples/kiss_modem/main.cpp b/examples/kiss_modem/main.cpp index 44b2a3df..8835418d 100644 --- a/examples/kiss_modem/main.cpp +++ b/examples/kiss_modem/main.cpp @@ -19,7 +19,6 @@ #endif #define NOISE_FLOOR_CALIB_INTERVAL_MS 2000 -#define AGC_RESET_INTERVAL_MS 30000 #define USB_TX_TIMEOUT_MS 50 #define USB_TX_BUFFER_SIZE 1024 @@ -27,7 +26,6 @@ StdRNG rng; mesh::LocalIdentity identity; KissModem* modem; static uint32_t next_noise_floor_calib_ms = 0; -static uint32_t next_agc_reset_ms = 0; void halt() { while (1) ; @@ -133,13 +131,6 @@ void loop() { modem->loop(); if (!modem->isActuallyTransmitting() && !modem->isHostOutputBackedUp()) { - if (!modem->isTxBusy()) { - if ((uint32_t)(millis() - next_agc_reset_ms) >= AGC_RESET_INTERVAL_MS) { - radio_driver.resetAGC(); - next_agc_reset_ms = millis(); - } - } - uint8_t rx_buf[256]; int rx_len = radio_driver.recvRaw(rx_buf, sizeof(rx_buf)); if (rx_len > 0) { diff --git a/src/MeshCore.h b/src/MeshCore.h index 2a3582de..5fdb064c 100644 --- a/src/MeshCore.h +++ b/src/MeshCore.h @@ -77,6 +77,14 @@ public: virtual bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) { return false; } + // External LoRa front-end (FEM) gain control. Boards without a controllable FEM keep these defaults. + virtual bool canControlLoRaFemLna() const { return false; } + virtual bool setLoRaFemLnaEnabled(bool enable) { return false; } + virtual bool isLoRaFemLnaEnabled() const { return false; } + virtual bool canControlLoRaFemPaGain() const { return false; } + virtual bool setLoRaFemPaGainEnabled(bool enable) { return false; } + virtual bool isLoRaFemPaGainEnabled() const { return false; } + // Called from the example main loops. Lets a board feed its watchdog and // run periodic housekeeping. Default no-op. virtual void loop() { /* no op */ } diff --git a/test/mocks/Mesh.h b/test/mocks/Mesh.h index b6c263c1..29a29b82 100644 --- a/test/mocks/Mesh.h +++ b/test/mocks/Mesh.h @@ -13,6 +13,7 @@ public: virtual bool isSendComplete() { return true; } virtual void onSendFinished() {} virtual int16_t getNoiseFloor() { return -120; } + virtual void resetAGC() {} }; class MainBoard { @@ -22,6 +23,12 @@ public: virtual float getMCUTemperature() { return 25.0f; } virtual const char* getManufacturerName() { return "mock-board"; } virtual void reboot() {} + virtual bool canControlLoRaFemLna() const { return false; } + virtual bool setLoRaFemLnaEnabled(bool) { return false; } + virtual bool isLoRaFemLnaEnabled() const { return false; } + virtual bool canControlLoRaFemPaGain() const { return false; } + virtual bool setLoRaFemPaGainEnabled(bool) { return false; } + virtual bool isLoRaFemPaGainEnabled() const { return false; } }; } diff --git a/test/test_kiss_modem/test_hw_controls.cpp b/test/test_kiss_modem/test_hw_controls.cpp new file mode 100644 index 00000000..ad6f1e36 --- /dev/null +++ b/test/test_kiss_modem/test_hw_controls.cpp @@ -0,0 +1,278 @@ +#include + +#include +#include + +#include "KissModem.h" + +namespace { + +class RecordingStream : public Stream { +public: + void pushRx(const std::vector& bytes) { + for (uint8_t b : bytes) _rx.push(b); + } + + int availableForWrite() override { return 4096; } + size_t write(const uint8_t* buffer, size_t size) override { + _writes.insert(_writes.end(), buffer, buffer + size); + return size; + } + size_t write(uint8_t b) override { return write(&b, 1); } + int available() override { return (int)_rx.size(); } + int read() override { + if (_rx.empty()) return -1; + int b = _rx.front(); + _rx.pop(); + return b; + } + + // Decoded SetHardware payloads (sub-command + data), consumed on read. + std::vector> takeHardwareFrames() { + std::vector> frames; + std::vector cur; + bool in_frame = false, esc = false; + for (uint8_t b : _writes) { + if (b == KISS_FEND) { + if (in_frame && cur.size() > 1 && cur[0] == KISS_CMD_SETHARDWARE) { + frames.emplace_back(cur.begin() + 1, cur.end()); + } + cur.clear(); + in_frame = true; + continue; + } + if (b == KISS_FESC) { esc = true; continue; } + if (esc) { b = (b == KISS_TFEND) ? KISS_FEND : KISS_FESC; esc = false; } + cur.push_back(b); + } + _writes.clear(); + return frames; + } + +private: + std::queue _rx; + std::vector _writes; +}; + +class ZeroRNG : public mesh::RNG { +public: + void random(uint8_t* dest, size_t sz) override { memset(dest, 0, sz); } +}; + +class AgcRadio : public mesh::Radio { +public: + bool startSendRaw(const uint8_t*, uint16_t) override { return true; } + bool isSendComplete() override { return send_complete; } + void resetAGC() override { agc_resets++; } + + bool send_complete = true; + int agc_resets = 0; +}; + +class FemBoard : public mesh::MainBoard { +public: + const char* getManufacturerName() override { return "fem-board"; } + + bool canControlLoRaFemLna() const override { return has_lna; } + bool setLoRaFemLnaEnabled(bool enable) override { + if (!has_lna) return false; + lna = enable; + lna_sets++; + return true; + } + bool isLoRaFemLnaEnabled() const override { return lna; } + + bool canControlLoRaFemPaGain() const override { return has_pa; } + bool setLoRaFemPaGainEnabled(bool enable) override { + if (!has_pa) return false; + pa = enable; + pa_sets++; + return true; + } + bool isLoRaFemPaGainEnabled() const override { return pa; } + + bool has_lna = false, has_pa = false; + bool lna = false, pa = false; + int lna_sets = 0, pa_sets = 0; +}; + +class NoSensors : public SensorManager { +public: + bool querySensors(uint8_t, CayenneLPP&) override { return false; } +}; + +class KissHwControlTest : public ::testing::Test { +protected: + RecordingStream serial; + mesh::LocalIdentity identity; + ZeroRNG rng; + AgcRadio radio; + FemBoard board; + NoSensors sensors; + KissModem modem; + + KissHwControlTest() : modem(serial, identity, rng, radio, board, sensors) { + g_mock_millis = 1000; + modem.begin(); + } + + std::vector> hw(const std::vector& payload) { + std::vector frame = {KISS_FEND, KISS_CMD_SETHARDWARE}; + frame.insert(frame.end(), payload.begin(), payload.end()); + frame.push_back(KISS_FEND); + serial.pushRx(frame); + modem.loop(); + return serial.takeHardwareFrames(); + } + + std::vector hw1(const std::vector& payload) { + auto frames = hw(payload); + EXPECT_EQ(frames.size(), 1U); + return frames.empty() ? std::vector{} : frames[0]; + } + + void advance(uint32_t ms) { + g_mock_millis += ms; + modem.loop(); + } + + void startTxAndHold() { + radio.send_complete = false; + serial.pushRx({KISS_FEND, KISS_CMD_DATA, 0x42, KISS_FEND}); + modem.loop(); + modem.loop(); + advance((uint32_t)KISS_DEFAULT_TXDELAY * 10); + ASSERT_TRUE(modem.isActuallyTransmitting()); + } +}; + +const std::vector ERR_UNSUPPORTED = {HW_RESP_ERROR, HW_ERR_UNSUPPORTED}; + +TEST_F(KissHwControlTest, VersionIsTwo) { + EXPECT_EQ(hw1({HW_CMD_GET_VERSION}), (std::vector{HW_RESP(HW_CMD_GET_VERSION), 2, 0})); +} + +TEST_F(KissHwControlTest, CapabilitiesOnBareBoardAreAgcOnly) { + EXPECT_EQ(hw1({HW_CMD_GET_CAPABILITIES}), (std::vector{0x9B, 0x01, 0x00, 0x00, 0x00})); +} + +TEST_F(KissHwControlTest, CapabilitiesReflectBoardFem) { + board.has_lna = true; + EXPECT_EQ(hw1({HW_CMD_GET_CAPABILITIES}), (std::vector{0x9B, 0x03, 0x00, 0x00, 0x00})); + board.has_pa = true; + EXPECT_EQ(hw1({HW_CMD_GET_CAPABILITIES}), (std::vector{0x9B, 0x07, 0x00, 0x00, 0x00})); +} + +TEST_F(KissHwControlTest, AgcIntervalDefaultsToThirtySeconds) { + EXPECT_EQ(hw1({HW_CMD_GET_AGC_RESET_INTERVAL}), (std::vector{0x9D, 30, 0})); +} + +TEST_F(KissHwControlTest, AgcIntervalSetReturnsEffectiveRoundedValue) { + EXPECT_EQ(hw1({HW_CMD_SET_AGC_RESET_INTERVAL, 10, 0}), (std::vector{0x9D, 8, 0})); + EXPECT_EQ(hw1({HW_CMD_SET_AGC_RESET_INTERVAL, 4, 0}), (std::vector{0x9D, 4, 0})); + EXPECT_EQ(hw1({HW_CMD_SET_AGC_RESET_INTERVAL, 0xFC, 0x03}), (std::vector{0x9D, 0xFC, 0x03})); + EXPECT_EQ(hw1({HW_CMD_SET_AGC_RESET_INTERVAL, 0, 0}), (std::vector{0x9D, 0, 0})); + EXPECT_EQ(hw1({HW_CMD_GET_AGC_RESET_INTERVAL}), (std::vector{0x9D, 0, 0})); +} + +TEST_F(KissHwControlTest, AgcIntervalRejectsOutOfRangeAndShortPayload) { + EXPECT_EQ(hw1({HW_CMD_SET_AGC_RESET_INTERVAL, 0xFD, 0x03}), (std::vector{HW_RESP_ERROR, HW_ERR_INVALID_PARAM})); + EXPECT_EQ(hw1({HW_CMD_SET_AGC_RESET_INTERVAL, 4}), (std::vector{HW_RESP_ERROR, HW_ERR_INVALID_LENGTH})); + EXPECT_EQ(hw1({HW_CMD_GET_AGC_RESET_INTERVAL}), (std::vector{0x9D, 30, 0})); +} + +TEST_F(KissHwControlTest, AgcResetsOnDefaultSchedule) { + advance(29999); + EXPECT_EQ(radio.agc_resets, 0); + advance(1); + EXPECT_EQ(radio.agc_resets, 1); + advance(29999); + EXPECT_EQ(radio.agc_resets, 1); + advance(1); + EXPECT_EQ(radio.agc_resets, 2); +} + +TEST_F(KissHwControlTest, AgcZeroDisablesResets) { + hw({HW_CMD_SET_AGC_RESET_INTERVAL, 0, 0}); + for (int i = 0; i < 10; i++) advance(60000); + EXPECT_EQ(radio.agc_resets, 0); +} + +TEST_F(KissHwControlTest, AgcIntervalChangeRestartsDeadline) { + hw({HW_CMD_SET_AGC_RESET_INTERVAL, 0x2C, 0x01}); // 300 s + advance(100000); + hw({HW_CMD_SET_AGC_RESET_INTERVAL, 4, 0}); + EXPECT_EQ(radio.agc_resets, 0); + advance(3999); + EXPECT_EQ(radio.agc_resets, 0); + advance(1); + EXPECT_EQ(radio.agc_resets, 1); +} + +TEST_F(KissHwControlTest, AgcResetWaitsForTxToFinish) { + hw({HW_CMD_SET_AGC_RESET_INTERVAL, 4, 0}); + startTxAndHold(); + advance(10000); + EXPECT_EQ(radio.agc_resets, 0); + radio.send_complete = true; + modem.loop(); // TX done -> TX_DONE_PENDING + modem.loop(); // TxDone flushed -> idle, overdue reset runs + EXPECT_EQ(radio.agc_resets, 1); +} + +TEST_F(KissHwControlTest, FemUnsupportedOnBareBoard) { + EXPECT_EQ(hw1({HW_CMD_GET_FEM_STATE}), (std::vector{0x9F, 0x00, 0x00})); + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN}), ERR_UNSUPPORTED); + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_TX_GAIN, 0}), ERR_UNSUPPORTED); +} + +TEST_F(KissHwControlTest, FemSetRxLeavesTxUntouched) { + board.has_lna = board.has_pa = true; + board.pa = true; + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN}), (std::vector{0x9F, 0x03, 0x03})); + EXPECT_TRUE(board.lna); + EXPECT_EQ(board.pa_sets, 0); + + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_TX_GAIN, 0}), (std::vector{0x9F, 0x03, 0x01})); + EXPECT_FALSE(board.pa); + EXPECT_EQ(board.lna_sets, 1); +} + +TEST_F(KissHwControlTest, FemPartialCapabilityRejectsWholeRequest) { + board.has_lna = true; + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN | HW_FEM_TX_GAIN, HW_FEM_RX_GAIN | HW_FEM_TX_GAIN}), ERR_UNSUPPORTED); + EXPECT_EQ(board.lna_sets, 0); + EXPECT_EQ(hw1({HW_CMD_GET_FEM_STATE}), (std::vector{0x9F, 0x01, 0x00})); +} + +TEST_F(KissHwControlTest, FemUnknownBitsAreUnsupported) { + board.has_lna = board.has_pa = true; + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, 0x04, 0x04}), ERR_UNSUPPORTED); +} + +TEST_F(KissHwControlTest, FemShortPayloadIsInvalidLength) { + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN}), (std::vector{HW_RESP_ERROR, HW_ERR_INVALID_LENGTH})); +} + +TEST_F(KissHwControlTest, FemSetDuringTxIsDeferredUntilTxCompletes) { + board.has_lna = true; + startTxAndHold(); + serial.takeHardwareFrames(); + + EXPECT_TRUE(hw({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN}).empty()); + EXPECT_EQ(board.lna_sets, 0); + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, 0}), (std::vector{HW_RESP_ERROR, HW_ERR_TX_BUSY})); + + radio.send_complete = true; + modem.loop(); + auto frames = serial.takeHardwareFrames(); + ASSERT_EQ(frames.size(), 1U); + EXPECT_EQ(frames[0], (std::vector{0x9F, 0x01, 0x01})); + EXPECT_TRUE(board.lna); + modem.loop(); + frames = serial.takeHardwareFrames(); + ASSERT_EQ(frames.size(), 1U); + EXPECT_EQ(frames[0], (std::vector{HW_RESP_TX_DONE, 0x01})); +} + +} // namespace diff --git a/variants/heltec_t096/T096Board.h b/variants/heltec_t096/T096Board.h index e926c8a6..66fa5047 100644 --- a/variants/heltec_t096/T096Board.h +++ b/variants/heltec_t096/T096Board.h @@ -16,9 +16,6 @@ protected: #endif void variant_shutdown(); - bool setLoRaFemLnaEnabled(bool enable); - bool isLoRaFemLnaEnabled() const; - public: RefCountedDigitalPin periph_power; LoRaFEMControl loRaFEMControl; @@ -27,6 +24,9 @@ public: void begin(); void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; + bool canControlLoRaFemLna() const override { return loRaFEMControl.isLnaCanControl(); } + bool setLoRaFemLnaEnabled(bool enable) override; + bool isLoRaFemLnaEnabled() const override; void onBeforeTransmit(void) override; void onAfterTransmit(void) override; diff --git a/variants/heltec_tracker_v2/HeltecTrackerV2Board.h b/variants/heltec_tracker_v2/HeltecTrackerV2Board.h index 5fed2b65..34454cac 100644 --- a/variants/heltec_tracker_v2/HeltecTrackerV2Board.h +++ b/variants/heltec_tracker_v2/HeltecTrackerV2Board.h @@ -8,9 +8,6 @@ class HeltecTrackerV2Board : public ESP32Board { KeyValueStore* _prefs = NULL; - bool setLoRaFemLnaEnabled(bool enable); - bool isLoRaFemLnaEnabled() const; - public: RefCountedDigitalPin periph_power; LoRaFEMControl loRaFEMControl; @@ -20,6 +17,9 @@ public: void begin(); void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; + bool canControlLoRaFemLna() const override { return loRaFEMControl.isLnaCanControl(); } + bool setLoRaFemLnaEnabled(bool enable) override; + bool isLoRaFemLnaEnabled() const override; void onBeforeTransmit(void) override; void onAfterTransmit(void) override; diff --git a/variants/heltec_v4/HeltecV4Board.h b/variants/heltec_v4/HeltecV4Board.h index 79a690e8..bd3bdb25 100644 --- a/variants/heltec_v4/HeltecV4Board.h +++ b/variants/heltec_v4/HeltecV4Board.h @@ -12,9 +12,6 @@ class HeltecV4Board : public ESP32Board { KeyValueStore* _prefs = NULL; - bool setLoRaFemLnaEnabled(bool enable); - bool isLoRaFemLnaEnabled() const; - protected: float adc_mult = ADC_MULTIPLIER; @@ -26,6 +23,9 @@ public: void begin(); void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; + bool canControlLoRaFemLna() const override { return loRaFEMControl.isLnaCanControl(); } + bool setLoRaFemLnaEnabled(bool enable) override; + bool isLoRaFemLnaEnabled() const override; void onBeforeTransmit(void) override; void onAfterTransmit(void) override; diff --git a/variants/heltec_v4_r8/HeltecV4R8Board.h b/variants/heltec_v4_r8/HeltecV4R8Board.h index 7ab29f96..c34ee449 100644 --- a/variants/heltec_v4_r8/HeltecV4R8Board.h +++ b/variants/heltec_v4_r8/HeltecV4R8Board.h @@ -13,8 +13,6 @@ class HeltecV4R8Board : public ESP32Board { KeyValueStore* _prefs = NULL; - bool setLoRaFemLnaEnabled(bool enable); - bool isLoRaFemLnaEnabled() const; protected: float adc_mult = ADC_MULTIPLIER; @@ -27,6 +25,9 @@ public: void begin(); void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; + bool canControlLoRaFemLna() const override { return loRaFEMControl.isLnaCanControl(); } + bool setLoRaFemLnaEnabled(bool enable) override; + bool isLoRaFemLnaEnabled() const override; void onBeforeTransmit(void) override; void onAfterTransmit(void) override; diff --git a/variants/heltec_v4_r8/LoRaFEMControl.h b/variants/heltec_v4_r8/LoRaFEMControl.h index 4b74c2e2..52d7a0f8 100644 --- a/variants/heltec_v4_r8/LoRaFEMControl.h +++ b/variants/heltec_v4_r8/LoRaFEMControl.h @@ -15,7 +15,7 @@ public: void setRxModeEnable(void); void setRxModeEnableWhenMCUSleep(void); void setLNAEnable(bool enabled); - bool isLnaCanControl(void) { return true; } + bool isLnaCanControl(void) const { return true; } void setLnaCanControl(bool can_control) { } bool isLNAEnabled(void) const { return lna_enabled; } LoRaFEMType getFEMType(void) const { return KCT8103L_PA; } diff --git a/variants/station_g3_esp32/StationG3Board.h b/variants/station_g3_esp32/StationG3Board.h index b4c5838c..f8cb75cb 100644 --- a/variants/station_g3_esp32/StationG3Board.h +++ b/variants/station_g3_esp32/StationG3Board.h @@ -8,10 +8,6 @@ class StationG3Board : public ESP32Board { KeyValueStore* _prefs = NULL; - bool setLoRaFemLnaEnabled(bool enable); - bool isLoRaFemLnaEnabled() const; - bool setLoRaFemPaGainEnabled(bool enable); - bool isLoRaFemPaGainEnabled() const; public: LoRaFEMControl loRaFEMControl; @@ -34,6 +30,12 @@ public: void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; + bool canControlLoRaFemLna() const override { return loRaFEMControl.canControlLNA(); } + bool setLoRaFemLnaEnabled(bool enable) override; + bool isLoRaFemLnaEnabled() const override; + bool canControlLoRaFemPaGain() const override { return loRaFEMControl.canControlPAGain(); } + bool setLoRaFemPaGainEnabled(bool enable) override; + bool isLoRaFemPaGainEnabled() const override; void setPrimaryLNAEnable(bool enabled) { loRaFEMControl.setLNAEnable(enabled); diff --git a/variants/wio-tracker-l1-1w/WioTrackerL1Board.h b/variants/wio-tracker-l1-1w/WioTrackerL1Board.h index 798145db..7dde409d 100644 --- a/variants/wio-tracker-l1-1w/WioTrackerL1Board.h +++ b/variants/wio-tracker-l1-1w/WioTrackerL1Board.h @@ -10,14 +10,14 @@ protected: bool _is_pa_enabled = false; KeyValueStore* _prefs = NULL; - bool setLoRaFemPaGainEnabled(bool enable); - bool isLoRaFemPaGainEnabled() const { return _is_pa_enabled; } - public: WioTrackerL1Board() : NRF52Board("WioTrackerL1 OTA") {} void begin(); void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; + bool canControlLoRaFemPaGain() const override { return true; } + bool setLoRaFemPaGainEnabled(bool enable) override; + bool isLoRaFemPaGainEnabled() const override { return _is_pa_enabled; } #if defined(P_LORA_TX_LED) void onBeforeTransmit() override { From a087a5198fd11b68f69dba075fe7d6fd0d72109a Mon Sep 17 00:00:00 2001 From: agessaman Date: Wed, 23 Sep 2026 15:51:05 -0700 Subject: [PATCH 02/10] kiss_modem: only set USB TX buffer size on HWCDC builds USBCDC (ARDUINO_USB_MODE=0, TinyUSB) has no setTxBufferSize, which broke the Station G3 and Heltec Tracker V2 KISS builds. --- examples/kiss_modem/main.cpp | 3 +++ 1 file changed, 3 insertions(+) diff --git a/examples/kiss_modem/main.cpp b/examples/kiss_modem/main.cpp index 8835418d..3d815d96 100644 --- a/examples/kiss_modem/main.cpp +++ b/examples/kiss_modem/main.cpp @@ -113,7 +113,10 @@ void setup() { delay(100); #if defined(ESP32) && defined(ARDUINO_USB_CDC_ON_BOOT) && ARDUINO_USB_CDC_ON_BOOT Serial.setTxTimeoutMs(USB_TX_TIMEOUT_MS); +#if defined(ARDUINO_USB_MODE) && ARDUINO_USB_MODE + // HWCDC only; TinyUSB's USBCDC TX buffer is fixed at build time Serial.setTxBufferSize(USB_TX_BUFFER_SIZE); +#endif #endif modem = new KissModem(Serial, identity, rng, radio_driver, board, sensors); #endif From 0d648e4a18a692adf6c84fe3d8bb4737fb8e1551 Mon Sep 17 00:00:00 2001 From: agessaman Date: Wed, 23 Sep 2026 16:11:29 -0700 Subject: [PATCH 03/10] kiss_modem: keep FEM replies ordered and deliverable; drop Wio FEM control - Wio Tracker L1 1W no longer advertises TX gain control: its setter drives LORA_PWR_EN, the shared LDO for the SX1262 and the PA, so "gain off" would power down the radio. - A SetFemState that arrives mid-TX is now applied after TxDone is queued, so its reply follows TxDone. - SetFemState replies (immediate or deferred) are retained until they fit in the host output queue instead of being dropped, so a change that took effect is always acknowledged. - GetFemState replies queue behind an outstanding SetFemState reply; a further SetFemState returns TxBusy until it clears. --- docs/kiss_modem_protocol.md | 2 +- examples/kiss_modem/KissModem.cpp | 64 ++++++++++---- examples/kiss_modem/KissModem.h | 8 +- test/test_kiss_modem/test_hw_controls.cpp | 83 +++++++++++++++++-- .../wio-tracker-l1-1w/WioTrackerL1Board.h | 6 +- 5 files changed, 131 insertions(+), 32 deletions(-) diff --git a/docs/kiss_modem_protocol.md b/docs/kiss_modem_protocol.md index 9b8aaa4b..1a668cc4 100644 --- a/docs/kiss_modem_protocol.md +++ b/docs/kiss_modem_protocol.md @@ -279,7 +279,7 @@ FemState response data: Example: enable RX gain without changing TX gain: apply `0x01`, value `0x01`. -If any bit in the apply mask is not in the board's capability mask (including reserved bits), the modem replies `Unsupported` and changes nothing. On success, SetFemState replies with the FemState response carrying the new state. A request received while a packet is on air is applied as soon as that transmission ends, and the FemState response is sent then; a second request during the same transmission returns `TxBusy`. Capabilities come from the board, so a board with a fixed, board-managed FEM (for example RAK3401) reports none. +If any bit in the apply mask is not in the board's capability mask (including reserved bits), the modem replies `Unsupported` and changes nothing. On success, SetFemState replies with the FemState response carrying the new state. A SetFemState received while a packet is on air (before its TxDone is queued) is held and applied after TxDone, so its FemState response follows TxDone. While a SetFemState is held or its response is still waiting for output space, GetFemState responses are queued behind it in order, and a further SetFemState returns `TxBusy`. Capabilities come from the board, so a board with a fixed, board-managed FEM (for example RAK3401) reports none. The setting is not persisted; the board's power-on default applies after reboot. diff --git a/examples/kiss_modem/KissModem.cpp b/examples/kiss_modem/KissModem.cpp index 5b61e83c..af678bbe 100644 --- a/examples/kiss_modem/KissModem.cpp +++ b/examples/kiss_modem/KissModem.cpp @@ -27,6 +27,9 @@ KissModem::KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& r _fem_deferred = false; _fem_deferred_apply = 0; _fem_deferred_value = 0; + _fem_reply_pending = false; + _fem_reply_ok = false; + _fem_deferred_gets = 0; resetOutputQueue(); } @@ -37,6 +40,8 @@ void KissModem::begin() { _has_pending_tx = false; _tx_state = TX_IDLE; _fem_deferred = false; + _fem_reply_pending = false; + _fem_deferred_gets = 0; _next_agc_reset_ms = millis() + (uint32_t)_agc_reset_interval_sec * 1000; resetOutputQueue(); } @@ -811,12 +816,16 @@ uint8_t KissModem::femValueMask() const { return mask; } -void KissModem::writeFemState() { +bool KissModem::queueFemReply(bool ok, bool mark_busy_error) { + if (!ok) { + const uint8_t err = HW_ERR_UNSUPPORTED; + return queueHardwareFrame(HW_RESP_ERROR, &err, 1, mark_busy_error); + } uint8_t buf[2] = { femCapabilityMask(), femValueMask() }; - writeHardwareFrame(HW_RESP(HW_CMD_GET_FEM_STATE), buf, 2); + return queueHardwareFrame(HW_RESP(HW_CMD_GET_FEM_STATE), buf, 2, mark_busy_error); } -void KissModem::applyFemState(uint8_t apply_mask, uint8_t value_mask) { +bool KissModem::applyFemState(uint8_t apply_mask, uint8_t value_mask) { bool ok = true; if (apply_mask & HW_FEM_RX_GAIN) { ok &= _board.setLoRaFemLnaEnabled((value_mask & HW_FEM_RX_GAIN) != 0); @@ -824,17 +833,26 @@ void KissModem::applyFemState(uint8_t apply_mask, uint8_t value_mask) { if (apply_mask & HW_FEM_TX_GAIN) { ok &= _board.setLoRaFemPaGainEnabled((value_mask & HW_FEM_TX_GAIN) != 0); } - if (ok) { - writeFemState(); - } else { - writeHardwareError(HW_ERR_UNSUPPORTED); - } + return ok; } void KissModem::processDeferredFem() { - if (!_fem_deferred || _tx_state == TX_SENDING) return; - _fem_deferred = false; - applyFemState(_fem_deferred_apply, _fem_deferred_value); + // wait for TxDone to be queued so the host sees the TX result before the FEM change + if (_fem_deferred && _tx_state != TX_SENDING && _tx_state != TX_DONE_PENDING) { + _fem_reply_ok = applyFemState(_fem_deferred_apply, _fem_deferred_value); + _fem_deferred = false; + _fem_reply_pending = true; + } + if (_fem_deferred) return; + // replies are retained until queued, and GetFemState replies stay behind the Set reply + if (_fem_reply_pending) { + if (!queueFemReply(_fem_reply_ok, false)) return; + _fem_reply_pending = false; + } + while (_fem_deferred_gets > 0) { + if (!queueFemReply(true, false)) return; + _fem_deferred_gets--; + } } void KissModem::handleSetFemState(const uint8_t* data, uint16_t len) { @@ -849,20 +867,30 @@ void KissModem::handleSetFemState(const uint8_t* data, uint16_t len) { writeHardwareError(HW_ERR_UNSUPPORTED); return; } - if (_tx_state == TX_SENDING) { + if (isFemReplyQueued()) { + writeHardwareError(HW_ERR_TX_BUSY); + return; + } + if (_tx_state == TX_SENDING || _tx_state == TX_DONE_PENDING) { // board setters drive FEM pins directly; changing them mid-packet would corrupt the TX - if (_fem_deferred) { - writeHardwareError(HW_ERR_TX_BUSY); - return; - } _fem_deferred = true; _fem_deferred_apply = apply_mask; _fem_deferred_value = value_mask; return; } - applyFemState(apply_mask, value_mask); + _fem_reply_ok = applyFemState(apply_mask, value_mask); + _fem_reply_pending = true; + processDeferredFem(); } void KissModem::handleGetFemState() { - writeFemState(); + if (isFemReplyQueued()) { + if (_fem_deferred_gets == UINT8_MAX) { + writeHardwareError(HW_ERR_TX_BUSY); + return; + } + _fem_deferred_gets++; + return; + } + queueFemReply(true, true); } diff --git a/examples/kiss_modem/KissModem.h b/examples/kiss_modem/KissModem.h index 751fb336..25184217 100644 --- a/examples/kiss_modem/KissModem.h +++ b/examples/kiss_modem/KissModem.h @@ -163,6 +163,9 @@ class KissModem { bool _fem_deferred; uint8_t _fem_deferred_apply; uint8_t _fem_deferred_value; + bool _fem_reply_pending; + bool _fem_reply_ok; + uint8_t _fem_deferred_gets; uint8_t _tx_frame_buf[KISS_TX_FRAME_QUEUE_DEPTH][KISS_MAX_ENCODED_FRAME_SIZE]; uint16_t _tx_frame_len[KISS_TX_FRAME_QUEUE_DEPTH]; uint16_t _tx_frame_written[KISS_TX_FRAME_QUEUE_DEPTH]; @@ -192,8 +195,9 @@ class KissModem { void maybeResetAgc(); uint8_t femCapabilityMask() const; uint8_t femValueMask() const; - void writeFemState(); - void applyFemState(uint8_t apply_mask, uint8_t value_mask); + bool queueFemReply(bool ok, bool mark_busy_error); + bool applyFemState(uint8_t apply_mask, uint8_t value_mask); + bool isFemReplyQueued() const { return _fem_deferred || _fem_reply_pending || _fem_deferred_gets > 0; } void processDeferredFem(); void handleGetIdentity(); diff --git a/test/test_kiss_modem/test_hw_controls.cpp b/test/test_kiss_modem/test_hw_controls.cpp index ad6f1e36..614ccc24 100644 --- a/test/test_kiss_modem/test_hw_controls.cpp +++ b/test/test_kiss_modem/test_hw_controls.cpp @@ -13,8 +13,9 @@ public: for (uint8_t b : bytes) _rx.push(b); } - int availableForWrite() override { return 4096; } + int availableForWrite() override { return blocked ? 0 : 4096; } size_t write(const uint8_t* buffer, size_t size) override { + if (blocked) return 0; _writes.insert(_writes.end(), buffer, buffer + size); return size; } @@ -49,6 +50,8 @@ public: return frames; } + bool blocked = false; + private: std::queue _rx; std::vector _writes; @@ -254,7 +257,7 @@ TEST_F(KissHwControlTest, FemShortPayloadIsInvalidLength) { EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN}), (std::vector{HW_RESP_ERROR, HW_ERR_INVALID_LENGTH})); } -TEST_F(KissHwControlTest, FemSetDuringTxIsDeferredUntilTxCompletes) { +TEST_F(KissHwControlTest, FemSetDuringTxIsDeferredUntilAfterTxDone) { board.has_lna = true; startTxAndHold(); serial.takeHardwareFrames(); @@ -264,15 +267,79 @@ TEST_F(KissHwControlTest, FemSetDuringTxIsDeferredUntilTxCompletes) { EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, 0}), (std::vector{HW_RESP_ERROR, HW_ERR_TX_BUSY})); radio.send_complete = true; + modem.loop(); // TX done -> TX_DONE_PENDING; FEM still held + modem.loop(); // TxDone queued -> idle; FEM applied + auto frames = serial.takeHardwareFrames(); + ASSERT_EQ(frames.size(), 2U); + EXPECT_EQ(frames[0], (std::vector{HW_RESP_TX_DONE, 0x01})); + EXPECT_EQ(frames[1], (std::vector{0x9F, 0x01, 0x01})); + EXPECT_TRUE(board.lna); + EXPECT_EQ(board.lna_sets, 1); +} + +TEST_F(KissHwControlTest, FemGetDuringDeferredSetIsAnsweredAfterSet) { + board.has_lna = true; + startTxAndHold(); + serial.takeHardwareFrames(); + + EXPECT_TRUE(hw({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN}).empty()); + EXPECT_TRUE(hw({HW_CMD_GET_FEM_STATE}).empty()); + + radio.send_complete = true; + modem.loop(); modem.loop(); auto frames = serial.takeHardwareFrames(); - ASSERT_EQ(frames.size(), 1U); - EXPECT_EQ(frames[0], (std::vector{0x9F, 0x01, 0x01})); - EXPECT_TRUE(board.lna); - modem.loop(); - frames = serial.takeHardwareFrames(); - ASSERT_EQ(frames.size(), 1U); + ASSERT_EQ(frames.size(), 3U); EXPECT_EQ(frames[0], (std::vector{HW_RESP_TX_DONE, 0x01})); + EXPECT_EQ(frames[1], (std::vector{0x9F, 0x01, 0x01})); + EXPECT_EQ(frames[2], (std::vector{0x9F, 0x01, 0x01})); +} + +TEST_F(KissHwControlTest, DeferredFemRepliesSurviveHostBackpressure) { + board.has_lna = true; + hw({HW_CMD_SET_SIGNAL_REPORT, 0}); // one output frame per RX packet + startTxAndHold(); + serial.takeHardwareFrames(); + EXPECT_TRUE(hw({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN}).empty()); + EXPECT_TRUE(hw({HW_CMD_GET_FEM_STATE}).empty()); + + // with writes blocked: RX packet takes slot 1, TxDone slot 2, so the Set reply cannot be queued + serial.blocked = true; + static constexpr uint8_t PKT[] = {0x01}; + modem.onPacketReceived(0, 0, PKT, sizeof(PKT)); + radio.send_complete = true; + for (int i = 0; i < 5; i++) modem.loop(); + EXPECT_TRUE(board.lna); // applied once TxDone was queued, reply still held + + serial.blocked = false; + for (int i = 0; i < 5; i++) modem.loop(); + EXPECT_EQ(board.lna_sets, 1); + + auto frames = serial.takeHardwareFrames(); + ASSERT_EQ(frames.size(), 3U); + EXPECT_EQ(frames[0], (std::vector{HW_RESP_TX_DONE, 0x01})); + EXPECT_EQ(frames[1], (std::vector{0x9F, 0x01, 0x01})); + EXPECT_EQ(frames[2], (std::vector{0x9F, 0x01, 0x01})); +} + +TEST_F(KissHwControlTest, ImmediateFemReplySurvivesHostBackpressure) { + board.has_lna = true; + hw({HW_CMD_SET_SIGNAL_REPORT, 0}); + + serial.blocked = true; + static constexpr uint8_t PKT[] = {0x01}; + modem.onPacketReceived(0, 0, PKT, sizeof(PKT)); + modem.onPacketReceived(0, 0, PKT, sizeof(PKT)); // output queue now full + serial.pushRx({KISS_FEND, KISS_CMD_SETHARDWARE, HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN, KISS_FEND}); + modem.loop(); + EXPECT_TRUE(board.lna); + + serial.blocked = false; + for (int i = 0; i < 5; i++) modem.loop(); + auto frames = serial.takeHardwareFrames(); + ASSERT_EQ(frames.size(), 1U); // FemState, not TxBusy + EXPECT_EQ(frames[0], (std::vector{0x9F, 0x01, 0x01})); + EXPECT_EQ(board.lna_sets, 1); } } // namespace diff --git a/variants/wio-tracker-l1-1w/WioTrackerL1Board.h b/variants/wio-tracker-l1-1w/WioTrackerL1Board.h index 7dde409d..798145db 100644 --- a/variants/wio-tracker-l1-1w/WioTrackerL1Board.h +++ b/variants/wio-tracker-l1-1w/WioTrackerL1Board.h @@ -10,14 +10,14 @@ protected: bool _is_pa_enabled = false; KeyValueStore* _prefs = NULL; + bool setLoRaFemPaGainEnabled(bool enable); + bool isLoRaFemPaGainEnabled() const { return _is_pa_enabled; } + public: WioTrackerL1Board() : NRF52Board("WioTrackerL1 OTA") {} void begin(); void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; - bool canControlLoRaFemPaGain() const override { return true; } - bool setLoRaFemPaGainEnabled(bool enable) override; - bool isLoRaFemPaGainEnabled() const override { return _is_pa_enabled; } #if defined(P_LORA_TX_LED) void onBeforeTransmit() override { From 8cefda9612011bd35b592cd610c40953c8e7815a Mon Sep 17 00:00:00 2001 From: agessaman Date: Wed, 23 Sep 2026 16:59:39 -0700 Subject: [PATCH 04/10] kiss_modem: add radio chip boosted RX gain control Add SetRxBoostedGain (0x20) / GetRxBoostedGain (0x21, reply 0xA1) and capability bit 3, the KISS equivalent of the radio.rxgain CLI setting. It is separate from FEM RX gain; a board may support either or both. - Support is declared by the driver via a new RadioLibWrapper::supportsRxBoostedGain() (SX1262, SX1268, LLCC68, LR1110, LR1121, LR2021), so nothing is written to the radio at boot. - The set is refused with TxBusy during TX or while host output is backed up. Otherwise any completed RX packet is delivered first, because some drivers (LR2021) drop to standby to apply the gain. - The reply always carries the state read back from the radio. Driver fixes found along the way, which also affect the radio.rxgain CLI in regular firmware: - CustomLR2021 never updated its cached gain state, so the getter always reported off. It now tracks the applied level per RX path and rolls RadioLib's cached level back if a write fails. - CustomLR1110/LR1121 cached the requested state even when the write failed. - lr11x0ResetAGC only reapplied the gain when RX_BOOSTED_GAIN was defined, so a runtime setting was lost on the next AGC reset. --- docs/kiss_modem_protocol.md | 16 ++- examples/kiss_modem/KissModem.cpp | 45 +++++++++ examples/kiss_modem/KissModem.h | 18 ++++ examples/kiss_modem/main.cpp | 30 ++++-- src/helpers/radiolib/CustomLLCC68Wrapper.h | 1 + src/helpers/radiolib/CustomLR1110.h | 5 +- src/helpers/radiolib/CustomLR1110Wrapper.h | 1 + src/helpers/radiolib/CustomLR1121.h | 5 +- src/helpers/radiolib/CustomLR1121Wrapper.h | 1 + src/helpers/radiolib/CustomLR2021.h | 20 +++- src/helpers/radiolib/CustomLR2021Wrapper.h | 1 + src/helpers/radiolib/CustomSX1262Wrapper.h | 1 + src/helpers/radiolib/CustomSX1268Wrapper.h | 1 + src/helpers/radiolib/LR11x0Reset.h | 3 +- src/helpers/radiolib/RadioLibWrappers.h | 1 + test/test_kiss_modem/test_hw_controls.cpp | 112 +++++++++++++++++++++ 16 files changed, 245 insertions(+), 16 deletions(-) diff --git a/docs/kiss_modem_protocol.md b/docs/kiss_modem_protocol.md index 1a668cc4..cb7be8b3 100644 --- a/docs/kiss_modem_protocol.md +++ b/docs/kiss_modem_protocol.md @@ -123,10 +123,12 @@ MeshCore-specific functionality uses the standard KISS SetHardware command. The | GetAgcResetInterval | `0x1D` | - | | SetFemState | `0x1E` | Apply mask (1) + Value mask (1) | | GetFemState | `0x1F` | - | +| SetRxBoostedGain | `0x20` | Enable (1): 0x00=disable, nonzero=enable | +| GetRxBoostedGain | `0x21` | - | ### Response Sub-commands (TNC to Host) -Response codes use the high-bit convention: `response = command | 0x80`. Generic and unsolicited responses use the `0xF0`+ range. Set commands that report state (SetSignalReport, SetAgcResetInterval, SetFemState) reply with the matching Get response, so `0x9C` and `0x9E` are never sent. +Response codes use the high-bit convention: `response = command | 0x80`. Generic and unsolicited responses use the `0xF0`+ range. Set commands that report state (SetSignalReport, SetAgcResetInterval, SetFemState, SetRxBoostedGain) reply with the matching Get response, so `0x9C`, `0x9E` and `0xA0` are never sent. | Sub-command | Value | Data | |--------------|--------|-----------------------------------------| @@ -155,6 +157,7 @@ Response codes use the high-bit convention: `response = command | 0x80`. Generic | Capabilities | `0x9B` | Feature bits (4) | | AgcResetInterval | `0x9D` | Effective seconds (2) | | FemState | `0x9F` | Capability mask (1) + Value mask (1) | +| RxBoostedGain | `0xA1` | Status (1): 0x00=disabled, 0x01=enabled | | OK | `0xF0` | - | | Error | `0xF1` | Error code (1) | | TxDone | `0xF8` | Result (1): 0x00=failed, 0x01=success | @@ -239,6 +242,7 @@ All values little-endian. Hosts should probe capabilities rather than infer them | 0 | `0x01` | AGC reset interval control (always set) | | 1 | `0x02` | External FEM RX (LNA) gain control | | 2 | `0x04` | External FEM TX (PA) gain control | +| 3 | `0x08` | Radio chip boosted RX gain control | Remaining bits are reserved and sent as 0. @@ -283,6 +287,16 @@ If any bit in the apply mask is not in the board's capability mask (including re The setting is not persisted; the board's power-on default applies after reboot. +### RX Boosted Gain (SetRxBoostedGain / RxBoostedGain response) + +Controls the radio chip's own boosted RX gain mode (SX1262, SX1268, LLCC68, LR11x0, LR2021), the equivalent of the MeshCore `radio.rxgain` setting. This is independent of the external FEM RX gain controlled by SetFemState; a board can support either, both or neither. + +| Field | Size | Description | +|--------|--------|------------------------------------| +| Status | 1 byte | 0x00 = power-saving, 0x01 = boosted | + +SetRxBoostedGain always replies with the RxBoostedGain response carrying the effective state read back from the radio; if it differs from the requested value, the change did not take effect. Some radios must drop to standby to apply it, so the modem replies `TxBusy` and changes nothing while a packet is on air or host output is backed up; retry later. Before applying, any completed received packet is delivered to the host first. A packet still being received at that moment can be lost. Radios whose driver has no boosted RX gain control (for example SX127x and STM32WLx) do not set capability bit 3 and reply `Unsupported` to both commands. The power-on default is the build's `SX126X_RX_BOOSTED_GAIN` setting; the value is not persisted, and periodic AGC resets preserve it. + ### Stats (Stats response) All values little-endian. diff --git a/examples/kiss_modem/KissModem.cpp b/examples/kiss_modem/KissModem.cpp index af678bbe..221c40b1 100644 --- a/examples/kiss_modem/KissModem.cpp +++ b/examples/kiss_modem/KissModem.cpp @@ -20,6 +20,9 @@ KissModem::KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& r _setTxPowerCallback = nullptr; _getCurrentRssiCallback = nullptr; _getStatsCallback = nullptr; + _setRxBoostedGainCallback = nullptr; + _getRxBoostedGainCallback = nullptr; + _pollRxCallback = nullptr; _config = {0, 0, 0, 0, 0}; _signal_report_enabled = true; _agc_reset_interval_sec = KISS_AGC_RESET_DEFAULT_SEC; @@ -422,6 +425,12 @@ void KissModem::handleHardwareCommand(uint8_t sub_cmd, const uint8_t* data, uint case HW_CMD_GET_FEM_STATE: handleGetFemState(); break; + case HW_CMD_SET_RX_BOOSTED_GAIN: + handleSetRxBoostedGain(data, len); + break; + case HW_CMD_GET_RX_BOOSTED_GAIN: + handleGetRxBoostedGain(); + break; default: writeHardwareError(HW_ERR_UNKNOWN_CMD); break; @@ -778,6 +787,7 @@ void KissModem::handleGetCapabilities() { uint32_t caps = HW_CAP_AGC_RESET; if (_board.canControlLoRaFemLna()) caps |= HW_CAP_FEM_RX_GAIN; if (_board.canControlLoRaFemPaGain()) caps |= HW_CAP_FEM_TX_GAIN; + if (_setRxBoostedGainCallback && _getRxBoostedGainCallback) caps |= HW_CAP_RX_BOOSTED_GAIN; uint8_t buf[4] = { (uint8_t)caps, (uint8_t)(caps >> 8), (uint8_t)(caps >> 16), (uint8_t)(caps >> 24) }; writeHardwareFrame(HW_RESP(HW_CMD_GET_CAPABILITIES), buf, 4); } @@ -894,3 +904,38 @@ void KissModem::handleGetFemState() { } queueFemReply(true, true); } + +void KissModem::handleSetRxBoostedGain(const uint8_t* data, uint16_t len) { + if (len < 1) { + writeHardwareError(HW_ERR_INVALID_LENGTH); + return; + } + if (!_setRxBoostedGainCallback || !_getRxBoostedGainCallback) { + writeHardwareError(HW_ERR_UNSUPPORTED); + return; + } + // some drivers (LR2021) drop to standby to apply the gain, which would abort a TX and + // discard a completed RX packet; so never during TX, and only after draining RX + if (_tx_state == TX_SENDING || isHostOutputBackedUp()) { + writeHardwareError(HW_ERR_TX_BUSY); + return; + } + if (_pollRxCallback) _pollRxCallback(); + tryFlushFrames(); + if (_tx_frame_count >= KISS_TX_FRAME_QUEUE_DEPTH) { + writeHardwareError(HW_ERR_TX_BUSY); // no room left for the reply; change nothing + return; + } + // always reply with the state read back, so a failed or partial write is never misreported + _setRxBoostedGainCallback(data[0] != 0x00); + handleGetRxBoostedGain(); +} + +void KissModem::handleGetRxBoostedGain() { + if (!_getRxBoostedGainCallback) { + writeHardwareError(HW_ERR_UNSUPPORTED); + return; + } + uint8_t val = _getRxBoostedGainCallback() ? 0x01 : 0x00; + writeHardwareFrame(HW_RESP(HW_CMD_GET_RX_BOOSTED_GAIN), &val, 1); +} diff --git a/examples/kiss_modem/KissModem.h b/examples/kiss_modem/KissModem.h index 25184217..ffe89191 100644 --- a/examples/kiss_modem/KissModem.h +++ b/examples/kiss_modem/KissModem.h @@ -67,6 +67,8 @@ #define HW_CMD_GET_AGC_RESET_INTERVAL 0x1D #define HW_CMD_SET_FEM_STATE 0x1E #define HW_CMD_GET_FEM_STATE 0x1F +#define HW_CMD_SET_RX_BOOSTED_GAIN 0x20 +#define HW_CMD_GET_RX_BOOSTED_GAIN 0x21 /* Response code = command code | 0x80. Generic / unsolicited use 0xF0+. */ #define HW_RESP(cmd) ((cmd) | 0x80) @@ -92,6 +94,7 @@ #define HW_CAP_AGC_RESET (1UL << 0) #define HW_CAP_FEM_RX_GAIN (1UL << 1) #define HW_CAP_FEM_TX_GAIN (1UL << 2) +#define HW_CAP_RX_BOOSTED_GAIN (1UL << 3) /* SetFemState / GetFemState mask bits */ #define HW_FEM_RX_GAIN (1 << 0) @@ -107,6 +110,9 @@ typedef void (*SetRadioCallback)(float freq, float bw, uint8_t sf, uint8_t cr); typedef void (*SetTxPowerCallback)(uint8_t power); typedef float (*GetCurrentRssiCallback)(); typedef void (*GetStatsCallback)(uint32_t* rx, uint32_t* tx, uint32_t* errors); +typedef bool (*SetRxBoostedGainCallback)(bool enable); +typedef bool (*GetRxBoostedGainCallback)(); +typedef void (*PollRxCallback)(); struct RadioConfig { uint32_t freq_hz; @@ -155,6 +161,9 @@ class KissModem { SetTxPowerCallback _setTxPowerCallback; GetCurrentRssiCallback _getCurrentRssiCallback; GetStatsCallback _getStatsCallback; + SetRxBoostedGainCallback _setRxBoostedGainCallback; + GetRxBoostedGainCallback _getRxBoostedGainCallback; + PollRxCallback _pollRxCallback; RadioConfig _config; bool _signal_report_enabled; @@ -231,6 +240,8 @@ class KissModem { void handleGetAgcResetInterval(); void handleSetFemState(const uint8_t* data, uint16_t len); void handleGetFemState(); + void handleSetRxBoostedGain(const uint8_t* data, uint16_t len); + void handleGetRxBoostedGain(); public: KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& rng, @@ -243,6 +254,13 @@ public: void setTxPowerCallback(SetTxPowerCallback cb) { _setTxPowerCallback = cb; } void setGetCurrentRssiCallback(GetCurrentRssiCallback cb) { _getCurrentRssiCallback = cb; } void setGetStatsCallback(GetStatsCallback cb) { _getStatsCallback = cb; } + // Only register these when the radio supports boosted RX gain; they define the capability. + // Delivers any completed RX packet to the host; called before settings that restart the receiver. + void setPollRxCallback(PollRxCallback cb) { _pollRxCallback = cb; } + void setRxBoostedGainCallbacks(SetRxBoostedGainCallback set_cb, GetRxBoostedGainCallback get_cb) { + _setRxBoostedGainCallback = set_cb; + _getRxBoostedGainCallback = get_cb; + } void onPacketReceived(int8_t snr, int8_t rssi, const uint8_t* packet, uint16_t len); bool isTxBusy() const { return _tx_state != TX_IDLE; } diff --git a/examples/kiss_modem/main.cpp b/examples/kiss_modem/main.cpp index 3d815d96..dd1ee14f 100644 --- a/examples/kiss_modem/main.cpp +++ b/examples/kiss_modem/main.cpp @@ -73,6 +73,24 @@ void onGetStats(uint32_t* rx, uint32_t* tx, uint32_t* errors) { *errors = radio_driver.getPacketsRecvErrors(); } +void pollRadioRx() { + uint8_t rx_buf[256]; + int rx_len = radio_driver.recvRaw(rx_buf, sizeof(rx_buf)); + if (rx_len > 0) { + int8_t snr = (int8_t)(radio_driver.getLastSNR() * 4); + int8_t rssi = (int8_t)radio_driver.getLastRSSI(); + modem->onPacketReceived(snr, rssi, rx_buf, rx_len); + } +} + +bool onSetRxBoostedGain(bool enable) { + return radio_driver.setRxBoostedGainMode(enable); +} + +bool onGetRxBoostedGain() { + return radio_driver.getRxBoostedGainMode(); +} + void setup() { board.begin(); @@ -125,6 +143,10 @@ void setup() { modem->setTxPowerCallback(onSetTxPower); modem->setGetCurrentRssiCallback(onGetCurrentRssi); modem->setGetStatsCallback(onGetStats); + modem->setPollRxCallback(pollRadioRx); + if (radio_driver.supportsRxBoostedGain()) { + modem->setRxBoostedGainCallbacks(onSetRxBoostedGain, onGetRxBoostedGain); + } modem->begin(); board.onBootComplete(); @@ -134,13 +156,7 @@ void loop() { modem->loop(); if (!modem->isActuallyTransmitting() && !modem->isHostOutputBackedUp()) { - uint8_t rx_buf[256]; - int rx_len = radio_driver.recvRaw(rx_buf, sizeof(rx_buf)); - if (rx_len > 0) { - int8_t snr = (int8_t)(radio_driver.getLastSNR() * 4); - int8_t rssi = (int8_t)radio_driver.getLastRSSI(); - modem->onPacketReceived(snr, rssi, rx_buf, rx_len); - } + pollRadioRx(); } board.loop(); diff --git a/src/helpers/radiolib/CustomLLCC68Wrapper.h b/src/helpers/radiolib/CustomLLCC68Wrapper.h index ae0fe0a2..89d5e1bc 100644 --- a/src/helpers/radiolib/CustomLLCC68Wrapper.h +++ b/src/helpers/radiolib/CustomLLCC68Wrapper.h @@ -37,6 +37,7 @@ public: void doResetAGC() override { sx126xResetAGC((SX126x *)_radio); } + bool supportsRxBoostedGain() const override { return true; } bool setRxBoostedGainMode(bool en) override { return ((CustomLLCC68 *)_radio)->setRxBoostedGainMode(en) == RADIOLIB_ERR_NONE; } diff --git a/src/helpers/radiolib/CustomLR1110.h b/src/helpers/radiolib/CustomLR1110.h index f0fde435..0d430c1d 100644 --- a/src/helpers/radiolib/CustomLR1110.h +++ b/src/helpers/radiolib/CustomLR1110.h @@ -39,8 +39,9 @@ class CustomLR1110 : public LR1110 { float getFreqMHz() const { return freqMHz; } int16_t setRxBoostedGainMode(bool en) { - _rx_boosted = en; - return LR1110::setRxBoostedGainMode(en); + int16_t status = LR1110::setRxBoostedGainMode(en); + if (status == RADIOLIB_ERR_NONE) _rx_boosted = en; + return status; } bool getRxBoostedGainMode() const { return _rx_boosted; } diff --git a/src/helpers/radiolib/CustomLR1110Wrapper.h b/src/helpers/radiolib/CustomLR1110Wrapper.h index e7aaeb93..bf2e8370 100644 --- a/src/helpers/radiolib/CustomLR1110Wrapper.h +++ b/src/helpers/radiolib/CustomLR1110Wrapper.h @@ -43,6 +43,7 @@ public: uint8_t getSpreadingFactor() const override { return ((CustomLR1110 *)_radio)->getSpreadingFactor(); } + bool supportsRxBoostedGain() const override { return true; } bool setRxBoostedGainMode(bool en) override { return ((CustomLR1110 *)_radio)->setRxBoostedGainMode(en) == RADIOLIB_ERR_NONE; } diff --git a/src/helpers/radiolib/CustomLR1121.h b/src/helpers/radiolib/CustomLR1121.h index 67e3b52a..eaa55be8 100644 --- a/src/helpers/radiolib/CustomLR1121.h +++ b/src/helpers/radiolib/CustomLR1121.h @@ -39,8 +39,9 @@ class CustomLR1121 : public LR1121 { float getFreqMHz() const { return freqMHz; } int16_t setRxBoostedGainMode(bool en) { - _rx_boosted = en; - return LR1121::setRxBoostedGainMode(en); + int16_t status = LR1121::setRxBoostedGainMode(en); + if (status == RADIOLIB_ERR_NONE) _rx_boosted = en; + return status; } bool getRxBoostedGainMode() const { return _rx_boosted; } diff --git a/src/helpers/radiolib/CustomLR1121Wrapper.h b/src/helpers/radiolib/CustomLR1121Wrapper.h index 5a754cee..d5620b45 100644 --- a/src/helpers/radiolib/CustomLR1121Wrapper.h +++ b/src/helpers/radiolib/CustomLR1121Wrapper.h @@ -44,6 +44,7 @@ public: uint8_t getSpreadingFactor() const override { return ((CustomLR1121 *)_radio)->getSpreadingFactor(); } + bool supportsRxBoostedGain() const override { return true; } bool setRxBoostedGainMode(bool en) override { return ((CustomLR1121 *)_radio)->setRxBoostedGainMode(en) == RADIOLIB_ERR_NONE; } diff --git a/src/helpers/radiolib/CustomLR2021.h b/src/helpers/radiolib/CustomLR2021.h index 0255b93c..d08d3dc7 100644 --- a/src/helpers/radiolib/CustomLR2021.h +++ b/src/helpers/radiolib/CustomLR2021.h @@ -8,7 +8,9 @@ class CustomLR2021 : public LR2021 { uint32_t _maxPayloadMillis = 3934; uint32_t _activityAt = 0; bool _headerSeen = false; - bool _rx_boosted = false; + // last applied gain level per RX path, mirroring RadioLib's gainModeLf/gainModeHf defaults + uint8_t _rx_gain_lf = RADIOLIB_LR2021_RX_BOOST_LF; + uint8_t _rx_gain_hf = RADIOLIB_LR2021_RX_BOOST_HF; public: CustomLR2021(Module *mod) : LR2021(mod) { irqDioNum = LR2021_IRQ_DIO; } @@ -68,7 +70,21 @@ class CustomLR2021 : public LR2021 { float getFreqMHz() const { return freqMHz; } - bool getRxBoostedGainMode() const { return _rx_boosted; } + bool isHighFreqPath() const { return freqMHz > RADIOLIB_LR2021_LF_CUTOFF_FREQ; } + + int16_t setRxBoostedGainMode(uint8_t level) { + uint8_t& applied = isHighFreqPath() ? _rx_gain_hf : _rx_gain_lf; + int16_t status = LR2021::setRxBoostedGainMode(level); + if (status == RADIOLIB_ERR_NONE) { + applied = level; + } else { + // RadioLib caches the level before sending it; restore it so the next startReceive keeps the old gain + LR2021::setRxBoostedGainMode(applied); + } + return status; + } + + bool getRxBoostedGainMode() const { return (isHighFreqPath() ? _rx_gain_hf : _rx_gain_lf) != 0; } int16_t startReceive() override { // include the PREAMBLE_DETECTED irq bit in reported flags diff --git a/src/helpers/radiolib/CustomLR2021Wrapper.h b/src/helpers/radiolib/CustomLR2021Wrapper.h index 8299e2bf..ca0affb6 100644 --- a/src/helpers/radiolib/CustomLR2021Wrapper.h +++ b/src/helpers/radiolib/CustomLR2021Wrapper.h @@ -93,6 +93,7 @@ public: uint8_t getSpreadingFactor() const override { return ((CustomLR2021 *)_radio)->getSpreadingFactor(); } + bool supportsRxBoostedGain() const override { return true; } bool setRxBoostedGainMode(bool en) override { ((CustomLR2021 *)_radio)->standby(); // LR2021 must be in standby to accept setRxBoostedGainMode int16_t status = ((CustomLR2021 *)_radio)->setRxBoostedGainMode(en ? LR2021_RX_BOOST_LEVEL: 0); diff --git a/src/helpers/radiolib/CustomSX1262Wrapper.h b/src/helpers/radiolib/CustomSX1262Wrapper.h index be314471..0caf0f1f 100644 --- a/src/helpers/radiolib/CustomSX1262Wrapper.h +++ b/src/helpers/radiolib/CustomSX1262Wrapper.h @@ -41,6 +41,7 @@ public: ((CustomSX1262 *)_radio)->sleep(false); } + bool supportsRxBoostedGain() const override { return true; } bool setRxBoostedGainMode(bool en) override { return ((CustomSX1262 *)_radio)->setRxBoostedGainMode(en) == RADIOLIB_ERR_NONE; } diff --git a/src/helpers/radiolib/CustomSX1268Wrapper.h b/src/helpers/radiolib/CustomSX1268Wrapper.h index 70f5dabd..9fef1184 100644 --- a/src/helpers/radiolib/CustomSX1268Wrapper.h +++ b/src/helpers/radiolib/CustomSX1268Wrapper.h @@ -38,6 +38,7 @@ public: } uint8_t getSpreadingFactor() const override { return ((CustomSX1268 *)_radio)->spreadingFactor; } + bool supportsRxBoostedGain() const override { return true; } bool setRxBoostedGainMode(bool en) override { return ((CustomSX1268 *)_radio)->setRxBoostedGainMode(en) == RADIOLIB_ERR_NONE; } diff --git a/src/helpers/radiolib/LR11x0Reset.h b/src/helpers/radiolib/LR11x0Reset.h index cdfc1f9f..3a10ff00 100644 --- a/src/helpers/radiolib/LR11x0Reset.h +++ b/src/helpers/radiolib/LR11x0Reset.h @@ -15,7 +15,6 @@ inline void lr11x0ResetAGC(LR11x0* radio, float freqMHz, bool rx_boost_gain) { // Re-calibrate for the actual operating frequency (band=4MHz matches RadioLib default). radio->calibrateImageRejection(freqMHz - 4.0f, freqMHz + 4.0f); -#ifdef RX_BOOSTED_GAIN + // always reapply: the gain may have been changed at runtime even when no build default is set radio->setRxBoostedGainMode(rx_boost_gain); -#endif } diff --git a/src/helpers/radiolib/RadioLibWrappers.h b/src/helpers/radiolib/RadioLibWrappers.h index 77dd9311..9b367ee4 100644 --- a/src/helpers/radiolib/RadioLibWrappers.h +++ b/src/helpers/radiolib/RadioLibWrappers.h @@ -75,6 +75,7 @@ public: float packetScore(float snr, int packet_len) override { return packetScoreInt(snr, 10, packet_len); } // assume sf=10 + virtual bool supportsRxBoostedGain() const { return false; } virtual bool setRxBoostedGainMode(bool) { return false; } virtual bool getRxBoostedGainMode() const { return false; } diff --git a/test/test_kiss_modem/test_hw_controls.cpp b/test/test_kiss_modem/test_hw_controls.cpp index 614ccc24..37b1b929 100644 --- a/test/test_kiss_modem/test_hw_controls.cpp +++ b/test/test_kiss_modem/test_hw_controls.cpp @@ -149,6 +149,29 @@ protected: } }; +bool g_rx_boost = false; +bool g_rx_boost_set_ok = true; +int g_rx_boost_sets = 0; +bool fakeSetRxBoost(bool en) { + g_rx_boost_sets++; + if (!g_rx_boost_set_ok) return false; + g_rx_boost = en; + return true; +} +bool fakeGetRxBoost() { return g_rx_boost; } + +KissModem* g_poll_modem = nullptr; +bool g_poll_has_packet = false; +int g_polls = 0; +void fakePollRx() { + g_polls++; + if (g_poll_has_packet && g_poll_modem) { + static constexpr uint8_t PKT[] = {0x55}; + g_poll_has_packet = false; + g_poll_modem->onPacketReceived(4, -80, PKT, sizeof(PKT)); + } +} + const std::vector ERR_UNSUPPORTED = {HW_RESP_ERROR, HW_ERR_UNSUPPORTED}; TEST_F(KissHwControlTest, VersionIsTwo) { @@ -342,4 +365,93 @@ TEST_F(KissHwControlTest, ImmediateFemReplySurvivesHostBackpressure) { EXPECT_EQ(board.lna_sets, 1); } +class KissRxBoostTest : public KissHwControlTest { +protected: + KissRxBoostTest() { + g_rx_boost = true; + g_rx_boost_set_ok = true; + g_rx_boost_sets = 0; + modem.setRxBoostedGainCallbacks(fakeSetRxBoost, fakeGetRxBoost); + g_poll_modem = &modem; + g_poll_has_packet = false; + g_polls = 0; + modem.setPollRxCallback(fakePollRx); + } +}; + +TEST_F(KissHwControlTest, RxBoostedGainUnsupportedWithoutCallbacks) { + EXPECT_EQ(hw1({HW_CMD_GET_RX_BOOSTED_GAIN}), ERR_UNSUPPORTED); + EXPECT_EQ(hw1({HW_CMD_SET_RX_BOOSTED_GAIN, 1}), ERR_UNSUPPORTED); +} + +TEST_F(KissRxBoostTest, CapabilityAdvertised) { + EXPECT_EQ(hw1({HW_CMD_GET_CAPABILITIES}), (std::vector{0x9B, 0x09, 0x00, 0x00, 0x00})); +} + +TEST_F(KissRxBoostTest, GetReportsCurrentState) { + EXPECT_EQ(hw1({HW_CMD_GET_RX_BOOSTED_GAIN}), (std::vector{0xA1, 0x01})); +} + +TEST_F(KissRxBoostTest, SetRepliesWithEffectiveState) { + EXPECT_EQ(hw1({HW_CMD_SET_RX_BOOSTED_GAIN, 0}), (std::vector{0xA1, 0x00})); + EXPECT_FALSE(g_rx_boost); + EXPECT_EQ(hw1({HW_CMD_SET_RX_BOOSTED_GAIN, 0x7F}), (std::vector{0xA1, 0x01})); + EXPECT_TRUE(g_rx_boost); +} + +TEST_F(KissRxBoostTest, SetFailureRepliesWithUnchangedState) { + g_rx_boost_set_ok = false; + EXPECT_EQ(hw1({HW_CMD_SET_RX_BOOSTED_GAIN, 0}), (std::vector{0xA1, 0x01})); + EXPECT_TRUE(g_rx_boost); +} + +TEST_F(KissRxBoostTest, SetDuringTxIsRejectedWithoutTouchingRadio) { + startTxAndHold(); + serial.takeHardwareFrames(); + EXPECT_EQ(hw1({HW_CMD_SET_RX_BOOSTED_GAIN, 0}), (std::vector{HW_RESP_ERROR, HW_ERR_TX_BUSY})); + EXPECT_EQ(g_rx_boost_sets, 0); + EXPECT_EQ(hw1({HW_CMD_GET_RX_BOOSTED_GAIN}), (std::vector{0xA1, 0x01})); +} + +TEST_F(KissRxBoostTest, SetShortPayloadIsInvalidLength) { + EXPECT_EQ(hw1({HW_CMD_SET_RX_BOOSTED_GAIN}), (std::vector{HW_RESP_ERROR, HW_ERR_INVALID_LENGTH})); + EXPECT_EQ(g_rx_boost_sets, 0); +} + +TEST_F(KissRxBoostTest, CompletedRxPacketIsDeliveredBeforeGainChange) { + g_poll_has_packet = true; + auto frames = hw({HW_CMD_SET_RX_BOOSTED_GAIN, 0}); + EXPECT_EQ(g_polls, 1); + EXPECT_FALSE(g_rx_boost); + ASSERT_EQ(frames.size(), 2U); // RxMeta for the drained packet, then the gain reply + EXPECT_EQ(frames[0][0], HW_RESP_RX_META); + EXPECT_EQ(frames[1], (std::vector{0xA1, 0x00})); +} + +TEST_F(KissRxBoostTest, NoRoomForReplyAfterDrainChangesNothing) { + serial.blocked = true; + g_poll_has_packet = true; // data + meta fill both output slots + serial.pushRx({KISS_FEND, KISS_CMD_SETHARDWARE, HW_CMD_SET_RX_BOOSTED_GAIN, 0, KISS_FEND}); + modem.loop(); + EXPECT_EQ(g_rx_boost_sets, 0); + EXPECT_TRUE(g_rx_boost); + + serial.blocked = false; + for (int i = 0; i < 5; i++) modem.loop(); + auto frames = serial.takeHardwareFrames(); + ASSERT_EQ(frames.size(), 2U); + EXPECT_EQ(frames[0][0], HW_RESP_RX_META); + EXPECT_EQ(frames[1], (std::vector{HW_RESP_ERROR, HW_ERR_TX_BUSY})); +} + +TEST_F(KissRxBoostTest, SetWhileHostOutputBackedUpIsRejected) { + serial.blocked = true; + static constexpr uint8_t PKT[] = {0x01}; + modem.onPacketReceived(0, 0, PKT, sizeof(PKT)); + serial.pushRx({KISS_FEND, KISS_CMD_SETHARDWARE, HW_CMD_SET_RX_BOOSTED_GAIN, 0, KISS_FEND}); + modem.loop(); + EXPECT_EQ(g_polls, 0); + EXPECT_EQ(g_rx_boost_sets, 0); +} + } // namespace From 7652ec5c267a6780adda6767bd260edc1c58653c Mon Sep 17 00:00:00 2001 From: agessaman Date: Wed, 23 Sep 2026 17:31:20 -0700 Subject: [PATCH 05/10] kiss_modem: reach FEM gain through the board's radio.fem CLI commands Boards own their FEM control through handleCommand() ("get/set radio.fem.rxgain|txgain"). Use that instead of a parallel set of FEM virtuals on MainBoard, so any board that implements the commands works in KISS with no extra code. - Remove the six FEM virtuals from MainBoard and the board overrides. - KissModem talks to the board in one adapter. A gain counts as controllable only if "get" replies exactly "> on" or "> off". "set" is checked by reading the state back, never by its reply wording. - SetFemState always replies with the read-back state once the requested bits pass the capability check. - Guard the boards' prefs writes against a NULL store. KISS attaches no prefs, so "set radio.fem.*" would dereference NULL. - Wio Tracker L1 1W TX gain is exposed again, matching its CLI. --- docs/kiss_modem_protocol.md | 2 +- examples/kiss_modem/KissModem.cpp | 92 ++++++++++++------- examples/kiss_modem/KissModem.h | 13 ++- src/MeshCore.h | 8 -- test/mocks/Mesh.h | 7 +- test/test_kiss_modem/test_hw_controls.cpp | 76 +++++++++++---- variants/heltec_t096/T096Board.cpp | 4 +- variants/heltec_t096/T096Board.h | 6 +- .../HeltecTrackerV2Board.cpp | 4 +- .../heltec_tracker_v2/HeltecTrackerV2Board.h | 6 +- variants/heltec_v4/HeltecV4Board.cpp | 4 +- variants/heltec_v4/HeltecV4Board.h | 6 +- variants/heltec_v4_r8/HeltecV4R8Board.cpp | 4 +- variants/heltec_v4_r8/HeltecV4R8Board.h | 5 +- variants/heltec_v4_r8/LoRaFEMControl.h | 2 +- variants/station_g3_esp32/StationG3Board.cpp | 8 +- variants/station_g3_esp32/StationG3Board.h | 10 +- .../wio-tracker-l1-1w/WioTrackerL1Board.cpp | 4 +- 18 files changed, 161 insertions(+), 100 deletions(-) diff --git a/docs/kiss_modem_protocol.md b/docs/kiss_modem_protocol.md index cb7be8b3..a37c4561 100644 --- a/docs/kiss_modem_protocol.md +++ b/docs/kiss_modem_protocol.md @@ -283,7 +283,7 @@ FemState response data: Example: enable RX gain without changing TX gain: apply `0x01`, value `0x01`. -If any bit in the apply mask is not in the board's capability mask (including reserved bits), the modem replies `Unsupported` and changes nothing. On success, SetFemState replies with the FemState response carrying the new state. A SetFemState received while a packet is on air (before its TxDone is queued) is held and applied after TxDone, so its FemState response follows TxDone. While a SetFemState is held or its response is still waiting for output space, GetFemState responses are queued behind it in order, and a further SetFemState returns `TxBusy`. Capabilities come from the board, so a board with a fixed, board-managed FEM (for example RAK3401) reports none. +If any bit in the apply mask is not in the board's capability mask (including reserved bits), the modem replies `Unsupported` and changes nothing. Otherwise SetFemState replies with the FemState response carrying the state read back from the board; if a bit differs from the request, that change did not take effect. A SetFemState received while a packet is on air (before its TxDone is queued) is held and applied after TxDone, so its FemState response follows TxDone. While a SetFemState is held or its response is still waiting for output space, GetFemState responses are queued behind it in order, and a further SetFemState returns `TxBusy`. Capabilities come from the board's own `get/set radio.fem.rxgain` and `radio.fem.txgain` CLI commands (see [cli_commands.md](./cli_commands.md)): a gain is controllable when the board answers `get` with `> on` or `> off`. Any board that implements those commands is supported without KISS changes, and a board with a fixed, board-managed FEM (for example RAK3401) reports none. Changes made over KISS are not saved to the board's preferences. The setting is not persisted; the board's power-on default applies after reboot. diff --git a/examples/kiss_modem/KissModem.cpp b/examples/kiss_modem/KissModem.cpp index 221c40b1..a6950bff 100644 --- a/examples/kiss_modem/KissModem.cpp +++ b/examples/kiss_modem/KissModem.cpp @@ -1,5 +1,6 @@ #include "KissModem.h" #include +#include KissModem::KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& rng, mesh::Radio& radio, mesh::MainBoard& board, SensorManager& sensors) @@ -31,7 +32,6 @@ KissModem::KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& r _fem_deferred_apply = 0; _fem_deferred_value = 0; _fem_reply_pending = false; - _fem_reply_ok = false; _fem_deferred_gets = 0; resetOutputQueue(); } @@ -785,8 +785,10 @@ void KissModem::handleGetSignalReport() { void KissModem::handleGetCapabilities() { uint32_t caps = HW_CAP_AGC_RESET; - if (_board.canControlLoRaFemLna()) caps |= HW_CAP_FEM_RX_GAIN; - if (_board.canControlLoRaFemPaGain()) caps |= HW_CAP_FEM_TX_GAIN; + uint8_t fem_caps, fem_values; + readFemState(&fem_caps, &fem_values); + if (fem_caps & HW_FEM_RX_GAIN) caps |= HW_CAP_FEM_RX_GAIN; + if (fem_caps & HW_FEM_TX_GAIN) caps |= HW_CAP_FEM_TX_GAIN; if (_setRxBoostedGainCallback && _getRxBoostedGainCallback) caps |= HW_CAP_RX_BOOSTED_GAIN; uint8_t buf[4] = { (uint8_t)caps, (uint8_t)(caps >> 8), (uint8_t)(caps >> 16), (uint8_t)(caps >> 24) }; writeHardwareFrame(HW_RESP(HW_CMD_GET_CAPABILITIES), buf, 4); @@ -812,55 +814,81 @@ void KissModem::handleGetAgcResetInterval() { writeHardwareFrame(HW_RESP(HW_CMD_GET_AGC_RESET_INTERVAL), buf, 2); } -uint8_t KissModem::femCapabilityMask() const { - uint8_t mask = 0; - if (_board.canControlLoRaFemLna()) mask |= HW_FEM_RX_GAIN; - if (_board.canControlLoRaFemPaGain()) mask |= HW_FEM_TX_GAIN; - return mask; +// FEM gain is reached through the board's own "radio.fem.*" CLI commands, the same ones users run. +static const char* femGainName(uint8_t bit) { + return bit == HW_FEM_RX_GAIN ? "rxgain" : "txgain"; } -uint8_t KissModem::femValueMask() const { - uint8_t mask = 0; - if (_board.canControlLoRaFemLna() && _board.isLoRaFemLnaEnabled()) mask |= HW_FEM_RX_GAIN; - if (_board.canControlLoRaFemPaGain() && _board.isLoRaFemPaGainEnabled()) mask |= HW_FEM_TX_GAIN; - return mask; -} - -bool KissModem::queueFemReply(bool ok, bool mark_busy_error) { - if (!ok) { - const uint8_t err = HW_ERR_UNSUPPORTED; - return queueHardwareFrame(HW_RESP_ERROR, &err, 1, mark_busy_error); +// Anything but an exact "> on" / "> off" (not handled, "Error: ...", unexpected text) means unsupported. +bool KissModem::queryFemGain(uint8_t bit, bool* enabled) { + char cmd[32]; + char reply[KISS_BOARD_REPLY_SIZE] = { 0 }; + snprintf(cmd, sizeof(cmd), "get radio.fem.%s", femGainName(bit)); + if (!_board.handleCommand(cmd, 0, reply)) return false; + if (strcmp(reply, "> on") == 0) { + *enabled = true; + } else if (strcmp(reply, "> off") == 0) { + *enabled = false; + } else { + return false; } - uint8_t buf[2] = { femCapabilityMask(), femValueMask() }; + return true; +} + +// Success is judged by reading the state back, not by the wording of the set reply. +bool KissModem::setFemGain(uint8_t bit, bool enable) { + char cmd[32]; + char reply[KISS_BOARD_REPLY_SIZE] = { 0 }; + snprintf(cmd, sizeof(cmd), "set radio.fem.%s %s", femGainName(bit), enable ? "on" : "off"); + _board.handleCommand(cmd, 0, reply); + bool now; + return queryFemGain(bit, &now) && now == enable; +} + +void KissModem::readFemState(uint8_t* caps, uint8_t* values) { + *caps = 0; + *values = 0; + const uint8_t bits[] = { HW_FEM_RX_GAIN, HW_FEM_TX_GAIN }; + for (uint8_t bit : bits) { + bool enabled; + if (queryFemGain(bit, &enabled)) { + *caps |= bit; + if (enabled) *values |= bit; + } + } +} + +bool KissModem::queueFemReply(bool mark_busy_error) { + uint8_t buf[2]; + readFemState(&buf[0], &buf[1]); return queueHardwareFrame(HW_RESP(HW_CMD_GET_FEM_STATE), buf, 2, mark_busy_error); } -bool KissModem::applyFemState(uint8_t apply_mask, uint8_t value_mask) { - bool ok = true; +// The reply always carries the read-back state, so a bit that failed to apply shows its real value. +void KissModem::applyFemState(uint8_t apply_mask, uint8_t value_mask) { if (apply_mask & HW_FEM_RX_GAIN) { - ok &= _board.setLoRaFemLnaEnabled((value_mask & HW_FEM_RX_GAIN) != 0); + setFemGain(HW_FEM_RX_GAIN, (value_mask & HW_FEM_RX_GAIN) != 0); } if (apply_mask & HW_FEM_TX_GAIN) { - ok &= _board.setLoRaFemPaGainEnabled((value_mask & HW_FEM_TX_GAIN) != 0); + setFemGain(HW_FEM_TX_GAIN, (value_mask & HW_FEM_TX_GAIN) != 0); } - return ok; } void KissModem::processDeferredFem() { // wait for TxDone to be queued so the host sees the TX result before the FEM change if (_fem_deferred && _tx_state != TX_SENDING && _tx_state != TX_DONE_PENDING) { - _fem_reply_ok = applyFemState(_fem_deferred_apply, _fem_deferred_value); + applyFemState(_fem_deferred_apply, _fem_deferred_value); _fem_deferred = false; _fem_reply_pending = true; } if (_fem_deferred) return; // replies are retained until queued, and GetFemState replies stay behind the Set reply if (_fem_reply_pending) { - if (!queueFemReply(_fem_reply_ok, false)) return; + if (!queueFemReply(false)) return; _fem_reply_pending = false; } while (_fem_deferred_gets > 0) { - if (!queueFemReply(true, false)) return; + if (!queueFemReply(false)) return; _fem_deferred_gets--; } } @@ -873,7 +901,9 @@ void KissModem::handleSetFemState(const uint8_t* data, uint16_t len) { uint8_t apply_mask = data[0]; uint8_t value_mask = data[1]; // validate every requested bit before touching hardware so a request is all-or-nothing - if (apply_mask & ~femCapabilityMask()) { + uint8_t fem_caps, fem_values; + readFemState(&fem_caps, &fem_values); + if (apply_mask & ~fem_caps) { writeHardwareError(HW_ERR_UNSUPPORTED); return; } @@ -888,7 +918,7 @@ void KissModem::handleSetFemState(const uint8_t* data, uint16_t len) { _fem_deferred_value = value_mask; return; } - _fem_reply_ok = applyFemState(apply_mask, value_mask); + applyFemState(apply_mask, value_mask); _fem_reply_pending = true; processDeferredFem(); } @@ -902,7 +932,7 @@ void KissModem::handleGetFemState() { _fem_deferred_gets++; return; } - queueFemReply(true, true); + queueFemReply(true); } void KissModem::handleSetRxBoostedGain(const uint8_t* data, uint16_t len) { diff --git a/examples/kiss_modem/KissModem.h b/examples/kiss_modem/KissModem.h index ffe89191..572999c4 100644 --- a/examples/kiss_modem/KissModem.h +++ b/examples/kiss_modem/KissModem.h @@ -100,6 +100,9 @@ #define HW_FEM_RX_GAIN (1 << 0) #define HW_FEM_TX_GAIN (1 << 1) +/* Matches the CLI reply buffer boards write into from handleCommand() */ +#define KISS_BOARD_REPLY_SIZE 160 + #define KISS_AGC_RESET_DEFAULT_SEC 30 #define KISS_AGC_RESET_MAX_SEC 1020 #define KISS_AGC_RESET_STEP_SEC 4 @@ -173,7 +176,6 @@ class KissModem { uint8_t _fem_deferred_apply; uint8_t _fem_deferred_value; bool _fem_reply_pending; - bool _fem_reply_ok; uint8_t _fem_deferred_gets; uint8_t _tx_frame_buf[KISS_TX_FRAME_QUEUE_DEPTH][KISS_MAX_ENCODED_FRAME_SIZE]; uint16_t _tx_frame_len[KISS_TX_FRAME_QUEUE_DEPTH]; @@ -202,10 +204,11 @@ class KissModem { void handleHardwareCommand(uint8_t sub_cmd, const uint8_t* data, uint16_t len); void processTx(); void maybeResetAgc(); - uint8_t femCapabilityMask() const; - uint8_t femValueMask() const; - bool queueFemReply(bool ok, bool mark_busy_error); - bool applyFemState(uint8_t apply_mask, uint8_t value_mask); + bool queryFemGain(uint8_t bit, bool* enabled); + bool setFemGain(uint8_t bit, bool enable); + void readFemState(uint8_t* caps, uint8_t* values); + bool queueFemReply(bool mark_busy_error); + void applyFemState(uint8_t apply_mask, uint8_t value_mask); bool isFemReplyQueued() const { return _fem_deferred || _fem_reply_pending || _fem_deferred_gets > 0; } void processDeferredFem(); diff --git a/src/MeshCore.h b/src/MeshCore.h index 5fdb064c..2a3582de 100644 --- a/src/MeshCore.h +++ b/src/MeshCore.h @@ -77,14 +77,6 @@ public: virtual bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) { return false; } - // External LoRa front-end (FEM) gain control. Boards without a controllable FEM keep these defaults. - virtual bool canControlLoRaFemLna() const { return false; } - virtual bool setLoRaFemLnaEnabled(bool enable) { return false; } - virtual bool isLoRaFemLnaEnabled() const { return false; } - virtual bool canControlLoRaFemPaGain() const { return false; } - virtual bool setLoRaFemPaGainEnabled(bool enable) { return false; } - virtual bool isLoRaFemPaGainEnabled() const { return false; } - // Called from the example main loops. Lets a board feed its watchdog and // run periodic housekeeping. Default no-op. virtual void loop() { /* no op */ } diff --git a/test/mocks/Mesh.h b/test/mocks/Mesh.h index 29a29b82..33c437f2 100644 --- a/test/mocks/Mesh.h +++ b/test/mocks/Mesh.h @@ -23,12 +23,7 @@ public: virtual float getMCUTemperature() { return 25.0f; } virtual const char* getManufacturerName() { return "mock-board"; } virtual void reboot() {} - virtual bool canControlLoRaFemLna() const { return false; } - virtual bool setLoRaFemLnaEnabled(bool) { return false; } - virtual bool isLoRaFemLnaEnabled() const { return false; } - virtual bool canControlLoRaFemPaGain() const { return false; } - virtual bool setLoRaFemPaGainEnabled(bool) { return false; } - virtual bool isLoRaFemPaGainEnabled() const { return false; } + virtual bool handleCommand(const char*, uint32_t, char*) { return false; } }; } diff --git a/test/test_kiss_modem/test_hw_controls.cpp b/test/test_kiss_modem/test_hw_controls.cpp index 37b1b929..16ef50df 100644 --- a/test/test_kiss_modem/test_hw_controls.cpp +++ b/test/test_kiss_modem/test_hw_controls.cpp @@ -72,31 +72,50 @@ public: int agc_resets = 0; }; +// Implements FEM through the "radio.fem.*" CLI text, worded like the Heltec / Station G3 boards. class FemBoard : public mesh::MainBoard { public: const char* getManufacturerName() override { return "fem-board"; } - bool canControlLoRaFemLna() const override { return has_lna; } - bool setLoRaFemLnaEnabled(bool enable) override { - if (!has_lna) return false; - lna = enable; - lna_sets++; - return true; + bool handleCommand(const char* command, uint32_t, char* reply) override { + commands++; + if (handleGain(command, reply, "rxgain", has_lna, lna, lna_sets, lna_sticks)) return true; + if (handleGain(command, reply, "txgain", has_pa, pa, pa_sets, pa_sticks)) return true; + return false; } - bool isLoRaFemLnaEnabled() const override { return lna; } - - bool canControlLoRaFemPaGain() const override { return has_pa; } - bool setLoRaFemPaGainEnabled(bool enable) override { - if (!has_pa) return false; - pa = enable; - pa_sets++; - return true; - } - bool isLoRaFemPaGainEnabled() const override { return pa; } bool has_lna = false, has_pa = false; bool lna = false, pa = false; int lna_sets = 0, pa_sets = 0; + bool lna_sticks = false, pa_sticks = false; // set reports OK but the state does not change + bool unhandled = false; // board does not implement radio.fem.* at all + const char* odd_get_reply = nullptr; // unexpected get wording + int commands = 0; + +private: + bool handleGain(const char* command, char* reply, const char* name, bool has, bool& state, int& sets, bool sticks) { + if (unhandled) return false; + char get_cmd[32], set_cmd[32]; + snprintf(get_cmd, sizeof(get_cmd), "get radio.fem.%s", name); + snprintf(set_cmd, sizeof(set_cmd), "set radio.fem.%s ", name); + if (strcmp(command, get_cmd) == 0) { + if (!has) strcpy(reply, "Error: unsupported"); + else if (odd_get_reply) strcpy(reply, odd_get_reply); + else sprintf(reply, "> %s", state ? "on" : "off"); + return true; + } + if (strncmp(command, set_cmd, strlen(set_cmd)) == 0) { + if (!has) { + strcpy(reply, "Error: unsupported"); + } else { + sets++; + if (!sticks) state = strcmp(command + strlen(set_cmd), "on") == 0; + strcpy(reply, "OK - LoRa FEM gain changed"); + } + return true; + } + return false; + } }; class NoSensors : public SensorManager { @@ -276,6 +295,31 @@ TEST_F(KissHwControlTest, FemUnknownBitsAreUnsupported) { EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, 0x04, 0x04}), ERR_UNSUPPORTED); } +TEST_F(KissHwControlTest, FemUnhandledCommandsMeanUnsupported) { + board.has_lna = board.has_pa = true; + board.unhandled = true; + EXPECT_EQ(hw1({HW_CMD_GET_FEM_STATE}), (std::vector{0x9F, 0x00, 0x00})); + EXPECT_EQ(hw1({HW_CMD_GET_CAPABILITIES}), (std::vector{0x9B, 0x01, 0x00, 0x00, 0x00})); + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN}), ERR_UNSUPPORTED); +} + +TEST_F(KissHwControlTest, FemUnexpectedGetWordingMeansUnsupported) { + board.has_lna = true; + board.odd_get_reply = "> enabled"; + EXPECT_EQ(hw1({HW_CMD_GET_FEM_STATE}), (std::vector{0x9F, 0x00, 0x00})); + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN}), ERR_UNSUPPORTED); + EXPECT_EQ(board.lna_sets, 0); +} + +TEST_F(KissHwControlTest, FemSetThatDoesNotTakeRepliesWithReadBackState) { + board.has_lna = board.has_pa = true; + board.lna_sticks = true; // board says OK but LNA stays off + EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN | HW_FEM_TX_GAIN, HW_FEM_RX_GAIN | HW_FEM_TX_GAIN}), + (std::vector{0x9F, 0x03, 0x02})); + EXPECT_FALSE(board.lna); + EXPECT_TRUE(board.pa); +} + TEST_F(KissHwControlTest, FemShortPayloadIsInvalidLength) { EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN}), (std::vector{HW_RESP_ERROR, HW_ERR_INVALID_LENGTH})); } diff --git a/variants/heltec_t096/T096Board.cpp b/variants/heltec_t096/T096Board.cpp index ea26d2cc..47ad8d96 100644 --- a/variants/heltec_t096/T096Board.cpp +++ b/variants/heltec_t096/T096Board.cpp @@ -158,14 +158,14 @@ bool T096Board::handleCommand(const char* command, uint32_t sender_timestamp, ch strcpy(reply, "Error: unsupported"); } else if (memcmp(&command[21], "on", 2) == 0) { if (setLoRaFemLnaEnabled(true)) { - _prefs->setByKey("fem_rxgain", "1"); + if (_prefs) _prefs->setByKey("fem_rxgain", "1"); strcpy(reply, "OK - LoRa FEM RX gain on"); } else { strcpy(reply, "Error: failed to apply LoRa FEM RX gain"); } } else if (memcmp(&command[21], "off", 3) == 0) { if (setLoRaFemLnaEnabled(false)) { - _prefs->setByKey("fem_rxgain", "0"); + if (_prefs) _prefs->setByKey("fem_rxgain", "0"); strcpy(reply, "OK - LoRa FEM RX gain off"); } else { strcpy(reply, "Error: failed to apply LoRa FEM RX gain"); diff --git a/variants/heltec_t096/T096Board.h b/variants/heltec_t096/T096Board.h index 66fa5047..e926c8a6 100644 --- a/variants/heltec_t096/T096Board.h +++ b/variants/heltec_t096/T096Board.h @@ -16,6 +16,9 @@ protected: #endif void variant_shutdown(); + bool setLoRaFemLnaEnabled(bool enable); + bool isLoRaFemLnaEnabled() const; + public: RefCountedDigitalPin periph_power; LoRaFEMControl loRaFEMControl; @@ -24,9 +27,6 @@ public: void begin(); void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; - bool canControlLoRaFemLna() const override { return loRaFEMControl.isLnaCanControl(); } - bool setLoRaFemLnaEnabled(bool enable) override; - bool isLoRaFemLnaEnabled() const override; void onBeforeTransmit(void) override; void onAfterTransmit(void) override; diff --git a/variants/heltec_tracker_v2/HeltecTrackerV2Board.cpp b/variants/heltec_tracker_v2/HeltecTrackerV2Board.cpp index 753824a0..95d56699 100644 --- a/variants/heltec_tracker_v2/HeltecTrackerV2Board.cpp +++ b/variants/heltec_tracker_v2/HeltecTrackerV2Board.cpp @@ -99,14 +99,14 @@ bool HeltecTrackerV2Board::handleCommand(const char* command, uint32_t sender_ti strcpy(reply, "Error: unsupported"); } else if (memcmp(&command[21], "on", 2) == 0) { if (setLoRaFemLnaEnabled(true)) { - _prefs->setByKey("fem_rxgain", "1"); + if (_prefs) _prefs->setByKey("fem_rxgain", "1"); strcpy(reply, "OK - LoRa FEM RX gain on"); } else { strcpy(reply, "Error: failed to apply LoRa FEM RX gain"); } } else if (memcmp(&command[21], "off", 3) == 0) { if (setLoRaFemLnaEnabled(false)) { - _prefs->setByKey("fem_rxgain", "0"); + if (_prefs) _prefs->setByKey("fem_rxgain", "0"); strcpy(reply, "OK - LoRa FEM RX gain off"); } else { strcpy(reply, "Error: failed to apply LoRa FEM RX gain"); diff --git a/variants/heltec_tracker_v2/HeltecTrackerV2Board.h b/variants/heltec_tracker_v2/HeltecTrackerV2Board.h index 34454cac..5fed2b65 100644 --- a/variants/heltec_tracker_v2/HeltecTrackerV2Board.h +++ b/variants/heltec_tracker_v2/HeltecTrackerV2Board.h @@ -8,6 +8,9 @@ class HeltecTrackerV2Board : public ESP32Board { KeyValueStore* _prefs = NULL; + bool setLoRaFemLnaEnabled(bool enable); + bool isLoRaFemLnaEnabled() const; + public: RefCountedDigitalPin periph_power; LoRaFEMControl loRaFEMControl; @@ -17,9 +20,6 @@ public: void begin(); void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; - bool canControlLoRaFemLna() const override { return loRaFEMControl.isLnaCanControl(); } - bool setLoRaFemLnaEnabled(bool enable) override; - bool isLoRaFemLnaEnabled() const override; void onBeforeTransmit(void) override; void onAfterTransmit(void) override; diff --git a/variants/heltec_v4/HeltecV4Board.cpp b/variants/heltec_v4/HeltecV4Board.cpp index 794257d7..2d941bd8 100644 --- a/variants/heltec_v4/HeltecV4Board.cpp +++ b/variants/heltec_v4/HeltecV4Board.cpp @@ -100,14 +100,14 @@ bool HeltecV4Board::handleCommand(const char* command, uint32_t sender_timestamp strcpy(reply, "Error: unsupported"); } else if (memcmp(&command[21], "on", 2) == 0) { if (setLoRaFemLnaEnabled(true)) { - _prefs->setByKey("fem_rxgain", "1"); + if (_prefs) _prefs->setByKey("fem_rxgain", "1"); strcpy(reply, "OK - LoRa FEM RX gain on"); } else { strcpy(reply, "Error: failed to apply LoRa FEM RX gain"); } } else if (memcmp(&command[21], "off", 3) == 0) { if (setLoRaFemLnaEnabled(false)) { - _prefs->setByKey("fem_rxgain", "0"); + if (_prefs) _prefs->setByKey("fem_rxgain", "0"); strcpy(reply, "OK - LoRa FEM RX gain off"); } else { strcpy(reply, "Error: failed to apply LoRa FEM RX gain"); diff --git a/variants/heltec_v4/HeltecV4Board.h b/variants/heltec_v4/HeltecV4Board.h index bd3bdb25..79a690e8 100644 --- a/variants/heltec_v4/HeltecV4Board.h +++ b/variants/heltec_v4/HeltecV4Board.h @@ -12,6 +12,9 @@ class HeltecV4Board : public ESP32Board { KeyValueStore* _prefs = NULL; + bool setLoRaFemLnaEnabled(bool enable); + bool isLoRaFemLnaEnabled() const; + protected: float adc_mult = ADC_MULTIPLIER; @@ -23,9 +26,6 @@ public: void begin(); void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; - bool canControlLoRaFemLna() const override { return loRaFEMControl.isLnaCanControl(); } - bool setLoRaFemLnaEnabled(bool enable) override; - bool isLoRaFemLnaEnabled() const override; void onBeforeTransmit(void) override; void onAfterTransmit(void) override; diff --git a/variants/heltec_v4_r8/HeltecV4R8Board.cpp b/variants/heltec_v4_r8/HeltecV4R8Board.cpp index ea2cfbed..d4860ab4 100644 --- a/variants/heltec_v4_r8/HeltecV4R8Board.cpp +++ b/variants/heltec_v4_r8/HeltecV4R8Board.cpp @@ -122,14 +122,14 @@ bool HeltecV4R8Board::handleCommand(const char* command, uint32_t sender_timesta strcpy(reply, "Error: unsupported"); } else if (memcmp(&command[21], "on", 2) == 0) { if (setLoRaFemLnaEnabled(true)) { - _prefs->setByKey("fem_rxgain", "1"); + if (_prefs) _prefs->setByKey("fem_rxgain", "1"); strcpy(reply, "OK - LoRa FEM RX gain on"); } else { strcpy(reply, "Error: failed to apply LoRa FEM RX gain"); } } else if (memcmp(&command[21], "off", 3) == 0) { if (setLoRaFemLnaEnabled(false)) { - _prefs->setByKey("fem_rxgain", "0"); + if (_prefs) _prefs->setByKey("fem_rxgain", "0"); strcpy(reply, "OK - LoRa FEM RX gain off"); } else { strcpy(reply, "Error: failed to apply LoRa FEM RX gain"); diff --git a/variants/heltec_v4_r8/HeltecV4R8Board.h b/variants/heltec_v4_r8/HeltecV4R8Board.h index c34ee449..7ab29f96 100644 --- a/variants/heltec_v4_r8/HeltecV4R8Board.h +++ b/variants/heltec_v4_r8/HeltecV4R8Board.h @@ -13,6 +13,8 @@ class HeltecV4R8Board : public ESP32Board { KeyValueStore* _prefs = NULL; + bool setLoRaFemLnaEnabled(bool enable); + bool isLoRaFemLnaEnabled() const; protected: float adc_mult = ADC_MULTIPLIER; @@ -25,9 +27,6 @@ public: void begin(); void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; - bool canControlLoRaFemLna() const override { return loRaFEMControl.isLnaCanControl(); } - bool setLoRaFemLnaEnabled(bool enable) override; - bool isLoRaFemLnaEnabled() const override; void onBeforeTransmit(void) override; void onAfterTransmit(void) override; diff --git a/variants/heltec_v4_r8/LoRaFEMControl.h b/variants/heltec_v4_r8/LoRaFEMControl.h index 52d7a0f8..4b74c2e2 100644 --- a/variants/heltec_v4_r8/LoRaFEMControl.h +++ b/variants/heltec_v4_r8/LoRaFEMControl.h @@ -15,7 +15,7 @@ public: void setRxModeEnable(void); void setRxModeEnableWhenMCUSleep(void); void setLNAEnable(bool enabled); - bool isLnaCanControl(void) const { return true; } + bool isLnaCanControl(void) { return true; } void setLnaCanControl(bool can_control) { } bool isLNAEnabled(void) const { return lna_enabled; } LoRaFEMType getFEMType(void) const { return KCT8103L_PA; } diff --git a/variants/station_g3_esp32/StationG3Board.cpp b/variants/station_g3_esp32/StationG3Board.cpp index 277c2b8b..9e8ef112 100644 --- a/variants/station_g3_esp32/StationG3Board.cpp +++ b/variants/station_g3_esp32/StationG3Board.cpp @@ -65,14 +65,14 @@ bool StationG3Board::handleCommand(const char* command, uint32_t sender_timestam strcpy(reply, "Error: unsupported"); } else if (memcmp(&command[21], "on", 2) == 0) { if (setLoRaFemLnaEnabled(true)) { - _prefs->setByKey("fem_rxgain", "1"); + if (_prefs) _prefs->setByKey("fem_rxgain", "1"); strcpy(reply, "OK - LoRa FEM RX gain on"); } else { strcpy(reply, "Error: failed to apply LoRa FEM RX gain"); } } else if (memcmp(&command[21], "off", 3) == 0) { if (setLoRaFemLnaEnabled(false)) { - _prefs->setByKey("fem_rxgain", "0"); + if (_prefs) _prefs->setByKey("fem_rxgain", "0"); strcpy(reply, "OK - LoRa FEM RX gain off"); } else { strcpy(reply, "Error: failed to apply LoRa FEM RX gain"); @@ -96,14 +96,14 @@ bool StationG3Board::handleCommand(const char* command, uint32_t sender_timestam strcpy(reply, "Error: unsupported"); } else if (memcmp(&command[21], "on", 2) == 0) { if (setLoRaFemPaGainEnabled(true)) { - _prefs->setByKey("fem_txgain", "1"); + if (_prefs) _prefs->setByKey("fem_txgain", "1"); strcpy(reply, "OK - LoRa FEM TX gain on"); } else { strcpy(reply, "Error: failed to apply LoRa FEM TX gain"); } } else if (memcmp(&command[21], "off", 3) == 0) { if (setLoRaFemPaGainEnabled(false)) { - _prefs->setByKey("fem_txgain", "0"); + if (_prefs) _prefs->setByKey("fem_txgain", "0"); strcpy(reply, "OK - LoRa FEM TX gain off"); } else { strcpy(reply, "Error: failed to apply LoRa FEM TX gain"); diff --git a/variants/station_g3_esp32/StationG3Board.h b/variants/station_g3_esp32/StationG3Board.h index f8cb75cb..b4c5838c 100644 --- a/variants/station_g3_esp32/StationG3Board.h +++ b/variants/station_g3_esp32/StationG3Board.h @@ -8,6 +8,10 @@ class StationG3Board : public ESP32Board { KeyValueStore* _prefs = NULL; + bool setLoRaFemLnaEnabled(bool enable); + bool isLoRaFemLnaEnabled() const; + bool setLoRaFemPaGainEnabled(bool enable); + bool isLoRaFemPaGainEnabled() const; public: LoRaFEMControl loRaFEMControl; @@ -30,12 +34,6 @@ public: void attachDynamicPrefs(KeyValueStore* prefs); bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply) override; - bool canControlLoRaFemLna() const override { return loRaFEMControl.canControlLNA(); } - bool setLoRaFemLnaEnabled(bool enable) override; - bool isLoRaFemLnaEnabled() const override; - bool canControlLoRaFemPaGain() const override { return loRaFEMControl.canControlPAGain(); } - bool setLoRaFemPaGainEnabled(bool enable) override; - bool isLoRaFemPaGainEnabled() const override; void setPrimaryLNAEnable(bool enabled) { loRaFEMControl.setLNAEnable(enabled); diff --git a/variants/wio-tracker-l1-1w/WioTrackerL1Board.cpp b/variants/wio-tracker-l1-1w/WioTrackerL1Board.cpp index c6dbdbf5..69b33f75 100644 --- a/variants/wio-tracker-l1-1w/WioTrackerL1Board.cpp +++ b/variants/wio-tracker-l1-1w/WioTrackerL1Board.cpp @@ -65,14 +65,14 @@ bool WioTrackerL1Board::handleCommand(const char* command, uint32_t sender_times if (memcmp(command, "set radio.fem.txgain ", 21) == 0) { if (memcmp(&command[21], "on", 2) == 0) { if (setLoRaFemPaGainEnabled(true)) { - _prefs->setByKey("fem_txgain", "1"); + if (_prefs) _prefs->setByKey("fem_txgain", "1"); strcpy(reply, "OK - LoRa FEM TX gain on"); } else { strcpy(reply, "Error: failed to apply LoRa FEM TX gain"); } } else if (memcmp(&command[21], "off", 3) == 0) { if (setLoRaFemPaGainEnabled(false)) { - _prefs->setByKey("fem_txgain", "0"); + if (_prefs) _prefs->setByKey("fem_txgain", "0"); strcpy(reply, "OK - LoRa FEM TX gain off"); } else { strcpy(reply, "Error: failed to apply LoRa FEM TX gain"); From 09ee2e1223eb4478e7421077f08fc218d9461fa2 Mon Sep 17 00:00:00 2001 From: agessaman Date: Wed, 23 Sep 2026 17:41:14 -0700 Subject: [PATCH 06/10] kiss_modem: answer FEM requests strictly in arrival order A second SetFemState sent while the first was held for a TX got an immediate TxBusy, which reached the host before the first request's reply. With no request IDs, the host could not tell which Set failed. FEM requests now go through a small ordered queue (Set, Get and their error replies). Sets still wait for TxDone to be queued and apply once. Each reply is kept until it can be queued. Capability checks happen in order at processing time. Only an overflow (more than 4 waiting) replies TxBusy immediately. --- docs/kiss_modem_protocol.md | 2 +- examples/kiss_modem/KissModem.cpp | 107 ++++++++++------------ examples/kiss_modem/KissModem.h | 30 ++++-- test/test_kiss_modem/test_hw_controls.cpp | 50 +++++++++- 4 files changed, 117 insertions(+), 72 deletions(-) diff --git a/docs/kiss_modem_protocol.md b/docs/kiss_modem_protocol.md index a37c4561..5eb09738 100644 --- a/docs/kiss_modem_protocol.md +++ b/docs/kiss_modem_protocol.md @@ -283,7 +283,7 @@ FemState response data: Example: enable RX gain without changing TX gain: apply `0x01`, value `0x01`. -If any bit in the apply mask is not in the board's capability mask (including reserved bits), the modem replies `Unsupported` and changes nothing. Otherwise SetFemState replies with the FemState response carrying the state read back from the board; if a bit differs from the request, that change did not take effect. A SetFemState received while a packet is on air (before its TxDone is queued) is held and applied after TxDone, so its FemState response follows TxDone. While a SetFemState is held or its response is still waiting for output space, GetFemState responses are queued behind it in order, and a further SetFemState returns `TxBusy`. Capabilities come from the board's own `get/set radio.fem.rxgain` and `radio.fem.txgain` CLI commands (see [cli_commands.md](./cli_commands.md)): a gain is controllable when the board answers `get` with `> on` or `> off`. Any board that implements those commands is supported without KISS changes, and a board with a fixed, board-managed FEM (for example RAK3401) reports none. Changes made over KISS are not saved to the board's preferences. +If any bit in the apply mask is not in the board's capability mask (including reserved bits), the modem replies `Unsupported` and changes nothing. Otherwise SetFemState replies with the FemState response carrying the state read back from the board; if a bit differs from the request, that change did not take effect. SetFemState and GetFemState requests, including their error replies, are answered strictly in the order received. A SetFemState received while a packet is on air (before its TxDone is queued) is held and applied after TxDone, so its reply follows TxDone, and FEM requests that arrive after it wait behind it. Up to 4 FEM requests can wait; beyond that the modem replies `TxBusy` immediately. Capabilities come from the board's own `get/set radio.fem.rxgain` and `radio.fem.txgain` CLI commands (see [cli_commands.md](./cli_commands.md)): a gain is controllable when the board answers `get` with `> on` or `> off`. Any board that implements those commands is supported without KISS changes, and a board with a fixed, board-managed FEM (for example RAK3401) reports none. Changes made over KISS are not saved to the board's preferences. The setting is not persisted; the board's power-on default applies after reboot. diff --git a/examples/kiss_modem/KissModem.cpp b/examples/kiss_modem/KissModem.cpp index a6950bff..4d9cdbdb 100644 --- a/examples/kiss_modem/KissModem.cpp +++ b/examples/kiss_modem/KissModem.cpp @@ -28,11 +28,8 @@ KissModem::KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& r _signal_report_enabled = true; _agc_reset_interval_sec = KISS_AGC_RESET_DEFAULT_SEC; _next_agc_reset_ms = 0; - _fem_deferred = false; - _fem_deferred_apply = 0; - _fem_deferred_value = 0; - _fem_reply_pending = false; - _fem_deferred_gets = 0; + _fem_op_head = 0; + _fem_op_count = 0; resetOutputQueue(); } @@ -42,9 +39,8 @@ void KissModem::begin() { _rx_active = false; _has_pending_tx = false; _tx_state = TX_IDLE; - _fem_deferred = false; - _fem_reply_pending = false; - _fem_deferred_gets = 0; + _fem_op_head = 0; + _fem_op_count = 0; _next_agc_reset_ms = millis() + (uint32_t)_agc_reset_interval_sec * 1000; resetOutputQueue(); } @@ -255,7 +251,7 @@ void KissModem::loop() { } processTx(); - processDeferredFem(); + processFemOps(); maybeResetAgc(); tryFlushFrames(); queuePendingBusyError(); @@ -858,10 +854,10 @@ void KissModem::readFemState(uint8_t* caps, uint8_t* values) { } } -bool KissModem::queueFemReply(bool mark_busy_error) { +bool KissModem::queueFemReply() { uint8_t buf[2]; readFemState(&buf[0], &buf[1]); - return queueHardwareFrame(HW_RESP(HW_CMD_GET_FEM_STATE), buf, 2, mark_busy_error); + return queueHardwareFrame(HW_RESP(HW_CMD_GET_FEM_STATE), buf, 2, false); } // The reply always carries the read-back state, so a bit that failed to apply shows its real value. @@ -874,65 +870,58 @@ void KissModem::applyFemState(uint8_t apply_mask, uint8_t value_mask) { } } -void KissModem::processDeferredFem() { - // wait for TxDone to be queued so the host sees the TX result before the FEM change - if (_fem_deferred && _tx_state != TX_SENDING && _tx_state != TX_DONE_PENDING) { - applyFemState(_fem_deferred_apply, _fem_deferred_value); - _fem_deferred = false; - _fem_reply_pending = true; +void KissModem::enqueueFemOp(FemOpKind kind, uint8_t apply_mask, uint8_t value_mask) { + if (_fem_op_count >= KISS_FEM_OP_QUEUE_DEPTH) { + writeHardwareError(HW_ERR_TX_BUSY); // too many FEM requests waiting + return; } - if (_fem_deferred) return; - // replies are retained until queued, and GetFemState replies stay behind the Set reply - if (_fem_reply_pending) { - if (!queueFemReply(false)) return; - _fem_reply_pending = false; - } - while (_fem_deferred_gets > 0) { - if (!queueFemReply(false)) return; - _fem_deferred_gets--; + FemOp& op = _fem_ops[(_fem_op_head + _fem_op_count) % KISS_FEM_OP_QUEUE_DEPTH]; + op.kind = kind; + op.apply_mask = apply_mask; + op.value_mask = value_mask; + op.applied = false; + _fem_op_count++; + processFemOps(); +} + +// Every FEM reply goes out in request order. A Set waits until TxDone is queued, since board +// setters drive FEM pins directly; each reply is retained until there is room to queue it. +void KissModem::processFemOps() { + while (_fem_op_count > 0) { + FemOp& op = _fem_ops[_fem_op_head]; + if (op.kind == FEM_OP_ERROR) { + if (!queueHardwareFrame(HW_RESP_ERROR, &op.value_mask, 1, false)) return; + } else { + if (op.kind == FEM_OP_SET && !op.applied) { + if (_tx_state == TX_SENDING || _tx_state == TX_DONE_PENDING) return; + uint8_t caps, values; + readFemState(&caps, &values); + if (op.apply_mask & ~caps) { + // all-or-nothing: any bit the board cannot control rejects the whole request + op.kind = FEM_OP_ERROR; + op.value_mask = HW_ERR_UNSUPPORTED; + continue; + } + applyFemState(op.apply_mask, op.value_mask); + op.applied = true; + } + if (!queueFemReply()) return; + } + _fem_op_head = (uint8_t)((_fem_op_head + 1) % KISS_FEM_OP_QUEUE_DEPTH); + _fem_op_count--; } } void KissModem::handleSetFemState(const uint8_t* data, uint16_t len) { if (len < 2) { - writeHardwareError(HW_ERR_INVALID_LENGTH); + enqueueFemOp(FEM_OP_ERROR, 0, HW_ERR_INVALID_LENGTH); return; } - uint8_t apply_mask = data[0]; - uint8_t value_mask = data[1]; - // validate every requested bit before touching hardware so a request is all-or-nothing - uint8_t fem_caps, fem_values; - readFemState(&fem_caps, &fem_values); - if (apply_mask & ~fem_caps) { - writeHardwareError(HW_ERR_UNSUPPORTED); - return; - } - if (isFemReplyQueued()) { - writeHardwareError(HW_ERR_TX_BUSY); - return; - } - if (_tx_state == TX_SENDING || _tx_state == TX_DONE_PENDING) { - // board setters drive FEM pins directly; changing them mid-packet would corrupt the TX - _fem_deferred = true; - _fem_deferred_apply = apply_mask; - _fem_deferred_value = value_mask; - return; - } - applyFemState(apply_mask, value_mask); - _fem_reply_pending = true; - processDeferredFem(); + enqueueFemOp(FEM_OP_SET, data[0], data[1]); } void KissModem::handleGetFemState() { - if (isFemReplyQueued()) { - if (_fem_deferred_gets == UINT8_MAX) { - writeHardwareError(HW_ERR_TX_BUSY); - return; - } - _fem_deferred_gets++; - return; - } - queueFemReply(true); + enqueueFemOp(FEM_OP_GET, 0, 0); } void KissModem::handleSetRxBoostedGain(const uint8_t* data, uint16_t len) { diff --git a/examples/kiss_modem/KissModem.h b/examples/kiss_modem/KissModem.h index 572999c4..24021bdb 100644 --- a/examples/kiss_modem/KissModem.h +++ b/examples/kiss_modem/KissModem.h @@ -103,6 +103,9 @@ /* Matches the CLI reply buffer boards write into from handleCommand() */ #define KISS_BOARD_REPLY_SIZE 160 +/* FEM requests are answered strictly in arrival order; this many may wait (e.g. during a TX) */ +#define KISS_FEM_OP_QUEUE_DEPTH 4 + #define KISS_AGC_RESET_DEFAULT_SEC 30 #define KISS_AGC_RESET_MAX_SEC 1020 #define KISS_AGC_RESET_STEP_SEC 4 @@ -125,6 +128,19 @@ struct RadioConfig { uint8_t tx_power; }; +enum FemOpKind : uint8_t { + FEM_OP_SET, + FEM_OP_GET, + FEM_OP_ERROR +}; + +struct FemOp { + FemOpKind kind; + uint8_t apply_mask; // FEM_OP_SET + uint8_t value_mask; // FEM_OP_SET; error code for FEM_OP_ERROR + bool applied; // FEM_OP_SET: hardware changed, reply still to be queued +}; + enum TxState { TX_IDLE, TX_WAIT_CLEAR, @@ -172,11 +188,9 @@ class KissModem { bool _signal_report_enabled; uint16_t _agc_reset_interval_sec; uint32_t _next_agc_reset_ms; - bool _fem_deferred; - uint8_t _fem_deferred_apply; - uint8_t _fem_deferred_value; - bool _fem_reply_pending; - uint8_t _fem_deferred_gets; + FemOp _fem_ops[KISS_FEM_OP_QUEUE_DEPTH]; + uint8_t _fem_op_head; + uint8_t _fem_op_count; uint8_t _tx_frame_buf[KISS_TX_FRAME_QUEUE_DEPTH][KISS_MAX_ENCODED_FRAME_SIZE]; uint16_t _tx_frame_len[KISS_TX_FRAME_QUEUE_DEPTH]; uint16_t _tx_frame_written[KISS_TX_FRAME_QUEUE_DEPTH]; @@ -207,10 +221,10 @@ class KissModem { bool queryFemGain(uint8_t bit, bool* enabled); bool setFemGain(uint8_t bit, bool enable); void readFemState(uint8_t* caps, uint8_t* values); - bool queueFemReply(bool mark_busy_error); + bool queueFemReply(); void applyFemState(uint8_t apply_mask, uint8_t value_mask); - bool isFemReplyQueued() const { return _fem_deferred || _fem_reply_pending || _fem_deferred_gets > 0; } - void processDeferredFem(); + void enqueueFemOp(FemOpKind kind, uint8_t apply_mask, uint8_t value_mask); + void processFemOps(); void handleGetIdentity(); void handleGetRandom(const uint8_t* data, uint16_t len); diff --git a/test/test_kiss_modem/test_hw_controls.cpp b/test/test_kiss_modem/test_hw_controls.cpp index 16ef50df..e0fdd729 100644 --- a/test/test_kiss_modem/test_hw_controls.cpp +++ b/test/test_kiss_modem/test_hw_controls.cpp @@ -330,20 +330,62 @@ TEST_F(KissHwControlTest, FemSetDuringTxIsDeferredUntilAfterTxDone) { serial.takeHardwareFrames(); EXPECT_TRUE(hw({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN}).empty()); + EXPECT_TRUE(hw({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, 0}).empty()); // queued behind the first EXPECT_EQ(board.lna_sets, 0); - EXPECT_EQ(hw1({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, 0}), (std::vector{HW_RESP_ERROR, HW_ERR_TX_BUSY})); radio.send_complete = true; modem.loop(); // TX done -> TX_DONE_PENDING; FEM still held - modem.loop(); // TxDone queued -> idle; FEM applied + modem.loop(); // TxDone queued -> idle; FEM applied in order + for (int i = 0; i < 3; i++) modem.loop(); auto frames = serial.takeHardwareFrames(); - ASSERT_EQ(frames.size(), 2U); + ASSERT_EQ(frames.size(), 3U); EXPECT_EQ(frames[0], (std::vector{HW_RESP_TX_DONE, 0x01})); EXPECT_EQ(frames[1], (std::vector{0x9F, 0x01, 0x01})); - EXPECT_TRUE(board.lna); + EXPECT_EQ(frames[2], (std::vector{0x9F, 0x01, 0x00})); + EXPECT_FALSE(board.lna); + EXPECT_EQ(board.lna_sets, 2); +} + +TEST_F(KissHwControlTest, PipelinedFemRequestsAreAnsweredInArrivalOrder) { + board.has_lna = true; + startTxAndHold(); + serial.takeHardwareFrames(); + + EXPECT_TRUE(hw({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN}).empty()); + EXPECT_TRUE(hw({HW_CMD_GET_FEM_STATE}).empty()); + EXPECT_TRUE(hw({HW_CMD_SET_FEM_STATE, HW_FEM_TX_GAIN, HW_FEM_TX_GAIN}).empty()); // unsupported bit + EXPECT_TRUE(hw({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN}).empty()); // short payload + + radio.send_complete = true; + for (int i = 0; i < 6; i++) modem.loop(); + auto frames = serial.takeHardwareFrames(); + ASSERT_EQ(frames.size(), 5U); + EXPECT_EQ(frames[0], (std::vector{HW_RESP_TX_DONE, 0x01})); + EXPECT_EQ(frames[1], (std::vector{0x9F, 0x01, 0x01})); + EXPECT_EQ(frames[2], (std::vector{0x9F, 0x01, 0x01})); + EXPECT_EQ(frames[3], ERR_UNSUPPORTED); + EXPECT_EQ(frames[4], (std::vector{HW_RESP_ERROR, HW_ERR_INVALID_LENGTH})); EXPECT_EQ(board.lna_sets, 1); } +TEST_F(KissHwControlTest, FemQueueOverflowRepliesTxBusyImmediately) { + board.has_lna = true; + startTxAndHold(); + serial.takeHardwareFrames(); + for (int i = 0; i < KISS_FEM_OP_QUEUE_DEPTH; i++) { + EXPECT_TRUE(hw({HW_CMD_SET_FEM_STATE, HW_FEM_RX_GAIN, HW_FEM_RX_GAIN}).empty()); + } + EXPECT_EQ(hw1({HW_CMD_GET_FEM_STATE}), (std::vector{HW_RESP_ERROR, HW_ERR_TX_BUSY})); + EXPECT_EQ(board.lna_sets, 0); +} + +TEST_F(KissHwControlTest, FemGetWithNothingQueuedIsAnsweredDuringTx) { + board.has_lna = true; + startTxAndHold(); + serial.takeHardwareFrames(); + EXPECT_EQ(hw1({HW_CMD_GET_FEM_STATE}), (std::vector{0x9F, 0x01, 0x00})); +} + TEST_F(KissHwControlTest, FemGetDuringDeferredSetIsAnsweredAfterSet) { board.has_lna = true; startTxAndHold(); From bc4d0227fe08b89f289f2a5a3226b2fab61ca74b Mon Sep 17 00:00:00 2001 From: agessaman Date: Wed, 23 Sep 2026 18:51:03 -0700 Subject: [PATCH 07/10] kiss_modem: default AGC reset interval to 32 s The AGC interval is set in 4 s steps, matching MeshCore's agc.reset.interval, so the old 30 s default could not be restored by a host: setting 30 gives 28. Found on hardware. Use 32 s, the nearest multiple of 4 above it. --- docs/kiss_modem_protocol.md | 4 ++-- examples/kiss_modem/KissModem.h | 2 +- test/test_kiss_modem/test_hw_controls.cpp | 13 ++++++++----- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/kiss_modem_protocol.md b/docs/kiss_modem_protocol.md index 5eb09738..5075cf4c 100644 --- a/docs/kiss_modem_protocol.md +++ b/docs/kiss_modem_protocol.md @@ -227,7 +227,7 @@ All values little-endian. |-------------|---------|-----------------------| | Noise floor | 2 bytes | int16_t, dBm (signed) | -The modem recalibrates the noise floor every 2 seconds. AGC resets follow the configured AGC reset interval (default 30 seconds). +The modem recalibrates the noise floor every 2 seconds. AGC resets follow the configured AGC reset interval (default 32 seconds). ### Capabilities (Capabilities response) @@ -256,7 +256,7 @@ All values little-endian. The modem periodically resets the radio's AGC while idle (no transmission in progress and host output not backed up). The interval has 4-second resolution, matching the MeshCore `agc.reset.interval` setting: requested values are rounded down to a multiple of 4, so 1-3 disable the reset. Values above 1020 return `InvalidParam`. SetAgcResetInterval replies with the AgcResetInterval response carrying the effective value, and restarts the countdown from the time of the request. -The default is 30 seconds. The setting is not persisted; hosts should re-send it after reconnecting or rebooting the modem. +The default is 32 seconds (previously a fixed 30; changed so the default is a settable 4-second multiple). The setting is not persisted; hosts should re-send it after reconnecting or rebooting the modem. ### FEM State (SetFemState / FemState response) diff --git a/examples/kiss_modem/KissModem.h b/examples/kiss_modem/KissModem.h index 24021bdb..bee41634 100644 --- a/examples/kiss_modem/KissModem.h +++ b/examples/kiss_modem/KissModem.h @@ -106,7 +106,7 @@ /* FEM requests are answered strictly in arrival order; this many may wait (e.g. during a TX) */ #define KISS_FEM_OP_QUEUE_DEPTH 4 -#define KISS_AGC_RESET_DEFAULT_SEC 30 +#define KISS_AGC_RESET_DEFAULT_SEC 32 // a multiple of the 4 s step, so hosts can set it back #define KISS_AGC_RESET_MAX_SEC 1020 #define KISS_AGC_RESET_STEP_SEC 4 diff --git a/test/test_kiss_modem/test_hw_controls.cpp b/test/test_kiss_modem/test_hw_controls.cpp index e0fdd729..2b0b779e 100644 --- a/test/test_kiss_modem/test_hw_controls.cpp +++ b/test/test_kiss_modem/test_hw_controls.cpp @@ -208,8 +208,11 @@ TEST_F(KissHwControlTest, CapabilitiesReflectBoardFem) { EXPECT_EQ(hw1({HW_CMD_GET_CAPABILITIES}), (std::vector{0x9B, 0x07, 0x00, 0x00, 0x00})); } -TEST_F(KissHwControlTest, AgcIntervalDefaultsToThirtySeconds) { - EXPECT_EQ(hw1({HW_CMD_GET_AGC_RESET_INTERVAL}), (std::vector{0x9D, 30, 0})); +TEST_F(KissHwControlTest, AgcIntervalDefaultsToThirtyTwoSeconds) { + EXPECT_EQ(hw1({HW_CMD_GET_AGC_RESET_INTERVAL}), (std::vector{0x9D, 32, 0})); + // the default must be restorable, i.e. a multiple of the 4 s step + EXPECT_EQ(hw1({HW_CMD_SET_AGC_RESET_INTERVAL, 4, 0}), (std::vector{0x9D, 4, 0})); + EXPECT_EQ(hw1({HW_CMD_SET_AGC_RESET_INTERVAL, KISS_AGC_RESET_DEFAULT_SEC, 0}), (std::vector{0x9D, KISS_AGC_RESET_DEFAULT_SEC, 0})); } TEST_F(KissHwControlTest, AgcIntervalSetReturnsEffectiveRoundedValue) { @@ -223,15 +226,15 @@ TEST_F(KissHwControlTest, AgcIntervalSetReturnsEffectiveRoundedValue) { TEST_F(KissHwControlTest, AgcIntervalRejectsOutOfRangeAndShortPayload) { EXPECT_EQ(hw1({HW_CMD_SET_AGC_RESET_INTERVAL, 0xFD, 0x03}), (std::vector{HW_RESP_ERROR, HW_ERR_INVALID_PARAM})); EXPECT_EQ(hw1({HW_CMD_SET_AGC_RESET_INTERVAL, 4}), (std::vector{HW_RESP_ERROR, HW_ERR_INVALID_LENGTH})); - EXPECT_EQ(hw1({HW_CMD_GET_AGC_RESET_INTERVAL}), (std::vector{0x9D, 30, 0})); + EXPECT_EQ(hw1({HW_CMD_GET_AGC_RESET_INTERVAL}), (std::vector{0x9D, 32, 0})); } TEST_F(KissHwControlTest, AgcResetsOnDefaultSchedule) { - advance(29999); + advance(31999); EXPECT_EQ(radio.agc_resets, 0); advance(1); EXPECT_EQ(radio.agc_resets, 1); - advance(29999); + advance(31999); EXPECT_EQ(radio.agc_resets, 1); advance(1); EXPECT_EQ(radio.agc_resets, 2); From 990ea55e2d664140a7f4a913efe3fac1add95859 Mon Sep 17 00:00:00 2001 From: agessaman Date: Wed, 23 Sep 2026 21:56:27 -0700 Subject: [PATCH 08/10] radiolib: reapply runtime RX boosted gain on SX126x AGC reset sx126xResetAGC only restored the gain when the build defined SX126X_RX_BOOSTED_GAIN, so a gain set at runtime was lost on reset. Match lr11x0ResetAGC and always reapply. Also pass the gain state from the LLCC68 wrapper, whose call did not match the helper's signature. --- src/helpers/radiolib/CustomLLCC68Wrapper.h | 2 +- src/helpers/radiolib/SX126xReset.h | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/src/helpers/radiolib/CustomLLCC68Wrapper.h b/src/helpers/radiolib/CustomLLCC68Wrapper.h index 89d5e1bc..e96ae663 100644 --- a/src/helpers/radiolib/CustomLLCC68Wrapper.h +++ b/src/helpers/radiolib/CustomLLCC68Wrapper.h @@ -35,7 +35,7 @@ public: } uint8_t getSpreadingFactor() const override { return ((CustomLLCC68 *)_radio)->spreadingFactor; } - void doResetAGC() override { sx126xResetAGC((SX126x *)_radio); } + void doResetAGC() override { sx126xResetAGC((SX126x *)_radio, getRxBoostedGainMode()); } bool supportsRxBoostedGain() const override { return true; } bool setRxBoostedGainMode(bool en) override { diff --git a/src/helpers/radiolib/SX126xReset.h b/src/helpers/radiolib/SX126xReset.h index 472eb33b..bce84191 100644 --- a/src/helpers/radiolib/SX126xReset.h +++ b/src/helpers/radiolib/SX126xReset.h @@ -25,9 +25,8 @@ inline void sx126xResetAGC(SX126x* radio, bool rx_boost_gain) { #ifdef SX126X_DIO2_AS_RF_SWITCH radio->setDio2AsRfSwitch(SX126X_DIO2_AS_RF_SWITCH); #endif -#ifdef SX126X_RX_BOOSTED_GAIN + // always reapply: the gain may have been changed at runtime even when no build default is set radio->setRxBoostedGainMode(rx_boost_gain); -#endif #ifdef SX126X_REGISTER_PATCH uint8_t r_data = 0; radio->readRegister(0x8B5, &r_data, 1); From c5a0673d678512acb261625c9977dd7d5607d342 Mon Sep 17 00:00:00 2001 From: Rastislav Vysoky Date: Sat, 7 Nov 2026 00:35:47 +0100 Subject: [PATCH 09/10] added rp2350 support, harmonized companions with other variants --- platformio.ini | 3 +- variants/rpi_picow/PicoWBoard.h | 4 + variants/rpi_picow/platformio.ini | 135 ++++++++++++++++++++---------- 3 files changed, 97 insertions(+), 45 deletions(-) diff --git a/platformio.ini b/platformio.ini index 92c94204..9ad9c890 100644 --- a/platformio.ini +++ b/platformio.ini @@ -101,7 +101,8 @@ lib_deps = extends = arduino_base upload_protocol = picotool board_build.core = earlephilhower -platform = https://github.com/maxgerhardt/platform-raspberrypi.git ; framework-arduinopico @ 1.50600.0+sha.6a1d13e9 +platform = https://github.com/maxgerhardt/platform-raspberrypi.git +platform_packages = framework-arduinopico @ https://github.com/earlephilhower/arduino-pico.git#6a1d13e960e0854da2bf328b1a5fc05481d89aba build_flags = ${arduino_base.build_flags} -D RP2040_PLATFORM diff --git a/variants/rpi_picow/PicoWBoard.h b/variants/rpi_picow/PicoWBoard.h index e64590f2..1660fe91 100644 --- a/variants/rpi_picow/PicoWBoard.h +++ b/variants/rpi_picow/PicoWBoard.h @@ -42,7 +42,11 @@ public: } const char* getManufacturerName() const override { + #if defined(PICO_RP2350) + return "Pico 2 W"; + #else return "Pico W"; + #endif } void reboot() override { diff --git a/variants/rpi_picow/platformio.ini b/variants/rpi_picow/platformio.ini index 9814f397..94fc40aa 100644 --- a/variants/rpi_picow/platformio.ini +++ b/variants/rpi_picow/platformio.ini @@ -56,8 +56,8 @@ build_src_filter = ${rpi_picow.build_src_filter} [env:PicoW_companion_radio_usb] extends = rpi_picow build_flags = ${rpi_picow.build_flags} - -D MAX_CONTACTS=100 - -D MAX_GROUP_CHANNELS=8 + -D MAX_CONTACTS=350 + -D MAX_GROUP_CHANNELS=40 -D ENABLE_USB_INTERFACE ; NOTE: DO NOT ENABLE --> -D MESH_PACKET_LOGGING=1 ; NOTE: DO NOT ENABLE --> -D MESH_DEBUG=1 @@ -70,33 +70,14 @@ lib_ignore = BLE [env:PicoW_companion_radio_ble] extends = rpi_picow build_flags = ${rpi_picow.build_flags} - -D MAX_CONTACTS=100 - -D MAX_GROUP_CHANNELS=8 + -D MAX_CONTACTS=350 + -D MAX_GROUP_CHANNELS=40 -D PIO_FRAMEWORK_ARDUINO_ENABLE_BLUETOOTH + -D ENABLE_WIFI_INTERFACE -D BLE_PIN_CODE=123456 -D BLE_DEBUG_LOGGING=1 ; -D MESH_PACKET_LOGGING=1 ; -D MESH_DEBUG=1 -build_src_filter = ${rpi_picow.build_src_filter} - + - +<../examples/companion_radio/*.cpp> -lib_deps = ${rpi_picow.lib_deps} - densaugeo/base64 @ ~1.4.0 - -; USB + WiFi + BLE together; the interface manager fans frames out to all of them -[env:PicoW_companion_radio] -extends = rpi_picow -build_flags = ${rpi_picow.build_flags} - -D MAX_CONTACTS=100 - -D MAX_GROUP_CHANNELS=8 - -D ENABLE_USB_INTERFACE - -D ENABLE_WIFI_INTERFACE - -D PIO_FRAMEWORK_ARDUINO_ENABLE_BLUETOOTH - -D BLE_PIN_CODE=123456 -; NOTE: DO NOT ENABLE --> -D BLE_DEBUG_LOGGING=1 (shares Serial with the USB interface) -; NOTE: DO NOT ENABLE --> -D WIFI_DEBUG_LOGGING=1 -; -D MESH_PACKET_LOGGING=1 -; -D MESH_DEBUG=1 build_src_filter = ${rpi_picow.build_src_filter} + + @@ -104,29 +85,11 @@ build_src_filter = ${rpi_picow.build_src_filter} lib_deps = ${rpi_picow.lib_deps} densaugeo/base64 @ ~1.4.0 -[env:PicoW_companion_radio_wifi] -extends = rpi_picow -build_flags = ${rpi_picow.build_flags} - -D ENABLE_WIFI_INTERFACE - -D MAX_CONTACTS=100 - -D MAX_GROUP_CHANNELS=8 - -D WIFI_DEBUG_LOGGING=1 - -D WIFI_SSID='""' ; no default network, configure with 'set wifi.ssid' / 'set wifi.pwd' - -D WIFI_PWD='""' -; -D MESH_PACKET_LOGGING=1 -; -D MESH_DEBUG=1 -build_src_filter = ${rpi_picow.build_src_filter} - + - +<../examples/companion_radio/*.cpp> -lib_deps = ${rpi_picow.lib_deps} - densaugeo/base64 @ ~1.4.0 -lib_ignore = BLE - [env:PicoW_terminal_chat] extends = rpi_picow build_flags = ${rpi_picow.build_flags} - -D MAX_CONTACTS=100 - -D MAX_GROUP_CHANNELS=1 + -D MAX_CONTACTS=350 + -D MAX_GROUP_CHANNELS=40 ; -D MESH_PACKET_LOGGING=1 ; -D MESH_DEBUG=1 build_src_filter = ${rpi_picow.build_src_filter} @@ -138,3 +101,87 @@ lib_deps = ${rpi_picow.lib_deps} extends = rpi_picow build_src_filter = ${rpi_picow.build_src_filter} +<../examples/kiss_modem/> + +[rpi_pico2w] +extends = rp2040_base +board = rpipico2w +board_build.core = earlephilhower +board_build.filesystem_size = 0.5m +build_flags = ${rpi_picow.build_flags} +build_src_filter = ${rpi_picow.build_src_filter} +lib_deps = ${rpi_picow.lib_deps} + +[env:Pico2W_repeater] +extends = rpi_pico2w +build_flags = ${rpi_pico2w.build_flags} + -D ADVERT_NAME='"Pico2W 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 = ${rpi_pico2w.build_src_filter} + +<../examples/simple_repeater> + +[env:Pico2W_room_server] +extends = rpi_pico2w +build_flags = ${rpi_pico2w.build_flags} + -D ADVERT_NAME='"Test 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 = ${rpi_pico2w.build_src_filter} + +<../examples/simple_room_server> + +[env:Pico2W_companion_radio_usb] +extends = rpi_pico2w +build_flags = ${rpi_pico2w.build_flags} + -D MAX_CONTACTS=350 + -D MAX_GROUP_CHANNELS=40 + -D ENABLE_USB_INTERFACE +; NOTE: DO NOT ENABLE --> -D MESH_PACKET_LOGGING=1 +; NOTE: DO NOT ENABLE --> -D MESH_DEBUG=1 +build_src_filter = ${rpi_pico2w.build_src_filter} + +<../examples/companion_radio/*.cpp> +lib_deps = ${rpi_pico2w.lib_deps} + densaugeo/base64 @ ~1.4.0 +lib_ignore = BLE + +[env:Pico2W_companion_radio_ble] +extends = rpi_pico2w +build_flags = ${rpi_pico2w.build_flags} + -D MAX_CONTACTS=350 + -D MAX_GROUP_CHANNELS=40 + -D PIO_FRAMEWORK_ARDUINO_ENABLE_BLUETOOTH + -D ENABLE_WIFI_INTERFACE + -D BLE_PIN_CODE=123456 + -D BLE_DEBUG_LOGGING=1 +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 +build_src_filter = ${rpi_pico2w.build_src_filter} + + + + + +<../examples/companion_radio/*.cpp> +lib_deps = ${rpi_pico2w.lib_deps} + densaugeo/base64 @ ~1.4.0 + +[env:Pico2W_terminal_chat] +extends = rpi_pico2w +build_flags = ${rpi_pico2w.build_flags} + -D MAX_CONTACTS=350 + -D MAX_GROUP_CHANNELS=40 +; -D MESH_PACKET_LOGGING=1 +; -D MESH_DEBUG=1 +build_src_filter = ${rpi_pico2w.build_src_filter} + +<../examples/simple_secure_chat/main.cpp> +lib_deps = ${rpi_pico2w.lib_deps} + densaugeo/base64 @ ~1.4.0 + +[env:Pico2W_kiss_modem] +extends = rpi_pico2w +build_src_filter = ${rpi_pico2w.build_src_filter} + +<../examples/kiss_modem/> From 683680d83b0f475db1cc2a5bac4f58ff10e69687 Mon Sep 17 00:00:00 2001 From: Rastislav Vysoky Date: Sat, 7 Nov 2026 00:49:21 +0100 Subject: [PATCH 10/10] fix: pin to 5.6.0 --- platformio.ini | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platformio.ini b/platformio.ini index 9ad9c890..f66fbf2e 100644 --- a/platformio.ini +++ b/platformio.ini @@ -101,8 +101,8 @@ lib_deps = extends = arduino_base upload_protocol = picotool board_build.core = earlephilhower -platform = https://github.com/maxgerhardt/platform-raspberrypi.git -platform_packages = framework-arduinopico @ https://github.com/earlephilhower/arduino-pico.git#6a1d13e960e0854da2bf328b1a5fc05481d89aba +; commit points to framework-arduinopico 5.6.0 +platform = https://github.com/maxgerhardt/platform-raspberrypi.git#4e22a0dcdd94eead72fdf56ea59a3d7c8aa2f379 build_flags = ${arduino_base.build_flags} -D RP2040_PLATFORM