Send and receive unaddressed, unreliable datagrams by Microchip MRF89XA and compatible transceivers. and modules. More...

#include <RH_MRF89.h>

Inheritance diagram for RH_MRF89:

Classes
struct	ModemConfig
	Defines register configuration values for a desired modulation. More...

Public Types
enum	ModemConfigChoice { FSK_Rb2Fd33 = 0 , FSK_Rb5Fd33 , FSK_Rb10Fd33 , FSK_Rb20Fd40 , FSK_Rb40Fd80 , FSK_Rb50Fd100 , FSK_Rb66Fd133 , FSK_Rb100Fd200 , FSK_Rb200Fd200 }

Public Types inherited from RHGenericDriver
enum	RHMode { RHModeInitialising = 0 , RHModeSleep , RHModeIdle , RHModeTx , RHModeRx , RHModeCad }
	Defines different operating modes for the transport hardware. More...

Public Member Functions
	RH_MRF89 (uint8_t csconPin=SS, uint8_t csdatPin=9, uint8_t interruptPin=2, RHGenericSPI &spi=hardware_spi)

virtual bool	init ()

bool	printRegisters ()

virtual bool	sleep ()

void	setModeIdle ()

void	setModeRx ()

void	setModeTx ()

void	setTxPower (uint8_t power)

bool	setModemConfig (ModemConfigChoice index)

virtual bool	available ()

virtual bool	recv (uint8_t buf, uint8_t len)

virtual bool	send (const uint8_t *data, uint8_t len)

virtual uint8_t	maxMessageLength ()

bool	setFrequency (float centre)

void	setPreambleLength (uint8_t bytes)

void	setSyncWords (const uint8_t *syncWords=NULL, uint8_t len=0)

Public Member Functions inherited from RHNRFSPIDriver
	RHNRFSPIDriver (uint8_t slaveSelectPin=SS, RHGenericSPI &spi=hardware_spi)

bool	init ()

uint8_t	spiCommand (uint8_t command)

uint8_t	spiRead (uint8_t reg)

uint8_t	spiWrite (uint8_t reg, uint8_t val)

uint8_t	spiBurstRead (uint8_t reg, uint8_t *dest, uint8_t len)

uint8_t	spiBurstWrite (uint8_t reg, const uint8_t *src, uint8_t len)

void	setSlaveSelectPin (uint8_t slaveSelectPin)

void	spiUsingInterrupt (uint8_t interruptNumber)

Public Member Functions inherited from RHGenericDriver
	RHGenericDriver ()
	Constructor.

virtual	~RHGenericDriver ()
	Generic destructor to prevent warnings when objects are dynamically allocated.

virtual bool	init ()

virtual bool	available ()=0

virtual bool	recv (uint8_t buf, uint8_t len)=0

virtual bool	send (const uint8_t *data, uint8_t len)=0

virtual uint8_t	maxMessageLength ()=0

virtual void	waitAvailable (uint16_t polldelay=0)

virtual bool	waitPacketSent ()

virtual bool	waitPacketSent (uint16_t timeout)

virtual bool	waitAvailableTimeout (uint16_t timeout, uint16_t polldelay=0)

virtual bool	waitCAD ()

void	setCADTimeout (unsigned long cad_timeout)

virtual bool	isChannelActive ()

virtual void	setThisAddress (uint8_t thisAddress)

virtual void	setHeaderTo (uint8_t to)

virtual void	setHeaderFrom (uint8_t from)

virtual void	setHeaderId (uint8_t id)

virtual void	setHeaderFlags (uint8_t set, uint8_t clear=RH_FLAGS_APPLICATION_SPECIFIC)

virtual void	setPromiscuous (bool promiscuous)

virtual uint8_t	headerTo ()

virtual uint8_t	headerFrom ()

virtual uint8_t	headerId ()

virtual uint8_t	headerFlags ()

virtual int16_t	lastRssi ()

virtual RHMode	mode ()

virtual void	setMode (RHMode mode)
	Sets the operating mode of the transport. More...

virtual bool	sleep ()

virtual uint16_t	rxBad ()

virtual uint16_t	rxGood ()

virtual uint16_t	txGood ()

Protected Member Functions
void	handleInterrupt ()

