RadioHead
Classes | Public Types | Public Member Functions | Protected Member Functions | List of all members
RH_MRF89 Class Reference

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

#include <RH_MRF89.h>

Inheritance diagram for RH_MRF89:
RHNRFSPIDriver RHGenericDriver

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 void waitAvailable ()
 
virtual bool waitPacketSent ()
 
virtual bool waitPacketSent (uint16_t timeout)
 
virtual bool waitAvailableTimeout (uint16_t timeout)
 
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 ()
 
int16_t lastRssi ()
 
RHMode mode ()
 
void setMode (RHMode mode)
 Sets the operating mode of the transport.
 
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.
 

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:

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.

Example programs

Several example programs are provided.

Member Enumeration Documentation

◆ 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]csconPinthe 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]csdatPinthe Arduino pin number connected to the CSDAT pin of the MRF89XA. Defaults to 9.
[in]interruptPinThe 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]spiPointer 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

◆ 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(), RHGenericSPI::setFrequency(), 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]bufLocation to copy the received message
[in,out]lenPointer to available space in buf. Set 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]dataArray of data to be sent
[in]lenNumber 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]indexThe 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]modeOne of RH_MRF89_CMOD_*

References 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]bytesPreamble 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]syncWordsArray of sync words, 1 to 4 octets long
[in]lenNumber 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]powerTransmitter 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]regRegister 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 ( uint8_t  data)
protected

Writes a single byte to the MRF89XA data FIFO.

Parameters
[in]dataThe data value to write
Returns
0

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

Referenced by send().

◆ spiWriteData() [2/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]dataPointer to a buffer containing the len bytes to be written
[in]lenThe 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().

◆ spiWriteRegister()

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

Writes to a single single register on the MRF89XA

Parameters
[in]regRegister number, one of RH_MRF89_REG_*
[in]valThe 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: