Collaboration diagram for RFM95:

Detailed Description

API declaration for RFM95.

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

[!] Exclamation mark is prepended in case of error

E	SYS	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	RFM95_SPI hwSPI
	default SPI

#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_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 bool noACK)
	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...

Enumeration Type Documentation

◆ rfm95_radioMode_t

enum rfm95_radioMode_t

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.

Definition at line 186 of file RFM95.h.

Function Documentation

◆ RFM95_ATCmode()

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

RFM95_ATCmode.

Parameters

targetRSSI	Target RSSI for transmitter (default -60)
OnOff	True to enable ATC

◆ RFM95_available()

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()

◆ RFM95_enableTCXO()

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.

◆ RFM95_executeATC()

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

◆ RFM95_getAddress()

LOCAL uint8_t RFM95_getAddress ( void )

Get driver/node address.

Returns: Node address

◆ RFM95_getReceivingRSSI()

LOCAL int16_t RFM95_getReceivingRSSI ( void )

RFM95_getSendingRSSI.

Returns: RSSI Signal strength of last packet received

◆ RFM95_getReceivingSNR()

LOCAL int16_t RFM95_getReceivingSNR ( void )

RFM95_getReceivingSNR.

Returns: SNR

◆ RFM95_getSendingRSSI()

LOCAL int16_t RFM95_getSendingRSSI ( void )

RFM95_getSendingRSSI.

Returns: RSSI Signal strength of last packet sent (if ACK and ATC enabled)

◆ RFM95_getSendingSNR()

LOCAL int16_t RFM95_getSendingSNR ( void )

RFM95_getSendingSNR.

Returns: SNR of last packet sent (if ACK and ATC enabled)

◆ RFM95_getTxPowerLevel()

LOCAL uint8_t RFM95_getTxPowerLevel ( void )

Get transmitter power level.

Returns: Transmitter power level in dBm

◆ RFM95_getTxPowerPercent()

LOCAL uint8_t RFM95_getTxPowerPercent ( void )

Get transmitter power level.

Returns: Transmitter power level in percents

◆ RFM95_initialise()

LOCAL bool RFM95_initialise ( const uint32_t frequencyHz )

Initialise the driver transport hardware and software.

Parameters

frequencyHz Transmitter frequency in Hz

Returns: True if initialisation succeeded

◆ RFM95_receive()

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

buf	Location to copy the received message
maxBufSize	Max buffer size

Returns: Number of bytes

◆ RFM95_sanityCheck()

LOCAL bool RFM95_sanityCheck ( void )

RFM95_sanityCheck.

Returns: True if sanity check passed

◆ RFM95_send()

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

◆ RFM95_sendACK()

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)

◆ RFM95_sendFrame()

LOCAL bool RFM95_sendFrame	(	rfm95_packet_t *	packet,
		const bool	increaseSequenceCounter = `true`
	)

RFM95_sendFrame.

Parameters

packet
increaseSequenceCounter

Returns: True if frame sent

◆ RFM95_sendWithRetry()

LOCAL bool RFM95_sendWithRetry	(	const uint8_t	recipient,
		const void *	buffer,
		const uint8_t	bufferSize,
		const bool	noACK
	)

RFM95_sendWithRetry.

Parameters

recipient
buffer
bufferSize
noACK

Returns: True if packet successfully sent

◆ RFM95_setAddress()

LOCAL void RFM95_setAddress ( const uint8_t addr )

Set the driver/node address.

Parameters

addr

◆ RFM95_setFrequency()

LOCAL void RFM95_setFrequency ( const uint32_t frequencyHz )

Sets the transmitter and receiver centre frequency.

Parameters

frequencyHz Frequency in Hz

◆ RFM95_setModemRegisters()

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

config See modemConfig_t and references therein

◆ RFM95_setPreambleLength()

LOCAL void RFM95_setPreambleLength ( const uint16_t preambleLength )

RFM95_setPreambleLength.

Parameters

preambleLength

◆ RFM95_setRadioMode()

LOCAL bool RFM95_setRadioMode ( const rfm95_radioMode_t newRadioMode )

RFM95_setRadioMode.

Parameters

newRadioMode

Returns: True if mode changed

◆ RFM95_setTxPowerLevel()

LOCAL bool RFM95_setTxPowerLevel ( rfm95_powerLevel_t newPowerLevel )

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

Parameters

newPowerLevel Transmitter power level in dBm (+5 to +23)

Returns: True power level adjusted

◆ RFM95_setTxPowerPercent()

LOCAL bool RFM95_setTxPowerPercent ( const uint8_t newPowerPercent )

Sets the transmitter power output percent.

Parameters

newPowerPercent Transmitter power level in percent

Returns: True power level adjusted

◆ RFM95_sleep()

LOCAL bool RFM95_sleep ( void )

Sets the radio into low-power sleep mode.

Returns: true if sleep mode was successfully entered

◆ RFM95_standBy()

LOCAL bool RFM95_standBy ( void )

Sets the radio into standby mode.

Returns: true if standby mode was successfully entered

◆ RFM95_waitCAD()

LOCAL bool RFM95_waitCAD ( void )

Wait until no channel activity detected.

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

Detailed Description

Classes

Macros

Typedefs

Enumerations

Functions

Enumeration Type Documentation

◆ rfm95_radioMode_t

Function Documentation

◆ RFM95_ATCmode()

◆ RFM95_available()

◆ RFM95_enableTCXO()

◆ RFM95_executeATC()

◆ RFM95_getAddress()

◆ RFM95_getReceivingRSSI()

◆ RFM95_getReceivingSNR()

◆ RFM95_getSendingRSSI()

◆ RFM95_getSendingSNR()

◆ RFM95_getTxPowerLevel()

◆ RFM95_getTxPowerPercent()

◆ RFM95_initialise()

◆ RFM95_receive()

◆ RFM95_sanityCheck()

◆ RFM95_send()

◆ RFM95_sendACK()

◆ RFM95_sendFrame()

◆ RFM95_sendWithRetry()

◆ RFM95_setAddress()

◆ RFM95_setFrequency()

◆ RFM95_setModemRegisters()

◆ RFM95_setPreambleLength()

◆ RFM95_setRadioMode()

◆ RFM95_setTxPowerLevel()

◆ RFM95_setTxPowerPercent()

◆ RFM95_sleep()

◆ RFM95_standBy()

◆ RFM95_waitCAD()