uint8_t	spiReadRegister (uint8_t reg)

uint8_t	spiWriteRegister (uint8_t reg, uint8_t val)

uint8_t	spiWriteData (uint8_t data)

uint8_t	spiWriteData (const uint8_t *data, uint8_t len)

uint8_t	spiReadData ()

void	setOpMode (uint8_t mode)

bool	verifyPLLLock ()

void	validateRxBuf ()
	Examine the revceive buffer to determine whether the message is for this node.

void	clearRxBuf ()
	Clear our local receive buffer.

Protected Member Functions inherited from RHNRFSPIDriver
virtual void	beginTransaction ()

virtual void	endTransaction ()
	Signal the end of an SPI transaction.

Additional Inherited Members
Static Public Member Functions inherited from RHGenericDriver
static void	printBuffer (const char prompt, const uint8_t buf, uint8_t len)

Protected Attributes inherited from RHNRFSPIDriver
RHGenericSPI &	_spi
	Reference to the RHGenericSPI instance to use to trasnfer data with teh SPI device.

uint8_t	_slaveSelectPin
	The pin number of the Slave Select pin that is used to select the desired device.

Protected Attributes inherited from RHGenericDriver
volatile RHMode	_mode
	The current transport operating mode.

uint8_t	_thisAddress
	This node id.

bool	_promiscuous
	Whether the transport is in promiscuous mode.

volatile uint8_t	_rxHeaderTo
	TO header in the last received mesasge.

volatile uint8_t	_rxHeaderFrom
	FROM header in the last received mesasge.

volatile uint8_t	_rxHeaderId
	ID header in the last received mesasge.

volatile uint8_t	_rxHeaderFlags
	FLAGS header in the last received mesasge.

uint8_t	_txHeaderTo
	TO header to send in all messages.

uint8_t	_txHeaderFrom
	FROM header to send in all messages.

uint8_t	_txHeaderId
	ID header to send in all messages.

uint8_t	_txHeaderFlags
	FLAGS header to send in all messages.

volatile int16_t	_lastRssi
	The value of the last received RSSI value, in some transport specific units.

volatile uint16_t	_rxBad
	Count of the number of bad messages (eg bad checksum etc) received.

volatile uint16_t	_rxGood
	Count of the number of successfully transmitted messaged.

volatile uint16_t	_txGood
	Count of the number of bad messages (correct checksum etc) received.

volatile bool	_cad
	Channel activity detected.

unsigned int	_cad_timeout
	Channel activity timeout in ms.

Detailed Description

Send and receive unaddressed, unreliable datagrams by Microchip MRF89XA and compatible transceivers. and modules.

The Microchip MRF89XA http://ww1.microchip.com/downloads/en/DeviceDoc/70622C.pdf is a low cost 900MHz bancd transceiver chip. It is commonly used on preassembled modules with supporting circcuits and antennas, such as the MRF89XAM9A http://www.microchip.com/wwwproducts/Devices.aspx?product=MRF89XAM9A This class supports all such modules

This base class provides basic functions for sending and receiving unaddressed, unreliable datagrams of arbitrary length to 59 octets per packet. Use one of the Manager classes to get addressing and acknowledgement reliability, routing, meshes etc.

Several MRF89XA modules can be connected to an Arduino, permitting the construction of translators and frequency changers, etc. Each instance requires 2 chip select pins, and interrupt pin the standard 3 SPI pins.

Naturally, for any 2 radios to communicate that must be configured to use the same frequency and data rate, and with identical network addresses.

Example Arduino programs are included to show the main modes of use.

All messages sent and received by this class conform to this packet format:

3 octets PREAMBLE
2 to 4 octets NETWORK ADDRESS (also call Sync Word)
1 octet message length bits packet control field
4 to 63 octets PAYLOAD, consisting of:
- 1 octet TO header
- 1 octet FROM header
- 1 octet ID header
- 1 octet FLAGS header
- 0 to 59 octets of user message
2 octets CRC

The payload is whitened. No Manchester encoding is used.

Connecting MRF89XA to Arduino

The electrical connection between the MRF89XA and the Arduino require 3.3V, the 3 x SPI pins (SCK, SDI, SDO), a 2 Chip Select pins (/CSCON and /CSDAT) and an interrupt.

