sx12xx.h

00001 /* SX127x driver
00002  * Copyright (c) 2013 Semtech
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016   
00017 #ifndef SX127x_H
00018 #define SX127x_H
00019 
00020 #include "mbed.h"
00021 
00022 #define XTAL_FREQ   32000000
00023 
00024 #define FREQ_STEP_MHZ     61.03515625e-6    // 32 / (2^19)
00025 #define FREQ_STEP_KHZ     61.03515625e-3    // 32e3 / (2^19)
00026 #define FREQ_STEP_HZ      61.03515625       // 32e6 / (2^19)
00027 
00028 #define MHZ_TO_FRF(m)   (m / FREQ_STEP_MHZ)
00029 
00030 /******************************************************************************/
00031 /*!
00032  * SX127x Internal registers Address
00033  */
00034 #define REG_FIFO                                    0x00
00035 #define REG_OPMODE                                  0x01
00036 #define REG_FRFMSB                                  0x06
00037 #define REG_FRFMID                                  0x07
00038 #define REG_FRFLSB                                  0x08
00039 // Tx settings
00040 #define REG_PACONFIG                                0x09
00041 #define REG_PARAMP                                  0x0A
00042 #define REG_OCP                                     0x0B 
00043 // Rx settings
00044 #define REG_LNA                                     0x0C
00045 
00046 
00047 /***** registers above 0x40 are same as FSK/OOK page */
00048 
00049 #define REG_DIOMAPPING1                             0x40
00050 #define REG_DIOMAPPING2                             0x41
00051 #define REG_VERSION                                 0x42
00052 
00053 #define REG_PATEST_SX1276                           0x44
00054 #define REG_PATEST_SX1272                           0x4b
00055 #define REG_PDSTRIM1_SX1276                         0x4d
00056 #define REG_PDSTRIM1_SX1272                         0x5a
00057 #define REG_PLL_SX1272                              0x5c    // RX PLL bandwidth
00058 #define REG_PLL_LOWPN_SX1272                        0x5e
00059 #define REG_PLL_SX1276                              0x70 
00060 #define REG_BSYNCTST2                               0x67
00061 /******************************************************************************/
00062 
00063 
00064 typedef enum {
00065     RF_OPMODE_SLEEP = 0,
00066     RF_OPMODE_STANDBY,          // 1
00067     RF_OPMODE_SYNTHESIZER_TX,   // 2
00068     RF_OPMODE_TRANSMITTER,      // 3
00069     RF_OPMODE_SYNTHESIZER_RX,   // 4
00070     RF_OPMODE_RECEIVER,         // 5
00071     RF_OPMODE_RECEIVER_SINGLE,  // 6
00072     RF_OPMODE_CAD               // 7
00073 } chip_mode_e;
00074 
00075 typedef enum {
00076     SX_NONE = 0,
00077     SX1272,
00078     SX1276
00079 } type_e;
00080 
00081 typedef enum {
00082     SERVICE_NONE = 0,
00083     SERVICE_ERROR,
00084     //! request to call read_fifo()
00085     SERVICE_READ_FIFO,
00086     //! notification to application of transmit complete
00087     SERVICE_TX_DONE
00088 } service_action_e;
00089 
00090 /******************************************************************************/
00091 
00092 typedef union {
00093     struct {    // sx1272 register 0x01
00094         uint8_t Mode                : 3;    // 0,1,2
00095         uint8_t ModulationShaping   : 2;    // 3,4  FSK/OOK
00096         uint8_t ModulationType      : 2;    // 5,6  FSK/OOK
00097         uint8_t LongRangeMode       : 1;    // 7    change this bit only in sleep mode
00098     } bits;
00099     struct {    // sx1276 register 0x01
00100         uint8_t Mode                : 3;    // 0,1,2
00101         uint8_t LowFrequencyModeOn  : 1;    // 3    1=access to LF test registers (0=HF regs)
00102         uint8_t reserved            : 1;    // 4
00103         uint8_t ModulationType      : 2;    // 5,6  FSK/OOK
00104         uint8_t LongRangeMode       : 1;    // 7    change this bit only in sleep mode
00105     } sx1276FSKbits;
00106     struct {    // sx1276 register 0x01
00107         uint8_t Mode                : 3;    // 0,1,2
00108         uint8_t LowFrequencyModeOn  : 1;    // 3    1=access to LF test registers (0=HF regs)
00109         uint8_t reserved            : 2;    // 4,5
00110         uint8_t AccessSharedReg     : 1;    // 6    1=FSK registers while in LoRa mode
00111         uint8_t LongRangeMode       : 1;    // 7    change this bit only in sleep mode
00112     } sx1276LORAbits;
00113     uint8_t octet;
00114 } RegOpMode_t;
00115 
00116 typedef union {
00117     struct {    // sx12xx register 0x09
00118         uint8_t OutputPower : 4;    // 0,1,2,3
00119         uint8_t MaxPower    : 3;    // 4,5,6
00120         uint8_t PaSelect    : 1;    // 7        1=PA_BOOST
00121     } bits;
00122     uint8_t octet;
00123 } RegPaConfig_t;
00124 
00125 typedef union {
00126     struct {    // sx12xx register 0x0b
00127         uint8_t OcpTrim : 5;    // 0,1,2,3,4
00128         uint8_t OcpOn   : 1;    // 5
00129         uint8_t unused  : 2;    // 6,7
00130     } bits;
00131     uint8_t octet;
00132 } RegOcp_t;
00133 
00134 typedef union {
00135     struct {    // sx12xx register 0x0c
00136         uint8_t LnaBoostHF           : 2;    // 0,1
00137         uint8_t reserved             : 1;    // 2
00138         uint8_t LnaBoostLF           : 2;    // 3,4
00139         uint8_t LnaGain              : 3;    // 5,6,7
00140     } bits;
00141     uint8_t octet;
00142 } RegLna_t; // RXFE
00143 
00144 typedef union {
00145     struct {    // sx127x register 0x0a
00146         uint8_t PaRamp             : 4;    // 0,1,2,3
00147         uint8_t LowPnTxPllOff      : 1;    // 4        sx1272 only
00148         uint8_t ModulationShaping  : 2;    // 5,6      sx1276 only
00149         uint8_t unused             : 1;    // 7
00150     } bits;
00151     uint8_t octet;
00152 } RegPaRamp_t; //
00153 
00154 /*********************** ****************************/
00155 
00156 typedef union {
00157     struct {    // sx12xx register 0x40
00158         uint8_t Dio3Mapping     : 2;    // 0,1
00159         uint8_t Dio2Mapping     : 2;    // 2,3
00160         uint8_t Dio1Mapping     : 2;    // 4,5
00161         uint8_t Dio0Mapping     : 2;    // 6,7 
00162     } bits;
00163     uint8_t octet;
00164 } RegDioMapping1_t;
00165 
00166 typedef union {
00167     struct {    // sx12xx register 0x41
00168         uint8_t MapPreambleDetect : 1;    // 0      //DIO4 assign: 1b=preambleDet 0b=rssiThresh
00169         uint8_t io_mode           : 3;    // 1,2,3  //0=normal,1=debug,2=fpga,3=pll_tx,4=pll_rx,5=analog
00170         uint8_t Dio5Mapping       : 2;    // 4,5
00171         uint8_t Dio4Mapping       : 2;    // 6,7 
00172     } bits;
00173     uint8_t octet;
00174 } RegDioMapping2_t;
00175 
00176 /***************************************************/
00177 
00178 typedef union {
00179     struct {    // sx1272 register 0x5a (sx1276 0x4d)
00180         uint8_t prog_txdac             : 3;    // 0,1,2     BGR ref current to PA DAC
00181         uint8_t pds_analog_test        : 1;    // 3      
00182         uint8_t pds_pa_test            : 2;    // 4,5
00183         uint8_t pds_ptat               : 2;    // 6,7     leave at 2 (5uA)
00184     } bits;
00185     uint8_t octet;
00186 } RegPdsTrim1_t;
00187 
00188 typedef union {
00189     struct {    // sx1272 register 0x5c
00190         uint8_t reserved           : 6;    // 0->5
00191         uint8_t PllBandwidth       : 2;    // 6,7 
00192     } bits;
00193     uint8_t octet;
00194 } RegPll_t;
00195 
00196 typedef union {
00197     struct {    // sx1272 register 0x67
00198         uint8_t bsync_mode              : 3;    // 0,1,2
00199         uint8_t reserved                : 1;    // 3
00200         uint8_t bsync_thresh_validity   : 1;    // 4
00201         uint8_t unused                  : 3;    // 5,6,7 
00202     } bits;
00203     uint8_t octet;
00204 } RegBsyncTest2_t;
00205 
00206 /** FSK/LoRa radio transceiver.
00207  * see http://en.wikipedia.org/wiki/Chirp_spread_spectrum
00208  */
00209 
00210 class SX127x {
00211     public:
00212             /** Create SX127x instance
00213          * @param mosi SPI master-out pin
00214          * @param miso SPI master-in pin
00215          * @param sclk SPI clock pin
00216          * @param cs SPI chip-select pin
00217          * @param rst radio hardware reset pin
00218          * @param dio_0 interrupt pin from radio
00219          * @param fem_ctx rx-tx switch for HF bands (800/900)
00220          * @param fem_cps rx-tx switch for LF bands (vhf/433)
00221          */
00222          
00223         SX127x(PinName dio0, PinName dio_1, PinName cs, SPI&, PinName rst);
00224         
00225         ~SX127x();
00226         
00227         /** set center operating frequency
00228          * @param MHz operating frequency in MHz
00229          */
00230         void set_frf_MHz( float MHz );
00231         
00232         /** get center operating frequency
00233          * @returns operating frequency in MHz
00234          */
00235         float get_frf_MHz(void);
00236 
00237         void set_opmode(chip_mode_e mode);
00238         
00239         /** reset radio using pin
00240          */
00241         void hw_reset(void);
00242         /** initialise SX1232 class to radio
00243          * @note this is called from class instantiation, but must also be manually called after hardware reset
00244          */
00245         void init(void);
00246         void get_type(void); // identify radio chip
00247         
00248         /** read register from radio
00249          * @param addr register address
00250          * @returns the value read from the register
00251          */
00252         uint8_t read_reg(uint8_t addr);
00253         uint16_t read_u16(uint8_t addr);
00254         int16_t read_s16(uint8_t addr);
00255         
00256         /** read register from radio. from an arbitrary amount of registers following the first
00257          * @param addr register address
00258          * @param buffer the read values will be placed here
00259          * @param size how many registers to read
00260          */        
00261         void ReadBuffer( uint8_t addr, uint8_t *buffer, uint8_t size );
00262         
00263         /** write register to radio
00264          * @param addr register address
00265          * @param data byte to write
00266          */
00267         void write_reg(uint8_t addr, uint8_t data);
00268         void write_u16(uint8_t addr, uint16_t data);
00269         void write_u24(uint8_t addr, uint32_t data);
00270         
00271         /** write register(s) to radio, to an arbitrary amount of registers following first
00272          * @param addr register address
00273          * @param buffer byte(s) to write
00274          * @param size count of registers to write to
00275          */
00276         void WriteBuffer( uint8_t addr, uint8_t *buffer, uint8_t size );
00277         
00278         /* *switch between FSK or LoRa modes */
00279         //void SetLoRaOn(bool);
00280         
00281         /*****************************************************/
00282         
00283         //! RF transmit packet buffer
00284         uint8_t tx_buf[256];    // lora fifo size
00285         
00286         //! RF receive packet buffer
00287         uint8_t rx_buf[256];    // lora fifo size
00288        
00289         //! radio chip type plugged in
00290         type_e type;
00291         
00292         //! operating mode
00293         RegOpMode_t RegOpMode;
00294         
00295         //! transmitter power configuration
00296         RegPaConfig_t RegPaConfig;
00297         
00298         RegOcp_t RegOcp;            // 0x0b
00299         
00300         // receiver front-end
00301         RegLna_t RegLna;            // 0x0c
00302         
00303         //! pin assignments
00304         RegDioMapping1_t RegDioMapping1;
00305         
00306         //! pin assignments
00307         RegDioMapping2_t RegDioMapping2;
00308                
00309         DigitalIn dio0;
00310         DigitalIn dio1;
00311         DigitalOut m_cs;
00312         SPI& m_spi;
00313         bool HF;    // sx1272 is always HF   
00314 
00315         /*! board-specific RF switch callback, called whenever operating mode is changed
00316          * This function should also set RegPaConfig.bits.PaSelect to use PA_BOOST or RFO during TX.
00317          * examples:
00318          *      PE4259-63: controlled directly by radio chip, no software function needed
00319          *      SKY13350-385LF: two separate control lines, requires two DigitalOut pins
00320          */
00321         Callback<void()> rf_switch ;
00322          
00323     private:    
00324         DigitalInOut reset_pin;        
00325         
00326     protected:
00327         
00328 };
00329 
00330 #endif /* SX127x_H */