From fa18757f2c8a4fd160b903d8ecc982f69e7e018c Mon Sep 17 00:00:00 2001 From: agessaman Date: Wed, 23 Sep 2026 15:43:01 -0700 Subject: [PATCH] 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 {