Caution: the MRF89XA is a 3.3V part and is not tolerant of 5V inputs. Connecting MRF89XA directly to a 5V MCU such as most Arduinos will damage the MRF89XA.

Connect the MRF89XA to most 3.3V Arduinos or Teensy 3.1 like this (use 3.3V not 5V).

         Teensy       MRF89XAM9A
       3.3V-----------VIN   (3.3V in)
     pin D9-----------/CSDAT (data chip select in)
  SS pin D10----------/CSCON (configuration chip select in)
 SCK pin D13----------SCK   (SPI clock in)
MOSI pin D11----------SDI   (SPI Data in)
MISO pin D12----------SDO   (SPI data out)
         D2-----------IRQ1  (Interrupt 1 output)
                      IRQ0  (Interrupt 0 output, not connected)
         GND----------GND   (ground in)

You can use other pins for /CSDAT, /CSCON, IRQ1 by passing appropriate arguments to the constructor.

Low Power Mode

Fernando Faria reports that:

In order for low power mode to work to achieve 1μA power consumption in this chip, you will need to do a few extra things:

the datasheet states that IRQ0 and IRQ1 must have a valid logic state at all times, so you will need to apply pull-down resistors to those pins (if not already present). See the data sheet Table 2-4 Note 3
You must also ensure the SPI pins are in a certain state after calling mrf89.sleep(); This may be suitable for your electrical connections:
digitalWrite(9, HIGH); // CSDAT

digitalWrite(10, LOW); // SS

digitalWrite(11, LOW); //MOSI

digitalWrite(13, LOW); // MISO

Example programs

Several example programs are provided.

Member Enumeration Documentation

◆ ModemConfigChoice

enum RH_MRF89::ModemConfigChoice

Choices for setModemConfig() for a selected subset of common data rates and frequency deviations. Rb is the data rate in kbps. Fd is the FSK Frequency deviation in kHz. These are indexes into MODEM_CONFIG_TABLE. We strongly recommend you use these symbolic definitions and not their integer equivalents: its possible that new values will be introduced in later versions (though we will try to avoid it). OOK is not yet supported. Based on sample configs in MRF89XA.h from Microchip

Enumerator
FSK_Rb2Fd33	FSK, No Manchester, Whitened, Rb = 2kbs, Fd = 33kHz.
FSK_Rb5Fd33	FSK, No Manchester, Whitened, Rb = 5kbs, Fd = 33kHz.
FSK_Rb10Fd33	FSK, No Manchester, Whitened, Rb = 10kbs, Fd = 33kHz.
FSK_Rb20Fd40	FSK, No Manchester, Whitened, Rb = 20kbs, Fd = 40kHz.
FSK_Rb40Fd80	FSK, No Manchester, Whitened, Rb = 40kbs, Fd = 80kHz.
FSK_Rb50Fd100	FSK, No Manchester, Whitened, Rb = 50kbs, Fd = 100kHz.
FSK_Rb66Fd133	FSK, No Manchester, Whitened, Rb = 66kbs, Fd = 133kHz.
FSK_Rb100Fd200	FSK, No Manchester, Whitened, Rb = 100kbs, Fd = 200kHz.
FSK_Rb200Fd200	FSK, No Manchester, Whitened, Rb = 200kbs, Fd = 200kHz.

Constructor & Destructor Documentation

◆ RH_MRF89()

RH_MRF89::RH_MRF89	(	uint8_t	csconPin = `SS`,
		uint8_t	csdatPin = `9`,
		uint8_t	interruptPin = `2`,
		RHGenericSPI &	spi = `hardware_spi`
	)

Constructor. Constructor. You can have multiple instances, but each instance must have its own interrupt and 2 slave select pins. After constructing, you must call init() to initialise the interface and the radio module. A maximum of 3 instances can co-exist on one processor, provided there are sufficient distinct interrupt lines, one for each instance.

Parameters

[in]	csconPin	the Arduino pin number connected to the CSCON pin of the MRF89XA. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega, D10 for Maple)
[in]	csdatPin	the Arduino pin number connected to the CSDAT pin of the MRF89XA. Defaults to 9.
[in]	interruptPin	The interrupt Pin number that is connected to the IRQ1 pin of the MRF89XA. Defaults to pin 2. (IRQ0 pin of the MRF89XA does not need to be connected).
[in]	spi	Pointer to the SPI interface object to use. Defaults to the standard Arduino hardware SPI interface

