Radio frequency interface, that helps to use meshNet with different radios or communication types. For each radio type has to be created new derivation of this class. Never create instance of this class, because it won't do nothing, you have to use only derivations of this class. More...

#include <RFInterface.h>

Inheritance diagram for RFInterface:

[legend]

Public Member Functions
	RFInterface (const uint8_t maxFrameLength, const RFIType interfaceType, const bool canCheckInterference, const uint8_t maxChannelNumber, const uint8_t minChannelNumber, const uint8_t maxPowerValue, const uint8_t minPowerValue, const bool canSetSpeed, const uint32_t baseFrequency, ThreadLock *_lock)
	Constructor - has to be overridden and parameters have to be set in overridden constructor. More...

virtual	~RFInterface ()=0

virtual bool	init ()=0
	Override this method to initialize radio and communication with it. More...

virtual bool	deInit ()=0
	Override this method to de-initialize radio and communication with it. More...

virtual bool	hasError ()=0
	Override this method to check if radio has some error or is not connected to MCU. If this method returns true, deInit() method in meshNet will be called. More...

virtual bool	send (uint8_t *data, uint8_t dataSize)=0
	Override this method to send data through radio. More...

virtual bool	recv (uint8_t *data, uint8_t &dataSize, int8_t &rssi)=0
	Override this method to read data from radio buffer. More...

virtual uint8_t	available ()=0
	Override this method to get raw size of received frame in bytes. More...

virtual bool	sleep ()=0
	Override this method to temporary power off the radio. If the radio cannot sleep, just return true. More...

virtual bool	wakeUp ()=0
	Override this method to temporary power on (wake up) the radio from sleep. If the radio cannot sleep, just return true. More...

virtual bool	checkInterference ()=0
	Override this method to check, if there is currently an interference in the air. If interference check cannot be done on selected radio, just return false. This method is used to check, if radio can send data or has to wait on another radio. More...

virtual bool	setChannel (uint8_t channel)=0
	Override this method to set radio channel. If channels cannot be set on selected radio, just return false. More...

virtual bool	setPower (uint8_t power)=0
	Override this method to set radio output power. If radio output power cannot be set, just return true. More...

virtual bool	setFullSpeed (bool enableFullSpeed)=0
	Override this method to set full or slow speed (data rate). If speed cannot be set, just return true. More...

virtual bool	setReceiveInterruptCallback (void(*InterruptCallback)(void))=0
	Override this method to set receive message interrupt method. If interrupt cannot be set or is not supported, return false. More...

virtual bool	interruptHandle ()=0
	This method has to be done, when ReceiveInterrupt happened. More...

virtual void	handle ()=0
	This method is included in meshNet::handle() method and it is included in main loop. More...

virtual void	printDetails (OSTREAM *stream)=0
	This method is used to print radio details to stream (usually to Serial port). Method is also called, when "mesh radio info" command has been called in SerialConsole. More...

virtual uint8_t	scanChannels (uint8_t startChannel, uint8_t endChannel, uint8_t retries=50, OSTREAM *stream=NULL)=0
	This method has to scan all free channels and returns channel with minimum interferences. Method is also called, when "mesh radio scan channels <int:retries>" command has been called in SerialConsole. More...

virtual uint8_t	scanChannels (uint8_t startChannel, uint8_t endChannel, OSTREAM *stream=NULL)=0
	This method has to scan all free channels and returns channel with minimum interferences. Method is also called, when "mesh radio scan channels <int:retries>" command has been called in SerialConsole. Retries count is set to best value. More...

virtual bool	scanChannelsWorking ()=0
	Checks if channel scan is processed now. More...

virtual uint32_t	getChannelsWidth ()=0
	Gets width of each channels in kHz. More...

virtual uint8_t *	getInternalTemporaryBuffer ()=0
	Gets pointer to internal temporary buffer with size of MaxFrameLength. This buffer can be used for temporary storing of received data. More...

