SX126x.h

Go to the documentation of this file.

/*
 * The MySensors Arduino library handles the wireless radio link and protocol
 * between your home built sensors/actuators and HA controller of choice.
 * The sensors forms a self healing radio network with optional repeaters. Each
 * repeater and gateway builds a routing tables in EEPROM which keeps track of the
 * network topology allowing messages to be routed to nodes.
 *
 * Created by Henrik Ekblad <[email protected]>
 * Copyright (C) 2013-2023 Sensnology AB
 * Full contributor list: https://github.com/mysensors/MySensors/graphs/contributors
 *
 * Documentation: http://www.mysensors.org
 * Support Forum: http://forum.mysensors.org
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * version 2 as published by the Free Software Foundation.
 *
 * Based on Olivier Mauti's RFM95 driver and Semtecs reference driver for the SX126x
 *
 * SX126x driver for MySensors, Copyright (C) 2020 Eduard Iten <[email protected]>
 *
 */
 
#ifndef _SX126x_h
#define _SX126x_h
 
#include <stdint.h>
 
// SX126x hardware defaults
#if !defined(SX126x_SPI)
#define SX126x_SPI hwSPI 
#endif
 
// default PIN assignments, can be overridden
#if defined(ARDUINO_ARCH_AVR)
#if defined(__AVR_ATmega32U4__)
#define DEFAULT_SX126x_IRQ_PIN          (3)             
#else
#define DEFAULT_SX126x_IRQ_PIN          (2)             
#endif
#elif defined(ARDUINO_ARCH_ESP8266)
#define DEFAULT_SX126x_IRQ_PIN          (5)             
#elif defined(ARDUINO_ARCH_ESP32)
#define DEFAULT_SX126x_IRQ_PIN          (16)                                                
#define DEFAULT_SX126x_IRQ_NUM          digitalPinToInterrupt(DEFAULT_SX126x_IRQ_PIN)       
#elif defined(ARDUINO_ARCH_SAMD)
#define DEFAULT_SX126x_IRQ_PIN          (2)             
#elif defined(LINUX_ARCH_RASPBERRYPI)
#define DEFAULT_SX126x_IRQ_PIN          (22)            
#elif defined(ARDUINO_ARCH_STM32F1)
#define DEFAULT_SX126x_IRQ_PIN          (PA3)           
#elif defined(TEENSYDUINO)
#define DEFAULT_SX126x_IRQ_PIN          (8)             
#else
#define DEFAULT_SX126x_IRQ_PIN          (2)             
#endif
 
#ifndef DEFAULT_SX126x_CS_PIN
#define DEFAULT_SX126x_CS_PIN           (SS)            
#endif
 
// Frequency helpers
#define SX126x_XTAL_FREQ ( double )32000000             
#define SX126x_FREQ_DIV  ( double )pow( 2.0, 25.0 )     
#define SX126x_FREQ_STEP ( double )( SX126x_XTAL_FREQ / SX126x_FREQ_DIV )   
 
// SX126x radio configurations: reg_1d, reg_1e, reg_26 (see datasheet)
#define SX126x_BW125CR45SF128 SX126x_BW_125KHZ | SX126x_CODING_RATE_4_5, SX126x_SPREADING_FACTOR_128CPS | SX126x_RX_PAYLOAD_CRC_ON, SX126x_AGC_AUTO_ON                                   
#define SX126x_BW500CR45SF128 SX126x_BW_500KHZ | SX126x_CODING_RATE_4_5, SX126x_SPREADING_FACTOR_128CPS | SX126x_RX_PAYLOAD_CRC_ON, SX126x_AGC_AUTO_ON                                   
#define SX126x_BW31_25CR48SF512 SX126x_BW_31_25KHZ | SX126x_CODING_RATE_4_8, SX126x_SPREADING_FACTOR_512CPS | SX126x_RX_PAYLOAD_CRC_ON, SX126x_AGC_AUTO_ON                               
#define SX126x_BW125CR48SF4096 SX126x_BW_125KHZ | SX126x_CODING_RATE_4_8, SX126x_SPREADING_FACTOR_4096CPS | SX126x_RX_PAYLOAD_CRC_ON, SX126x_AGC_AUTO_ON | SX126x_LOW_DATA_RATE_OPTIMIZE 
 
