RHGenericDriver.h

00001 // RHGenericDriver.h
00002 // Author: Mike McCauley (mikem@airspayce.com)
00003 // Copyright (C) 2014 Mike McCauley
00004 // $Id: RHGenericDriver.h,v 1.16 2015/01/02 21:38:24 mikem Exp $
00005 
00006 #ifndef RHGenericDriver_h
00007 #define RHGenericDriver_h
00008 
00009 #include <RadioHead.h>
00010 
00011 // Defines bits of the FLAGS header reserved for use by the RadioHead library and 
00012 // the flags available for use by applications
00013 #define RH_FLAGS_RESERVED                 0xf0
00014 #define RH_FLAGS_APPLICATION_SPECIFIC     0x0f
00015 #define RH_FLAGS_NONE                     0
00016 
00017 /////////////////////////////////////////////////////////////////////
00018 /// \class RHGenericDriver RHGenericDriver.h <RHGenericDriver.h>
00019 /// \brief Abstract base class for a RadioHead driver.
00020 ///
00021 /// This class defines the functions that must be provided by any RadioHead driver.
00022 /// Different types of driver will implement all the abstract functions, and will perhaps override 
00023 /// other functions in this subclass, or perhaps add new functions specifically required by that driver.
00024 /// Do not directly instantiate this class: it is only to be subclassed by driver classes.
00025 ///
00026 /// Subclasses are expected to implement a half-duplex, unreliable, error checked, unaddressed packet transport.
00027 /// They are expected to carry a message payload with an appropriate maximum length for the transport hardware
00028 /// and to also carry unaltered 4 message headers: TO, FROM, ID, FLAGS
00029 ///
00030 /// \par Headers
00031 ///
00032 /// Each message sent and received by a RadioHead driver includes 4 headers:
00033 /// -TO The node address that the message is being sent to (broadcast RH_BROADCAST_ADDRESS (255) is permitted)
00034 /// -FROM The node address of the sending node
00035 /// -ID A message ID, distinct (over short time scales) for each message sent by a particilar node
00036 /// -FLAGS A bitmask of flags. The most significant 4 bits are reserved for use by RadioHead. The least
00037 /// significant 4 bits are reserved for applications.
00038 class RHGenericDriver
00039 {
00040 public:
00041     /// \brief Defines different operating modes for the transport hardware
00042     ///
00043     /// These are the different values that can be adopted by the _mode variable and 
00044     /// returned by the mode() member function,
00045     typedef enum
00046     {
00047     RHModeInitialising = 0, ///< Transport is initialising. Initial default value until init() is called..
00048     RHModeSleep,            ///< Transport hardware is in low power sleep mode (if supported)
00049     RHModeIdle,             ///< Transport is idle.
00050     RHModeTx,               ///< Transport is in the process of transmitting a message.
00051     RHModeRx                ///< Transport is in the process of receiving a message.
00052     } RHMode;
00053 
00054     /// Constructor
00055     RHGenericDriver();
00056 
00057     /// Initialise the Driver transport hardware and software.
00058     /// Make sure the Driver is properly configured before calling init().
00059     /// \return true if initialisation succeeded.
00060     virtual bool init();
00061 
00062     /// Tests whether a new message is available
00063     /// from the Driver. 
00064     /// On most drivers, if there is an uncollected received message, and there is no message
00065     /// currently bing transmitted, this will also put the Driver into RHModeRx mode until
00066     /// a message is actually received by the transport, when it will be returned to RHModeIdle.
00067     /// This can be called multiple times in a timeout loop.
00068     /// \return true if a new, complete, error-free uncollected message is available to be retreived by recv().
00069     virtual bool available() = 0;
00070 
00071     /// Turns the receiver on if it not already on.
00072     /// If there is a valid message available, copy it to buf and return true
00073     /// else return false.
00074     /// If a message is copied, *len is set to the length (Caution, 0 length messages are permitted).
00075     /// You should be sure to call this function frequently enough to not miss any messages
00076     /// It is recommended that you call it in your main loop.
00077     /// \param[in] buf Location to copy the received message
00078     /// \param[in,out] len Pointer to available space in buf. Set to the actual number of octets copied.
00079     /// \return true if a valid message was copied to buf
00080     virtual bool recv(uint8_t* buf, uint8_t* len) = 0;
00081 
00082     /// Waits until any previous transmit packet is finished being transmitted with waitPacketSent().
00083     /// Then loads a message into the transmitter and starts the transmitter. Note that a message length
00084     /// of 0 is NOT permitted. If the message is too long for the underlying radio technology, send() will
00085     /// return false and will not send the message.
00086     /// \param[in] data Array of data to be sent
00087     /// \param[in] len Number of bytes of data to send (> 0)
00088     /// \return true if the message length was valid and it was correctly queued for transmit
00089     virtual bool send(const uint8_t* data, uint8_t len) = 0;
00090 
00091     /// Returns the maximum message length 
00092     /// available in this Driver.
00093     /// \return The maximum legal message length
00094     virtual uint8_t maxMessageLength() = 0;
00095 
00096     /// Starts the receiver and blocks until a valid received 
00097     /// message is available.
00098     virtual void            waitAvailable();
00099 
00100     /// Blocks until the transmitter 
00101     /// is no longer transmitting.
00102     virtual bool            waitPacketSent();
00103 
00104     /// Blocks until the transmitter is no longer transmitting.
00105     /// or until the timeout occuers, whichever happens first
00106     /// \param[in] timeout Maximum time to wait in milliseconds.
00107     /// \return true if the RF22 completed transmission within the timeout period. False if it timed out.
00108     virtual bool            waitPacketSent(uint16_t timeout);
00109 
00110     /// Starts the receiver and blocks until a received message is available or a timeout
00111     /// \param[in] timeout Maximum time to wait in milliseconds.
00112     /// \return true if a message is available
00113     virtual bool            waitAvailableTimeout(uint16_t timeout);
00114 
00115     /// Sets the address of this node. Defaults to 0xFF. Subclasses or the user may want to change this.
00116     /// This will be used to test the adddress in incoming messages. In non-promiscuous mode,
00117     /// only messages with a TO header the same as thisAddress or the broadcast addess (0xFF) will be accepted.
00118     /// In promiscuous mode, all messages will be accepted regardless of the TO header.
00119     /// In a conventional multinode system, all nodes will have a unique address 
00120     /// (which you could store in EEPROM).
00121     /// You would normally set the header FROM address to be the same as thisAddress (though you dont have to, 
00122     /// allowing the possibilty of address spoofing).
00123     /// \param[in] thisAddress The address of this node.
00124     virtual void setThisAddress(uint8_t thisAddress);
00125 
00126     /// Sets the TO header to be sent in all subsequent messages
00127     /// \param[in] to The new TO header value
00128     virtual void           setHeaderTo(uint8_t to);
00129 
00130     /// Sets the FROM header to be sent in all subsequent messages
00131     /// \param[in] from The new FROM header value
00132     virtual void           setHeaderFrom(uint8_t from);
00133 
00134     /// Sets the ID header to be sent in all subsequent messages
00135     /// \param[in] id The new ID header value
00136     virtual void           setHeaderId(uint8_t id);
00137 
00138     /// Sets and clears bits in the FLAGS header to be sent in all subsequent messages
00139     /// First it clears he FLAGS according to the clear argument, then sets the flags according to the 
00140     /// set argument. The default for clear always clears the application specific flags.
00141     /// \param[in] set bitmask of bits to be set. Flags are cleared with the clear mask before being set.
00142     /// \param[in] clear bitmask of flags to clear. Defaults to RH_FLAGS_APPLICATION_SPECIFIC
00143     ///            which clears the application specific flags, resultiung in new application specific flags
00144     ///            identical to the set.
00145     virtual void           setHeaderFlags(uint8_t set, uint8_t clear = RH_FLAGS_APPLICATION_SPECIFIC);
00146 
00147     /// Tells the receiver to accept messages with any TO address, not just messages
00148     /// addressed to thisAddress or the broadcast address
00149     /// \param[in] promiscuous true if you wish to receive messages with any TO address
00150     virtual void           setPromiscuous(bool promiscuous);
00151 
00152     /// Returns the TO header of the last received message
00153     /// \return The TO header
00154     virtual uint8_t        headerTo();
00155 
00156     /// Returns the FROM header of the last received message
00157     /// \return The FROM header
00158     virtual uint8_t        headerFrom();
00159 
00160     /// Returns the ID header of the last received message
00161     /// \return The ID header
00162     virtual uint8_t        headerId();
00163 
00164     /// Returns the FLAGS header of the last received message
00165     /// \return The FLAGS header
00166     virtual uint8_t        headerFlags();
00167 
00168     /// Returns the most recent RSSI (Receiver Signal Strength Indicator).
00169     /// Usually it is the RSSI of the last received message, which is measured when the preamble is received.
00170     /// If you called readRssi() more recently, it will return that more recent value.
00171     /// \return The most recent RSSI measurement in dBm.
00172     int8_t        lastRssi();
00173 
00174     /// Returns the operating mode of the library.
00175     /// \return the current mode, one of RF69_MODE_*
00176     RHMode          mode();
00177 
00178     /// Sets the operating mode of the transport.
00179     void            setMode(RHMode mode);
00180 
00181     /// Sets the transport hardware into low-power sleep mode
00182     /// (if supported). May be overridden by specific drivers to initialte sleep mode.
00183     /// If successful, the transport will stay in sleep mode until woken by 
00184     /// changing mode it idle, transmit or receive (eg by calling send(), recv(), available() etc)
00185     /// \return true if sleep mode is supported by transport hardware and the RadioHead driver, and if sleep mode
00186     ///         was successfully entered. If sleep mode is not suported, return false.
00187     virtual bool    sleep();
00188 
00189     /// Prints a data buffer in HEX.
00190     /// For diagnostic use
00191     /// \param[in] prompt string to preface the print
00192     /// \param[in] buf Location of the buffer to print
00193     /// \param[in] len Length of the buffer in octets.
00194     static void    printBuffer(const char* prompt, const uint8_t* buf, uint8_t len);
00195 
00196     /// Returns the count of the number of bad received packets (ie packets with bad lengths, checksum etc)
00197     /// which were rejected and not delivered to the application.
00198     /// Caution: not all drivers can correctly report this count. Some underlying hardware only report
00199     /// good packets.
00200     /// \return The number of bad packets received.
00201     uint16_t       rxBad();
00202 
00203     /// Returns the count of the number of 
00204     /// good received packets
00205     /// \return The number of good packets received.
00206     uint16_t       rxGood();
00207 
00208     /// Returns the count of the number of 
00209     /// packets successfully transmitted (though not necessarily received by the destination)
00210     /// \return The number of packets successfully transmitted
00211     uint16_t       txGood();
00212 
00213 protected:
00214 
00215     /// The current transport operating mode
00216     volatile RHMode     _mode;
00217 
00218     /// This node id
00219     uint8_t             _thisAddress;
00220     
00221     /// Whether the transport is in promiscuous mode
00222     bool                _promiscuous;
00223 
00224     /// TO header in the last received mesasge
00225     volatile uint8_t    _rxHeaderTo;
00226 
00227     /// FROM header in the last received mesasge
00228     volatile uint8_t    _rxHeaderFrom;
00229 
00230     /// ID header in the last received mesasge
00231     volatile uint8_t    _rxHeaderId;
00232 
00233     /// FLAGS header in the last received mesasge
00234     volatile uint8_t    _rxHeaderFlags;
00235 
00236     /// TO header to send in all messages
00237     uint8_t             _txHeaderTo;
00238 
00239     /// FROM header to send in all messages
00240     uint8_t             _txHeaderFrom;
00241 
00242     /// ID header to send in all messages
00243     uint8_t             _txHeaderId;
00244 
00245     /// FLAGS header to send in all messages
00246     uint8_t             _txHeaderFlags;
00247 
00248     /// The value of the last received RSSI value, in some transport specific units
00249     volatile int8_t     _lastRssi;
00250 
00251     /// Count of the number of bad messages (eg bad checksum etc) received
00252     volatile uint16_t   _rxBad;
00253 
00254     /// Count of the number of successfully transmitted messaged
00255     volatile uint16_t   _rxGood;
00256 
00257     /// Count of the number of bad messages (correct checksum etc) received
00258     volatile uint16_t   _txGood;
00259     
00260 private:
00261 
00262 };
00263 
00264 
00265 #endif