RHGenericSPI.h

00001 // RHGenericSPI.h
00002 // Author: Mike McCauley (mikem@airspayce.com)
00003 // Copyright (C) 2011 Mike McCauley
00004 // Contributed by Joanna Rutkowska
00005 // $Id: RHGenericSPI.h,v 1.7 2014/04/14 08:37:11 mikem Exp $
00006 
00007 #ifndef RHGenericSPI_h
00008 #define RHGenericSPI_h
00009 
00010 #include <RadioHead.h>
00011 
00012 /////////////////////////////////////////////////////////////////////
00013 /// \class RHGenericSPI RHGenericSPI.h <RHGenericSPI.h>
00014 /// \brief Base class for SPI interfaces
00015 ///
00016 /// This generic abstract class is used to encapsulate hardware or software SPI interfaces for 
00017 /// a variety of platforms.
00018 /// The intention is so that driver classes can be configured to use hardware or software SPI
00019 /// without changing the main code.
00020 ///
00021 /// You must provide a subclass of this class to driver constructors that require SPI.
00022 /// A concrete subclass that encapsualates the standard Arduino hardware SPI and a bit-banged
00023 /// software implementation is included.
00024 ///
00025 /// Do not directly use this class: it must be subclassed and the following abstract functions at least 
00026 /// must be implmented:
00027 /// - begin()
00028 /// - end() 
00029 /// - transfer()
00030 class RHGenericSPI 
00031 {
00032 public:
00033 
00034     /// \brief Defines constants for different SPI modes
00035     ///
00036     /// Defines constants for different SPI modes
00037     /// that can be passed to the constructor or setMode()
00038     /// We need to define these in a device and platform independent way, because the
00039     /// SPI implementation is different on each platform.
00040     typedef enum
00041     {
00042     DataMode0 = 0, ///< SPI Mode 0: CPOL = 0, CPHA = 0
00043     DataMode1,     ///< SPI Mode 1: CPOL = 0, CPHA = 1
00044     DataMode2,     ///< SPI Mode 2: CPOL = 1, CPHA = 0
00045     DataMode3,     ///< SPI Mode 3: CPOL = 1, CPHA = 1
00046     } DataMode;
00047 
00048     /// \brief Defines constants for different SPI bus frequencies
00049     ///
00050     /// Defines constants for different SPI bus frequencies
00051     /// that can be passed to setFrequency().
00052     /// The frequency you get may not be exactly the one according to the name.
00053     /// We need to define these in a device and platform independent way, because the
00054     /// SPI implementation is different on each platform.
00055     typedef enum
00056     {
00057     Frequency1MHz = 0,  ///< SPI bus frequency close to 1MHz
00058     Frequency2MHz,      ///< SPI bus frequency close to 2MHz
00059     Frequency4MHz,      ///< SPI bus frequency close to 4MHz
00060     Frequency8MHz,      ///< SPI bus frequency close to 8MHz
00061     Frequency16MHz      ///< SPI bus frequency close to 16MHz
00062     } Frequency;
00063 
00064     /// \brief Defines constants for different SPI endianness
00065     ///
00066     /// Defines constants for different SPI endianness
00067     /// that can be passed to setBitOrder()
00068     /// We need to define these in a device and platform independent way, because the
00069     /// SPI implementation is different on each platform.
00070     typedef enum
00071     {
00072     BitOrderMSBFirst = 0,  ///< SPI MSB first
00073     BitOrderLSBFirst,      ///< SPI LSB first
00074     } BitOrder;
00075 
00076     /// Constructor
00077     /// Creates an instance of an abstract SPI interface.
00078     /// Do not use this contructor directly: you must instead use on of the concrete subclasses provided 
00079     /// such as RHHardwareSPI or RHSoftwareSPI
00080     /// \param[in] frequency One of RHGenericSPI::Frequency to select the SPI bus frequency. The frequency
00081     /// is mapped to the closest available bus frequency on the platform.
00082     /// \param[in] bitOrder Select the SPI bus bit order, one of RHGenericSPI::BitOrderMSBFirst or 
00083     /// RHGenericSPI::BitOrderLSBFirst.
00084     /// \param[in] dataMode Selects the SPI bus data mode. One of RHGenericSPI::DataMode
00085     RHGenericSPI(Frequency frequency = Frequency1MHz, BitOrder bitOrder = BitOrderMSBFirst, DataMode dataMode = DataMode0);
00086 
00087     /// Transfer a single octet to and from the SPI interface
00088     /// \param[in] data The octet to send
00089     /// \return The octet read from SPI while the data octet was sent
00090     virtual uint8_t transfer(uint8_t data) = 0;
00091 
00092     /// SPI Configuration methods
00093     /// Enable SPI interrupts (if supported)
00094     /// This can be used in an SPI slave to indicate when an SPI message has been received
00095     virtual void attachInterrupt() {};
00096 
00097     /// Disable SPI interrupts (if supported)
00098     /// This can be used to diable the SPI interrupt in slaves where that is supported.
00099     virtual void detachInterrupt() {};
00100 
00101     /// Initialise the SPI library.
00102     /// Call this after configuring and before using the SPI library
00103     virtual void begin() = 0;
00104 
00105     /// Disables the SPI bus (leaving pin modes unchanged). 
00106     /// Call this after you have finished using the SPI interface
00107     virtual void end() = 0;
00108 
00109     /// Sets the bit order the SPI interface will use
00110     /// Sets the order of the bits shifted out of and into the SPI bus, either 
00111     /// LSBFIRST (least-significant bit first) or MSBFIRST (most-significant bit first). 
00112     /// \param[in] bitOrder Bit order to be used: one of RHGenericSPI::BitOrder
00113     virtual void setBitOrder(BitOrder bitOrder);
00114 
00115     /// Sets the SPI data mode: that is, clock polarity and phase. 
00116     /// See the Wikipedia article on SPI for details. 
00117     /// \param[in] dataMode The mode to use: one of RHGenericSPI::DataMode
00118     virtual void setDataMode(DataMode dataMode);
00119 
00120     /// Sets the SPI clock divider relative to the system clock. 
00121     /// On AVR based boards, the dividers available are 2, 4, 8, 16, 32, 64 or 128. 
00122     /// The default setting is SPI_CLOCK_DIV4, which sets the SPI clock to one-quarter 
00123     /// the frequency of the system clock (4 Mhz for the boards at 16 MHz). 
00124     /// \param[in] frequency The data rate to use: one of RHGenericSPI::Frequency
00125     virtual void setFrequency(Frequency frequency);
00126 
00127 protected:
00128     /// The configure SPI Bus frequency, one of RHGenericSPI::Frequency
00129     Frequency    _frequency; // Bus frequency, one of RHGenericSPI::Frequency
00130 
00131     /// Bit order, one of RHGenericSPI::BitOrder
00132     BitOrder     _bitOrder;  
00133 
00134     /// SPI bus mode, one of RHGenericSPI::DataMode
00135     DataMode     _dataMode;  
00136 };
00137 #endif