#define SX126x_BROADCAST_ADDRESS (255u)  
#define SX126x_ATC_TARGET_RANGE_DBM (2u) 
#define SX126x_RSSI_OFFSET (137u)        
#define SX126x_TARGET_RSSI (-70)         
#define SX126x_PROMISCUOUS (false)       
 
#if (MY_SX126x_MAX_POWER_LEVEL_DBM) <= (MY_SX126x_MIN_POWER_LEVEL_DBM)
#error SX126x_MAX_POWER_DBM has to be bigger than SX126x_MIN_POWER_DBM
#endif
 
#define SX126x_PACKET_HEADER_VERSION (1u)     
#define SX126x_MIN_PACKET_HEADER_VERSION (1u) 
 
#if !defined(SX126x_RETRY_TIMEOUT_MS)
// air-time approximation for timeout, 1 hop ~15 bytes payload - adjust if needed
// BW125/SF128: 50ms
// BW500/SF128: 15ms
// BW31.25/SF512: 900ms
// BW125/SF4096: 1500ms
#define SX126x_RETRY_TIMEOUT_MS (500ul) 
#endif
 
#if !defined(MY_SX126x_TX_TIMEOUT_MS)
#define MY_SX126x_TX_TIMEOUT_MS                 (5*1000ul)      
#endif
 
#ifndef MY_SX126x_TX_POWER_DBM
#define MY_SX126x_TX_POWER_DBM (13u)    // 20mW
#endif
 
// Frequency definitions
#define SX126x_169MHZ (169000000ul) 
#define SX126x_315MHZ (315000000ul) 
#define SX126x_434MHZ (433920000ul) 
#define SX126x_868MHZ (868100000ul) 
#define SX126x_915MHZ (915000000ul) 
 
#define SX126x_RETRIES (5u)                
#define SX126x_MAX_PACKET_LEN (0x40u)      
#define SX126x_PREAMBLE_LENGTH (8u)        
#define SX126x_CAD_TIMEOUT_MS (2 * 1000ul) 
 
#define SX126x_POWERUP_DELAY_MS 3    
#define SX126x_SLEEP_WARM_START 0x04 
 
 
#define SX126x_REG_OCP           0x08E7 
#define SX126x_REG_LORASW        0x0740 
 
 
typedef enum sx126xCommands_e {
    SX126x_RESET_STATS = 0x00,
    SX126x_CLR_IRQSTATUS = 0x02,
    SX126x_CLR_ERROR = 0x07,
    SX126x_CFG_DIOIRQ = 0x08,
    SX126x_SET_LORASYMBTIMEOUT = 0xA0,
    SX126x_WRITE_REGISTER = 0x0D,
    SX126x_WRITE_BUFFER = 0x0E,
    SX126x_GET_STATS = 0x10,
    SX126x_GET_PACKETTYPE = 0x11,
    SX126x_GET_IRQSTATUS = 0x12,
    SX126x_GET_RXBUFFERSTATUS = 0x13,
    SX126x_GET_PACKETSTATUS = 0x14,
    SX126x_GET_RSSIINST = 0x15,
    SX126x_GET_ERROR = 0x17,
    SX126x_READ_REGISTER = 0x1D,
    SX126x_READ_BUFFER = 0x1E,
    SX126x_SET_STANDBY = 0x80,
    SX126x_SET_RX = 0x82,
    SX126x_SET_TX = 0x83,
    SX126x_SET_SLEEP = 0x84,
    SX126x_SET_RFFREQUENCY = 0x86,
    SX126x_SET_CADPARAMS = 0x88,
    SX126x_CALIBRATE = 0x89,
    SX126x_SET_PACKETTYPE = 0x8A,
    SX126x_SET_MODULATIONPARAMS = 0x8B,
    SX126x_SET_PACKETPARAMS = 0x8C,
    SX126x_SET_TXPARAMS = 0x8E,
    SX126x_SET_BUFFERBASEADDRESS = 0x8F,
    SX126x_SET_TXFALLBACKMODE = 0x93,
    SX126x_SET_RXDUTYCYCLE = 0x94,
    SX126x_SET_PACONFIG = 0x95,
    SX126x_SET_REGULATORMODE = 0x96,
    SX126x_SET_TCXOMODE = 0x97,
    SX126x_CALIBRATEIMAGE = 0x98,
    SX126x_SET_RFSWITCHMODE = 0x9D,
    SX126x_SET_STOPRXTIMERONPREAMBLE = 0x9F,
    SX126x_GET_STATUS = 0xC0,
    SX126x_SET_FS = 0xC1,
    SX126x_SET_CAD = 0xC5,
    SX126x_SET_TXCONTINUOUSWAVE = 0xD1,
    SX126x_SET_TXCONTINUOUSPREAMBLE = 0xD2,
} sx126x_commands_t;
 