Data Fields
const uint8_t	MaxFrameLength
	RF_NO_INTERNAL_TMP_BUFFER. More...

const RFIType	InterfaceType
	Interface type, see RFIType. More...

const bool	CanCheckInterference:1
	True when interference can be checked. More...

const uint8_t	MaxChannelNumber
	Maximum channel number. When this value is equal or lower than MinChannelNumber, radio channel cannot be set. More...

const uint8_t	MinChannelNumber
	Minimum channel number. When this value is equal or higher than MaxChannelNumber, radio channel cannot be set. More...

const uint8_t	MaxPowerValue
	Maximum power level value. When this value is equal or lower than MinPowerValue, radio output power cannot be set. More...

const uint8_t	MinPowerValue
	Minimum power level value. When this value is equal or higher than MaxPowerValue, radio output power cannot be set. More...

const bool	CanSetSpeed:1
	True when speed (data rate) can be set. More...

const uint32_t	BaseFrequency
	Frequency of channel 0 in kHz. More...

ThreadLock *	lock
	Thread lock, that is used to lock current methods. More...

Detailed Description

Radio frequency interface, that helps to use meshNet with different radios or communication types. For each radio type has to be created new derivation of this class. Never create instance of this class, because it won't do nothing, you have to use only derivations of this class.

How to set radio to make it work correctly with meshNet

Disable auto acknowledgment system and auto retransmission.
Enable CRC calculation for each frame.
Ensure, that data are sent by broadcast and every radio within reach with same channel can receive this data. On some radios broadcast cannot be set, but it can be hacked by setting same address to each radio.

Warning: Every method marked as virtual and constructor have to be overridden in derived class to avoid errors.

See also: RFInterface.h; RFIType

Constructor & Destructor Documentation

◆ RFInterface()

RFInterface::RFInterface	(	const uint8_t	maxFrameLength,
		const RFIType	interfaceType,
		const bool	canCheckInterference,
		const uint8_t	maxChannelNumber,
		const uint8_t	minChannelNumber,
		const uint8_t	maxPowerValue,
		const uint8_t	minPowerValue,
		const bool	canSetSpeed,
		const uint32_t	baseFrequency,
		ThreadLock *	_lock
	)

Constructor - has to be overridden and parameters have to be set in overridden constructor.

Parameters

maxFrameLength	Maximum frame length, that can be sent in one packet using this interface. (Value can be between MESH_FRAME_SIZE_MIN_LIMIT and MESH_FRAME_SIZE_LIMIT(from 24 to 128)).
interfaceType	Type of interface, see RFIType enum.
canCheckInterference	True, if CheckInterface() method can be used or not.
maxChannelNumber	Maximum channel number that can be set using setChannel() method. If you set this value to the equal or lower value than minChannelNumber, setChannel() method cannot be used.
minChannelNumber	Minimum channel number that can be set using setChannel() method. If you set this value to the equal or higher value than maxChannelNumber, setChannel() method cannot be used.
maxPowerValue	Some radios contains antenna amplifiers, so you can set signal output power. Set this value to maximum possible power setting value. It is recommended to use directly levels numbers, not calculated output power in dBm, because this variable is unsigned and can be incremented by 1. If you set this value to the equal or lower value than minPowerValue, setPower() method cannot be used.
minPowerValue	Some radios contains antenna amplifiers, so you can set signal output power. Set this value to maximum possible power setting value. It is recommended to use directly levels numbers, not calculated output power in dBm, because this variable is unsigned and can be incremented by 1. If you set this value to the equal or higher value than maxPowerValue, setPower() method cannot be used.
canSetSpeed	True, when radio supports multiple speed (data rate) settings. When false, setFullSpeed cannot be used.
baseFrequency	Frequency of channel 0 in kHz.
_lock	Thread lock, that is used to lock current methods in interrupts. Set to NULL when do not use.

◆ ~RFInterface()

