RH_NRF51.h

00001 // RH_NRF51.h
00002 // Author: Mike McCauley
00003 // Copyright (C) 2015 Mike McCauley
00004 // $Id: RH_NRF51.h,v 1.3 2015/08/14 21:20:12 mikem Exp mikem $
00005 //
00006 
00007 #ifndef RH_NRF51_h
00008 #define RH_NRF51_h
00009 
00010 #include <RHGenericDriver.h>
00011 
00012 // This is the maximum number of bytes that can be carried by the nRF51.
00013 // We use some for headers, keeping fewer for RadioHead messages
00014 #define RH_NRF51_MAX_PAYLOAD_LEN 254
00015 
00016 // The length of the headers we add.
00017 // The headers are inside the nRF51 payload
00018 #define RH_NRF51_HEADER_LEN 4
00019 
00020 // This is the maximum RadioHead user message length that can be supported by this library. Limited by
00021 // the supported message lengths in the nRF51
00022 #define RH_NRF51_MAX_MESSAGE_LEN (RH_NRF51_MAX_PAYLOAD_LEN-RH_NRF51_HEADER_LEN)
00023 
00024 /////////////////////////////////////////////////////////////////////
00025 /// \class RH_NRF51 RH_NRF51.h <RH_NRF51.h>
00026 /// \brief Send and receive addressed datagrams by nRF51 compatible transceivers.
00027 ///
00028 /// Supported transceivers include:
00029 /// - Nordic nRF51 based 2.4GHz radio modules, such as nRF51822 
00030 /// and other compatible chips, such as used in RedBearLabs devices like:
00031 /// http://store.redbearlab.com/products/redbearlab-nrf51822
00032 /// http://store.redbearlab.com/products/blenano
00033 ///
00034 /// This base class provides basic functions for sending and receiving unaddressed, unreliable datagrams
00035 /// of arbitrary length to 254 octets per packet. Use one of the Manager classes to get addressing and 
00036 /// acknowledgement reliability, routing, meshes etc.
00037 ///
00038 /// The nRF51822 (https://www.nordicsemi.com/eng/Products/Bluetooth-Smart-Bluetooth-low-energy/nRF51822)
00039 /// is a complete SoC (system on a chip) with ARM microprocessor and 2.4 GHz radio, which supports a range of channels 
00040 /// and transmission bit rates. Chip antenna is on-board.
00041 ///
00042 /// This library provides functions for sending and receiving messages of up to 254 octets on any 
00043 /// frequency supported by the nRF51822, at a selected data rate.
00044 ///
00045 /// The nRF51 transceiver is configured to use Enhanced Shockburst with no acknowledgement and no retransmits.
00046 /// TXADDRESS and RXADDRESSES:RXADDR0 (ie pipe 0) are the logical address used. The on-air network address
00047 /// is set in BASE0 and PREFIX0. SHORTS is used to automatically transition the radio between Ready, Start and Disable.
00048 /// No interrupts are used.
00049 ///
00050 /// Naturally, for any 2 radios to communicate that must be configured to use the same frequency and 
00051 /// data rate, and with identical network addresses.
00052 ///
00053 /// Example programs are included to show the main modes of use.
00054 ///
00055 /// \par Packet Format
00056 ///
00057 /// All messages sent and received by this class conform to this packet format. It is NOT compatible
00058 /// with the one used by RH_NRF24 and the nRF24L01 product specification, mainly because the nRF24 only suports
00059 /// 6 bits of message length.
00060 ///
00061 /// - 1 octets PREAMBLE
00062 /// - 3 to 5 octets NETWORK ADDRESS
00063 /// - 8 bits PAYLOAD LENGTH
00064 /// - 0 to 254 octets PAYLOAD, consisting of:
00065 ///   - 1 octet TO header
00066 ///   - 1 octet FROM header
00067 ///   - 1 octet ID header
00068 ///   - 1 octet FLAGS header
00069 ///   - 0 to 250 octets of user message
00070 /// - 2 octets CRC (Algorithm x^16+x^12^x^5+1 with initial value 0xFFFF).
00071 ///
00072 /// \par Example programs
00073 ///
00074 /// Several example programs are provided.
00075 ///
00076 /// The sample programs are designed to be built using Arduino 1.6.4 or later using the procedures outlined
00077 /// in http://redbearlab.com/getting-started-nrf51822/
00078 ///
00079 /// \par Radio Performance
00080 ///
00081 /// At DataRate2Mbps (2Mb/s), payload length vs airtime:
00082 /// 0 bytes takes about 70us, 128 bytes takes 520us, 254 bytes take 1020us.
00083 /// You can extrapolate linearly to slower data rates.
00084 ///
00085 /// The RF powers claimed by the chip manufacturer have not been independently verified here.
00086 ///
00087 /// \par Memory
00088 ///
00089 /// The compiled client and server sketches are about 42k bytes on Arduino. 
00090 /// The reliable client and server sketches compile to about 43k bytes on Arduino. Unfortunately the 
00091 /// Arduino build environmnet does not drop unused clsses and code, so the resulting programs include
00092 /// all the unused classes ad code. This needs to be revisited.
00093 /// RAM requirements are minimal.
00094 ///
00095 class RH_NRF51 : public RHGenericDriver
00096 {
00097 public:
00098 
00099     /// \brief Defines convenient values for setting data rates in setRF()
00100     typedef enum
00101     {
00102     DataRate1Mbps = 0,   ///< 1 Mbps
00103     DataRate2Mbps,       ///< 2 Mbps
00104     DataRate250kbps      ///< 250 kbps
00105     } DataRate;
00106 
00107     /// \brief Convenient values for setting transmitter power in setRF()
00108     typedef enum
00109     {
00110     // Add 20dBm for nRF24L01p with PA and LNA modules
00111     TransmitPower4dBm = 0,        ///<  4 dBm
00112     TransmitPower0dBm,            ///<  0 dBm
00113     TransmitPowerm4dBm,           ///< -4 dBm
00114     TransmitPowerm8dBm,           ///< -8 dBm
00115     TransmitPowerm12dBm,          ///< -12 dBm
00116     TransmitPowerm16dBm,          ///< -16 dBm
00117     TransmitPowerm20dBm,          ///< -20 dBm
00118     TransmitPowerm30dBm,          ///< -30 dBm
00119     } TransmitPower;
00120 
00121     /// Constructor.
00122     /// After constructing, you must call init() to initialise the interface
00123     /// and the radio module
00124     RH_NRF51();
00125   
00126     /// Initialises this instance and the radio module connected to it.
00127     /// The following steps are taken:
00128     /// - Start the processors High Frequency clock  DC/DC converter and 
00129     /// - Disable and reset the radio
00130     /// - Set the logical channel to 0 for transmit and receive (only pipe 0 is used)
00131     /// - Configure the CRC (2 octets, algorithm x^16+x^12^x^5+1 with initial value 0xffff)
00132     /// - Set the default network address of 0xE7E7E7E7E7
00133     /// - Set channel to 2
00134     /// - Set data rate to DataRate2Mbps
00135     /// - Set TX power to TransmitPower0dBm
00136     /// \return  true if everything was successful
00137     bool        init();
00138 
00139     /// Sets the transmit and receive channel number.
00140     /// The frequency used is (2400 + channel) MHz
00141     /// \return true on success
00142     bool setChannel(uint8_t channel);
00143 
00144     /// Sets the Network address.
00145     /// Only nodes with the same network address can communicate with each other. You 
00146     /// can set different network addresses in different sets of nodes to isolate them from each other.
00147     /// Internally, this sets the nRF51 BASE0 and PREFIX0 to be the given network address.
00148     /// The first octet of the address is used for PREFIX0 and the rest is used for BASE0. BALEN is
00149     /// set to the approprtae base length.
00150     /// The default network address is 0xE7E7E7E7E7.
00151     /// \param[in] address The new network address. Must match the network address of any receiving node(s).
00152     /// \param[in] len Number of bytes of address to set (3 to 5).
00153     /// \return true on success, false if len is not in the range 3-5 inclusive.
00154     bool setNetworkAddress(uint8_t* address, uint8_t len);
00155 
00156     /// Sets the data rate and transmitter power to use.
00157     /// \param [in] data_rate The data rate to use for all packets transmitted and received. One of RH_NRF51::DataRate.
00158     /// \param [in] power Transmitter power. One of RH_NRF51::TransmitPower.
00159     /// \return true on success
00160     bool setRF(DataRate data_rate, TransmitPower power);
00161 
00162     /// Sets the radio in power down mode, with the configuration set to the
00163     /// last value from setOpMode().
00164     /// Sets chip enable to LOW.
00165     void setModeIdle();
00166 
00167     /// Sets the radio in RX mode.
00168     void setModeRx();
00169 
00170     /// Sets the radio in TX mode.
00171     void setModeTx();
00172 
00173     /// Sends data to the address set by setTransmitAddress()
00174     /// Sets the radio to TX mode.
00175     /// \param [in] data Data bytes to send.
00176     /// \param [in] len Number of data bytes to send
00177     /// \return true on success (which does not necessarily mean the receiver got the message, only that the message was
00178     /// successfully transmitted).
00179     bool send(const uint8_t* data, uint8_t len);
00180 
00181     /// Blocks until the current message (if any) 
00182     /// has been transmitted
00183     /// \return true on success, false if the chip is not in transmit mode or other transmit failure
00184     virtual bool waitPacketSent();
00185 
00186     /// Indicates if the chip is in transmit mode and 
00187     /// there is a packet currently being transmitted
00188     /// \return true if the chip is in transmit mode and there is a transmission in progress
00189     bool isSending();
00190 
00191     /// Prints the value of all NRF_RADIO registers.
00192     /// to the Serial device if RH_HAVE_SERIAL is defined for the current platform
00193     /// For debugging purposes only.
00194     /// Caution: there are 1024 of them (many reserved and set to 0).
00195     /// \return true on success
00196     bool printRegisters();
00197 
00198     /// Checks whether a received message is available.
00199     /// This can be called multiple times in a timeout loop
00200     /// \return true if a complete, valid message has been received and is able to be retrieved by
00201     /// recv()
00202     bool        available();
00203 
00204     /// Turns the receiver on if it not already on.
00205     /// Once a message with CRC correct is received, the receiver will be returned to Idle mode.
00206     /// If there is a valid message available, copy it to buf and return true
00207     /// else return false.
00208     /// If a message is copied, *len is set to the length (Caution, 0 length messages are permitted).
00209     /// You should be sure to call this function frequently enough to not miss any messages
00210     /// It is recommended that you call it in your main loop.
00211     /// \param[in] buf Location to copy the received message
00212     /// \param[in,out] len Pointer to available space in buf. Set to the actual number of octets copied.
00213     /// \return true if a valid message was copied to buf
00214     bool        recv(uint8_t* buf, uint8_t* len);
00215 
00216     /// The maximum message length supported by this driver
00217     /// \return The maximum message length supported by this driver
00218     uint8_t maxMessageLength();
00219 
00220 protected:
00221     /// Examine the receive buffer to determine whether the message is for this node
00222     void validateRxBuf();
00223 
00224     /// Clear our local receive buffer
00225     void clearRxBuf();
00226 
00227 private:
00228     /// The receiver/transmitter buffer
00229     /// First octet is the payload length, remainder is the payload
00230     uint8_t             _buf[RH_NRF51_MAX_PAYLOAD_LEN+1];
00231 
00232     /// True when there is a valid message in the buffer
00233     bool                _rxBufValid;
00234 };
00235 
00236 /// @example nrf51_client.pde
00237 /// @example nrf51_server.pde
00238 /// @example nrf51_reliable_datagram_client.pde
00239 /// @example nrf51_reliable_datagram_server.pde
00240 /// @example nrf51_audio_tx.pde
00241 /// @example nrf51_audio_rx.pde
00242 #endif