RFM95.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-2022 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 Mike McCauley's RFM95 library, Copyright (C) 2014 Mike McCauley <[email protected]>
 * Radiohead http://www.airspayce.com/mikem/arduino/RadioHead/index.html
 *
 * RFM95 driver refactored and optimized for MySensors, Copyright (C) 2017-2018 Olivier Mauti <[email protected]>
 *
 * Changelog:
 * - ACK with sequenceNumber
 * - ATC control
 *
 * Definitions for HopeRF LoRa radios:
 * http://www.hoperf.com/upload/rf/RFM95_96_97_98W.pdf
 *
 */
 
#ifndef _RFM95_h
#define _RFM95_h
 
#include "RFM95registers.h"
 
#if !defined(RFM95_SPI)
#define RFM95_SPI hwSPI 
#endif
 
// default PIN assignments, can be overridden
#if defined(ARDUINO_ARCH_AVR)
#if defined(__AVR_ATmega32U4__)
#define DEFAULT_RFM95_IRQ_PIN           (3)             
#else
#define DEFAULT_RFM95_IRQ_PIN           (2)             
#endif
#elif defined(ARDUINO_ARCH_ESP8266)
#define DEFAULT_RFM95_IRQ_PIN           (5)             
#elif defined(ARDUINO_ARCH_ESP32)
#define DEFAULT_RFM95_IRQ_PIN           (16)                                                
#define DEFAULT_RFM95_IRQ_NUM           digitalPinToInterrupt(DEFAULT_RFM95_IRQ_PIN)        
#elif defined(ARDUINO_ARCH_SAMD)
#define DEFAULT_RFM95_IRQ_PIN           (2)             
#elif defined(LINUX_ARCH_RASPBERRYPI)
#define DEFAULT_RFM95_IRQ_PIN           (22)            
#elif defined(ARDUINO_ARCH_STM32F1)
#define DEFAULT_RFM95_IRQ_PIN           (PA3)           
#elif defined(TEENSYDUINO)
#define DEFAULT_RFM95_IRQ_PIN           (8)             
#else
#define DEFAULT_RFM95_IRQ_PIN           (2)             
#endif
 
#define DEFAULT_RFM95_CS_PIN            (SS)            
 
// SPI settings
#define RFM95_SPI_DATA_ORDER        MSBFIRST        
#define RFM95_SPI_DATA_MODE         SPI_MODE0       
 
// RFM95 radio configurations: reg_1d, reg_1e, reg_26 (see datasheet)
#define RFM95_BW125CR45SF128 RFM95_BW_125KHZ | RFM95_CODING_RATE_4_5, RFM95_SPREADING_FACTOR_128CPS | RFM95_RX_PAYLOAD_CRC_ON, RFM95_AGC_AUTO_ON 
#define RFM95_BW500CR45SF128 RFM95_BW_500KHZ | RFM95_CODING_RATE_4_5, RFM95_SPREADING_FACTOR_128CPS | RFM95_RX_PAYLOAD_CRC_ON, RFM95_AGC_AUTO_ON 
#define RFM95_BW31_25CR48SF512 RFM95_BW_31_25KHZ | RFM95_CODING_RATE_4_8, RFM95_SPREADING_FACTOR_512CPS | RFM95_RX_PAYLOAD_CRC_ON, RFM95_AGC_AUTO_ON 
#define RFM95_BW125CR48SF4096   RFM95_BW_125KHZ | RFM95_CODING_RATE_4_8, RFM95_SPREADING_FACTOR_4096CPS | RFM95_RX_PAYLOAD_CRC_ON, RFM95_AGC_AUTO_ON | RFM95_LOW_DATA_RATE_OPTIMIZE 
 
#if !defined(RFM95_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 RFM95_RETRY_TIMEOUT_MS          (500ul)         
#endif
 
#if !defined(MY_RFM95_TX_TIMEOUT_MS)
#define MY_RFM95_TX_TIMEOUT_MS                 (5*1000ul)       
#endif
 
// Frequency definitions
#define RFM95_169MHZ                           (169000000ul)    
#define RFM95_315MHZ                           (315000000ul)    
#define RFM95_434MHZ                           (433920000ul)    
#define RFM95_868MHZ                           (868100000ul)    
#define RFM95_915MHZ                           (915000000ul)    
 