RFInterface::~RFInterface ( )

pure virtual

Member Function Documentation

◆ available()

virtual uint8_t RFInterface::available ( )

pure virtual

Override this method to get raw size of received frame in bytes.

Note: This method should not be locked, because it returns value and can be called in interrupt. Lock has to be provided there, where this method is used.

Returns: Returns size of received packet in bytes.

Implemented in NRF24L01_RFI.

◆ checkInterference()

virtual bool RFInterface::checkInterference ( )

pure virtual

Override this method to check, if there is currently an interference in the air. If interference check cannot be done on selected radio, just return false. This method is used to check, if radio can send data or has to wait on another radio.

Note: This method should not be locked, because it returns value and can be called in interrupt. Lock has to be provided there, where this method is used.

Returns: Returns true when interference is present in the air.

Implemented in NRF24L01_RFI.

◆ deInit()

virtual bool RFInterface::deInit ( )

pure virtual

Override this method to de-initialize radio and communication with it.

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Returns: Returns true when de-initialization was done correctly.

Implemented in NRF24L01_RFI.

◆ getChannelsWidth()

virtual uint32_t RFInterface::getChannelsWidth ( )

pure virtual

Gets width of each channels in kHz.

Returns: Returns width of each channels in kHz.

Implemented in NRF24L01_RFI.

◆ getInternalTemporaryBuffer()

virtual uint8_t* RFInterface::getInternalTemporaryBuffer ( )

pure virtual

Gets pointer to internal temporary buffer with size of MaxFrameLength. This buffer can be used for temporary storing of received data.

Implemented in NRF24L01_RFI.

◆ handle()

virtual void RFInterface::handle ( )

pure virtual

This method is included in meshNet::handle() method and it is included in main loop.

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Implemented in NRF24L01_RFI.

◆ hasError()

virtual bool RFInterface::hasError ( )

pure virtual

Override this method to check if radio has some error or is not connected to MCU. If this method returns true, deInit() method in meshNet will be called.

Note: This method should not be locked, because it returns value and can be called in interrupt. Lock has to be provided there, where this method is used.

Returns: Returns true when there is some error.

Implemented in NRF24L01_RFI.

◆ init()

virtual bool RFInterface::init ( )

pure virtual

Override this method to initialize radio and communication with it.

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Returns: Returns true when initialization was done correctly.

Implemented in NRF24L01_RFI.

◆ interruptHandle()

virtual bool RFInterface::interruptHandle ( )

pure virtual

This method has to be done, when ReceiveInterrupt happened.

Note: This method should not be locked, because it returns value and can be called in interrupt. Lock has to be provided there, where this method is used.

Returns: Returns true, when new message has been received and it should be read in interrupt.

See also: setReceiveInterruptCallback

Implemented in NRF24L01_RFI.

◆ printDetails()

virtual void RFInterface::printDetails ( OSTREAM * stream )

pure virtual

This method is used to print radio details to stream (usually to Serial port). Method is also called, when "mesh radio info" command has been called in SerialConsole.

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Parameters

stream Stream, where to print details.

Implemented in NRF24L01_RFI.

◆ recv()

virtual bool RFInterface::recv	(	uint8_t *	data,
		uint8_t &	dataSize,
		int8_t &	rssi
	)

pure virtual

Override this method to read data from radio buffer.

Parameters

[out]	data	Buffer reserved for data to be recived. The size of buffer has to at least MaxFrameLength value. Internal temporary buffer can be used here, see getInternalTemporaryBuffer().
[in,out]	dataSize	Insert size of buffer. After calling, size of received data is assigned to this variable.
[out]	rssi	RSSI value of current frame in dBm. If RSSI is unknown, set it to 0.

Note: This method should not be locked, because it returns value and can be called in interrupt. Lock has to be provided there, where this method is used.

Returns: Returns true when data was read correctly. Returns false, when some error happened, or data are not available.