typedef enum {
    SX126x_STDBY_RC = 0x00,
    SX126x_STDBY_XOSC = 0x01,
} sx126x_radioStandbyModes_t;
 
typedef enum {
    SX126x_USE_LDO = 0x00, // default
    SX126x_USE_DCDC = 0x01,
} sx126x_radioRegulatorMode_t;
 
typedef enum {
    SX126x_PACKET_TYPE_GFSK = 0x00,
    SX126x_PACKET_TYPE_LORA = 0x01,
    SX126x_PACKET_TYPE_NONE = 0x0F,
} sx126x_radioPacketTypes_t;
 
typedef union {
    struct {
        uint8_t payloadLength;  
        uint8_t startPointer;   
    } fields;                   
    uint8_t values[2];          
} sx126x_rxBufferStatus_t;
 
typedef union {
    struct {
        uint8_t rawRssiPkt;     
        int8_t rawSnrPkt;       
        uint8_t rawSignalRssiPkt; 
    } fields;                   
    uint8_t values[3];          
} sx126x_packetStatus_t;
 
typedef union {
    struct {
        bool wakeUpRTC : 1; 
        uint8_t : 1;        
        bool warmStart : 1; 
        uint8_t : 5;        
    } fields;               
    uint8_t value;          
} sx126x_sleepParams_t;
 
typedef enum {
    SX126x_MODE_SLEEP = 0x00, 
    SX126x_MODE_STDBY_RC,     
    SX126x_MODE_STDBY_XOSC,   
    SX126x_MODE_FS,           
    SX126x_MODE_TX,           
    SX126x_MODE_RX,           
    SX126x_MODE_RX_DC,        
    SX126x_MODE_CAD           
} sx126x_radioModes_t;
 
typedef enum {
    LORA_SF5                                = 0x05,
    LORA_SF6                                = 0x06,
    LORA_SF7                                = 0x07,
    LORA_SF8                                = 0x08,
    LORA_SF9                                = 0x09,
    LORA_SF10                               = 0x0A,
    LORA_SF11                               = 0x0B,
    LORA_SF12                               = 0x0C,
} sx126x_loRaSpreadingFactors_t;
 
typedef enum {
    LORA_BW_500                             = 6,
    LORA_BW_250                             = 5,
    LORA_BW_125                             = 4,
    LORA_BW_062                             = 3,
    LORA_BW_041                             = 10,
    LORA_BW_031                             = 2,
    LORA_BW_020                             = 9,
    LORA_BW_015                             = 1,
    LORA_BW_010                             = 8,
    LORA_BW_007                             = 0,
} sx126x_loRaBandwidths_t;
 
typedef enum {
    LORA_CR_4_5                             = 0x01,
    LORA_CR_4_6                             = 0x02,
    LORA_CR_4_7                             = 0x03,
    LORA_CR_4_8                             = 0x04,
} sx126x_loRaCodingRates_t;
 
typedef enum {
    LORA_CAD_ON_1_SYMB  = 0x00,
    LORA_CAD_ON_2_SYMB  = 0x01,
    LORA_CAD_ON_4_SYMB  = 0x02,
    LORA_CAD_ON_8_SYMB  = 0x03,
    LORA_CAD_ON_16_SYMB = 0x04,
} sx126x_loRaCADSymbols_t;
 
typedef enum {
    SX126x_CAD_ONLY = 0x00,
    SX126x_CAD_RX   = 0x01,
} sx126x_cadExitModes_t;
 
