#include "sx126x.h" #include "board.h" #include #include "freertos/FreeRTOS.h" #include "freertos/task.h" #include "freertos/semphr.h" #include "driver/spi_master.h" #include "driver/gpio.h" #include "esp_timer.h" #include "esp_rom_sys.h" // ---- opcodes ---- #define OP_SET_SLEEP 0x84 #define OP_SET_STANDBY 0x80 #define OP_SET_FS 0xC1 #define OP_SET_TX 0x83 #define OP_SET_RX 0x82 #define OP_SET_PACKET_TYPE 0x8A #define OP_GET_PACKET_TYPE 0x11 #define OP_SET_RF_FREQUENCY 0x86 #define OP_SET_PA_CONFIG 0x95 #define OP_SET_TX_PARAMS 0x8E #define OP_SET_MODULATION 0x8B #define OP_SET_PACKET_PARAMS 0x8C #define OP_SET_BUFFER_BASE 0x8F #define OP_WRITE_BUFFER 0x0E #define OP_READ_BUFFER 0x1E #define OP_WRITE_REGISTER 0x0D #define OP_READ_REGISTER 0x1D #define OP_SET_DIO_IRQ_PARAMS 0x08 #define OP_GET_IRQ_STATUS 0x12 #define OP_CLEAR_IRQ_STATUS 0x02 #define OP_SET_DIO2_RF_SWITCH 0x9D #define OP_SET_DIO3_TCXO_CTRL 0x97 #define OP_CALIBRATE 0x89 #define OP_CALIBRATE_IMAGE 0x98 #define OP_GET_STATUS 0xC0 #define OP_GET_RX_BUFFER_STATUS 0x13 #define OP_GET_PACKET_STATUS 0x14 #define OP_GET_RSSI_INST 0x15 #define OP_GET_DEVICE_ERRORS 0x17 #define OP_CLEAR_DEVICE_ERRORS 0x07 #define OP_SET_REGULATOR_MODE 0x96 #define OP_SET_RXTX_FALLBACK 0x93 // ---- registers ---- #define REG_SYNCWORD_0 0x06C0 #define REG_OCP 0x08E7 #define REG_RX_GAIN 0x08AC #define BUSY_TIMEOUT_US 20000 static spi_device_handle_t s_spi; static sx126x_irq_cb_t s_irq_cb; static uint8_t s_rx_payload_len = 255; static int8_t s_tx_dbm = -9; static SemaphoreHandle_t s_lock; // serializes SPI access across tasks static bool s_pa_low = true; // true = +10 dBm-optimal PA row (lowest output) // Preamble detector length. Shorter = more sensitive but more false syncs, // and every false sync costs one fixed-255-byte RX window (~12 ms). // SX126x codes: 0x00 off, 0x04 = 8 bits, 0x05 = 16, 0x06 = 24, 0x07 = 32. static uint8_t s_preamble_det = 0x04; // ---------------------------------------------------------------- low level static bool busy_wait(void) { int64_t t0 = esp_timer_get_time(); while (gpio_get_level(BOARD_LORA_BUSY)) { if (esp_timer_get_time() - t0 > BUSY_TIMEOUT_US) return false; esp_rom_delay_us(5); } return true; } static bool xfer(const uint8_t *tx, uint8_t *rx, size_t len) { if (s_lock) xSemaphoreTake(s_lock, portMAX_DELAY); bool ok = false; if (busy_wait()) { spi_transaction_t t = { .length = len * 8, .tx_buffer = tx, .rx_buffer = rx, }; ok = spi_device_polling_transmit(s_spi, &t) == ESP_OK; } if (s_lock) xSemaphoreGive(s_lock); return ok; } static bool cmd(uint8_t op, const uint8_t *args, size_t n) { uint8_t buf[16]; if (n + 1 > sizeof(buf)) return false; buf[0] = op; if (n) memcpy(buf + 1, args, n); return xfer(buf, NULL, n + 1); } static bool cmd_read(uint8_t op, uint8_t *out, size_t n) { // op + status byte + n data uint8_t tx[20] = {0}, rx[20] = {0}; if (n + 2 > sizeof(tx)) return false; tx[0] = op; if (!xfer(tx, rx, n + 2)) return false; memcpy(out, rx + 2, n); return true; } static bool write_regs(uint16_t addr, const uint8_t *data, size_t n) { uint8_t buf[16]; if (n + 3 > sizeof(buf)) return false; buf[0] = OP_WRITE_REGISTER; buf[1] = addr >> 8; buf[2] = addr & 0xFF; memcpy(buf + 3, data, n); return xfer(buf, NULL, n + 3); } static bool read_regs(uint16_t addr, uint8_t *out, size_t n) { uint8_t tx[20] = {0}, rx[20] = {0}; if (n + 4 > sizeof(tx)) return false; tx[0] = OP_READ_REGISTER; tx[1] = addr >> 8; tx[2] = addr & 0xFF; // byte 3 is a NOP/status byte before data if (!xfer(tx, rx, n + 4)) return false; memcpy(out, rx + 4, n); return true; } // ---------------------------------------------------------------- FEM static bool s_rx_csd_en = true; // LNA experiment: CSD level while in RX void fem_power(bool on) { gpio_set_level(BOARD_FEM_PWR_EN, on); gpio_set_level(BOARD_FEM_CSD, on && s_rx_csd_en); if (!on) gpio_set_level(BOARD_FEM_CTX, 0); } void fem_set_rx_csd(bool en) { s_rx_csd_en = en; } void fem_set_tx(bool tx) { // KCT8103L: CTX HIGH = TX/PA path, LOW = RX/LNA path. CPS is driven by // SX1262 DIO2 (DIO2-as-RF-switch), which the radio raises during TX. // TX always needs CSD high; in RX the CSD level is an LNA experiment // variable (CSD low is expected to bypass/disable the FEM RX chain). gpio_set_level(BOARD_FEM_CSD, tx || s_rx_csd_en); gpio_set_level(BOARD_FEM_CTX, tx); } // ---------------------------------------------------------------- IRQ static void IRAM_ATTR dio1_isr(void *arg) { (void)arg; if (s_irq_cb) s_irq_cb(esp_timer_get_time()); } void sx126x_set_irq_callback(sx126x_irq_cb_t cb) { s_irq_cb = cb; } // ---------------------------------------------------------------- init static bool radio_reset(void) { gpio_set_level(BOARD_LORA_RESET, 0); vTaskDelay(pdMS_TO_TICKS(2)); gpio_set_level(BOARD_LORA_RESET, 1); vTaskDelay(pdMS_TO_TICKS(5)); return busy_wait(); } bool sx126x_init(sx126x_diag_t *diag) { memset(diag, 0, sizeof(*diag)); // GPIO setup gpio_config_t out_cfg = { .pin_bit_mask = (1ULL << BOARD_LORA_RESET) | (1ULL << BOARD_FEM_PWR_EN) | (1ULL << BOARD_FEM_CSD) | (1ULL << BOARD_FEM_CTX), .mode = GPIO_MODE_OUTPUT, }; gpio_config(&out_cfg); gpio_config_t in_cfg = { .pin_bit_mask = (1ULL << BOARD_LORA_BUSY), .mode = GPIO_MODE_INPUT, }; gpio_config(&in_cfg); gpio_config_t irq_cfg = { .pin_bit_mask = (1ULL << BOARD_LORA_DIO1), .mode = GPIO_MODE_INPUT, .intr_type = GPIO_INTR_POSEDGE, }; gpio_config(&irq_cfg); gpio_install_isr_service(0); gpio_isr_handler_add(BOARD_LORA_DIO1, dio1_isr, NULL); // FEM: power up, enable, RX path gpio_set_level(BOARD_LORA_RESET, 1); fem_power(true); fem_set_tx(false); vTaskDelay(pdMS_TO_TICKS(5)); // SPI if (!s_lock) s_lock = xSemaphoreCreateMutex(); if (!s_spi) { spi_bus_config_t bus = { .sclk_io_num = BOARD_LORA_SCK, .mosi_io_num = BOARD_LORA_MOSI, .miso_io_num = BOARD_LORA_MISO, .quadwp_io_num = -1, .quadhd_io_num = -1, .max_transfer_sz = 300, }; if (spi_bus_initialize(SPI2_HOST, &bus, SPI_DMA_CH_AUTO) != ESP_OK) return false; spi_device_interface_config_t dev = { .clock_speed_hz = 8 * 1000 * 1000, .mode = 0, .spics_io_num = BOARD_LORA_NSS, .queue_size = 2, }; if (spi_bus_add_device(SPI2_HOST, &dev, &s_spi) != ESP_OK) return false; } diag->reset_ok = radio_reset(); diag->busy_ok = (gpio_get_level(BOARD_LORA_BUSY) == 0); // standby RC uint8_t stdby = 0x00; cmd(OP_SET_STANDBY, &stdby, 1); // SPI sanity: write + readback sync word registers uint8_t probe[2] = {0x54, 0x3D}, verify[2] = {0, 0}; write_regs(REG_SYNCWORD_0, probe, 2); read_regs(REG_SYNCWORD_0, verify, 2); diag->spi_ok = (verify[0] == 0x54 && verify[1] == 0x3D); // TCXO on DIO3 (1.8 V, ~4 ms). The first calibrate after enabling the // TCXO latches a benign XOSC_START_ERR (the XOSC block briefly probes // the crystal before DIO3 powers the TCXO). Correct sequence: enable, // clear stale errors, force STDBY_XOSC (actually starts the TCXO), // recalibrate, then judge the remaining error flags. uint8_t tcxo[4] = {BOARD_TCXO_VOLTAGE_CODE, 0x00, 0x00, BOARD_TCXO_DELAY_STEPS}; cmd(OP_SET_DIO3_TCXO_CTRL, tcxo, 4); cmd(OP_CLEAR_DEVICE_ERRORS, (uint8_t[]){0, 0}, 2); uint8_t stdby_xosc = 0x01; cmd(OP_SET_STANDBY, &stdby_xosc, 1); vTaskDelay(pdMS_TO_TICKS(10)); busy_wait(); bool xosc_running = (((sx126x_get_status() >> 4) & 0x7) == 0x3); cmd(OP_CLEAR_DEVICE_ERRORS, (uint8_t[]){0, 0}, 2); uint8_t calib = 0x7F; cmd(OP_CALIBRATE, &calib, 1); vTaskDelay(pdMS_TO_TICKS(10)); busy_wait(); uint16_t errs = sx126x_get_device_errors(); diag->device_errors = errs; diag->tcxo_ok = xosc_running && ((errs & 0x20) == 0); if (errs) cmd(OP_CLEAR_DEVICE_ERRORS, (uint8_t[]){0, 0}, 2); cmd(OP_SET_STANDBY, &(uint8_t){0x00}, 1); // DC-DC regulator (Heltec module has the inductor; RNode uses default LDO, // but SX1262 modules from Heltec are DCDC-capable. Use DCDC for lower // current; fall back to LDO if instability is ever observed.) uint8_t reg = 0x01; cmd(OP_SET_REGULATOR_MODE, ®, 1); // DIO2 drives the FEM CPS pin uint8_t dio2 = 0x01; cmd(OP_SET_DIO2_RF_SWITCH, &dio2, 1); // fallback to STDBY_RC after TX/RX uint8_t fb = 0x20; cmd(OP_SET_RXTX_FALLBACK, &fb, 1); diag->chip_mode = (sx126x_get_status() >> 4) & 0x7; return diag->spi_ok && diag->reset_ok && diag->tcxo_ok; } // ------------------------------------------------------------- wM-Bus C1 bool sx126x_config_wmbus_c1(uint32_t freq_hz, uint8_t rx_payload_len) { s_rx_payload_len = rx_payload_len; bool ok = true; uint8_t pkt_type = 0x00; // GFSK ok &= cmd(OP_SET_PACKET_TYPE, &pkt_type, 1); // image calibration for 863-870 MHz band ok &= cmd(OP_CALIBRATE_IMAGE, (uint8_t[]){0xD7, 0xDB}, 2); uint32_t frf = (uint32_t)(((uint64_t)freq_hz << 25) / 32000000ULL); uint8_t f[4] = {frf >> 24, frf >> 16, frf >> 8, frf}; ok &= cmd(OP_SET_RF_FREQUENCY, f, 4); // PA config. SX1262 datasheet table 13-21 documents optimal settings // per target power; we deliberately use the +10 dBm-optimal row // (paDutyCycle=0x01, hpMax=0x00) because it yields the lowest output // this chip supports, and the external KCT8103L PA adds gain after it. // s_pa_low=false selects the +14 dBm row for comparison experiments. ok &= s_pa_low ? cmd(OP_SET_PA_CONFIG, (uint8_t[]){0x01, 0x00, 0x00, 0x01}, 4) : cmd(OP_SET_PA_CONFIG, (uint8_t[]){0x02, 0x02, 0x00, 0x01}, 4); ok &= sx126x_set_tx_power(s_tx_dbm); // OCP uint8_t ocp = BOARD_SX1262_OCP; ok &= write_regs(REG_OCP, &ocp, 1); // Boosted RX gain uint8_t gain = 0x96; ok &= write_regs(REG_RX_GAIN, &gain, 1); // Modulation: 100 kbps, no shaping (wM-Bus C is plain FSK), // RX BW 234.3 kHz, fdev 45 kHz // br = 32 * 32e6 / 100e3 = 10240 = 0x002800 // fdev = 45e3 * 2^25 / 32e6 = 47186 = 0x00B852 uint8_t mod[8] = { 0x00, 0x28, 0x00, // bitrate 0x00, // no pulse shaping 0x0A, // RX BW 234.3 kHz 0x00, 0xB8, 0x52, // fdev }; ok &= cmd(OP_SET_MODULATION, mod, 8); // Sync word = wM-Bus T/C access code 0x543D. The two C-mode "mode bytes" // (54CD = frame A, 543D = frame B) are received/sent as payload so that // RX and TX can share one radio configuration. ok &= write_regs(REG_SYNCWORD_0, (uint8_t[]){0x54, 0x3D}, 2); ok &= cmd(OP_SET_BUFFER_BASE, (uint8_t[]){0x00, 0x00}, 2); // IRQs: enable ALL in the latch mask (diagnosis of missing TxDone/RxDone; // flags only latch when enabled here), route all to DIO1. uint8_t di[8] = { 0x03, 0xFF, // IRQ mask: all 0x02, 0x03, // DIO1: TxDone | RxDone | Timeout 0x00, 0x00, // DIO2 (RF switch) 0x00, 0x00, // DIO3 (TCXO) }; ok &= cmd(OP_SET_DIO_IRQ_PARAMS, di, 8); ok &= sx126x_restore_rx_payload_len(); return ok; } static bool set_packet_params(uint8_t payload_len) { // preamble 48 bits TX, detector 8 bits, sync 16 bits, fixed length, no // radio CRC (wM-Bus CRC is per-block, validated in software), no whitening uint8_t pp[9] = { 0x00, 0x30, // TX preamble length: 48 bits s_preamble_det, // preamble detector length (see s_preamble_det) 16, // sync word length in bits 0x00, // no address filtering 0x00, // fixed length packet payload_len, 0x01, // CRC off 0x00, // no whitening }; return cmd(OP_SET_PACKET_PARAMS, pp, 9); } bool sx126x_restore_rx_payload_len(void) { return set_packet_params(s_rx_payload_len); } bool sx126x_set_tx_power(int8_t dbm) { if (dbm < -9) dbm = -9; if (dbm > 14) dbm = 14; // deliberately capped: external FEM adds gain s_tx_dbm = dbm; uint8_t tp[2] = {(uint8_t)dbm, 0x02}; // ramp 40 us return cmd(OP_SET_TX_PARAMS, tp, 2); } // Integrity check: the sync word registers must still hold the wM-Bus // access code. A radio that was reset, slept, or glitched loses its // configuration while still reporting a plausible chip mode, so checking // the mode alone cannot detect that failure. bool sx126x_config_intact(void) { uint8_t v[2] = {0, 0}; if (!read_regs(REG_SYNCWORD_0, v, 2)) return false; return v[0] == 0x54 && v[1] == 0x3D; } // Fault injection for exercising the recovery ladder (see console `inject`). bool sx126x_inject_sleep(void) { // cold start: configuration is lost on wake uint8_t cfg = 0x00; return cmd(OP_SET_SLEEP, &cfg, 1); } bool sx126x_standby(void) { uint8_t stdby = 0x00; return cmd(OP_SET_STANDBY, &stdby, 1); } bool sx126x_set_rx(void) { fem_set_tx(false); sx126x_clear_irq(SX126X_IRQ_ALL); // RX continuous return cmd(OP_SET_RX, (uint8_t[]){0xFF, 0xFF, 0xFF}, 3); } bool sx126x_start_tx(const uint8_t *buf, uint8_t len) { if (!sx126x_standby()) return false; sx126x_clear_irq(SX126X_IRQ_ALL); if (!set_packet_params(len)) return false; // WriteBuffer needs op + offset + payload in one transaction static uint8_t txbuf[258]; txbuf[0] = OP_WRITE_BUFFER; txbuf[1] = 0x00; memcpy(txbuf + 2, buf, len); if (!xfer(txbuf, NULL, (size_t)len + 2)) return false; fem_set_tx(true); // TX timeout ~500 ms = 32000 * 15.625 us -> 0x007D00 if (!cmd(OP_SET_TX, (uint8_t[]){0x00, 0x7D, 0x00}, 3)) { fem_set_tx(false); return false; } return true; } uint16_t sx126x_get_irq(void) { uint8_t st[2] = {0, 0}; if (!cmd_read(OP_GET_IRQ_STATUS, st, 2)) return 0; return ((uint16_t)st[0] << 8) | st[1]; } bool sx126x_clear_irq(uint16_t mask) { return cmd(OP_CLEAR_IRQ_STATUS, (uint8_t[]){mask >> 8, mask & 0xFF}, 2); } int sx126x_read_rx(uint8_t *out, size_t maxlen, int8_t *rssi_dbm) { uint8_t st[2]; if (!cmd_read(OP_GET_RX_BUFFER_STATUS, st, 2)) return -1; uint8_t n = st[0], off = st[1]; if (n > maxlen) n = maxlen; if (rssi_dbm) { uint8_t ps[3] = {0}; if (cmd_read(OP_GET_PACKET_STATUS, ps, 3)) { *rssi_dbm = (int8_t)(-(int)ps[1] / 2); // RssiSync } else { *rssi_dbm = 0; } } static uint8_t rdbuf_tx[259]; static uint8_t rdbuf_rx[259]; memset(rdbuf_tx, 0, (size_t)n + 3); rdbuf_tx[0] = OP_READ_BUFFER; rdbuf_tx[1] = off; // byte 2 is status/NOP, data starts at byte 3 if (!xfer(rdbuf_tx, rdbuf_rx, (size_t)n + 3)) return -1; memcpy(out, rdbuf_rx + 3, n); return n; } int8_t sx126x_get_rssi_inst(void) { uint8_t v = 0; cmd_read(OP_GET_RSSI_INST, &v, 1); return (int8_t)(-(int)v / 2); } uint16_t sx126x_get_device_errors(void) { uint8_t e[2] = {0, 0}; if (!cmd_read(OP_GET_DEVICE_ERRORS, e, 2)) return 0xFFFF; return ((uint16_t)e[0] << 8) | e[1]; } bool sx126x_raw(uint8_t op, const uint8_t *args, size_t n_tx, uint8_t *rx, size_t rx_len) { uint8_t tx[32] = {0}, rxb[32] = {0}; size_t total = 1 + n_tx; if (rx_len > total) total = rx_len; if (total > sizeof(tx)) return false; tx[0] = op; if (n_tx) memcpy(tx + 1, args, n_tx); if (!xfer(tx, rxb, total)) return false; if (rx && rx_len) memcpy(rx, rxb, rx_len); return true; } uint8_t sx126x_get_status(void) { uint8_t tx[2] = {OP_GET_STATUS, 0}, rx[2] = {0, 0}; if (!xfer(tx, rx, 2)) return 0; return rx[1]; } void sx126x_set_pa_low(bool low) { s_pa_low = low; } void sx126x_set_preamble_detect(uint8_t code) { s_preamble_det = code; } uint8_t sx126x_get_preamble_detect(void) { return s_preamble_det; }