Implemented in NRF24L01_RFI.

◆ scanChannels() [1/2]

virtual uint8_t RFInterface::scanChannels	(	uint8_t	startChannel,
		uint8_t	endChannel,
		OSTREAM *	stream = `NULL`
	)

pure virtual

This method has to scan all free channels and returns channel with minimum interferences. Method is also called, when "mesh radio scan channels <int:retries>" command has been called in SerialConsole. Retries count is set to best value.

Parameters

stream	Stream, where to print details about scanning. If stream is NULL, no data will be printed. First line has to contain: "Retries: X" where the X is the number of retries for each channel. Second line has to contain: "Channel span: X" where the X is the number of skipped channels (those skipped channels has same interference count as previous channel). Value has to be greater than 0. Third line has to contain: "Base frequency: X" where the X is the frequency of channel 0 in kHz. Fourth line has to contain: "Channel width: X" where the X is the width of each channel in kHz. Each line has to contain this text: "C: I" where C is channel number and I is the number of retries, where interference has been found.
startChannel	Channel, from which to start scanning.
endChannel	Last scanned channel.

Note: This method can take some time, do not call it often.; This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Returns: Returns channel with lowest interference count or 255 on error.

Implemented in NRF24L01_RFI.

◆ scanChannels() [2/2]

virtual uint8_t RFInterface::scanChannels	(	uint8_t	startChannel,
		uint8_t	endChannel,
		uint8_t	retries = `50`,
		OSTREAM *	stream = `NULL`
	)

pure virtual

This method has to scan all free channels and returns channel with minimum interferences. Method is also called, when "mesh radio scan channels <int:retries>" command has been called in SerialConsole.

Parameters

stream	Stream, where to print details about scanning. If stream is NULL, no data will be printed. First line has to contain: "Retries: X" where the X is number of retries for each channel. Each line has to contain this text: "C: I" where C is channel number and I is the number of retries, where interference has been found.
retries	Number of retries for each channel.
startChannel	Channel, from which to start scanning.
endChannel	Last scanned channel.

Note: This method can take some time, do not call it often.

Returns: Returns channel with lowest interference count.

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Implemented in NRF24L01_RFI.

◆ scanChannelsWorking()

virtual bool RFInterface::scanChannelsWorking ( )

pure virtual

Checks if channel scan is processed now.

Returns: Returns true when channel scan is processed now.

Implemented in NRF24L01_RFI.

◆ send()

virtual bool RFInterface::send	(	uint8_t *	data,
		uint8_t	dataSize
	)

pure virtual

Override this method to send data through radio.

Parameters

[in]	data	Raw frame data to be sent.
[in]	dataSize	Size of sending data. The size cannot exceed MaxFrameLength value.

Warning: The raw length of (use GetRawLength() method) MeshFrame has to be lower or equal than MaxFrameLength, else false will be returned.

Note: This method should not be locked, because it returns value and can be called in interrupt. Lock has to be provided there, where this method is used.

Returns: Returns true when data was sent correctly. True is returned also, when data were transmitted, but not received by any radio.

Implemented in NRF24L01_RFI.

◆ setChannel()

virtual bool RFInterface::setChannel ( uint8_t channel )

pure virtual

Override this method to set radio channel. If channels cannot be set on selected radio, just return false.

Parameters

channel Channel number to set. This value have to be between MaxChannelNumber (included) and MinChannelNumber (included).

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Returns: Returns true when channel was set.

Implemented in NRF24L01_RFI.

◆ setFullSpeed()

virtual bool RFInterface::setFullSpeed ( bool enableFullSpeed )

pure virtual

Override this method to set full or slow speed (data rate). If speed cannot be set, just return true.

Parameters

enableFullSpeed True to send data at full speed or false to send data at slow speed.

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Returns: Returns false when error happened.

Implemented in NRF24L01_RFI.

◆ setPower()

virtual bool RFInterface::setPower ( uint8_t power )

