RadioHead
RHGenericDriver Class Reference
Abstract base class for a RadioHead driver. More...
#include <RHGenericDriver.h>
Inherited by RH_RF95.
Public Types | |
enum | RHMode { RHModeInitialising = 0, RHModeSleep, RHModeIdle, RHModeTx, RHModeRx, RHModeCad } |
Defines different operating modes for the transport hardware. More... | |
Public Member Functions | |
RHGenericDriver () | |
Constructor. | |
virtual bool | init () |
Initialise the Driver transport hardware and software. | |
virtual bool | available ()=0 |
Tests whether a new message is available from the Driver. | |
virtual bool | recv (uint8_t *buf, uint8_t *len)=0 |
Turns the receiver on if it not already on. | |
virtual bool | send (const uint8_t *data, uint8_t len)=0 |
Waits until any previous transmit packet is finished being transmitted with waitPacketSent(). | |
virtual uint8_t | maxMessageLength ()=0 |
Returns the maximum message length available in this Driver. | |
virtual void | waitAvailable () |
Starts the receiver and blocks until a valid received message is available. | |
virtual bool | waitPacketSent () |
Blocks until the transmitter is no longer transmitting. | |
virtual bool | waitPacketSent (uint16_t timeout) |
Blocks until the transmitter is no longer transmitting. | |
virtual bool | waitAvailableTimeout (uint16_t timeout) |
Starts the receiver and blocks until a received message is available or a timeout. | |
virtual bool | waitCAD () |
Channel Activity Detection (CAD). | |
void | setCADTimeout (unsigned long cad_timeout) |
Sets the Channel Activity Detection timeout in milliseconds to be used by waitCAD(). | |
virtual bool | isChannelActive () |
Determine if the currently selected radio channel is active. | |
virtual void | setThisAddress (uint8_t thisAddress) |
Sets the address of this node. | |
virtual void | setHeaderTo (uint8_t to) |
Sets the TO header to be sent in all subsequent messages. | |
virtual void | setHeaderFrom (uint8_t from) |
Sets the FROM header to be sent in all subsequent messages. | |
virtual void | setHeaderId (uint8_t id) |
Sets the ID header to be sent in all subsequent messages. | |
virtual void | setHeaderFlags (uint8_t set, uint8_t clear=RH_FLAGS_APPLICATION_SPECIFIC) |
Sets and clears bits in the FLAGS header to be sent in all subsequent messages First it clears he FLAGS according to the clear argument, then sets the flags according to the set argument. | |
virtual void | setPromiscuous (bool promiscuous) |
Tells the receiver to accept messages with any TO address, not just messages addressed to thisAddress or the broadcast address. | |
virtual uint8_t | headerTo () |
Returns the TO header of the last received message. | |
virtual uint8_t | headerFrom () |
Returns the FROM header of the last received message. | |
virtual uint8_t | headerId () |
Returns the ID header of the last received message. | |
virtual uint8_t | headerFlags () |
Returns the FLAGS header of the last received message. | |
int8_t | lastRssi () |
Returns the most recent RSSI (Receiver Signal Strength Indicator). | |
RHMode | mode () |
Returns the operating mode of the library. | |
void | setMode (RHMode mode) |
Sets the operating mode of the transport. | |
virtual bool | sleep () |
Sets the transport hardware into low-power sleep mode (if supported). | |
uint16_t | rxBad () |
Returns the count of the number of bad received packets (ie packets with bad lengths, checksum etc) which were rejected and not delivered to the application. | |
uint16_t | rxGood () |
Returns the count of the number of good received packets. | |
uint16_t | txGood () |
Returns the count of the number of packets successfully transmitted (though not necessarily received by the destination) | |
Static Public Member Functions | |
static void | printBuffer (const char *prompt, const uint8_t *buf, uint8_t len) |
Prints a data buffer in HEX. | |
Protected Attributes | |
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 int8_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
Abstract base class for a RadioHead driver.
This class defines the functions that must be provided by any RadioHead driver. Different types of driver will implement all the abstract functions, and will perhaps override other functions in this subclass, or perhaps add new functions specifically required by that driver. Do not directly instantiate this class: it is only to be subclassed by driver classes.
Subclasses are expected to implement a half-duplex, unreliable, error checked, unaddressed packet transport. They are expected to carry a message payload with an appropriate maximum length for the transport hardware and to also carry unaltered 4 message headers: TO, FROM, ID, FLAGS
- Headers
Each message sent and received by a RadioHead driver includes 4 headers: -TO The node address that the message is being sent to (broadcast RH_BROADCAST_ADDRESS (255) is permitted) -FROM The node address of the sending node -ID A message ID, distinct (over short time scales) for each message sent by a particilar node -FLAGS A bitmask of flags. The most significant 4 bits are reserved for use by RadioHead. The least significant 4 bits are reserved for applications.
Definition at line 47 of file RHGenericDriver.h.
Member Enumeration Documentation
enum RHMode |
Defines different operating modes for the transport hardware.
These are the different values that can be adopted by the _mode variable and returned by the mode() member function,
- Enumerator:
RHModeInitialising Transport is initialising. Initial default value until init() is called..
RHModeSleep Transport hardware is in low power sleep mode (if supported)
RHModeIdle Transport is idle.
RHModeTx Transport is in the process of transmitting a message.
RHModeRx Transport is in the process of receiving a message.
RHModeCad Transport is in the process of detecting channel activity (if supported)
Definition at line 54 of file RHGenericDriver.h.
Constructor & Destructor Documentation
RHGenericDriver | ( | ) |
Constructor.
Definition at line 11 of file RHGenericDriver.cpp.
Member Function Documentation
virtual bool available | ( | ) | [pure virtual] |
Tests whether a new message is available from the Driver.
On most drivers, if there is an uncollected received message, and there is no message currently bing transmitted, 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().
Implemented in RH_RF95.
uint8_t headerFlags | ( | ) | [virtual] |
Returns the FLAGS header of the last received message.
- Returns:
- The FLAGS header
Definition at line 163 of file RHGenericDriver.cpp.
uint8_t headerFrom | ( | ) | [virtual] |
Returns the FROM header of the last received message.
- Returns:
- The FROM header
Definition at line 153 of file RHGenericDriver.cpp.
uint8_t headerId | ( | ) | [virtual] |
Returns the ID header of the last received message.
- Returns:
- The ID header
Definition at line 158 of file RHGenericDriver.cpp.
uint8_t headerTo | ( | ) | [virtual] |
Returns the TO header of the last received message.
- Returns:
- The TO header
Definition at line 148 of file RHGenericDriver.cpp.
bool 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 in RH_RF95.
Definition at line 26 of file RHGenericDriver.cpp.
bool isChannelActive | ( | ) | [virtual] |
Determine if the currently selected radio channel is active.
This is expected to be subclassed by specific radios to implement their Channel Activity Detection if supported. If the radio does not support CAD, returns true immediately. If a RadioHead radio supports isChannelActive() it will be documented in the radio specific documentation. This is called automatically by waitCAD().
- Returns:
- true if the radio-specific CAD (as returned by override of isChannelActive()) shows the current radio channel as active, else false. If there is no radio-specific CAD, returns false.
Reimplemented in RH_RF95.
Definition at line 112 of file RHGenericDriver.cpp.
int8_t 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.
- Returns:
- The most recent RSSI measurement in dBm.
Definition at line 168 of file RHGenericDriver.cpp.
virtual uint8_t maxMessageLength | ( | ) | [pure virtual] |
Returns the maximum message length available in this Driver.
- Returns:
- The maximum legal message length
Implemented in RH_RF95.
RHGenericDriver::RHMode mode | ( | ) |
Returns the operating mode of the library.
- Returns:
- the current mode, one of RF69_MODE_*
Definition at line 173 of file RHGenericDriver.cpp.
void printBuffer | ( | const char * | prompt, |
const uint8_t * | buf, | ||
uint8_t | len | ||
) | [static] |
Prints a data buffer in HEX.
For diagnostic use
- Parameters:
-
[in] prompt string to preface the print [in] buf Location of the buffer to print [in] len Length of the buffer in octets.
Definition at line 189 of file RHGenericDriver.cpp.
virtual bool recv | ( | uint8_t * | buf, |
uint8_t * | len | ||
) | [pure 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 available space in buf. Set to the actual number of octets copied.
- Returns:
- true if a valid message was copied to buf
Implemented in RH_RF95.
uint16_t rxBad | ( | ) |
Returns the count of the number of bad received packets (ie packets with bad lengths, checksum etc) which were rejected and not delivered to the application.
Caution: not all drivers can correctly report this count. Some underlying hardware only report good packets.
- Returns:
- The number of bad packets received.
Definition at line 206 of file RHGenericDriver.cpp.
uint16_t rxGood | ( | ) |
Returns the count of the number of good received packets.
- Returns:
- The number of good packets received.
Definition at line 211 of file RHGenericDriver.cpp.
virtual bool send | ( | const uint8_t * | data, |
uint8_t | len | ||
) | [pure virtual] |
Waits until any previous transmit packet is finished being transmitted with waitPacketSent().
Then optionally waits for Channel Activity Detection (CAD) to show the channnel is clear (if the radio supports CAD) by calling waitCAD(). Then loads a message into the transmitter and starts the transmitter. Note that a message length of 0 is NOT permitted. If the message is too long for the underlying radio technology, send() will return false and will not send the message.
- Parameters:
-
[in] data Array of data to be sent [in] len Number of bytes of data to send (> 0) specify the maximum time in ms to wait. If 0 (the default) do not wait for CAD before transmitting.
- Returns:
- true if the message length was valid and it was correctly queued for transmit. Return false if CAD was requested and the CAD timeout timed out before clear channel was detected.
Implemented in RH_RF95.
void setCADTimeout | ( | unsigned long | cad_timeout ) |
Sets the Channel Activity Detection timeout in milliseconds to be used by waitCAD().
The default is 0, which means do not wait for CAD detection. CAD detection depends on support for isChannelActive() by your particular radio.
Definition at line 221 of file RHGenericDriver.cpp.
void setHeaderFlags | ( | uint8_t | set, |
uint8_t | clear = RH_FLAGS_APPLICATION_SPECIFIC |
||
) | [virtual] |
Sets and clears bits in the FLAGS header to be sent in all subsequent messages First it clears he FLAGS according to the clear argument, then sets the flags according to the set argument.
The default for clear always clears the application specific flags.
- Parameters:
-
[in] set bitmask of bits to be set. Flags are cleared with the clear mask before being set. [in] clear bitmask of flags to clear. Defaults to RH_FLAGS_APPLICATION_SPECIFIC which clears the application specific flags, resulting in new application specific flags identical to the set.
Definition at line 142 of file RHGenericDriver.cpp.
void setHeaderFrom | ( | uint8_t | from ) | [virtual] |
Sets the FROM header to be sent in all subsequent messages.
- Parameters:
-
[in] from The new FROM header value
Definition at line 132 of file RHGenericDriver.cpp.
void setHeaderId | ( | uint8_t | id ) | [virtual] |
Sets the ID header to be sent in all subsequent messages.
- Parameters:
-
[in] id The new ID header value
Definition at line 137 of file RHGenericDriver.cpp.
void setHeaderTo | ( | uint8_t | to ) | [virtual] |
Sets the TO header to be sent in all subsequent messages.
- Parameters:
-
[in] to The new TO header value
Definition at line 127 of file RHGenericDriver.cpp.
void setMode | ( | RHMode | mode ) |
Sets the operating mode of the transport.
Definition at line 178 of file RHGenericDriver.cpp.
void setPromiscuous | ( | bool | promiscuous ) | [virtual] |
Tells the receiver to accept messages with any TO address, not just messages addressed to thisAddress or the broadcast address.
- Parameters:
-
[in] promiscuous true if you wish to receive messages with any TO address
Definition at line 117 of file RHGenericDriver.cpp.
void setThisAddress | ( | uint8_t | thisAddress ) | [virtual] |
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).
- Parameters:
-
[in] thisAddress The address of this node.
Definition at line 122 of file RHGenericDriver.cpp.
bool sleep | ( | ) | [virtual] |
Sets the transport hardware into low-power sleep mode (if supported).
May be overridden by specific drivers to initialte sleep mode. If successful, the transport will stay in sleep mode until woken by changing mode it idle, transmit or receive (eg by calling send(), recv(), available() etc)
- Returns:
- true if sleep mode is supported by transport hardware and the RadioHead driver, and if sleep mode was successfully entered. If sleep mode is not suported, return false.
Reimplemented in RH_RF95.
Definition at line 183 of file RHGenericDriver.cpp.
uint16_t txGood | ( | ) |
Returns the count of the number of packets successfully transmitted (though not necessarily received by the destination)
- Returns:
- The number of packets successfully transmitted
Definition at line 216 of file RHGenericDriver.cpp.
void waitAvailable | ( | ) | [virtual] |
Starts the receiver and blocks until a valid received message is available.
Definition at line 32 of file RHGenericDriver.cpp.
bool waitAvailableTimeout | ( | uint16_t | timeout ) | [virtual] |
Starts the receiver and blocks until a received message is available or a timeout.
- Parameters:
-
[in] timeout Maximum time to wait in milliseconds.
- Returns:
- true if a message is available
Definition at line 41 of file RHGenericDriver.cpp.
bool waitCAD | ( | ) | [virtual] |
Channel Activity Detection (CAD).
Blocks until channel activity is finished or CAD timeout occurs. Uses the radio's CAD function (if supported) to detect channel activity. Implements random delays of 100 to 1000ms while activity is detected and until timeout. Caution: the random() function is not seeded. If you want non-deterministic behaviour, consider using something like randomSeed(analogRead(A0)); in your sketch. Permits the implementation of listen-before-talk mechanism (Collision Avoidance). Calls the isChannelActive() member function for the radio (if supported) to determine if the channel is active. If the radio does not support isChannelActive(), always returns true immediately
- Returns:
- true if the radio-specific CAD (as returned by isChannelActive()) shows the channel is clear within the timeout period (or the timeout period is 0), else returns false.
Definition at line 84 of file RHGenericDriver.cpp.
bool waitPacketSent | ( | uint16_t | timeout ) | [virtual] |
Blocks until the transmitter is no longer transmitting.
or until the timeout occuers, whichever happens first
- Parameters:
-
[in] timeout Maximum time to wait in milliseconds.
- Returns:
- true if the radio completed transmission within the timeout period. False if it timed out.
Definition at line 66 of file RHGenericDriver.cpp.
bool waitPacketSent | ( | ) | [virtual] |
Blocks until the transmitter is no longer transmitting.
Definition at line 59 of file RHGenericDriver.cpp.
Field Documentation
volatile bool _cad [protected] |
Channel activity detected.
Definition at line 304 of file RHGenericDriver.h.
unsigned int _cad_timeout [protected] |
Channel activity timeout in ms.
Definition at line 307 of file RHGenericDriver.h.
volatile int8_t _lastRssi [protected] |
The value of the last received RSSI value, in some transport specific units.
Definition at line 292 of file RHGenericDriver.h.
The current transport operating mode.
Definition at line 259 of file RHGenericDriver.h.
bool _promiscuous [protected] |
Whether the transport is in promiscuous mode.
Definition at line 265 of file RHGenericDriver.h.
volatile uint16_t _rxBad [protected] |
Count of the number of bad messages (eg bad checksum etc) received.
Definition at line 295 of file RHGenericDriver.h.
volatile uint16_t _rxGood [protected] |
Count of the number of successfully transmitted messaged.
Definition at line 298 of file RHGenericDriver.h.
volatile uint8_t _rxHeaderFlags [protected] |
FLAGS header in the last received mesasge.
Definition at line 277 of file RHGenericDriver.h.
volatile uint8_t _rxHeaderFrom [protected] |
FROM header in the last received mesasge.
Definition at line 271 of file RHGenericDriver.h.
volatile uint8_t _rxHeaderId [protected] |
ID header in the last received mesasge.
Definition at line 274 of file RHGenericDriver.h.
volatile uint8_t _rxHeaderTo [protected] |
TO header in the last received mesasge.
Definition at line 268 of file RHGenericDriver.h.
uint8_t _thisAddress [protected] |
This node id.
Definition at line 262 of file RHGenericDriver.h.
volatile uint16_t _txGood [protected] |
Count of the number of bad messages (correct checksum etc) received.
Definition at line 301 of file RHGenericDriver.h.
uint8_t _txHeaderFlags [protected] |
FLAGS header to send in all messages.
Definition at line 289 of file RHGenericDriver.h.
uint8_t _txHeaderFrom [protected] |
FROM header to send in all messages.
Definition at line 283 of file RHGenericDriver.h.
uint8_t _txHeaderId [protected] |
ID header to send in all messages.
Definition at line 286 of file RHGenericDriver.h.
uint8_t _txHeaderTo [protected] |
TO header to send in all messages.
Definition at line 280 of file RHGenericDriver.h.
Generated on Mon Jul 18 2022 11:18:50 by 1.7.2