Member Function Documentation

◆ available()

bool RH_MRF89::available ( )

virtual

Tests whether a new message is available from the Driver. On most drivers, this will also put the Driver into RHModeRx mode until a message is actually received by the transport, when it will be returned to RHModeIdle. This can be called multiple times in a timeout loop

Returns: true if a new, complete, error-free uncollected message is available to be retreived by recv()

Implements RHGenericDriver.

References RHGenericDriver::_mode, RHGenericDriver::RHModeTx, and setModeRx().

Referenced by recv().

◆ handleInterrupt()

void RH_MRF89::handleInterrupt ( )

protected

Called automatically when a CRCOK or TXDONE interrupt occurs. Handles the interrupt.

References RHGenericDriver::_lastRssi, RHGenericDriver::_mode, RHGenericDriver::_txGood, clearRxBuf(), RHGenericDriver::RHModeRx, RHGenericDriver::RHModeTx, setModeIdle(), spiReadData(), spiReadRegister(), and validateRxBuf().

◆ init()

bool RH_MRF89::init ( )

virtual

Initialise the Driver transport hardware and software. Make sure the Driver is properly configured before calling init().

Returns: true if initialisation succeeded.

Reimplemented from RHGenericDriver.

References RHNRFSPIDriver::_spi, RHGenericSPI::Frequency1MHz, FSK_Rb20Fd40, RHNRFSPIDriver::init(), setFrequency(), RHGenericSPI::setFrequency(), setModemConfig(), setOpMode(), setPreambleLength(), setSyncWords(), setTxPower(), spiReadRegister(), RHNRFSPIDriver::spiUsingInterrupt(), and spiWriteRegister().

◆ maxMessageLength()

uint8_t RH_MRF89::maxMessageLength ( )

virtual

Returns the maximum message length available in this Driver.

Returns: The maximum legal message length

Implements RHGenericDriver.

◆ printRegisters()

bool RH_MRF89::printRegisters ( )

Prints the value of all chip registers to the Serial device if RH_HAVE_SERIAL is defined for the current platform For debugging purposes only.

Returns: true on success

References spiReadRegister().

◆ recv()

bool RH_MRF89::recv	(	uint8_t *	buf,
		uint8_t *	len
	)

virtual

Turns the receiver on if it not already on. If there is a valid message available, copy it to buf and return true else return false. If a message is copied, *len is set to the length (Caution, 0 length messages are permitted). You should be sure to call this function frequently enough to not miss any messages It is recommended that you call it in your main loop.

Parameters

[in]	buf	Location to copy the received message
[in,out]	len	Pointer to the number of octets available in buf. The number be reset to the actual number of octets copied.

Returns: true if a valid message was copied to buf

Implements RHGenericDriver.

References available(), and clearRxBuf().

◆ send()

bool RH_MRF89::send	(	const uint8_t *	data,
		uint8_t	len
	)

virtual

Waits until any previous transmit packet is finished being transmitted with waitPacketSent(). Then loads a message into the transmitter and starts the transmitter. Note that a message length of 0 is permitted.

Parameters

[in]	data	Array of data to be sent
[in]	len	Number of bytes of data to send

Returns: true if the message length was valid and it was correctly queued for transmit

Implements RHGenericDriver.

References RHGenericDriver::_txHeaderFlags, RHGenericDriver::_txHeaderFrom, RHGenericDriver::_txHeaderId, RHGenericDriver::_txHeaderTo, setModeIdle(), setModeTx(), spiWriteData(), RHGenericDriver::waitCAD(), and RHGenericDriver::waitPacketSent().

◆ setFrequency()

bool RH_MRF89::setFrequency ( float centre )

Sets the centre frequency in MHz. Permitted ranges are: 902.0 to 928.0 and 950.0 to 960.0 (inclusive) Caution not all freqs are supported on all modules: check your module specifications Caution: not all available and supported frequencies are legal in every country: check Regulatory Approval eg for MRF89XAM9A (in 75015B.pdf) Australia 915.0 to 928.0

