PCF2127.h

00001 /*
00002  *  PCF2127 library
00003  *
00004  *  @author     Akifumi (Tedd) OKANO, NXP Semiconductors
00005  *  @version    1.8
00006  *  @date       10-Dec-2014
00007  *
00008  *  PCF2127 is a "real time clock (RTC)" module which is including a Xtal and TCXO
00009  *  http://www.nxp.com/products/interface_and_connectivity/real_time_clocks/rtcs_with_temp_compensation/series/PCF2127.html
00010  *
00011  *  RTC initializing part is ported from..
00012  *    http://mbed.org/users/roen/notebook/real-time/
00013  *
00014  *  This code is refined version of..
00015  *    http://developer.mbed.org/users/okano/code/NXP_PCF2127A/
00016  */
00017 
00018 #ifndef        MBED_PCF2127
00019 #define        MBED_PCF2127
00020 
00021 #include    "mbed.h"
00022 
00023 /** PCF2127 class
00024  *
00025  *  This is a driver code for the PPCF2127: "real time clock (RTC)" module which is including a Xtal and TCXO
00026  *  This class provides interface for PCF2127 operation and accessing its registers.
00027  *  Detail information is available on next URL.
00028  *    http://www.nxp.com/products/interface_and_connectivity/real_time_clocks/rtcs_with_temp_compensation/series/PCF2127.html
00029  *
00030  *  Example:
00031  *  @code
00032  *  #include "mbed.h"
00033  *  #include "PCF2127.h"
00034  *  
00035  *  PCF2127 rtc( p28, p27 );
00036  *  
00037  *  int main()
00038  *  {
00039  *      time_t  t;
00040  *      
00041  *      printf( "PCF2127 demo started.\r\n" );
00042  *  
00043  *      if ( rtc.is_init_required() ) {
00044  *          rtc.set_time( "2014 12 10 12 00 00" );
00045  *      }
00046  *  
00047  *      while ( 1 ) {
00048  *          t   = rtc.time( NULL );
00049  *          printf( "%s\r", ctime( &t ) );
00050  *          wait( 0.25 );
00051  *      }
00052  *  }
00053  *  @endcode
00054  */
00055 
00056 class PCF2127
00057 {
00058 public:
00059 
00060     /** name of the PCF2127 registers */
00061     typedef enum {
00062         Control_1,
00063         Control_2,
00064         Control_3,
00065         Seconds,
00066         Minutes,
00067         Hours,
00068         Days,
00069         Weekdays,
00070         Months,
00071         Years,
00072         Second_alarm,
00073         Minute_alarm,
00074         Hour_alarm,
00075         Day_alarm,
00076         Weekday_alarm,
00077         CLKOUT_ctl,
00078         Watchdg_tim_ctl,
00079         Watchdg_tim_val,
00080         Timestp_ctl,
00081         Sec_timestp,
00082         Min_timestp,
00083         Hour_timestp,
00084         Day_timestp,
00085         Mon_timestp,
00086         Year_timestp,
00087         Aging_offset,
00088         RAM_addr_MSB,
00089         RAM_addr_LSB,
00090         RAM_wrt_cmd,
00091         RAM_rd_cmd
00092     }
00093     RegisterName;
00094 
00095     /** Error code */
00096     typedef enum {
00097         NO_ERROR                = 0,
00098         CLOCK_INTEGRITY_FAIL    = 1,
00099         I2C_ACCESS_FAIL         = 2,
00100         TIME_FUNC_ERROR         = ((time_t)-1)
00101     }
00102     ErrorNum;
00103 
00104     /** Create a PCF2127 instance connected to specified I2C pins with specified address
00105      *
00106      *  @param I2C_sda      I2C-bus SDA pin
00107      *  @param I2C_scl      I2C-bus SCL pin
00108      *  @param vControl_1   (option) data for Control_1 register (default setting generates interrupts by second and minute)
00109      *  @param vControl_2   (option) data for Control_2 register
00110      *  @param vControl_3   (option) data for Control_3 register (default setting of battery switch-over function as standard mode)
00111      *  @param vCLKOUT_ctl  (option) data for CLKOUT_ctl register (default setting 1Hz output on CLKOUT pin)
00112      CLKOUT_ctl
00113      */
00114     PCF2127( PinName sda, PinName sdl, char vControl_1 = Cntl1, char vControl_2 = Cntl2, char vControl_3 = Cntl1, char vCLKOUT_ctl = ClkOut );
00115 
00116     /** Create a PCF2127 instance connected to specified I2C pins with specified address
00117      *
00118      *  @param i2c          I2C object (instance)
00119      *  @param vControl_1   (option) data for Control_1 register (default setting generates interrupts by second and minute)
00120      *  @param vControl_2   (option) data for Control_2 register
00121      *  @param vControl_3   (option) data for Control_3 register (default setting of battery switch-over function as standard mode)
00122      *  @param vCLKOUT_ctl  (option) data for CLKOUT_ctl register (default setting 1Hz output on CLKOUT pin)
00123      */
00124     PCF2127( I2C &i2c, char vControl_1 = Cntl1, char vControl_2 = Cntl2, char vControl_3 = Cntl1, char vCLKOUT_ctl = ClkOut );
00125 
00126     /** Destractor
00127      */
00128     ~PCF2127();
00129 
00130     /** Clock integrity check
00131      *
00132      *  @return     non-zero value if the clock was stopped (means need to set the time)
00133      */
00134     int     is_init_required( void );
00135 
00136     /** Set the time
00137      *
00138      *  @param dtp  Pointer to struct tm
00139      *  @return     Error code (NO_ERROR==0)
00140      */
00141     int     set_time( struct tm *dtp );
00142 
00143     /** Set the time
00144      *
00145      *  @param tp   pointer to time_t
00146      *  @return     Error code (NO_ERROR==0)
00147      */
00148     int     set_time( time_t *tp );
00149 
00150     /** Set the time
00151      *
00152      *  @param s    String data: The time information should be given in format of "YYYY MM DD HH MM SS"
00153      *  @return     Error code (NO_ERROR==0)
00154      */
00155     int     set_time( char *s );
00156 
00157     /** Get time of day
00158      *
00159      *  This function works similar to "time()" in standard-C-library
00160      *
00161      *  @param tp   Pointer to time_t
00162      *  @return     Error code (NO_ERROR==0)
00163      */
00164     time_t  time( time_t *tp );
00165 
00166     /** Register access interface with integer to BCD conversion
00167      *
00168      *  @param addr Register address
00169      *  @param s    Integer data. Converted to BCD before writing inot the register.
00170      *  @return     Error code (NO_ERROR==0)
00171      */
00172     int     set_alarm( char addr, char s );
00173 
00174     /** Clear interrupt flag
00175      *
00176      *  Clears interrupt flags by writing 0x00 into Control_2 register
00177      *
00178      *  @return Error code (NO_ERROR==0)
00179      */
00180     int     clear_intr( void );
00181 
00182     /** Writing data into RAM (for PCF2127 only)
00183      *
00184      *  Write data into PCF2127 internal RAM
00185      *
00186      *  @param address  target address of internal RAM
00187      *  @param *p       pointer to write data buffer
00188      *  @param size     size of writing data
00189      *  @return         Error code (NO_ERROR==0)
00190      */
00191     int     RAM_write( int address, char *p, int size );
00192 
00193     /** Reading data from RAM (for PCF2127 only)
00194      *
00195      *  Read data from PCF2127 internal RAM
00196      *
00197      *  @param address  target address of internal RAM
00198      *  @param *p       pointer to read data buffer
00199      *  @param size     size of writing data
00200      *  @return         Error code (NO_ERROR==0)
00201      */
00202     int     RAM_read( int address, char *p, int size );
00203 
00204 private:
00205 
00206     typedef enum {
00207         Cntl1   = 0x03,
00208         Cntl2   = 0x00,
00209         Cntl3   = 0x00,
00210         ClkOut  = 0x46
00211     }
00212     DefaultRegParam;
00213 
00214     int     init( char vControl_1, char vControl_2, char vControl_3, char vCLKOUT_ctl );
00215     int     set_register( char addr, char data );
00216     int     read_register( char addr );
00217     char    i2bcd( char n );
00218     char    bcd2i( char bcd );
00219     int     set_RAM_address( char address );
00220     
00221     I2C     *i2c_p;
00222     I2C     &i2c;
00223     char    device_address;
00224 }
00225 ;
00226 #endif  // end of "#ifndef MBED_PCF2127"