MySensors Library & Examples  2.2.0-61-g15351cd
Classes | Macros | Typedefs | Enumerations | Functions | Variables
+ Collaboration diagram for RFM95:

Detailed Description

API declaration for RFM95.

RFM95 driver-related log messages, format: [!]SYSTEM:[SUB SYSTEM:]MESSAGE

ESYS SUB Message Comment
RFM95 INIT Initialise RFM95 radio
RFM95 INIT PIN,CS=%d,IQP=%d,IQN=%d[,RST=%d] Pin configuration: chip select (CS), IRQ pin (IQP), IRQ number (IQN), Reset (RST)
!RFM95 INIT SANCHK FAIL Sanity check failed, check wiring or replace module
!RFM95 IRH CRC FAIL Incoming packet has CRC error, skip
RFM95 RCV SEND ACK ACK request received, sending ACK back
RFM95 PTC LEVEL=%d Set TX power level
RFM95 SAC SEND ACK,TO=%d,RSSI=%d,SNR=%d Send ACK to node (TO), RSSI of received message (RSSI), SNR of message (SNR)
RFM95 ATC ADJ TXL,cR=%d,tR=%d..%d,TXL=%d Adjust TX level, current RSSI (cR), target RSSI range (tR), TX level (TXL)
RFM95 SWR SEND,TO=%d,RETRY=%d Send message to (TO), NACK retry counter (RETRY)
RFM95 SWR ACK FROM=%d,SEQ=%d,RSSI=%d,SNR=%d ACK received from node (FROM), seq ID (SEQ), (RSSI), (SNR)
!RFM95 SWR NACK No ACK received
RFM95 SPP PCT=%d,TX LEVEL=%d Set TX level percent (PCT), TX level (LEVEL)
RFM95 PWD Power down radio
RFM95 PWU Power up radio

RFM95 modem configuration

BW = Bandwidth in kHz CR = Error correction code SF = Spreading factor, chips / symbol

CONFIG BW CR SF Comment air-time (15 bytes)
BW125CR45SF128 125 4/5 128 Default, medium range 50ms
BW500CR45SF128 500 4/5 128 Fast, short range 15ms
BW31_25CR48SF512 31.25 4/8 512 Slow, long range 900ms
BW125CR48SF4096 125 4/8 4096 Slow, long range 1500ms

See here for air-time calculation: https://docs.google.com/spreadsheets/d/1voGAtQAjC1qBmaVuP1ApNKs1ekgUjavHuVQIXyYSvNc

Classes

struct  rfm95_modemConfig_t
 RFM95 modem config registers. More...
 
struct  __attribute__
 FW config structure, stored in eeprom. More...
 
struct  rfm95_internal_t
 RFM95 internal variables. More...
 

Macros

#define DEFAULT_RFM95_IRQ_PIN   (2)
 DEFAULT_RFM95_IRQ_PIN.
 
#define DEFAULT_RFM95_CS_PIN   (SS)
 DEFAULT_RFM95_CS_PIN.
 
#define RFM95_SPI_DATA_ORDER   MSBFIRST
 SPI data order.
 
#define RFM95_SPI_DATA_MODE   SPI_MODE0
 SPI mode.
 
#define RFM95_SPI   SPI
 SPI.
 
#define RFM95_BW125CR45SF128   RFM95_BW_125KHZ | RFM95_CODING_RATE_4_5, RFM95_SPREADING_FACTOR_128CPS | RFM95_RX_PAYLOAD_CRC_ON, RFM95_AGC_AUTO_ON
 0x72,0x74,0x04
 
#define RFM95_BW500CR45SF128   RFM95_BW_500KHZ | RFM95_CODING_RATE_4_5, RFM95_SPREADING_FACTOR_128CPS | RFM95_RX_PAYLOAD_CRC_ON, RFM95_AGC_AUTO_ON
 0x92,0x74,0x04
 
#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
 0x48,0x94,0x04
 
#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
 0x78,0xc4,0x0C
 
#define RFM95_RETRY_TIMEOUT_MS   (500ul)
 Timeout for ACK, adjustments needed if modem configuration changed (air time different)
 