pure virtual

Override this method to set radio output power. If radio output power cannot be set, just return true.

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Returns: Returns false when error happened.

Implemented in NRF24L01_RFI.

◆ setReceiveInterruptCallback()

virtual bool RFInterface::setReceiveInterruptCallback ( void(*)(void) InterruptCallback )

pure virtual

Override this method to set receive message interrupt method. If interrupt cannot be set or is not supported, return false.

Parameters

InterruptCallback Callback function, that is called when radio has received new packet. When InterruptCallback is nullptr, interrupt has to be detached.

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Returns: Returns true when interrupt function was set.

Implemented in NRF24L01_RFI.

◆ sleep()

virtual bool RFInterface::sleep ( )

pure virtual

Override this method to temporary power off the radio. If the radio cannot sleep, just return true.

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Returns: Returns false when some error happened.

Implemented in NRF24L01_RFI.

◆ wakeUp()

virtual bool RFInterface::wakeUp ( )

pure virtual

Override this method to temporary power on (wake up) the radio from sleep. If the radio cannot sleep, just return true.

Note: This method should be called in main thread, that's why thread locking TLWhenUnlocked is recommended to use.

Returns: Returns false when some error happened.

Implemented in NRF24L01_RFI.

Field Documentation

◆ BaseFrequency

const uint32_t RFInterface::BaseFrequency

Frequency of channel 0 in kHz.

◆ CanCheckInterference

const bool RFInterface::CanCheckInterference

True when interference can be checked.

◆ CanSetSpeed

const bool RFInterface::CanSetSpeed

True when speed (data rate) can be set.

◆ InterfaceType

const RFIType RFInterface::InterfaceType

Interface type, see RFIType.

◆ lock

ThreadLock* RFInterface::lock

Thread lock, that is used to lock current methods.

◆ MaxChannelNumber

const uint8_t RFInterface::MaxChannelNumber

Maximum channel number. When this value is equal or lower than MinChannelNumber, radio channel cannot be set.

◆ MaxFrameLength

const uint8_t RFInterface::MaxFrameLength

RF_NO_INTERNAL_TMP_BUFFER.

Maximum possible message length, that can be sent or received.

◆ MaxPowerValue

const uint8_t RFInterface::MaxPowerValue

Maximum power level value. When this value is equal or lower than MinPowerValue, radio output power cannot be set.

◆ MinChannelNumber

const uint8_t RFInterface::MinChannelNumber

Minimum channel number. When this value is equal or higher than MaxChannelNumber, radio channel cannot be set.

◆ MinPowerValue

const uint8_t RFInterface::MinPowerValue

Minimum power level value. When this value is equal or higher than MaxPowerValue, radio output power cannot be set.

The documentation for this class was generated from the following files:

RadioInterfaces/Inc/RFInterface.h
RadioInterfaces/Src/RFInterface.cpp

Public Member Functions

Data Fields

Detailed Description

How to set radio to make it work correctly with meshNet

Constructor & Destructor Documentation

◆ RFInterface()

◆ ~RFInterface()

Member Function Documentation

◆ available()

◆ checkInterference()

◆ deInit()

◆ getChannelsWidth()

◆ getInternalTemporaryBuffer()

◆ handle()

◆ hasError()

◆ init()

◆ interruptHandle()

◆ printDetails()

◆ recv()

◆ scanChannels() [1/2]

◆ scanChannels() [2/2]

◆ scanChannelsWorking()

◆ send()

◆ setChannel()

◆ setFullSpeed()

◆ setPower()

◆ setReceiveInterruptCallback()

◆ sleep()

◆ wakeUp()

Field Documentation

◆ BaseFrequency

◆ CanCheckInterference

◆ CanSetSpeed

◆ InterfaceType

◆ lock

◆ MaxChannelNumber

◆ MaxFrameLength

◆ MaxPowerValue

◆ MinChannelNumber

◆ MinPowerValue