Team Walter / RadioHead

RadioHead

Embed: (wiki syntax)

« Back to documentation index

RHGenericDriver Class Reference
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes

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]promptstring to preface the print
[in]bufLocation of the buffer to print
[in]lenLength 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]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

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]dataArray of data to be sent
[in]lenNumber 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]setbitmask of bits to be set. Flags are cleared with the clear mask before being set.
[in]clearbitmask 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]fromThe 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]idThe 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]toThe 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]promiscuoustrue 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]thisAddressThe 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]timeoutMaximum 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]timeoutMaximum 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.

volatile RHMode _mode [protected]

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  doxygen 1.7.2