#define MY_RFM95_TX_TIMEOUT_MS   (5*1000ul)
 TX timeout.
 
#define RFM95_169MHZ   (169000000ul)
 169 Mhz
 
#define RFM95_315MHZ   (315000000ul)
 315 Mhz
 
#define RFM95_434MHZ   (433920000ul)
 433.92 Mhz
 
#define RFM95_868MHZ   (868100000ul)
 868.1 Mhz
 
#define RFM95_915MHZ   (915000000ul)
 915 Mhz
 
#define RFM95_RETRIES   (5u)
 Retries in case of failed transmission.
 
#define RFM95_FIFO_SIZE   (0xFFu)
 Max number of bytes the LORA Rx/Tx FIFO can hold.
 
#define RFM95_RX_FIFO_ADDR   (0x00u)
 RX FIFO addr pointer.
 
#define RFM95_TX_FIFO_ADDR   (0x80u)
 TX FIFO addr pointer.
 
#define RFM95_MAX_PACKET_LEN   (0x40u)
 This is the maximum number of bytes that can be carried by the LORA.
 
#define RFM95_PREAMBLE_LENGTH   (8u)
 Preamble length, default=8.
 
#define RFM95_CAD_TIMEOUT_MS   (2*1000ul)
 channel activity detection timeout
 
#define RFM95_POWERUP_DELAY_MS   (100u)
 Power up delay, allow VCC to settle, transport to become fully operational.
 
#define RFM95_PACKET_HEADER_VERSION   (1u)
 RFM95 packet header version.
 
#define RFM95_MIN_PACKET_HEADER_VERSION   (1u)
 Minimal RFM95 packet header version.
 
#define RFM95_BIT_ACK_REQUESTED   (7u)
 RFM95 header, controlFlag, bit 7.
 
#define RFM95_BIT_ACK_RECEIVED   (6u)
 RFM95 header, controlFlag, bit 6.
 
#define RFM95_BIT_ACK_RSSI_REPORT   (5u)
 RFM95 header, controlFlag, bit 5.
 
#define RFM95_BROADCAST_ADDRESS   (255u)
 Broadcasting address.
 
#define RFM95_ATC_TARGET_RANGE_DBM   (2u)
 ATC target range +/- dBm.
 
#define RFM95_RSSI_OFFSET   (137u)
 RSSI offset.
 
#define RFM95_TARGET_RSSI   (-70)
 RSSI target.
 
#define RFM95_PROMISCUOUS   (false)
 RFM95 promiscuous mode.
 
#define RFM95_FXOSC   (32*1000000ul)
 The crystal oscillator frequency of the module.
 
#define RFM95_FSTEP   (RFM95_FXOSC / 524288.0f)
 The Frequency Synthesizer step.
 
#define RFM95_getACKRequested(__value)   ((bool)bitRead(__value, RFM95_BIT_ACK_REQUESTED))
 getACKRequested
 
#define RFM95_setACKRequested(__value, __flag)   bitWrite(__value, RFM95_BIT_ACK_REQUESTED,__flag)
 setACKRequested
 
#define RFM95_getACKReceived(__value)   ((bool)bitRead(__value, RFM95_BIT_ACK_RECEIVED))
 getACKReceived
 
#define RFM95_setACKReceived(__value, __flag)   bitWrite(__value, RFM95_BIT_ACK_RECEIVED,__flag)
 setACKReceived
 
#define RFM95_setACKRSSIReport(__value, __flag)   bitWrite(__value, RFM95_BIT_ACK_RSSI_REPORT,__flag)
 setACKRSSIReport
 
#define RFM95_getACKRSSIReport(__value)   ((bool)bitRead(__value, RFM95_BIT_ACK_RSSI_REPORT))
 getACKRSSIReport
 
#define RFM95_internalToSNR(__value)   ((int8_t)(__value / 4))
 Convert internal SNR to SNR.
 
#define RFM95_MIN_POWER_LEVEL_DBM   ((rfm95_powerLevel_t)5u)
 min. power level
 