References spiReadRegister(), spiWriteRegister(), and verifyPLLLock().

Referenced by init().

◆ setModeIdle()

void RH_MRF89::setModeIdle ( )

If current mode is Rx or Tx changes it to Idle. If the transmitter or receiver is running, disables them.

References RHGenericDriver::_mode, RHGenericDriver::RHModeIdle, and setOpMode().

Referenced by handleInterrupt(), and send().

◆ setModemConfig()

bool RH_MRF89::setModemConfig ( ModemConfigChoice index )

Select one of the predefined modem configurations. If you need a modem configuration not provided here, use setModemRegisters() with your own ModemConfig.

Parameters

[in] index The configuration choice.

Returns: true if index is a valid choice.

References RH_MRF89::ModemConfig::BRVAL, RH_MRF89::ModemConfig::FDVAL, RH_MRF89::ModemConfig::FILCREG, RH_MRF89::ModemConfig::MODSEL, spiReadRegister(), spiWriteRegister(), and RH_MRF89::ModemConfig::TXIPOLFV.

Referenced by init().

◆ setModeRx()

void RH_MRF89::setModeRx ( )

If current mode is Tx or Idle, changes it to Rx. Starts the receiver in the radio.

References RHGenericDriver::_mode, RHGenericDriver::RHModeRx, and setOpMode().

Referenced by available().

◆ setModeTx()

void RH_MRF89::setModeTx ( )

If current mode is Rx or Idle, changes it to Rx. F Starts the transmitter in the radio.

References RHGenericDriver::_mode, RHGenericDriver::RHModeTx, and setOpMode().

Referenced by send().

◆ setOpMode()

void RH_MRF89::setOpMode ( uint8_t mode )

protected

Sets the operating mode in the CMOD bits in RH_MRF89_REG_00_GCONREG which controls what mode the MRF89XA is running in

Parameters

[in] mode One of RH_MRF89_CMOD_*

References RHGenericDriver::mode(), spiReadRegister(), and spiWriteRegister().

Referenced by init(), setModeIdle(), setModeRx(), setModeTx(), sleep(), and verifyPLLLock().

◆ setPreambleLength()

void RH_MRF89::setPreambleLength ( uint8_t bytes )

Sets the length of the preamble in bytes. Caution: this should be set to the same value on all nodes in your network. Default is 4. Sets the message preamble length in RH_MRF89_REG_1E_PKTCREG

Parameters

[in] bytes Preamble length in bytes of 8 bits each.

References spiReadRegister(), and spiWriteRegister().

Referenced by init().

◆ setSyncWords()

void RH_MRF89::setSyncWords	(	const uint8_t *	syncWords = `NULL`,
		uint8_t	len = `0`
	)

Sets the sync words for transmit and receive in registers RH_MRF89_REG_16_SYNCV31REG et seq. Caution: SyncWords should be set to the same value on all nodes in your network. Nodes with different SyncWords set will never receive each others messages, so different SyncWords can be used to isolate different networks from each other. Default is { 0x69, 0x81, 0x7e, 0x96 }. Caution, sync words of 2 bytes and less do not work well with this chip.

Parameters

[in]	syncWords	Array of sync words, 1 to 4 octets long
[in]	len	Number of sync words to set, 1 to 4.

References spiReadRegister(), and spiWriteRegister().

Referenced by init().

◆ setTxPower()

void RH_MRF89::setTxPower ( uint8_t power )

Sets the transmitter power output level in register RH_MRF89_REG_1A_TXCONREG. Be a good neighbour and set the lowest power level you need. After init(), the power will be set to RH_MRF89_TXOPVAL_1DBM (1dBm) The highest power available is RH_MRF89_TXOPVAL_13DBM (13dBm) Caution: In some countries you may only select certain higher power levels if you are also using frequency hopping. Make sure you are aware of the legal limitations and regulations in your region. Caution: in some countries the maximum permitted power level may depend on the Bit rate

Parameters

[in] power Transmitter power level, one of RH_MRF89_TXOPVAL*

References spiReadRegister(), and spiWriteRegister().

Referenced by init().

◆ sleep()

bool RH_MRF89::sleep ( )

virtual

