RHSPIDriver.h

00001 // RHSPIDriver.h
00002 // Author: Mike McCauley (mikem@airspayce.com)
00003 // Copyright (C) 2014 Mike McCauley
00004 // $Id: RHSPIDriver.h,v 1.9 2014/04/23 06:00:59 mikem Exp $
00005 
00006 #ifndef RHSPIDriver_h
00007 #define RHSPIDriver_h
00008 
00009 #include <RHGenericDriver.h>
00010 #include <RHHardwareSPI.h>
00011 
00012 // This is the bit in the SPI address that marks it as a write
00013 #define RH_SPI_WRITE_MASK 0x80
00014 
00015 class RHGenericSPI;
00016 
00017 /////////////////////////////////////////////////////////////////////
00018 /// \class RHSPIDriver RHSPIDriver.h <RHSPIDriver.h>
00019 /// \brief Base class for a RadioHead drivers that use the SPI bus
00020 /// to communicate with its transport hardware.
00021 ///
00022 /// This class can be subclassed by Drivers that require to use the SPI bus.
00023 /// It can be configured to use either the RHHardwareSPI class (if there is one available on the platform)
00024 /// of the bitbanged RHSoftwareSPI class. The default behaviour is to use a pre-instantiated built-in RHHardwareSPI
00025 /// interface.
00026 ///
00027 /// SPI bus access is protected by ATOMIC_BLOCK_START and ATOMIC_BLOCK_END, which will ensure interrupts 
00028 /// are disabled during access.
00029 /// 
00030 /// The read and write routines implement commonly used SPI conventions: specifically that the MSB
00031 /// of the first byte transmitted indicates that it is a write and the remaining bits indicate the rehgister to access)
00032 /// This can be overriden 
00033 /// in subclasses if necessaryor an alternative class, RHNRFSPIDriver can be used to access devices like 
00034 /// Nordic NRF series radios, which have different requirements.
00035 ///
00036 /// Application developers are not expected to instantiate this class directly: 
00037 /// it is for the use of Driver developers.
00038 class RHSPIDriver : public RHGenericDriver
00039 {
00040 public:
00041     /// Constructor
00042     /// \param[in] slaveSelectPin The controler pin to use to select the desired SPI device. This pin will be driven LOW
00043     /// during SPI communications with the SPI device that uis iused by this Driver.
00044     /// \param[in] spi Reference to the SPI interface to use. The default is to use a default built-in Hardware interface.
00045     RHSPIDriver(PINS slaveSelectPin, RHGenericSPI& spi = hardware_spi);
00046 
00047     /// Initialise the Driver transport hardware and software.
00048     /// Make sure the Driver is properly configured before calling init().
00049     /// \return true if initialisation succeeded.
00050     bool init();
00051 
00052     /// Reads a single register from the SPI device
00053     /// \param[in] reg Register number
00054     /// \return The value of the register
00055     uint8_t        spiRead(uint8_t reg);
00056 
00057     /// Writes a single byte to the SPI device
00058     /// \param[in] reg Register number
00059     /// \param[in] val The value to write
00060     /// \return Some devices return a status byte during the first data transfer. This byte is returned.
00061     ///  it may or may not be meaningfule depending on the the type of device being accessed.
00062     uint8_t           spiWrite(uint8_t reg, uint8_t val);
00063 
00064     /// Reads a number of consecutive registers from the SPI device using burst read mode
00065     /// \param[in] reg Register number of the first register
00066     /// \param[in] dest Array to write the register values to. Must be at least len bytes
00067     /// \param[in] len Number of bytes to read
00068     /// \return Some devices return a status byte during the first data transfer. This byte is returned.
00069     ///  it may or may not be meaningfule depending on the the type of device being accessed.
00070     uint8_t           spiBurstRead(uint8_t reg, uint8_t* dest, uint8_t len);
00071 
00072     /// Write a number of consecutive registers using burst write mode
00073     /// \param[in] reg Register number of the first register
00074     /// \param[in] src Array of new register values to write. Must be at least len bytes
00075     /// \param[in] len Number of bytes to write
00076     /// \return Some devices return a status byte during the first data transfer. This byte is returned.
00077     ///  it may or may not be meaningfule depending on the the type of device being accessed.
00078     uint8_t           spiBurstWrite(uint8_t reg, const uint8_t* src, uint8_t len);
00079 
00080 protected:
00081     /// Reference to the RHGenericSPI instance to use to trasnfer data with teh SPI device
00082     RHGenericSPI&       _spi;
00083 
00084     /// The pin number of the Slave Selct pin that is used to select the desired device.   
00085 #if (RH_PLATFORM == RH_PLATFORM_MBED)
00086     DigitalOut             _slaveSelectPin;
00087 #else
00088     uint8_t             _slaveSelectPin;
00089 #endif
00090 };
00091 
00092 #endif