#define RFM95_MAX_POWER_LEVEL_DBM   ((rfm95_powerLevel_t)23u)
 max. power level
 
#define RFM95_HEADER_LEN   sizeof(rfm95_header_t)
 Size header inside LoRa payload.
 
#define RFM95_MAX_PAYLOAD_LEN   (RFM95_MAX_PACKET_LEN - RFM95_HEADER_LEN)
 Max payload length.
 
#define LOCAL   static
 static
 

Typedefs

typedef uint16_t rfm95_sequenceNumber_t
 Sequence number data type.
 
typedef uint8_t rfm95_RSSI_t
 RSSI data type.
 
typedef int8_t rfm95_SNR_t
 SNR data type.
 
typedef uint8_t rfm95_controlFlags_t
 Control flag data type.
 
typedef int8_t rfm95_powerLevel_t
 Power level in dBm.
 

Enumerations

enum  rfm95_radioMode_t {
  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
}
 Radio modes. More...
 

Functions

LOCAL bool RFM95_initialise (const uint32_t frequencyHz)
 Initialise the driver transport hardware and software. More...
 
LOCAL void RFM95_setAddress (const uint8_t addr)
 Set the driver/node address. More...
 
LOCAL uint8_t RFM95_getAddress (void)
 Get driver/node address. More...
 
LOCAL void RFM95_setModemRegisters (const rfm95_modemConfig_t *config)
 Sets all the registers required to configure the data modem in the RF95/96/97/98, including the bandwidth, spreading factor etc. More...
 
LOCAL bool RFM95_available (void)
 Tests whether a new message is available. More...
 
LOCAL uint8_t RFM95_receive (uint8_t *buf, const uint8_t maxBufSize)
 If a valid message is received, copy it to buf and return length. 0 byte messages are permitted. More...
 
LOCAL bool RFM95_send (const uint8_t recipient, uint8_t *data, const uint8_t len, const rfm95_controlFlags_t flags, const bool increaseSequenceCounter=true)
 RFM95_send. More...
 
LOCAL bool RFM95_sendFrame (rfm95_packet_t *packet, const bool increaseSequenceCounter=true)
 RFM95_sendFrame. More...
 
LOCAL void RFM95_setPreambleLength (const uint16_t preambleLength)
 RFM95_setPreambleLength. More...
 
LOCAL void RFM95_setFrequency (const uint32_t frequencyHz)
 Sets the transmitter and receiver centre frequency. More...
 
LOCAL bool RFM95_setTxPowerLevel (rfm95_powerLevel_t newPowerLevel)
 Sets the transmitter power output level, and configures the transmitter pin. More...
 
LOCAL bool RFM95_setTxPowerPercent (const uint8_t newPowerPercent)
 Sets the transmitter power output percent. More...
 
LOCAL void RFM95_enableTCXO (void)
 Enable TCXO mode Call this immediately after init(), to force your radio to use an external frequency source, such as a Temperature Compensated Crystal Oscillator (TCXO). See the comments in the main documentation about the sensitivity of this radio to clock frequency especially when using narrow bandwidths. More...
 
LOCAL bool RFM95_sleep (void)
 Sets the radio into low-power sleep mode. More...
 
LOCAL bool RFM95_standBy (void)
 Sets the radio into standby mode. More...
 
LOCAL void RFM95_powerDown (void)
 Powerdown radio, if RFM95_POWER_PIN defined.
 
LOCAL void RFM95_powerUp (void)
 Powerup radio, if RFM95_POWER_PIN defined.
 
LOCAL void RFM95_sendACK (const uint8_t recipient, const rfm95_sequenceNumber_t sequenceNumber, const rfm95_RSSI_t RSSI, const rfm95_SNR_t SNR)
 RFM95_sendACK. More...
 
LOCAL bool RFM95_sendWithRetry (const uint8_t recipient, const void *buffer, const uint8_t bufferSize, const uint8_t retries=RFM95_RETRIES, const uint32_t retryWaitTime=RFM95_RETRY_TIMEOUT_MS)
 RFM95_sendWithRetry. More...
 
