sx1232.h

00001 /* SX1232 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 SX1232_H
00018 #define SX1232_H
00019 
00020 #include "mbed.h"
00021 
00022 #define XTAL_FREQ   32000000
00023 
00024 #define FREQ_STEP_MHZ     61.03515625e-6
00025 #define FREQ_STEP_KHZ     61.03515625e-3
00026 #define FREQ_STEP_HZ      61.03515625
00027 
00028 /******************************************************************************/
00029 /*!
00030  * SX1232 Internal registers Address
00031  */
00032 #define REG_FIFO                                    0x00
00033 // Common settings
00034 #define REG_OPMODE                                  0x01
00035 #define REG_BITRATEMSB                              0x02
00036 #define REG_BITRATELSB                              0x03
00037 #define REG_FDEVMSB                                 0x04 
00038 #define REG_FDEVLSB                                 0x05
00039 #define REG_FRFMSB                                  0x06
00040 #define REG_FRFMID                                  0x07
00041 #define REG_FRFLSB                                  0x08
00042 // Tx settings
00043 #define REG_PACONFIG                                0x09
00044 #define REG_PARAMP                                  0x0A
00045 #define REG_OCP                                     0x0B 
00046 // Rx settings
00047 #define REG_LNA                                     0x0C
00048 #define REG_RXCONFIG                                0x0D
00049 #define REG_RSSICONFIG                              0x0E
00050 #define REG_RSSICOLLISION                           0x0F
00051 #define REG_RSSITHRESH                              0x10
00052 #define REG_RSSIVALUE                               0x11
00053 #define REG_RXBW                                    0x12 
00054 #define REG_AFCBW                                   0x13
00055 #define REG_OOKPEAK                                 0x14
00056 #define REG_OOKFIX                                  0x15
00057 #define REG_OOKAVG                                  0x16
00058 #define REG_RES17                                   0x17
00059 #define REG_RES18                                   0x18
00060 #define REG_RES19                                   0x19
00061 #define REG_AFCFEI                                  0x1A
00062 #define REG_AFCMSB                                  0x1B
00063 #define REG_AFCLSB                                  0x1C
00064 #define REG_FEIMSB                                  0x1D
00065 #define REG_FEILSB                                  0x1E
00066 #define REG_PREAMBLEDETECT                          0x1F
00067 #define REG_RXTIMEOUT1                              0x20
00068 #define REG_RXTIMEOUT2                              0x21
00069 #define REG_RXTIMEOUT3                              0x22
00070 #define REG_RXDELAY                                 0x23
00071 // Oscillator settings
00072 #define REG_OSC                                     0x24
00073 // Packet handler settings
00074 #define REG_PREAMBLEMSB                             0x25
00075 #define REG_PREAMBLELSB                             0x26
00076 #define REG_SYNCCONFIG                              0x27
00077 #define REG_SYNCVALUE1                              0x28
00078 #define REG_SYNCVALUE2                              0x29
00079 #define REG_SYNCVALUE3                              0x2A
00080 #define REG_SYNCVALUE4                              0x2B
00081 #define REG_SYNCVALUE5                              0x2C
00082 #define REG_SYNCVALUE6                              0x2D
00083 #define REG_SYNCVALUE7                              0x2E
00084 #define REG_SYNCVALUE8                              0x2F
00085 #define REG_PACKETCONFIG1                           0x30
00086 #define REG_PACKETCONFIG2                           0x31
00087 #define REG_PAYLOADLENGTH                           0x32
00088 #define REG_NODEADRS                                0x33
00089 #define REG_BROADCASTADRS                           0x34
00090 #define REG_FIFOTHRESH                              0x35
00091 // SM settings
00092 #define REG_SEQCONFIG1                              0x36
00093 #define REG_SEQCONFIG2                              0x37
00094 #define REG_TIMERRESOL                              0x38
00095 #define REG_TIMER1COEF                              0x39
00096 #define REG_TIMER2COEF                              0x3A
00097 // Service settings
00098 #define REG_IMAGECAL                                0x3B
00099 #define REG_TEMP                                    0x3C
00100 #define REG_LOWBAT                                  0x3D
00101 // Status
00102 #define REG_IRQFLAGS1                               0x3E
00103 #define REG_IRQFLAGS2                               0x3F
00104 // I/O settings
00105 #define REG_DIOMAPPING1                             0x40
00106 #define REG_DIOMAPPING2                             0x41
00107 // Version
00108 #define REG_VERSION                                 0x42
00109 // Additional settings
00110 #define REG_AGCREF                                  0x43
00111 #define REG_AGCTHRESH1                              0x44
00112 #define REG_AGCTHRESH2                              0x45
00113 #define REG_AGCTHRESH3                              0x46
00114 #define REG_PLLHOP                                  0x4B
00115 #define REG_TCXO                                    0x58
00116 #define REG_PADAC                                   0x5A
00117 #define REG_PLL                                     0x5C
00118 #define REG_PLLLOWPN                                0x5E
00119 #define REG_FORMERTEMP                              0x6C
00120 #define REG_BITRATEFRAC                             0x70
00121 
00122 /******************************************************************************/
00123 
00124 typedef enum {
00125     RF_OPMODE_SLEEP = 0,
00126     RF_OPMODE_STANDBY,
00127     RF_OPMODE_SYNTHESIZER_TX,
00128     RF_OPMODE_TRANSMITTER,
00129     RF_OPMODE_SYNTHESIZER_RX,
00130     RF_OPMODE_RECEIVER
00131 } chip_mode_e;
00132 
00133 /******************************************************************************/
00134 
00135 typedef union {
00136     struct {    // sx1232 register 0x01
00137         uint8_t Mode                : 3;    // 0,1,2
00138         uint8_t ModulationShaping   : 2;    // 3,4  FSK/OOK
00139         uint8_t ModulationType      : 2;    // 5,6  FSK/OOK
00140         uint8_t LongRangeMode       : 1;    // 7    change this bit only in sleep mode
00141     } bits;
00142     uint8_t octet;
00143 } RegOpMode_t;
00144 
00145 typedef union {
00146     struct {    // sx1232 register 0x09
00147         uint8_t OutputPower : 4;    // 0,1,2,3
00148         uint8_t unused      : 3;    // 4,5,6
00149         uint8_t PaSelect    : 1;    // 7        1=PA_BOOST
00150     } bits;
00151     uint8_t octet;
00152 } RegPaConfig_t;
00153 
00154 typedef union {
00155     struct {    // sx1232 register 0x0c
00156         uint8_t lna_i_boost  : 2;    // 0,1
00157         uint8_t unused       : 1;    // 2
00158         uint8_t trim_rx_crfo : 2;    // 3,4     add caps to RFo
00159         uint8_t rxfe_gain    : 3;    // 5,6,7        1=PA_BOOST
00160     } bits;
00161     uint8_t octet;
00162 } RegLna_t; // RXFE
00163 
00164 typedef union {
00165     struct {    // sx1232 register 0x0d
00166         uint8_t RxTrigger               : 3;    // 0,1,2: 0=none 1=rssiInt 6=preambleDet 7=both
00167         uint8_t AgcAutoOn               : 1;    // 3
00168         uint8_t AfcAutoOn               : 1;    // 4
00169         uint8_t RestartRxWithPllLock    : 1;    // 5    manual rx restart, for use with FHSS
00170         uint8_t RestartRxWithoutPllLock : 1;    // 6    manual rx restart
00171         uint8_t RestartRxOnCollision    : 1;    // 7    collision detector (see RegRssiCollision at 0x0f)
00172     } bits;
00173     uint8_t octet;
00174 } RegRxConfig_t;
00175 
00176 typedef union {
00177     struct {    // sx1232 register 0x14
00178         uint8_t OokPeakThreshStep   : 3;    // 0,1,2
00179         uint8_t OokThreshType       : 2;    // 3,4
00180         uint8_t BitSyncOn           : 1;    // 5
00181         uint8_t barker_en           : 1;    // 6
00182         uint8_t bsync_opt           : 1;    // 7    not used
00183     } bits;
00184     uint8_t octet;
00185 } RegOokPeak_t; // DEMOD1 0x14
00186 
00187 typedef union {
00188     struct {    // sx1232 register 0x1a
00189         uint8_t AfcAutoClearOn  : 1;    // 0
00190         uint8_t AfcClear        : 1;    // 1    manual clear
00191         uint8_t unused1         : 1;    // 2
00192         uint8_t fei_range       : 1;    // 3    FEI range limited by: 0=rxbw    1=fs/2
00193         uint8_t AgcStart        : 1;    // 4    manual trigger AGC
00194         uint8_t unused          : 3;    // 5,6,7 
00195     } bits;
00196     uint8_t octet;
00197 } RegAfcFei_t;
00198 
00199 typedef union {
00200     struct {    // sx1232 register 0x1f
00201         uint8_t PreambleDetectorTol     : 5;    // 0,1,2,3,4    allowed chip errors
00202         uint8_t PreambleDetectorSize    : 2;    // 5,6      00b=1bytes... 11b=4bytes
00203         uint8_t PreambleDetectorOn      : 1;    // 7
00204     } bits;
00205     uint8_t octet;
00206 } RegPreambleDetect_t;
00207 
00208 typedef union {
00209     struct {    // sx1232 register 0x27
00210         uint8_t SyncSize            : 3;    // 0,1,2
00211         uint8_t FifoFillCondition   : 1;    // 3    rx fifo fill starting 0=start-on-sync
00212         uint8_t SyncOn              : 1;    // 4    enable pattern recognition
00213         uint8_t PreamblePolarity    : 1;    // 5    0=0xaa 1=0x55
00214         uint8_t AutoRestartRxMode   : 2;    // 6,7  00b=manual restart, 01b=auto-restart after fifo pulled, and 10b=add wait-for-pll
00215     } bits; // manual Rx restart is in RegRxConfig
00216     uint8_t octet;
00217 } RegSyncConfig_t;
00218 
00219 typedef union {
00220     struct {    // sx1232 register 0x30
00221         uint8_t CrCWhiteningType : 1;    // 0       1=IBM-crc   0=ccitt-crc
00222         uint8_t AddressFiltering : 2;    // 1,2     11b = two-byte nodeadrs at 0x2c->0x2f
00223         uint8_t CrcAutoClearOff  : 1;    // 3
00224         uint8_t CrcOn            : 1;    // 4
00225         uint8_t DcFree           : 2;    // 5,6 
00226         uint8_t PacketFormatVariable : 1;    // 7       1=variable length, 0=fixed
00227     } bits;
00228     uint8_t octet;
00229 } RegPktConfig1_t;
00230 
00231 typedef union {
00232     struct {    // sx1232 register 0x31
00233         uint8_t PayloadLengthHi  : 3;    // 0,1,2       PayloadLength(10:8)
00234         uint8_t BeaconOn         : 1;    // 3
00235         uint8_t IoHomePowerFrame : 1;    // 4   CRC LFSR init: 0=0x1d0f, 1=0x0000=powerlink
00236         uint8_t IoHomeOn         : 1;    // 5
00237         uint8_t DataModePacket   : 1;    // 6   1=packet mode, 0=continuous mode
00238         uint8_t unused           : 1;    // 7 
00239     } bits;
00240     uint8_t octet;
00241 } RegPktConfig2_t;
00242 
00243 typedef union {
00244     struct {    // sx1232 register 0x35
00245         uint8_t FifoThreshold       : 6;    // 0,1,2,3,4,5       PayloadLength(10:8)
00246         uint8_t unused              : 1;    // 6 
00247         uint8_t TxStartCondition    : 1;    // 7        0=fifoThresh 1=fifoNotEmpty
00248     } bits;
00249     uint8_t octet;
00250 } RegFifoThreshold_t;
00251 
00252 typedef union {
00253     struct {    // sx1232 register 0x36
00254         uint8_t FromTransmit        : 1;    // 0
00255         uint8_t FromIdle            : 1;    // 1
00256         uint8_t LowPowerSelection   : 1;    // 2
00257         uint8_t FromStart           : 2;    // 3,4
00258         uint8_t IdleMode            : 1;    // 5 
00259         uint8_t SequencerStop       : 1;    // 6 
00260         uint8_t SequencerStart      : 1;    // 7
00261     } bits;
00262     uint8_t octet;
00263 } RegSeqConfig1_t;   // @0x36
00264 
00265 typedef union {
00266     struct {    // sx1232 register 0x37
00267         uint8_t FromPacketReceived  : 3;    // 0,1,2
00268         uint8_t FromRxTimeout       : 2;    // 3,4
00269         uint8_t FromReceive         : 3;    // 5,6,7
00270     } bits;
00271     uint8_t octet;
00272 } RegSeqConfig2_t;   // @0x37
00273 
00274 typedef union {
00275     struct {    // sx1232 register 0x38
00276         uint8_t timer2_resol   : 2;    // 0,1
00277         uint8_t timer1_resol   : 2;    // 2,3
00278         uint8_t force_hlm_irq  : 1;    // 4 
00279         uint8_t hlm_started    : 1;    // 5 
00280         uint8_t unused         : 2;    // 6,7
00281     } bits;
00282     uint8_t octet;
00283 } RegTimerResol_t ;   // HL42 @0x38
00284 
00285 typedef union {
00286     struct {    // sx1232 register 0x3e
00287         uint8_t SyncAddressMatch    : 1;    // 0 
00288         uint8_t PreambleDetect      : 1;    // 1 
00289         uint8_t Timeout             : 1;    // 2    rx-timeout
00290         uint8_t Rssi                : 1;    // 3 
00291         uint8_t PllLock             : 1;    // 4 
00292         uint8_t TxReady             : 1;    // 5 
00293         uint8_t RxReady             : 1;    // 6 
00294         uint8_t ModeReady           : 1;    // 7 
00295     } bits;
00296     uint8_t octet;
00297 } RegIrqFlags1_t;   // STAT0
00298 
00299 typedef union {
00300     struct {    // sx1232 register 0x3f
00301         uint8_t LowBat          : 1;    // 0    "eol"
00302         uint8_t CrcOk           : 1;    // 1 
00303         uint8_t PayloadReady    : 1;    // 2 
00304         uint8_t PacketSent      : 1;    // 3 
00305         uint8_t FifoOverrun     : 1;    // 4 
00306         uint8_t FifoLevel       : 1;    // 5 
00307         uint8_t FifoEmpty       : 1;    // 6 
00308         uint8_t FifoFull        : 1;    // 7 
00309     } bits;
00310     uint8_t octet;
00311 } RegIrqFlags2_t;   // STAT1 @0x3f
00312 
00313 typedef union {
00314     struct {    // sx1232 register 0x40
00315         uint8_t Dio3Mapping     : 2;    // 0,1
00316         uint8_t Dio2Mapping     : 2;    // 2,3
00317         uint8_t Dio1Mapping     : 2;    // 4,5
00318         uint8_t Dio0Mapping     : 2;    // 6,7 
00319     } bits;
00320     uint8_t octet;
00321 } RegDioMapping1_t;
00322 
00323 typedef union {
00324     struct {    // sx1232 register 0x41
00325         uint8_t MapPreambleDetect : 1;    // 0      //DIO4 assign: 1b=preambleDet 0b=rssiThresh
00326         uint8_t io_mode           : 3;    // 1,2,3  //0=normal,1=debug,2=fpga,3=pll_tx,4=pll_rx,5=analog
00327         uint8_t Dio5Mapping       : 2;    // 4,5
00328         uint8_t Dio4Mapping       : 2;    // 6,7 
00329     } bits;
00330     uint8_t octet;
00331 } RegDioMapping2_t;
00332 
00333 /***************************************************/
00334 
00335 typedef enum {
00336     SERVICE_NONE = 0,
00337     SERVICE_ERROR,
00338     //! request to call read_fifo()
00339     SERVICE_READ_FIFO,
00340     //! notification to application of transmit complete
00341     SERVICE_TX_DONE
00342 } service_action_e;
00343 
00344 /** FSK radio transceiver for 800/900MHz.
00345  * Compared with ADF7023 in Xbee PRO 900:
00346  *  Receiver bandwidth configurable to narrower operation, for performance at lower bitrates.
00347  *  Transmit power option to +20dBm.
00348  *  Superior blocking immunity in receiver.
00349  * http://www.semtech.com/apps/product.php?pn=sx1232
00350  */
00351 class SX1232 {
00352     public:
00353             /** Create SX1232 instance
00354          * @param mosi SPI master-out pin
00355          * @param miso SPI master-in pin
00356          * @param sclk SPI clock pin
00357          * @param cs SPI chip-select pin
00358          * @param rst radio hardware reset pin
00359          * @param dio_0 interrupt pin from radio
00360          */
00361         SX1232(PinName mosi, PinName miso, PinName sclk, PinName cs, PinName rst, PinName dio_0);
00362         
00363         ~SX1232();
00364         
00365         /** set receiver bandwidth
00366          * @note Value is selected to frequency deviation and bit-rate (occupied bandwidth)
00367          * @note Narrower bandwidths may require AFC, depending on reference crystal accuracy
00368          * @note RX start-up time is slower at narrower bandwidths
00369          * @note you cannot change bandwith while in receive mode
00370          * @note usable range is 2.6KHz to 250KHz
00371          */
00372         void set_rx_dcc_bw_hz(uint32_t dccValue, uint32_t bw_hz );
00373         /** get receiver bandwidth
00374          * @returns the receiver bandwidth in Hz
00375          */
00376         uint32_t get_rx_bw_hz(uint8_t addr);
00377         
00378         /** set center operating frequency
00379          * @param MHz operating frequency in MHz
00380          */
00381         void set_frf_MHz( float MHz );
00382         
00383         /** get center operating frequency
00384          * @returns operating frequency in MHz
00385          */
00386         float get_frf_MHz(void);
00387         
00388         /** set over-the-air bitrate
00389          * @param bps bits per second
00390          * @note TX frequency deviation must be set according to desired modulation index
00391          * @note you cannot change bitrate while in receive mode
00392          */
00393         void set_bitrate(uint32_t bps);
00394         /** get over-the-air bitrte
00395          * @returns bits per second
00396          */
00397         uint32_t get_bitrate(void);
00398         
00399         /** set transmitted frequency deviation
00400          * @param hz frequency deviation in Hz
00401          * @note occupied bandwith is primarily determined by fdev; set receiver bandwidth appropriately
00402          * @note usable range is 600Hz to 200KHz
00403          */
00404         void set_tx_fdev_hz(uint32_t hz);
00405         /** get transmitted frequency deviation
00406          * @returns transmitter frequency deviation in Hz
00407          */
00408         uint32_t get_tx_fdev_hz(void);
00409         
00410         /** enable AFC with preamble detector
00411          * @note AFC generally used when crystal tolerance is worse than receiver bandwidth.  Narrower bandwidths require better ppm on crystal, without AFC.
00412          * @note this enables with RxTrigger on preamble detect without RSSI threshold.
00413          * @note other option is to also use RSSI threshold, but requires calibration from ambient RSSI on vacant channel.
00414          */
00415         void enable_afc(char enable);
00416         
00417         /** write payload length
00418          * @note PayloadLength is maximum 255 in variable-length packet format, or fixed-length maximum of 2047 bytes.
00419          * @note if PacketFormat is fixed-length, then PayloadLength of 0 enables unlimited length mode.
00420          * @note In variable length mode, this sets maximum allowed received packet length.
00421          * @param len PayloadLength
00422          */
00423         void set_RegPayloadLength(uint16_t len);
00424         /** read payload length
00425          */
00426         uint16_t get_PayloadLength(void);        
00427         
00428         /** transmit a packet
00429          * @param len size of packet, variable-length format only.  unused in fixed-length format.
00430          * @note Limited to 64 bytes. Lengths greater than 64 require flow control (radio FIFO size)
00431          */
00432         void start_tx(uint8_t len);
00433         
00434         /** start receive mode
00435          * @note the variable service_action needs to be monitored to indicate read_fifo() needs to be called to pull packet from FIFO.
00436          */
00437         void start_rx(void);
00438         /** Called by main program when indicated by service_action variable, to pull recevied packet from radio FIFO.
00439          * @returns count of bytes received
00440          * @note received packet in rx_buf[]
00441          */
00442         int read_fifo(void);
00443         
00444         void set_opmode(chip_mode_e mode);
00445         
00446         /** reset radio using pin
00447          */
00448         void hw_reset(void);
00449         /** initialise SX1232 class to radio
00450          * @note this is called from class instantiation, but must also be manually called after hardware reset
00451          */
00452         void init(void);
00453         
00454         /** read register from radio
00455          * @param addr register address
00456          * @returns the value read from the register
00457          */
00458         uint8_t read_reg(uint8_t addr);
00459         int16_t read_reg_s16(uint8_t addr);  // for signed 16bit values, such as AFC/FEI
00460         
00461         /** write register to radio
00462          * @param addr register address
00463          * @param data byte to write
00464          */
00465         void write_reg(uint8_t addr, uint8_t data);
00466                 
00467         //! set from ISR to indicate an action to be performed from main loop
00468         volatile service_action_e service_action;
00469         
00470         //! RF transmit packet buffer
00471         uint8_t tx_buf[64]; 
00472         
00473         //! RF receive packet buffer
00474         uint8_t rx_buf[64]; 
00475         
00476         //! operating mode
00477         RegOpMode_t RegOpMode; 
00478         
00479         //! pin assignments
00480         RegDioMapping1_t RegDioMapping1; 
00481         
00482         //! pin assignments
00483         RegDioMapping2_t RegDioMapping2; 
00484         
00485         //! packet format configuration
00486         RegPktConfig1_t RegPktConfig1; 
00487         
00488         //! packet mode control and payload length MSB
00489         RegPktConfig2_t RegPktConfig2; 
00490         
00491         //! payload length LSByte
00492         uint8_t RegPayloadLength; 
00493         
00494         //! TxStartCondition
00495         RegFifoThreshold_t RegFifoThreshold; 
00496         
00497         //! AutoRestartRx configuration and start-of-frame control
00498         RegSyncConfig_t RegSyncConfig; 
00499         
00500         //! receiver preamble detector control
00501         RegPreambleDetect_t RegPreambleDetect; 
00502         
00503         //! TX preamble length
00504         uint8_t RegPreambleMsb; 
00505         
00506         //! TX preamble length
00507         uint8_t RegPreambleLsb; 
00508         
00509         //! transmitter power configuration
00510         RegPaConfig_t RegPaConfig; 
00511         
00512         //! AFC/AGC configuration
00513         RegRxConfig_t RegRxConfig; 
00514         
00515         // receiver front-end
00516         RegLna_t RegLna; 
00517         
00518         //! sequencer timing
00519         RegTimerResol_t RegTimerResol; 
00520         
00521         //! receiver: trigger level for RSSI interrupt
00522         uint8_t RegRssiThresh; 
00523         
00524         //! sequencer control
00525         RegSeqConfig1_t RegSeqConfig1; 
00526         
00527         //! sequencer control
00528         RegSeqConfig2_t RegSeqConfig2; 
00529         
00530         //! AFC clearing control and manual AFC trigger
00531         RegAfcFei_t RegAfcFei; 
00532         
00533         RegOokPeak_t RegOokPeak;
00534         
00535     private:
00536         SPI m_spi;
00537         DigitalOut m_cs;
00538         DigitalInOut reset_pin;
00539         void dio0_callback(void);
00540         void ComputeRxBwMantExp( uint32_t rxBwValue, uint8_t* mantisse, uint8_t* exponent );
00541         uint32_t ComputeRxBw( uint8_t mantisse, uint8_t exponent );
00542         void write_fifo__varlen(uint8_t len);
00543         void write_fifo__fixedlen(void);
00544         
00545         
00546     protected:
00547         InterruptIn dio0;
00548         FunctionPointer _callback_rx;
00549 };
00550 
00551 
00552 #endif /* SX1232_H */