typedef union {
    struct {
        sx126x_loRaCADSymbols_t cadSymbolsNum;      
        uint8_t cadDetPeak;                         
        uint8_t cadDetMin;                          
        sx126x_cadExitModes_t cadExitMode;          
        uint8_t cadTimeout1;                        
        uint8_t cadTimeout2;                        
        uint8_t cadTimeout3;                        
    } fields;                                       
    uint8_t values[7];                              
} sx126x_cadParameters_t;
 
// Define CAD parameters
 
typedef struct {
    union {
        struct {
            sx126x_loRaSpreadingFactors_t spreadingFactor;  
            sx126x_loRaBandwidths_t bandwidth;              
            sx126x_loRaCodingRates_t codingRate;            
            bool lowDatarateOptimize;                       
        } fields;                                           
        uint8_t values[8];                                  
    };
} sx126x_modulationParams_t;
 
typedef enum {
    PACKET_TYPE_GFSK                        = 0x00,
    PACKET_TYPE_LORA                        = 0x01,
    PACKET_TYPE_NONE                        = 0x0F,
} SX126x_packetTypes_t;
 
typedef struct {
    union {
        struct {
            uint8_t paDutyCycle;        
            uint8_t hpMax;              
            uint8_t deviceSel;          
            uint8_t paLut = 0x01;       
        } fields;                       
        uint8_t values[4];              
    };
} sx126x_paSettings_t;
 
typedef enum {
    RADIO_RAMP_10_US                        = 0x00,
    RADIO_RAMP_20_US                        = 0x01,
    RADIO_RAMP_40_US                        = 0x02,
    RADIO_RAMP_80_US                        = 0x03,
    RADIO_RAMP_200_US                       = 0x04,
    RADIO_RAMP_800_US                       = 0x05,
    RADIO_RAMP_1700_US                      = 0x06,
    RADIO_RAMP_3400_US                      = 0x07,
} sx126x_RampTimes_t;
 
typedef struct {
    union {
        struct {
            uint8_t power;                  
            sx126x_RampTimes_t rampTime;    
        } fields;                           
        uint8_t values[2];                  
    };
} sx126x_txSettings_t;
 
typedef uint16_t sx126x_sequenceNumber_t; // will eventually change to uint8_t in 3.0
typedef uint8_t sx126x_RSSI_t;
typedef int8_t sx126x_SNR_t;
typedef union {
    struct {
        uint8_t :5;             
        bool ackRssiReport :1;  
        bool ackReceived :1;    
        bool ackRequested :1;   
    } fields;                   
    uint8_t values;             
} sx126x_controlFlags_t;
 
typedef int8_t sx126x_powerLevel_t;
typedef struct {
    uint8_t version;                        
    uint8_t recipient;                      
    uint8_t sender;                         
    sx126x_controlFlags_t controlFlags;     
    sx126x_sequenceNumber_t sequenceNumber; 
} __attribute__((packed)) sx126x_header_t;
 
typedef struct {
    sx126x_sequenceNumber_t sequenceNumber; 
    sx126x_RSSI_t RSSI;                     
    sx126x_SNR_t SNR;                       
} __attribute__((packed)) sx126x_ack_t;
 
#define SX126x_HEADER_LEN sizeof(sx126x_header_t)                          
#define SX126x_MAX_PAYLOAD_LEN (SX126x_MAX_PACKET_LEN - SX126x_HEADER_LEN) 
 
 
typedef struct {
    union {
        struct {
            sx126x_header_t header; 
            union {
                uint8_t payload[SX126x_MAX_PAYLOAD_LEN]; 
                sx126x_ack_t ACK;                        
            };
        };
        uint8_t data[SX126x_MAX_PACKET_LEN]; 
    };
    uint8_t payloadLen; 
    sx126x_RSSI_t RSSI; 
    sx126x_SNR_t SNR;   
} __attribute__((packed)) sx126x_packet_t;
 
typedef struct {
    uint8_t address;                          
    sx126x_packet_t currentPacket;            
    sx126x_sequenceNumber_t txSequenceNumber; 
    sx126x_powerLevel_t powerLevel;           
    sx126x_radioModes_t radioMode;            
    sx126x_powerLevel_t targetRSSI;           
    bool ATCenabled;                          
    bool channelActive : 1;                   
    bool channelFree : 1;                     
    volatile bool ackReceived : 1;            
    volatile bool dataReceived : 1;           
    volatile bool txComplete : 1;             
    volatile bool irqFired : 1;               
} sx126x_internal_t;
 
