RF69
|
Send and receive unaddressed, unreliable datagrams. More...
#include <RF69.h>
Classes | |
struct | ModemConfig |
Defines register values for a set of modem configuration registers. More... | |
Public Member Functions | |
RF69 (uint8_t slaveSelectPin=SS, uint8_t interrupt=0, GenericSPIClass *spi=&Hardware_spi) | |
boolean | init () |
void | reset () |
uint8_t | spiRead (uint8_t reg) |
void | spiWrite (uint8_t reg, uint8_t val) |
void | spiBurstRead (uint8_t reg, uint8_t *dest, uint8_t len) |
void | spiBurstWrite (uint8_t reg, const uint8_t *src, uint8_t len) |
int8_t | temperatureRead () |
boolean | setFrequency (float centre, float afcPullInRange=0.05) |
int8_t | rssiRead () |
void | setMode (uint8_t mode) |
void | setModeIdle () |
void | setModeRx () |
void | setModeTx () |
uint8_t | mode () |
void | setTxPower (int8_t power) |
void | setModemRegisters (const ModemConfig *config) |
boolean | setModemConfig (ModemConfigChoice index) |
boolean | available () |
void | waitAvailable () |
bool | waitAvailableTimeout (uint16_t timeout) |
void | setThisAddress (uint8_t thisAddress) |
boolean | recv (uint8_t *buf, uint8_t *len) |
boolean | send (const uint8_t *data, uint8_t len) |
void | waitPacketSent () |
bool | waitPacketSent (uint16_t timeout) |
void | setPromiscuous (boolean promiscuous) |
uint8_t | headerTo () |
uint8_t | headerFrom () |
uint8_t | headerId () |
uint8_t | headerFlags () |
int8_t | lastRssi () |
void | setPreambleLength (uint16_t bytes) |
void | setSyncWords (const uint8_t *syncWords=NULL, uint8_t len=0) |
void | setEncryptionKey (uint8_t *key=NULL) |
Static Public Member Functions | |
static void | printBuffer (const char *prompt, const uint8_t *buf, uint8_t len) |
Protected Member Functions | |
void | handleInterrupt () |
void | readFifo () |
void | setHeaderTo (uint8_t to) |
void | setHeaderFrom (uint8_t from) |
void | setHeaderId (uint8_t id) |
void | setHeaderFlags (uint8_t flags) |
Static Protected Member Functions | |
static void | isr0 () |
Low level interrupt service routine for RF69 connected to interrupt 0. | |
static void | isr1 () |
Low level interrupt service routine for RF69 connected to interrupt 1. | |
static void | isr2 () |
Low level interrupt service routine for RF69 connected to interrupt 1. | |
Protected Attributes | |
GenericSPIClass * | _spi |
volatile uint8_t | _mode |
uint8_t | _idleMode |
uint8_t | _slaveSelectPin |
uint8_t | _interrupt |
uint8_t | _deviceType |
volatile uint8_t | _bufLen |
uint8_t | _buf [RF69_MAX_MESSAGE_LEN] |
uint8_t | _thisAddress |
boolean | _promiscuous |
uint8_t | _rxHeaderTo |
uint8_t | _rxHeaderFrom |
uint8_t | _rxHeaderId |
uint8_t | _rxHeaderFlags |
uint8_t | _txHeaderTo |
uint8_t | _txHeaderFrom |
uint8_t | _txHeaderId |
uint8_t | _txHeaderFlags |
volatile boolean | _rxBufValid |
volatile boolean | _txPacketSent |
volatile uint16_t | _rxBad |
volatile uint16_t | _rxGood |
volatile uint16_t | _txGood |
volatile int8_t | _lastRssi |
Static Protected Attributes | |
static RF69 * | _RF69ForInterrupt [] = {0, 0, 0} |
Array of instances connected to interrupts 0 and 1. | |
Send and receive unaddressed, unreliable datagrams.
This base class provides basic functions for sending and receiving unaddressed, unreliable datagrams of arbitrary length to 64 octets per packet.
Subclasses may use this class to implement reliable, addressed datagrams and streams, mesh routers, repeaters, translators etc.
Naturally, for any 2 radios to communicate that must be configured to use the same frequency and modulation scheme.
Choices for setModemConfig() for a selected subset of common modulation types, and data rates. If you need another configuration, use the register calculator. and call setModemRegisters() with your desired settings. These are indexes into MODEM_CONFIG_TABLE
RF69::RF69 | ( | uint8_t | slaveSelectPin = SS , |
uint8_t | interrupt = 0 , |
||
GenericSPIClass * | spi = &Hardware_spi |
||
) |
Constructor. You can have multiple instances, but each instance must have its own interrupt and slave select pin. After constructing, you must call init() to initialise the interface and the radio module
[in] | slaveSelectPin | the Arduino pin number of the output to use to select the RF69 before accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega) |
[in] | interrupt | The interrupt number to use. 0 - 2. Default is interrupt 0 (Usually Arduino input pin 2) |
[in] | spi | Pointer to the SPI interface object to use. Defaults to the standard Arduino hardware SPI interface |
boolean RF69::available | ( | ) |
Starts the receiver and checks whether a received message is available. This can be called multiple times in a timeout loop
References setModeRx().
Referenced by recv(), waitAvailable(), and waitAvailableTimeout().
|
protected |
This is a low level function to handle the interrupts for one instance of RF69. Called automatically by isr*() Should not need to be called by user code.
References readFifo(), setModeIdle(), and spiRead().
uint8_t RF69::headerFlags | ( | ) |
Returns the FLAGS header of the last received message
uint8_t RF69::headerFrom | ( | ) |
Returns the FROM header of the last received message
uint8_t RF69::headerId | ( | ) |
Returns the ID header of the last received message
uint8_t RF69::headerTo | ( | ) |
Returns the TO header of the last received message
boolean RF69::init | ( | ) |
Initialises this instance and the radio module connected to it. The following steps are taken:
References _RF69ForInterrupt, GenericSPIClass::begin(), FSK_Rb2Fd5, isr0(), isr1(), isr2(), reset(), GenericSPIClass::setBitOrder(), GenericSPIClass::setClockDivider(), GenericSPIClass::setDataMode(), setEncryptionKey(), setFrequency(), setMode(), setModemConfig(), setPreambleLength(), setSyncWords(), setTxPower(), spiRead(), and spiWrite().
int8_t RF69::lastRssi | ( | ) |
Returns the most recent RSSI (Receiver Signal Strength Indicator). Usually it is the RSSI of the last received message, which is measured when the preamble is received. If you called readRssi() more recently, it will return that more recent value.
uint8_t RF69::mode | ( | ) |
Returns the operating mode of the library.
|
static |
Prints a data buffer in HEX. For diagnostic use
[in] | prompt | string to preface the print |
[in] | buf | Location of the buffer to print |
[in] | len | Length of the buffer in octets. |
|
protected |
Low level function to read the FIFO and put the received data into the receive buffer Should not need to be called by user code.
References GenericSPIClass::transfer().
Referenced by handleInterrupt().
boolean RF69::recv | ( | uint8_t * | buf, |
uint8_t * | len | ||
) |
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.
[in] | buf | Location to copy the received message |
[in,out] | len | Pointer to available space in buf. Set to the actual number of octets copied. |
References available().
void RF69::reset | ( | ) |
int8_t RF69::rssiRead | ( | ) |
Reads and returns the current RSSI value. Causes the current signal strength to be measured and returned If you want to find the RSSI of the last received message, use lastRssi() instead.
References spiRead(), and spiWrite().
boolean RF69::send | ( | const uint8_t * | data, |
uint8_t | len | ||
) |
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 NOT permitted.
[in] | data | Array of data to be sent |
[in] | len | Number of bytes of data to send (> 0) |
References setModeIdle(), setModeTx(), GenericSPIClass::transfer(), and waitPacketSent().
void RF69::setEncryptionKey | ( | uint8_t * | key = NULL | ) |
Enables AES encryption and sets the AES encryption key, used to encrypt and decrypt all messages. The default is disabled.
[in] | key | The key to use. Must be 16 bytes long. The same key must be installed in other instances of RF69, otherwise communications will not work correctly. If key is NULL, encryption is disabled. |
References spiBurstWrite(), spiRead(), and spiWrite().
Referenced by init().
boolean RF69::setFrequency | ( | float | centre, |
float | afcPullInRange = 0.05 |
||
) |
Sets the transmitter and receiver centre frequency
[in] | centre | Frequency in MHz. 240.0 to 960.0. Caution, RF69 comes in several different frequency ranges, and setting a frequency outside that range of your radio will probably not work |
[in] | afcPullInRange | Not used |
References spiWrite().
Referenced by init().
|
protected |
Sets the FLAGS header to be sent in all subsequent messages
[in] | flags | The new FLAGS header value |
|
protected |
Sets the FROM header to be sent in all subsequent messages
[in] | from | The new FROM header value |
|
protected |
Sets the ID header to be sent in all subsequent messages
[in] | id | The new ID header value |
|
protected |
Sets the TO header to be sent in all subsequent messages
[in] | to | The new TO header value |
void RF69::setMode | ( | uint8_t | mode | ) |
Sets the parameters for the RF69 OPMODE. This is a low level device access funciton, and should not normally ned to be used by user code. Instead can use stModeRx(), setModeTx(), setModeIdle()
[in] | mode | RF69 OPMODE to set, one of RF69_OPMODE_MODE_*. |
References spiRead(), and spiWrite().
Referenced by init(), setModeIdle(), setModeRx(), and setModeTx().
void RF69::setModeIdle | ( | ) |
If current mode is Rx or Tx changes it to Idle. If the transmitter or receiver is running, disables them.
References setMode().
Referenced by handleInterrupt(), and send().
boolean RF69::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.
[in] | index | The configuration choice. |
References setModemRegisters().
Referenced by init().
void RF69::setModemRegisters | ( | const ModemConfig * | config | ) |
Sets all the registered required to configure the data modem in the RF69, including the data rate, bandwidths etc. You cas use this to configure the modem with custom configurations if none of the canned configurations in ModemConfigChoice suit you.
[in] | config | A ModemConfig structure containing values for the modem configuration registers. |
References RF69::ModemConfig::reg_02, RF69::ModemConfig::reg_19, RF69::ModemConfig::reg_37, spiBurstWrite(), and spiWrite().
Referenced by setModemConfig().
void RF69::setModeRx | ( | ) |
If current mode is Tx or Idle, changes it to Rx. Starts the receiver in the RF69.
References setMode(), and spiWrite().
Referenced by available().
void RF69::setModeTx | ( | ) |
If current mode is Rx or Idle, changes it to Rx. F Starts the transmitter in the RF69.
References setMode(), and spiWrite().
Referenced by send().
void RF69::setPreambleLength | ( | uint16_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 REG_0?_PREAMBLE?SB
[in] | bytes | Preamble length in bytes. |
References spiWrite().
Referenced by init().
void RF69::setPromiscuous | ( | boolean | promiscuous | ) |
Tells the receiver to accept messages with any TO address, not just messages addressed to thisAddress or the broadcast address
[in] | promiscuous | true if you wish to receive messages with any TO address |
void RF69::setSyncWords | ( | const uint8_t * | syncWords = NULL , |
uint8_t | len = 0 |
||
) |
Sets the sync words for transmit and receive 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 { 0x2d, 0xd4 }.
[in] | syncWords | Array of sync words, 1 to 4 octets long. NULL if no sync words to be used. |
[in] | len | Number of sync words to set, 1 to 4. 0 if no sync words to be used. |
References spiBurstWrite(), spiRead(), and spiWrite().
Referenced by init().
void RF69::setThisAddress | ( | uint8_t | thisAddress | ) |
Sets the address of this node. Defaults to 0xFF. Subclasses or the user may want to change this. This will be used to test the adddress in incoming messages. In non-promiscuous mode, only messages with a TO header the same as thisAddress or the broadcast addess (0xFF) will be accepted. In promiscuous mode, all messages will be accepted regardless of the TO header. In a conventional multinode system, all nodes will have a unique address (which you could store in EEPROM). You would normally set the header FROM address to be the same as thisAddress (though you dont have to, allowing the possibilty of address spoofing).
[in] | thisAddress | The address of this node. |
void RF69::setTxPower | ( | int8_t | power | ) |
Sets the transmitter power output level. Be a good neighbour and set the lowest power level you need. Caution: legal power limits may apply in certain countries. After init(), the power will be set to 13dBm.
[in] | power | Transmitter power level in dBm from -18dBm to +13dB (higher powers may be available depending on which version of RF69 radio you have). |
References spiWrite().
Referenced by init().
void RF69::spiBurstRead | ( | uint8_t | reg, |
uint8_t * | dest, | ||
uint8_t | len | ||
) |
Reads a number of consecutive registers from the RF69 using burst read mode
[in] | reg | Register number of the first register, one of RF69_REG_* |
[in] | dest | Array to write the register values to. Must be at least len bytes |
[in] | len | Number of bytes to read |
References GenericSPIClass::transfer().
void RF69::spiBurstWrite | ( | uint8_t | reg, |
const uint8_t * | src, | ||
uint8_t | len | ||
) |
Write a number of consecutive registers using burst write mode
[in] | reg | Register number of the first register, one of RF69_REG_* |
[in] | src | Array of new register values to write. Must be at least len bytes |
[in] | len | Number of bytes to write |
References GenericSPIClass::transfer().
Referenced by setEncryptionKey(), setModemRegisters(), and setSyncWords().
uint8_t RF69::spiRead | ( | uint8_t | reg | ) |
Reads a single register from the RF69
[in] | reg | Register number, one of RF69_REG_* |
References GenericSPIClass::transfer().
Referenced by handleInterrupt(), init(), rssiRead(), setEncryptionKey(), setMode(), setSyncWords(), and temperatureRead().
void RF69::spiWrite | ( | uint8_t | reg, |
uint8_t | val | ||
) |
Writes a single byte to the RF69
[in] | reg | Register number, one of RF69_REG_* |
[in] | val | The value to write |
References GenericSPIClass::transfer().
Referenced by init(), rssiRead(), setEncryptionKey(), setFrequency(), setMode(), setModemRegisters(), setModeRx(), setModeTx(), setPreambleLength(), setSyncWords(), setTxPower(), and temperatureRead().
int8_t RF69::temperatureRead | ( | ) |
Reads the on-chip temperature sensor. The RF69 must be in Idle mode (= RF69 Standby) to measure temperature. The measurement is uncalibrated and without calibration, you can expectit to be far from correct.
References spiRead(), and spiWrite().
void RF69::waitAvailable | ( | ) |
Starts the receiver and blocks until a valid received message is available.
References available().
bool RF69::waitAvailableTimeout | ( | uint16_t | timeout | ) |
Starts the receiver and blocks until a received message is available or a timeout
[in] | timeout | Maximum time to wait in milliseconds. |
References available().
void RF69::waitPacketSent | ( | ) |
Blocks until the RF69 is not in mode RF69_MODE_TX (ie until the RF69 is not transmitting). This effectively waits until any previous transmit packet is finished being transmitted.
Referenced by send().
bool RF69::waitPacketSent | ( | uint16_t | timeout | ) |