LOCAL bool RFM95_waitCAD (void)
 Wait until no channel activity detected. More...
 
LOCAL bool RFM95_setRadioMode (const rfm95_radioMode_t newRadioMode)
 RFM95_setRadioMode. More...
 
LOCAL void RFM95_interruptHandler (void)
 Low level interrupt handler.
 
LOCAL void RFM95_interruptHandling (void)
 Packet engine.
 
LOCAL void RFM95_handler (void)
 RFM95_handler.
 
LOCAL int16_t RFM95_getReceivingRSSI (void)
 RFM95_getSendingRSSI. More...
 
LOCAL int16_t RFM95_getSendingRSSI (void)
 RFM95_getSendingRSSI. More...
 
LOCAL int16_t RFM95_getReceivingSNR (void)
 RFM95_getReceivingSNR. More...
 
LOCAL int16_t RFM95_getSendingSNR (void)
 RFM95_getSendingSNR. More...
 
LOCAL uint8_t RFM95_getTxPowerPercent (void)
 Get transmitter power level. More...
 
LOCAL uint8_t RFM95_getTxPowerLevel (void)
 Get transmitter power level. More...
 
LOCAL bool RFM95_executeATC (const rfm95_RSSI_t currentRSSI, const rfm95_RSSI_t targetRSSI)
 RFM_executeATC. More...
 
LOCAL void RFM95_ATCmode (const bool OnOff, const int16_t targetRSSI=RFM95_TARGET_RSSI)
 RFM95_ATCmode. More...
 
LOCAL bool RFM95_sanityCheck (void)
 RFM95_sanityCheck. More...
 

Variables

HardwareSPI SPI
 SPI.
 

Enumeration Type Documentation

Radio modes.

Enumerator
RFM95_RADIO_MODE_RX 

RX mode.

RFM95_RADIO_MODE_TX 

TX mode.

RFM95_RADIO_MODE_CAD 

CAD mode.

RFM95_RADIO_MODE_SLEEP 

SLEEP mode.

RFM95_RADIO_MODE_STDBY 

STDBY mode.

Function Documentation

LOCAL void RFM95_ATCmode ( const bool  OnOff,
const int16_t  targetRSSI = RFM95_TARGET_RSSI 
)

RFM95_ATCmode.

Parameters
targetRSSITarget RSSI for transmitter (default -60)
OnOffTrue to enable ATC
LOCAL bool RFM95_available ( void  )

Tests whether a new message is available.

Returns
True if a new, complete, error-free uncollected message is available to be retreived by RFM95_receive()
LOCAL void RFM95_enableTCXO ( void  )

Enable TCXO mode Call this immediately after init(), to force your radio to use an external frequency source, such as a Temperature Compensated Crystal Oscillator (TCXO). See the comments in the main documentation about the sensitivity of this radio to clock frequency especially when using narrow bandwidths.

Note
Has to be called while radio is in sleep mode.
LOCAL bool RFM95_executeATC ( const rfm95_RSSI_t  currentRSSI,
const rfm95_RSSI_t  targetRSSI 
)

RFM_executeATC.

Parameters
currentRSSI
targetRSSI
Returns
True if power level adjusted
LOCAL uint8_t RFM95_getAddress ( void  )

Get driver/node address.

Returns
Node address
LOCAL int16_t RFM95_getReceivingRSSI ( void  )

RFM95_getSendingRSSI.

Returns
RSSI Signal strength of last packet received
LOCAL int16_t RFM95_getReceivingSNR ( void  )

RFM95_getReceivingSNR.

Returns
SNR
LOCAL int16_t RFM95_getSendingRSSI ( void  )

RFM95_getSendingRSSI.

Returns
RSSI Signal strength of last packet sent (if ACK and ATC enabled)
LOCAL int16_t RFM95_getSendingSNR ( void  )

RFM95_getSendingSNR.

Returns
SNR of last packet sent (if ACK and ATC enabled)
LOCAL uint8_t RFM95_getTxPowerLevel ( void  )