typedef enum {
    SX126x_TCXO_1V6 = 0x00,
    SX126x_TCXO_1V7,
    SX126x_TCXO_1V8,
    SX126x_TCXO_2V2,
    SX126x_TCXO_2V4,
    SX126x_TCXO_2V7,
    SX126x_TCXO_3V0,
    SX126x_TCXO_3V3,
} sx126x_tcxoVoltage_t;
 
typedef enum {
    SX126x_IRQ_NONE                          = 0x0000,
    SX126x_IRQ_TX_DONE                       = 0x0001,
    SX126x_IRQ_RX_DONE                       = 0x0002,
    SX126x_IRQ_PREAMBLE_DETECTED             = 0x0004,
    SX126x_IRQ_SYNCWORD_VALID                = 0x0008,
    SX126x_IRQ_HEADER_VALID                  = 0x0010,
    SX126x_IRQ_HEADER_ERROR                  = 0x0020,
    SX126x_IRQ_CRC_ERROR                     = 0x0040,
    SX126x_IRQ_CAD_DONE                      = 0x0080,
    SX126x_IRQ_CAD_ACTIVITY_DETECTED         = 0x0100,
    SX126x_IRQ_RX_TX_TIMEOUT                 = 0x0200,
    SX126x_IRQ_ALL                           = 0xFFFF,
} sx126x_irqMasks_t;
 
static void
SX126x_sendCommand(sx126x_commands_t command, uint8_t *buffer, uint16_t size);
 
static void SX126x_sendCommand(sx126x_commands_t command, uint8_t parameter);
 
static void SX126x_readCommand(sx126x_commands_t command, uint8_t *buffer, uint16_t size);
 
static void SX126x_sendRegisters(uint16_t address, uint8_t *buffer, uint16_t size);
 
static void SX126x_sendRegister(uint16_t address, uint8_t value);
 
static bool SX126x_initialise();
 
static void SX126x_wakeUp();
 
static void SX126x_standBy();
 
static void SX126x_busy();
 
static void SX126x_sleep();
 
static void SX126x_interruptHandler();
 
static void SX126x_handle();
 
static bool SX126x_txPower(sx126x_powerLevel_t power);
 
static void SX126x_setFrequency(uint32_t frequency);
 
static void SX126x_setIrqMask(uint16_t mask);
 
static void SX126x_clearIrq(uint16_t mask);
 
static void SX126x_setPacketParameters(uint8_t length);
 
static bool SX126x_sanityCheck();
 
static void SX126x_setAddress(uint8_t address);
 
static uint8_t SX126x_getAddress(void);
 
static bool SX126x_sendWithRetry(const uint8_t recipient, const void *buffer,
                                 const uint8_t bufferSize, const bool noACK);
 
static bool SX126x_send(const uint8_t recipient, uint8_t *data, const uint8_t len,
                        const sx126x_controlFlags_t flags);
static bool SX126x_sendPacket(sx126x_packet_t *packet);
 
static void SX126x_sendBuffer(const uint8_t offset, const uint8_t *buffer, const uint8_t size);
 
static void SX126x_readBuffer(const uint8_t offset, uint8_t *buffer, const uint8_t size);
 
static void SX126x_tx();
 
 
static void SX126x_rx();
 
static bool SX126x_cad();
 
static bool SX126x_packetAvailable();
 
static uint8_t SX126x_getData(uint8_t *buffer, const uint8_t bufferSize);
 
static void SX126x_sendAck(const uint8_t recipient, const sx126x_sequenceNumber_t sequenceNumber,
                           const sx126x_RSSI_t RSSI, const sx126x_SNR_t SNR);
 
static void SX126x_ATC();
 
static void SX126x_setATC(bool onOff, int8_t targetRSSI);
 
static int16_t SX126x_getSendingRSSI();
 
static int16_t SX126x_getSendingSNR();
 
static int16_t SX126x_getReceivingRSSI();
 
static int16_t SX126x_getReceivingSNR();
 
static int8_t SX126x_getTxPowerLevel();
 
static uint8_t SX126x_getTxPowerPercent();
 
static bool SX126x_setTxPowerPercent(const uint8_t newPowerPercent);
 
#endif