#define RFM95_RETRIES                          (5u)                 
#define RFM95_FIFO_SIZE                        (0xFFu)          
#define RFM95_RX_FIFO_ADDR                     (0x00u)          
#define RFM95_TX_FIFO_ADDR                     (0x80u)          
#define RFM95_MAX_PACKET_LEN                   (0x40u)          
#define RFM95_PREAMBLE_LENGTH                  (8u)                 
#define RFM95_CAD_TIMEOUT_MS                   (2*1000ul)       
#define RFM95_POWERUP_DELAY_MS                 (100u)               
 
#define RFM95_PACKET_HEADER_VERSION            (1u)         
#define RFM95_MIN_PACKET_HEADER_VERSION        (1u)         
#define RFM95_BIT_ACK_REQUESTED                (7u)         
#define RFM95_BIT_ACK_RECEIVED                 (6u)         
#define RFM95_BIT_ACK_RSSI_REPORT              (5u)         
 
#define RFM95_BROADCAST_ADDRESS                (255u)           
#define RFM95_ATC_TARGET_RANGE_DBM             (2u)         
#define RFM95_RSSI_OFFSET                      (137u)           
#define RFM95_TARGET_RSSI                      (-70)            
#define RFM95_PROMISCUOUS                      (false)          
 
#define RFM95_FXOSC                            (32*1000000ul)               
#define RFM95_FSTEP                            (RFM95_FXOSC / 524288.0f)    
 
// helper macros
#define RFM95_getACKRequested(__value) ((bool)bitRead(__value, RFM95_BIT_ACK_REQUESTED))                
#define RFM95_setACKRequested(__value, __flag) bitWrite(__value, RFM95_BIT_ACK_REQUESTED,__flag)        
#define RFM95_getACKReceived(__value) ((bool)bitRead(__value, RFM95_BIT_ACK_RECEIVED))                  
#define RFM95_setACKReceived(__value, __flag) bitWrite(__value, RFM95_BIT_ACK_RECEIVED,__flag)          
#define RFM95_setACKRSSIReport(__value, __flag) bitWrite(__value, RFM95_BIT_ACK_RSSI_REPORT,__flag)     
#define RFM95_getACKRSSIReport(__value) ((bool)bitRead(__value, RFM95_BIT_ACK_RSSI_REPORT))             
#define RFM95_internalToSNR(__value)    ((int8_t)(__value / 4))                     
 
#define RFM95_MIN_POWER_LEVEL_DBM       ((rfm95_powerLevel_t)5u)    
#if defined(MY_RFM95_MAX_POWER_LEVEL_DBM)
#define RFM95_MAX_POWER_LEVEL_DBM       MY_RFM95_MAX_POWER_LEVEL_DBM    
#else
#define RFM95_MAX_POWER_LEVEL_DBM       ((rfm95_powerLevel_t)23u)   
#endif
 
typedef enum {
    RFM95_RADIO_MODE_RX = 0,                    
    RFM95_RADIO_MODE_TX = 1,                    
    RFM95_RADIO_MODE_CAD = 2,                   
    RFM95_RADIO_MODE_SLEEP = 3,                 
    RFM95_RADIO_MODE_STDBY = 4                  
} rfm95_radioMode_t;
 
typedef struct {
    uint8_t reg_1d; 
    uint8_t reg_1e; 
    uint8_t reg_26; 
} rfm95_modemConfig_t;
 
typedef uint16_t rfm95_sequenceNumber_t;        // will eventually change to uint8_t in 3.0
typedef uint8_t rfm95_RSSI_t;
typedef int8_t rfm95_SNR_t;
typedef uint8_t rfm95_controlFlags_t;
typedef int8_t rfm95_powerLevel_t;
typedef struct {
    uint8_t version;                                
    uint8_t recipient;                              
    uint8_t sender;                                 
    rfm95_controlFlags_t controlFlags;              
    rfm95_sequenceNumber_t sequenceNumber;          
} __attribute__((packed)) rfm95_header_t;
 