Sets the radio into low-power sleep mode. If successful, the transport will stay in sleep mode until woken by changing mode to idle, transmit or receive (eg by calling send(), recv(), available() etc) Caution: there is a time penalty as the radio takes a finite time to wake from sleep mode.

Returns: true if sleep mode was successfully entered.

Reimplemented from RHGenericDriver.

References RHGenericDriver::_mode, RHGenericDriver::RHModeSleep, and setOpMode().

◆ spiReadData()

uint8_t RH_MRF89::spiReadData ( )

protected

Reads a single byte from the MRF89XA data FIFO.

Returns: The next data byte in the FIFO

References RHNRFSPIDriver::setSlaveSelectPin(), RHNRFSPIDriver::spiCommand(), and spiWriteRegister().

Referenced by handleInterrupt().

◆ spiReadRegister()

uint8_t RH_MRF89::spiReadRegister ( uint8_t reg )

protected

Reads a single register from the MRF89XA

Parameters

[in] reg Register number, one of RH_MRF89_REG

Returns: The value of the register

References RHNRFSPIDriver::setSlaveSelectPin(), and RHNRFSPIDriver::spiRead().

Referenced by handleInterrupt(), init(), printRegisters(), setFrequency(), setModemConfig(), setOpMode(), setPreambleLength(), setSyncWords(), setTxPower(), and verifyPLLLock().

◆ spiWriteData() [1/2]

uint8_t RH_MRF89::spiWriteData	(	const uint8_t *	data,
		uint8_t	len
	)

protected

Write a number of bytes from a buffer to the MRF89XA data FIFO.

Parameters

[in]	data	Pointer to a buffer containing the len bytes to be written
[in]	len	The number of bytes to write to teh FIFO

Returns: 0;

References RHNRFSPIDriver::_slaveSelectPin, RHNRFSPIDriver::_spi, RHGenericSPI::beginTransaction(), RHGenericSPI::endTransaction(), RHNRFSPIDriver::setSlaveSelectPin(), spiWriteRegister(), and RHGenericSPI::transfer().

◆ spiWriteData() [2/2]

uint8_t RH_MRF89::spiWriteData ( uint8_t data )

protected

Writes a single byte to the MRF89XA data FIFO.

Parameters

[in] data The data value to write

Returns: 0

References RHNRFSPIDriver::setSlaveSelectPin(), RHNRFSPIDriver::spiCommand(), and spiWriteRegister().

Referenced by send().

◆ spiWriteRegister()

uint8_t RH_MRF89::spiWriteRegister	(	uint8_t	reg,
		uint8_t	val
	)

protected

Writes to a single single register on the MRF89XA

Parameters

[in]	reg	Register number, one of RH_MRF89_REG_*
[in]	val	The value to write

Returns: the current value of RH_MRF89_REG_00_GCONREG (read while the command is sent)

References RHNRFSPIDriver::setSlaveSelectPin(), and RHNRFSPIDriver::spiWrite().

Referenced by init(), setFrequency(), setModemConfig(), setOpMode(), setPreambleLength(), setSyncWords(), setTxPower(), spiReadData(), spiWriteData(), and verifyPLLLock().

◆ verifyPLLLock()

bool RH_MRF89::verifyPLLLock ( )

protected

Verifies that the MRF89XA PLL has locked on the slected frequency. This needs to be called if the frequency is changed

References setOpMode(), spiReadRegister(), and spiWriteRegister().

Referenced by setFrequency().

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

RH_MRF89.h
RH_MRF89.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ ModemConfigChoice

Constructor & Destructor Documentation

◆ RH_MRF89()

Member Function Documentation

◆ available()

◆ handleInterrupt()

◆ init()

◆ maxMessageLength()

◆ printRegisters()

◆ recv()

◆ send()

◆ setFrequency()

◆ setModeIdle()

◆ setModemConfig()

◆ setModeRx()

◆ setModeTx()

◆ setOpMode()

◆ setPreambleLength()

◆ setSyncWords()

◆ setTxPower()

◆ sleep()

◆ spiReadData()

◆ spiReadRegister()

◆ spiWriteData() [1/2]

◆ spiWriteData() [2/2]

◆ spiWriteRegister()

◆ verifyPLLLock()