Get transmitter power level.

Returns
Transmitter power level in dBm
LOCAL uint8_t RFM95_getTxPowerPercent ( void  )

Get transmitter power level.

Returns
Transmitter power level in percents
LOCAL bool RFM95_initialise ( const uint32_t  frequencyHz)

Initialise the driver transport hardware and software.

Parameters
frequencyHzTransmitter frequency in Hz
Returns
True if initialisation succeeded
LOCAL uint8_t RFM95_receive ( uint8_t *  buf,
const uint8_t  maxBufSize 
)

If a valid message is received, copy it to buf and return length. 0 byte messages are permitted.

Parameters
bufLocation to copy the received message
maxBufSizeMax buffer size
Returns
Number of bytes
LOCAL bool RFM95_sanityCheck ( void  )

RFM95_sanityCheck.

Returns
True if sanity check passed
LOCAL bool RFM95_send ( const uint8_t  recipient,
uint8_t *  data,
const uint8_t  len,
const rfm95_controlFlags_t  flags,
const bool  increaseSequenceCounter = true 
)

RFM95_send.

Parameters
recipient
data
len
flags
increaseSequenceCounter
Returns
True if packet sent
LOCAL void RFM95_sendACK ( const uint8_t  recipient,
const rfm95_sequenceNumber_t  sequenceNumber,
const rfm95_RSSI_t  RSSI,
const rfm95_SNR_t  SNR 
)

RFM95_sendACK.

Parameters
recipient
sequenceNumber
RSSI(rfm95_RSSI_t)
SNR(rfm95_SNR_t)
LOCAL bool RFM95_sendFrame ( rfm95_packet_t *  packet,
const bool  increaseSequenceCounter = true 
)

RFM95_sendFrame.

Parameters
packet
increaseSequenceCounter
Returns
True if frame sent
LOCAL bool RFM95_sendWithRetry ( const uint8_t  recipient,
const void *  buffer,
const uint8_t  bufferSize,
const uint8_t  retries = RFM95_RETRIES,
const uint32_t  retryWaitTime = RFM95_RETRY_TIMEOUT_MS 
)

RFM95_sendWithRetry.

Parameters
recipient
buffer
bufferSize
retries
retryWaitTime
Returns
True if packet successfully sent
LOCAL void RFM95_setAddress ( const uint8_t  addr)

Set the driver/node address.

Parameters
addr
LOCAL void RFM95_setFrequency ( const uint32_t  frequencyHz)

Sets the transmitter and receiver centre frequency.

Parameters
frequencyHzFrequency in Hz
LOCAL void RFM95_setModemRegisters ( const rfm95_modemConfig_t config)

Sets all the registers required to configure the data modem in the RF95/96/97/98, including the bandwidth, spreading factor etc.

Parameters
configSee modemConfig_t and references therein
LOCAL void RFM95_setPreambleLength ( const uint16_t  preambleLength)

RFM95_setPreambleLength.

Parameters
preambleLength
LOCAL bool RFM95_setRadioMode ( const rfm95_radioMode_t  newRadioMode)

RFM95_setRadioMode.

Parameters
newRadioMode
Returns
True if mode changed
LOCAL bool RFM95_setTxPowerLevel ( rfm95_powerLevel_t  newPowerLevel)

Sets the transmitter power output level, and configures the transmitter pin.

Parameters
newPowerLevelTransmitter power level in dBm (+5 to +23)
Returns
True power level adjusted
LOCAL bool RFM95_setTxPowerPercent ( const uint8_t  newPowerPercent)

Sets the transmitter power output percent.

Parameters
newPowerPercentTransmitter power level in percent
Returns
True power level adjusted
LOCAL bool RFM95_sleep ( void  )

Sets the radio into low-power sleep mode.

Returns
true if sleep mode was successfully entered
LOCAL bool RFM95_standBy ( void  )

Sets the radio into standby mode.

Returns
true if standby mode was successfully entered
LOCAL bool RFM95_waitCAD ( void  )

Wait until no channel activity detected.

Returns
True if no channel activity detected, False if timeout occured