typedef struct {
    rfm95_sequenceNumber_t sequenceNumber;              
    rfm95_RSSI_t RSSI;                                  
    rfm95_SNR_t SNR;                                    
} __attribute__((packed)) rfm95_ack_t;
 
 
#define RFM95_HEADER_LEN sizeof(rfm95_header_t)     
#define RFM95_MAX_PAYLOAD_LEN (RFM95_MAX_PACKET_LEN - RFM95_HEADER_LEN) 
 
 
typedef struct {
    union {
        struct {
            rfm95_header_t header;                      
            union {
                uint8_t payload[RFM95_MAX_PAYLOAD_LEN]; 
                rfm95_ack_t ACK;                        
            };
        };
        uint8_t data[RFM95_MAX_PACKET_LEN];             
    };
    uint8_t payloadLen;                                 
    rfm95_RSSI_t RSSI;                                  
    rfm95_SNR_t SNR;                                    
} __attribute__((packed)) rfm95_packet_t;
 
 
typedef struct {
    uint8_t address;                          
    rfm95_packet_t currentPacket;             
    rfm95_sequenceNumber_t txSequenceNumber;  
    rfm95_powerLevel_t powerLevel;            
    rfm95_RSSI_t ATCtargetRSSI;               
    // 8 bit
    rfm95_radioMode_t radioMode : 3;          
    bool channelActive : 1;                   
    bool ATCenabled : 1;                      
    bool ackReceived : 1;                     
    bool dataReceived : 1;                    
    bool reserved : 1;                        
} rfm95_internal_t;
 
#define LOCAL static        
 
 
LOCAL bool RFM95_initialise(const uint32_t frequencyHz);
LOCAL void RFM95_setAddress(const uint8_t addr);
LOCAL uint8_t RFM95_getAddress(void);
LOCAL void RFM95_setModemRegisters(const rfm95_modemConfig_t *config);
LOCAL bool RFM95_available(void);
LOCAL uint8_t RFM95_receive(uint8_t *buf, const uint8_t maxBufSize);
LOCAL bool RFM95_send(const uint8_t recipient, uint8_t *data, const uint8_t len,
                      const rfm95_controlFlags_t flags, const bool increaseSequenceCounter = true);
LOCAL bool RFM95_sendFrame(rfm95_packet_t *packet, const bool increaseSequenceCounter = true);
LOCAL void RFM95_setPreambleLength(const uint16_t preambleLength);
LOCAL void RFM95_setFrequency(const uint32_t frequencyHz);
LOCAL bool RFM95_setTxPowerLevel(rfm95_powerLevel_t newPowerLevel);
 
LOCAL bool RFM95_setTxPowerPercent(const uint8_t newPowerPercent);
 
LOCAL void RFM95_enableTCXO(void);
 
LOCAL bool RFM95_sleep(void);
LOCAL bool RFM95_standBy(void);
LOCAL void RFM95_powerDown(void);
LOCAL void RFM95_powerUp(void);
LOCAL void RFM95_sendACK(const uint8_t recipient, const rfm95_sequenceNumber_t sequenceNumber,
                         const rfm95_RSSI_t RSSI, const rfm95_SNR_t SNR);
LOCAL bool RFM95_sendWithRetry(const uint8_t recipient, const void *buffer,
                               const uint8_t bufferSize, const bool noACK);
LOCAL bool RFM95_waitCAD(void);
 
LOCAL bool RFM95_setRadioMode(const rfm95_radioMode_t newRadioMode);
LOCAL void RFM95_interruptHandler(void);
 
LOCAL void RFM95_interruptHandling(void);
 
LOCAL void RFM95_handler(void);
LOCAL int16_t RFM95_getReceivingRSSI(void);
LOCAL int16_t RFM95_getSendingRSSI(void);
LOCAL int16_t RFM95_getReceivingSNR(void);
LOCAL int16_t RFM95_getSendingSNR(void);
LOCAL uint8_t RFM95_getTxPowerPercent(void);
LOCAL uint8_t RFM95_getTxPowerLevel(void);
LOCAL bool RFM95_executeATC(const rfm95_RSSI_t currentRSSI, const rfm95_RSSI_t targetRSSI);
LOCAL void RFM95_ATCmode(const bool OnOff, const int16_t targetRSSI = RFM95_TARGET_RSSI);
LOCAL bool RFM95_sanityCheck(void);
 
#endif