MySensors Library & Examples  9ecb785
Classes | Macros | Typedefs | Enumerations | Functions | Variables

API declaration for RFM95. More...

Collaboration diagram for RFM95:

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 RFM95_IRQ_PIN   (2)
 RFM95_IRQ_PIN.
 
#define RFM95_RST_PIN   (9)
 RFM95_RST_PIN.
 
#define RFM95_SPI_CS   (SS)
 RFM95_SPI_CS.
 
#define MY_RFM95_SPI_MAX_SPEED   (4*1000000ul)
 Max SPI speed, 4Mhz.
 
#define MY_RFM95_SPI_DATA_ORDER   MSBFIRST
 SPI data order.
 
#define MY_RFM95_SPI_DATA_MODE   SPI_MODE0
 SPI mode.
 
#define _SPI   SPI
 SPI.
 
#define RFM95_DEBUG(x, ...)
 Debug null.
 
#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_RETRIES   (2u)
 Retries in case of failed transmission.
 
#define RFM95_RETRY_TIMEOUT_MS   (500ul)
 Timeout for ACK, adjustments needed if modem configuration changed (air time different)
 
#define RFM95_CAD_TIMEOUT_MS   (2*1000ul)
 channel activity detection timeout
 
#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_PERCENT   (5u)
 ATC target range +/-%.
 
#define RFM95_RSSI_OFFSET   (137u)
 RSSI offset.
 
#define RFM95_TARGET_RSSI   (-60)
 RSSI target.
 
#define RFM95_RSSI_INVALID   (127)
 RSSI invalid.
 
#define RFM95_SNR_INVALID   (127)
 SNR invalid.
 
#define RFM95_PROMISCUOUS   (false)
 RFM95 promiscuous mode.
 
#define RFM95_FXOSC   (32*1000000ul)
 The crystal oscillator frequency of the module.
 
#define RFM95_FSTEP   (RFM95_FXOSC / 524288ul)
 The Frequency Synthesizer step = RFM95_FXOSC /.
 
#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_internalToRSSI(__value)   ((int16_t)(__value - RFM95_RSSI_OFFSET))
 Convert internal RSSI to RSSI.
 
#define RFM95_RSSItoInternal(__value)   ((uint8_t)(__value + RFM95_RSSI_OFFSET))
 Convert RSSI to internal RSSI.
 
#define RFM95_internalToSNR(__value)   ((int8_t)(__value / 4))
 Convert internal SNR to SNR.
 
#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_MIN_POWER_LEVEL_DBM   (5u)
 min. power level
 
#define RFM95_MAX_POWER_LEVEL_DBM   (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_flag_t
 Control flag data type.
 

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 float frequency)
 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 registered 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_recv (uint8_t *buf)
 If a valid message is received, copy it to buf and return length. 0 byte messages are permitted. More...
 
LOCAL bool RFM95_send (rfm95_packet_t &packet)
 RFM95_send. More...
 
LOCAL bool RFM95_sendFrame (const uint8_t recipient, uint8_t *data, const uint8_t len, const rfm95_flag_t flags)
 RFM95_sendFrame. More...
 
LOCAL void RFM95_setPreambleLength (const uint16_t preambleLength)
 RFM95_setPreambleLength. More...
 
LOCAL void RFM95_setFrequency (const float centre)
 Sets the transmitter and receiver centre frequency. More...
 
LOCAL bool RFM95_setTxPower (uint8_t powerLevel)
 Sets the transmitter power output level, and configures the transmitter pin. More...
 
LOCAL bool RFM95_sleep (void)
 Sets the radio into low-power sleep mode. More...
 
LOCAL void RFM95_sendACK (const uint8_t recipient, const rfm95_sequenceNumber_t sequenceNumber, const rfm95_RSSI_t RSSI, const rfm95_RSSI_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_waitPacketSent (void)
 RFM95_waitPacketSent. 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_clearRxBuffer (void)
 RFM95_clearRxBuffer.
 
LOCAL int16_t RFM95_getReceivingRSSI (void)
 RFM95_getSendingRSSI. More...
 
LOCAL int16_t RFM95_getSendingRSSI (void)
 RFM95_getSendingRSSI. 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.
 

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 SANCHK FAIL Sanity check failed, check wiring or replace module
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 Send ACK to node (TO), RSSI of received message (RSSI)
RFM95 ATC ADJ TXL,cR=d,tR=d,TXL=d Adjust TX level, current RSSI (cR), target RSSI (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 modem configuration

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

CONFIG REG_1D REG_1E REG_26 BW CR SF Comment
BW125CR45SF128 0x72 0x74 0x04 125 4/5 128 Default, medium range
BW500CR45SF128 0x92 0x74 0x04 500 4/5 128 Fast, short range
BW31_25CR48SF512 0x48 0x94 0x04 31.25 4/8 512 Slow, long range
BW125CR48SF4096 0x78 0xC4 0x0C 125 4/8 4096 Slow, long range

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_recv()
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_getSendingRSSI ( void  )

RFM95_getSendingRSSI.

Returns
RSSI Signal strength of last packet sent (if ACK and ATC enabled)
LOCAL bool RFM95_initialise ( const float  frequency)

Initialise the driver transport hardware and software.

Parameters
frequency
Returns
True if initialisation succeeded
LOCAL uint8_t RFM95_recv ( uint8_t *  buf)

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
Returns
Number of bytes
LOCAL bool RFM95_sanityCheck ( void  )

RFM95_sanityCheck.

Returns
True if sanity check passed
LOCAL bool RFM95_send ( rfm95_packet_t &  packet)

RFM95_send.

Parameters
packet
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_RSSI_t  SNR 
)

RFM95_sendACK.

Parameters
recipient
sequenceNumber
RSSI(rfm95_RSSI_t)
SNR(rfm95_RSSI_t)
LOCAL bool RFM95_sendFrame ( const uint8_t  recipient,
uint8_t *  data,
const uint8_t  len,
const rfm95_flag_t  flags 
)

RFM95_sendFrame.

Parameters
recipient
data
len
flags
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 float  centre)

Sets the transmitter and receiver centre frequency.

Parameters
centreFrequency in MHz (137.0 to 1020.0)
LOCAL void RFM95_setModemRegisters ( const rfm95_modemConfig_t config)

Sets all the registered 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_setTxPower ( uint8_t  powerLevel)

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

Parameters
powerLevelTransmitter power level in dBm (+5 to +23)
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_waitCAD ( void  )

Wait until no channel activity detected.

Returns
True if no channel activity detected, False if timeout occured
LOCAL bool RFM95_waitPacketSent ( void  )

RFM95_waitPacketSent.

Returns
True if packet sent