ilkay KOZAK / RadioHead-148

V148

Fork of RadioHead-148 by David Rimer

RHGenericDriver.h@1:b7641da2b203, 2017-10-25 (annotated)

Committer:
ilkaykozak
Date:
Wed Oct 25 05:14:09 2017 +0000
Revision:
1:b7641da2b203
Parent:
0:ab4e012489ef 
V148

Who changed what in which revision?

UserRevisionLine numberNew contents of line
davidr99 0:ab4e012489ef 1 // RHGenericDriver.h
davidr99 0:ab4e012489ef 2 // Author: Mike McCauley (mikem@airspayce.com)
davidr99 0:ab4e012489ef 3 // Copyright (C) 2014 Mike McCauley
davidr99 0:ab4e012489ef 4 // $Id: RHGenericDriver.h,v 1.16 2015/01/02 21:38:24 mikem Exp $
davidr99 0:ab4e012489ef 5
davidr99 0:ab4e012489ef 6 #ifndef RHGenericDriver_h
davidr99 0:ab4e012489ef 7 #define RHGenericDriver_h
davidr99 0:ab4e012489ef 8
davidr99 0:ab4e012489ef 9 #include <RadioHead.h>
davidr99 0:ab4e012489ef 10
davidr99 0:ab4e012489ef 11 // Defines bits of the FLAGS header reserved for use by the RadioHead library and
davidr99 0:ab4e012489ef 12 // the flags available for use by applications
davidr99 0:ab4e012489ef 13 #define RH_FLAGS_RESERVED 0xf0
davidr99 0:ab4e012489ef 14 #define RH_FLAGS_APPLICATION_SPECIFIC 0x0f
davidr99 0:ab4e012489ef 15 #define RH_FLAGS_NONE 0
davidr99 0:ab4e012489ef 16
davidr99 0:ab4e012489ef 17 /////////////////////////////////////////////////////////////////////
davidr99 0:ab4e012489ef 18 /// \class RHGenericDriver RHGenericDriver.h <RHGenericDriver.h>
davidr99 0:ab4e012489ef 19 /// \brief Abstract base class for a RadioHead driver.
davidr99 0:ab4e012489ef 20 ///
davidr99 0:ab4e012489ef 21 /// This class defines the functions that must be provided by any RadioHead driver.
davidr99 0:ab4e012489ef 22 /// Different types of driver will implement all the abstract functions, and will perhaps override
davidr99 0:ab4e012489ef 23 /// other functions in this subclass, or perhaps add new functions specifically required by that driver.
davidr99 0:ab4e012489ef 24 /// Do not directly instantiate this class: it is only to be subclassed by driver classes.
davidr99 0:ab4e012489ef 25 ///
davidr99 0:ab4e012489ef 26 /// Subclasses are expected to implement a half-duplex, unreliable, error checked, unaddressed packet transport.
davidr99 0:ab4e012489ef 27 /// They are expected to carry a message payload with an appropriate maximum length for the transport hardware
davidr99 0:ab4e012489ef 28 /// and to also carry unaltered 4 message headers: TO, FROM, ID, FLAGS
davidr99 0:ab4e012489ef 29 ///
davidr99 0:ab4e012489ef 30 /// \par Headers
davidr99 0:ab4e012489ef 31 ///
davidr99 0:ab4e012489ef 32 /// Each message sent and received by a RadioHead driver includes 4 headers:
davidr99 0:ab4e012489ef 33 /// -TO The node address that the message is being sent to (broadcast RH_BROADCAST_ADDRESS (255) is permitted)
davidr99 0:ab4e012489ef 34 /// -FROM The node address of the sending node
davidr99 0:ab4e012489ef 35 /// -ID A message ID, distinct (over short time scales) for each message sent by a particilar node
davidr99 0:ab4e012489ef 36 /// -FLAGS A bitmask of flags. The most significant 4 bits are reserved for use by RadioHead. The least
davidr99 0:ab4e012489ef 37 /// significant 4 bits are reserved for applications.
davidr99 0:ab4e012489ef 38 class RHGenericDriver
davidr99 0:ab4e012489ef 39 {
davidr99 0:ab4e012489ef 40 public:
davidr99 0:ab4e012489ef 41 /// \brief Defines different operating modes for the transport hardware
davidr99 0:ab4e012489ef 42 ///
davidr99 0:ab4e012489ef 43 /// These are the different values that can be adopted by the _mode variable and
davidr99 0:ab4e012489ef 44 /// returned by the mode() member function,
davidr99 0:ab4e012489ef 45 typedef enum
davidr99 0:ab4e012489ef 46 {
davidr99 0:ab4e012489ef 47 RHModeInitialising = 0, ///< Transport is initialising. Initial default value until init() is called..
davidr99 0:ab4e012489ef 48 RHModeSleep, ///< Transport hardware is in low power sleep mode (if supported)
davidr99 0:ab4e012489ef 49 RHModeIdle, ///< Transport is idle.
davidr99 0:ab4e012489ef 50 RHModeTx, ///< Transport is in the process of transmitting a message.
davidr99 0:ab4e012489ef 51 RHModeRx ///< Transport is in the process of receiving a message.
davidr99 0:ab4e012489ef 52 } RHMode;
davidr99 0:ab4e012489ef 53
davidr99 0:ab4e012489ef 54 /// Constructor
davidr99 0:ab4e012489ef 55 RHGenericDriver();
davidr99 0:ab4e012489ef 56
davidr99 0:ab4e012489ef 57 /// Initialise the Driver transport hardware and software.
davidr99 0:ab4e012489ef 58 /// Make sure the Driver is properly configured before calling init().
davidr99 0:ab4e012489ef 59 /// \return true if initialisation succeeded.
davidr99 0:ab4e012489ef 60 virtual bool init();
davidr99 0:ab4e012489ef 61
davidr99 0:ab4e012489ef 62 /// Tests whether a new message is available
davidr99 0:ab4e012489ef 63 /// from the Driver.
davidr99 0:ab4e012489ef 64 /// On most drivers, if there is an uncollected received message, and there is no message
davidr99 0:ab4e012489ef 65 /// currently bing transmitted, this will also put the Driver into RHModeRx mode until
davidr99 0:ab4e012489ef 66 /// a message is actually received by the transport, when it will be returned to RHModeIdle.
davidr99 0:ab4e012489ef 67 /// This can be called multiple times in a timeout loop.
davidr99 0:ab4e012489ef 68 /// \return true if a new, complete, error-free uncollected message is available to be retreived by recv().
davidr99 0:ab4e012489ef 69 virtual bool available() = 0;
davidr99 0:ab4e012489ef 70
davidr99 0:ab4e012489ef 71 /// Turns the receiver on if it not already on.
davidr99 0:ab4e012489ef 72 /// If there is a valid message available, copy it to buf and return true
davidr99 0:ab4e012489ef 73 /// else return false.
davidr99 0:ab4e012489ef 74 /// If a message is copied, *len is set to the length (Caution, 0 length messages are permitted).
davidr99 0:ab4e012489ef 75 /// You should be sure to call this function frequently enough to not miss any messages
davidr99 0:ab4e012489ef 76 /// It is recommended that you call it in your main loop.
davidr99 0:ab4e012489ef 77 /// \param[in] buf Location to copy the received message
davidr99 0:ab4e012489ef 78 /// \param[in,out] len Pointer to available space in buf. Set to the actual number of octets copied.
davidr99 0:ab4e012489ef 79 /// \return true if a valid message was copied to buf
davidr99 0:ab4e012489ef 80 virtual bool recv(uint8_t* buf, uint8_t* len) = 0;
davidr99 0:ab4e012489ef 81
davidr99 0:ab4e012489ef 82 /// Waits until any previous transmit packet is finished being transmitted with waitPacketSent().
davidr99 0:ab4e012489ef 83 /// Then loads a message into the transmitter and starts the transmitter. Note that a message length
davidr99 0:ab4e012489ef 84 /// of 0 is NOT permitted. If the message is too long for the underlying radio technology, send() will
davidr99 0:ab4e012489ef 85 /// return false and will not send the message.
davidr99 0:ab4e012489ef 86 /// \param[in] data Array of data to be sent
davidr99 0:ab4e012489ef 87 /// \param[in] len Number of bytes of data to send (> 0)
davidr99 0:ab4e012489ef 88 /// \return true if the message length was valid and it was correctly queued for transmit
davidr99 0:ab4e012489ef 89 virtual bool send(const uint8_t* data, uint8_t len) = 0;
davidr99 0:ab4e012489ef 90
davidr99 0:ab4e012489ef 91 /// Returns the maximum message length
davidr99 0:ab4e012489ef 92 /// available in this Driver.
davidr99 0:ab4e012489ef 93 /// \return The maximum legal message length
davidr99 0:ab4e012489ef 94 virtual uint8_t maxMessageLength() = 0;
davidr99 0:ab4e012489ef 95
davidr99 0:ab4e012489ef 96 /// Starts the receiver and blocks until a valid received
davidr99 0:ab4e012489ef 97 /// message is available.
davidr99 0:ab4e012489ef 98 virtual void waitAvailable();
davidr99 0:ab4e012489ef 99
davidr99 0:ab4e012489ef 100 /// Blocks until the transmitter
davidr99 0:ab4e012489ef 101 /// is no longer transmitting.
davidr99 0:ab4e012489ef 102 virtual bool waitPacketSent();
davidr99 0:ab4e012489ef 103
davidr99 0:ab4e012489ef 104 /// Blocks until the transmitter is no longer transmitting.
davidr99 0:ab4e012489ef 105 /// or until the timeout occuers, whichever happens first
davidr99 0:ab4e012489ef 106 /// \param[in] timeout Maximum time to wait in milliseconds.
davidr99 0:ab4e012489ef 107 /// \return true if the RF22 completed transmission within the timeout period. False if it timed out.
davidr99 0:ab4e012489ef 108 virtual bool waitPacketSent(uint16_t timeout);
davidr99 0:ab4e012489ef 109
davidr99 0:ab4e012489ef 110 /// Starts the receiver and blocks until a received message is available or a timeout
davidr99 0:ab4e012489ef 111 /// \param[in] timeout Maximum time to wait in milliseconds.
davidr99 0:ab4e012489ef 112 /// \return true if a message is available
davidr99 0:ab4e012489ef 113 virtual bool waitAvailableTimeout(uint16_t timeout);
davidr99 0:ab4e012489ef 114
davidr99 0:ab4e012489ef 115 /// Sets the address of this node. Defaults to 0xFF. Subclasses or the user may want to change this.
davidr99 0:ab4e012489ef 116 /// This will be used to test the adddress in incoming messages. In non-promiscuous mode,
davidr99 0:ab4e012489ef 117 /// only messages with a TO header the same as thisAddress or the broadcast addess (0xFF) will be accepted.
davidr99 0:ab4e012489ef 118 /// In promiscuous mode, all messages will be accepted regardless of the TO header.
davidr99 0:ab4e012489ef 119 /// In a conventional multinode system, all nodes will have a unique address
davidr99 0:ab4e012489ef 120 /// (which you could store in EEPROM).
davidr99 0:ab4e012489ef 121 /// You would normally set the header FROM address to be the same as thisAddress (though you dont have to,
davidr99 0:ab4e012489ef 122 /// allowing the possibilty of address spoofing).
davidr99 0:ab4e012489ef 123 /// \param[in] thisAddress The address of this node.
davidr99 0:ab4e012489ef 124 virtual void setThisAddress(uint8_t thisAddress);
davidr99 0:ab4e012489ef 125
davidr99 0:ab4e012489ef 126 /// Sets the TO header to be sent in all subsequent messages
davidr99 0:ab4e012489ef 127 /// \param[in] to The new TO header value
davidr99 0:ab4e012489ef 128 virtual void setHeaderTo(uint8_t to);
davidr99 0:ab4e012489ef 129
davidr99 0:ab4e012489ef 130 /// Sets the FROM header to be sent in all subsequent messages
davidr99 0:ab4e012489ef 131 /// \param[in] from The new FROM header value
davidr99 0:ab4e012489ef 132 virtual void setHeaderFrom(uint8_t from);
davidr99 0:ab4e012489ef 133
davidr99 0:ab4e012489ef 134 /// Sets the ID header to be sent in all subsequent messages
davidr99 0:ab4e012489ef 135 /// \param[in] id The new ID header value
davidr99 0:ab4e012489ef 136 virtual void setHeaderId(uint8_t id);
davidr99 0:ab4e012489ef 137
davidr99 0:ab4e012489ef 138 /// Sets and clears bits in the FLAGS header to be sent in all subsequent messages
davidr99 0:ab4e012489ef 139 /// First it clears he FLAGS according to the clear argument, then sets the flags according to the
davidr99 0:ab4e012489ef 140 /// set argument. The default for clear always clears the application specific flags.
davidr99 0:ab4e012489ef 141 /// \param[in] set bitmask of bits to be set. Flags are cleared with the clear mask before being set.
davidr99 0:ab4e012489ef 142 /// \param[in] clear bitmask of flags to clear. Defaults to RH_FLAGS_APPLICATION_SPECIFIC
davidr99 0:ab4e012489ef 143 /// which clears the application specific flags, resultiung in new application specific flags
davidr99 0:ab4e012489ef 144 /// identical to the set.
davidr99 0:ab4e012489ef 145 virtual void setHeaderFlags(uint8_t set, uint8_t clear = RH_FLAGS_APPLICATION_SPECIFIC);
davidr99 0:ab4e012489ef 146
davidr99 0:ab4e012489ef 147 /// Tells the receiver to accept messages with any TO address, not just messages
davidr99 0:ab4e012489ef 148 /// addressed to thisAddress or the broadcast address
davidr99 0:ab4e012489ef 149 /// \param[in] promiscuous true if you wish to receive messages with any TO address
davidr99 0:ab4e012489ef 150 virtual void setPromiscuous(bool promiscuous);
davidr99 0:ab4e012489ef 151
davidr99 0:ab4e012489ef 152 /// Returns the TO header of the last received message
davidr99 0:ab4e012489ef 153 /// \return The TO header
davidr99 0:ab4e012489ef 154 virtual uint8_t headerTo();
davidr99 0:ab4e012489ef 155
davidr99 0:ab4e012489ef 156 /// Returns the FROM header of the last received message
davidr99 0:ab4e012489ef 157 /// \return The FROM header
davidr99 0:ab4e012489ef 158 virtual uint8_t headerFrom();
davidr99 0:ab4e012489ef 159
davidr99 0:ab4e012489ef 160 /// Returns the ID header of the last received message
davidr99 0:ab4e012489ef 161 /// \return The ID header
davidr99 0:ab4e012489ef 162 virtual uint8_t headerId();
davidr99 0:ab4e012489ef 163
davidr99 0:ab4e012489ef 164 /// Returns the FLAGS header of the last received message
davidr99 0:ab4e012489ef 165 /// \return The FLAGS header
davidr99 0:ab4e012489ef 166 virtual uint8_t headerFlags();
davidr99 0:ab4e012489ef 167
davidr99 0:ab4e012489ef 168 /// Returns the most recent RSSI (Receiver Signal Strength Indicator).
davidr99 0:ab4e012489ef 169 /// Usually it is the RSSI of the last received message, which is measured when the preamble is received.
davidr99 0:ab4e012489ef 170 /// If you called readRssi() more recently, it will return that more recent value.
davidr99 0:ab4e012489ef 171 /// \return The most recent RSSI measurement in dBm.
davidr99 0:ab4e012489ef 172 int8_t lastRssi();
davidr99 0:ab4e012489ef 173
davidr99 0:ab4e012489ef 174 /// Returns the operating mode of the library.
davidr99 0:ab4e012489ef 175 /// \return the current mode, one of RF69_MODE_*
davidr99 0:ab4e012489ef 176 RHMode mode();
davidr99 0:ab4e012489ef 177
davidr99 0:ab4e012489ef 178 /// Sets the operating mode of the transport.
davidr99 0:ab4e012489ef 179 void setMode(RHMode mode);
davidr99 0:ab4e012489ef 180
davidr99 0:ab4e012489ef 181 /// Sets the transport hardware into low-power sleep mode
davidr99 0:ab4e012489ef 182 /// (if supported). May be overridden by specific drivers to initialte sleep mode.
davidr99 0:ab4e012489ef 183 /// If successful, the transport will stay in sleep mode until woken by
davidr99 0:ab4e012489ef 184 /// changing mode it idle, transmit or receive (eg by calling send(), recv(), available() etc)
davidr99 0:ab4e012489ef 185 /// \return true if sleep mode is supported by transport hardware and the RadioHead driver, and if sleep mode
davidr99 0:ab4e012489ef 186 /// was successfully entered. If sleep mode is not suported, return false.
davidr99 0:ab4e012489ef 187 virtual bool sleep();
davidr99 0:ab4e012489ef 188
davidr99 0:ab4e012489ef 189 /// Prints a data buffer in HEX.
davidr99 0:ab4e012489ef 190 /// For diagnostic use
davidr99 0:ab4e012489ef 191 /// \param[in] prompt string to preface the print
davidr99 0:ab4e012489ef 192 /// \param[in] buf Location of the buffer to print
davidr99 0:ab4e012489ef 193 /// \param[in] len Length of the buffer in octets.
davidr99 0:ab4e012489ef 194 static void printBuffer(const char* prompt, const uint8_t* buf, uint8_t len);
davidr99 0:ab4e012489ef 195
davidr99 0:ab4e012489ef 196 /// Returns the count of the number of bad received packets (ie packets with bad lengths, checksum etc)
davidr99 0:ab4e012489ef 197 /// which were rejected and not delivered to the application.
davidr99 0:ab4e012489ef 198 /// Caution: not all drivers can correctly report this count. Some underlying hardware only report
davidr99 0:ab4e012489ef 199 /// good packets.
davidr99 0:ab4e012489ef 200 /// \return The number of bad packets received.
davidr99 0:ab4e012489ef 201 uint16_t rxBad();
davidr99 0:ab4e012489ef 202
davidr99 0:ab4e012489ef 203 /// Returns the count of the number of
davidr99 0:ab4e012489ef 204 /// good received packets
davidr99 0:ab4e012489ef 205 /// \return The number of good packets received.
davidr99 0:ab4e012489ef 206 uint16_t rxGood();
davidr99 0:ab4e012489ef 207
davidr99 0:ab4e012489ef 208 /// Returns the count of the number of
davidr99 0:ab4e012489ef 209 /// packets successfully transmitted (though not necessarily received by the destination)
davidr99 0:ab4e012489ef 210 /// \return The number of packets successfully transmitted
davidr99 0:ab4e012489ef 211 uint16_t txGood();
davidr99 0:ab4e012489ef 212
davidr99 0:ab4e012489ef 213 protected:
davidr99 0:ab4e012489ef 214
davidr99 0:ab4e012489ef 215 /// The current transport operating mode
davidr99 0:ab4e012489ef 216 volatile RHMode _mode;
davidr99 0:ab4e012489ef 217
davidr99 0:ab4e012489ef 218 /// This node id
davidr99 0:ab4e012489ef 219 uint8_t _thisAddress;
davidr99 0:ab4e012489ef 220
davidr99 0:ab4e012489ef 221 /// Whether the transport is in promiscuous mode
davidr99 0:ab4e012489ef 222 bool _promiscuous;
davidr99 0:ab4e012489ef 223
davidr99 0:ab4e012489ef 224 /// TO header in the last received mesasge
davidr99 0:ab4e012489ef 225 volatile uint8_t _rxHeaderTo;
davidr99 0:ab4e012489ef 226
davidr99 0:ab4e012489ef 227 /// FROM header in the last received mesasge
davidr99 0:ab4e012489ef 228 volatile uint8_t _rxHeaderFrom;
davidr99 0:ab4e012489ef 229
davidr99 0:ab4e012489ef 230 /// ID header in the last received mesasge
davidr99 0:ab4e012489ef 231 volatile uint8_t _rxHeaderId;
davidr99 0:ab4e012489ef 232
davidr99 0:ab4e012489ef 233 /// FLAGS header in the last received mesasge
davidr99 0:ab4e012489ef 234 volatile uint8_t _rxHeaderFlags;
davidr99 0:ab4e012489ef 235
davidr99 0:ab4e012489ef 236 /// TO header to send in all messages
davidr99 0:ab4e012489ef 237 uint8_t _txHeaderTo;
davidr99 0:ab4e012489ef 238
davidr99 0:ab4e012489ef 239 /// FROM header to send in all messages
davidr99 0:ab4e012489ef 240 uint8_t _txHeaderFrom;
davidr99 0:ab4e012489ef 241
davidr99 0:ab4e012489ef 242 /// ID header to send in all messages
davidr99 0:ab4e012489ef 243 uint8_t _txHeaderId;
davidr99 0:ab4e012489ef 244
davidr99 0:ab4e012489ef 245 /// FLAGS header to send in all messages
davidr99 0:ab4e012489ef 246 uint8_t _txHeaderFlags;
davidr99 0:ab4e012489ef 247
davidr99 0:ab4e012489ef 248 /// The value of the last received RSSI value, in some transport specific units
davidr99 0:ab4e012489ef 249 volatile int8_t _lastRssi;
davidr99 0:ab4e012489ef 250
davidr99 0:ab4e012489ef 251 /// Count of the number of bad messages (eg bad checksum etc) received
davidr99 0:ab4e012489ef 252 volatile uint16_t _rxBad;
davidr99 0:ab4e012489ef 253
davidr99 0:ab4e012489ef 254 /// Count of the number of successfully transmitted messaged
davidr99 0:ab4e012489ef 255 volatile uint16_t _rxGood;
davidr99 0:ab4e012489ef 256
davidr99 0:ab4e012489ef 257 /// Count of the number of bad messages (correct checksum etc) received
davidr99 0:ab4e012489ef 258 volatile uint16_t _txGood;
davidr99 0:ab4e012489ef 259
davidr99 0:ab4e012489ef 260 private:
davidr99 0:ab4e012489ef 261
davidr99 0:ab4e012489ef 262 };
davidr99 0:ab4e012489ef 263
davidr99 0:ab4e012489ef 264
davidr99 0:ab4e012489ef 265 #endif