max3133x.hpp

00001 /*******************************************************************************
00002  * Copyright(C) Analog Devices Inc., All Rights Reserved.
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a
00005  * copy of this software and associated documentation files(the "Software"),
00006  * to deal in the Software without restriction, including without limitation
00007  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00008  * and/or sell copies of the Software, and to permit persons to whom the
00009  * Software is furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included
00012  * in all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00015  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00016  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00017  * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00018  * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00019  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00020  * OTHER DEALINGS IN THE SOFTWARE.
00021  *
00022  * Except as contained in this notice, the name of Analog Devices Inc.
00023  * shall not be used except as stated in the Analog Devices Inc.
00024  * Branding Policy.
00025  *
00026  * The mere transfer of this software does not imply any licenses
00027  * of trade secrets, proprietary technology, copyrights, patents,
00028  * trademarks, maskwork rights, or any other form of intellectual
00029  * property whatsoever. Analog Devices Inc.retains all ownership rights.
00030  *******************************************************************************
00031  */
00032 
00033 #ifndef MAX3133X_HPP_
00034 #define MAX3133X_HPP_
00035 
00036 #include "mbed.h"
00037 #include "rtos.h"
00038 #include "max3133x_regs.hpp"
00039 
00040 #define MAX3133X_I2C_ADDRESS        0x68
00041 #define MAX3133X_I2C_W              (MAX3133X_I2C_ADDRESS << 1)
00042 #define MAX3133X_I2C_R              ((MAX3133X_I2C_ADDRESS << 1) | 1)
00043 
00044 enum max3133x_error_codes {
00045     MAX3133X_NO_ERR,
00046     MAX3133X_NULL_VALUE_ERR   = -1,
00047     MAX3133X_READ_REG_ERR     = -2,
00048     MAX3133X_WRITE_REG_ERR    = -3,
00049     MAX3133X_INVALID_TIME_ERR = -4,
00050     MAX3133X_INVALID_DATE_ERR = -5,
00051     MAX3133X_INVALID_MASK_ERR = -6,
00052     MAX3133X_INVALID_ALARM_PERIOD_ERR       = -7,
00053     MAX3133X_ALARM_ONETIME_NOT_SUPP_ERR     = -8,
00054     MAX3133X_ALARM_YEARLY_NOT_SUPP_ERR      = -9,
00055     MAX3133X_ALARM_EVERYMINUTE_NOT_SUPP_ERR = -10,
00056     MAX3133X_ALARM_EVERYSECOND_NOT_SUPP_ERR = -11
00057 };
00058 
00059 class MAX3133X
00060 {
00061 public:
00062     /* PUBLIC FUNCTION DECLARATIONS */
00063  
00064     /**
00065     * @brief        Read from a register.
00066     *
00067     * @param[in]    reg Address of a register to be read.
00068     * @param[out]   value Pointer to save result value.
00069     * @param[in]    len Size of result to be read.
00070     *
00071     * @returns      MAX3133X_NO_ERR on success, error code on failure.
00072     */
00073     int read_register(uint8_t reg, uint8_t *value, uint8_t len);
00074  
00075     /**
00076     * @brief        Write to a register.
00077     *
00078     * @param[in]    reg Address of a register to be written.
00079     * @param[out]   value Pointer of value to be written to register.
00080     * @param[in]    len Size of result to be written.
00081     *
00082     * @returns      MAX3133X_NO_ERR on success, error code on failure.
00083     */
00084     int write_register(uint8_t reg, const uint8_t *value, uint8_t len);
00085 
00086     /**
00087     * @brief        Read time info from RTC.
00088     *
00089     * @param[out]   rtc_ctime Time info from RTC.
00090     *
00091     * @returns      MAX3133X_NO_ERR on success, error code on failure.
00092     */
00093     int get_time(struct tm *rtc_ctime, uint16_t *sub_sec = NULL);
00094 
00095     /**
00096     * @brief        Selection of 24hr-12hr hour format
00097     */
00098     typedef enum {
00099         HOUR24 = 0,     /**< 24-Hour format */
00100         HOUR12 = 1,     /**< 12-Hour format */
00101     }hour_format_t;
00102 
00103     /**
00104     * @brief        Set time info to RTC.
00105     *
00106     * @param[in]    rtc_ctime Time info to be written to RTC.
00107     *
00108     * @returns      MAX3133X_NO_ERR on success, error code on failure.
00109     */
00110     int set_time(const struct tm *rtc_ctime, hour_format_t format = HOUR24);
00111 
00112     /**
00113     * @brief        Alarm periodicity selection
00114     */
00115     typedef enum {
00116         ALARM_PERIOD_EVERYSECOND,    /**< Once a second */
00117         ALARM_PERIOD_EVERYMINUTE,    /**< Seconds match */
00118         ALARM_PERIOD_HOURLY,         /**< Seconds and Minutes match */
00119         ALARM_PERIOD_DAILY,          /**< Hours, Minutes and Seconds match*/
00120         ALARM_PERIOD_WEEKLY,         /**< Day and Time match */
00121         ALARM_PERIOD_MONTHLY,        /**< Date and Time match */
00122         ALARM_PERIOD_YEARLY,         /**< Month, Date and Time match */
00123         ALARM_PERIOD_ONETIME,        /**< Year, Month, Date and Time match */
00124     }alarm_period_t;
00125 
00126     /**
00127     * @brief        Alarm number selection
00128     */
00129     typedef enum {
00130         ALARM1, /**< Alarm number 1 */
00131         ALARM2, /**< Alarm number 2 */
00132     }alarm_no_t;
00133 
00134     /**
00135     * @brief        Set an alarm condition
00136     *
00137     * @param[in]    alarm_no Alarm number, ALARM1 or ALARM2
00138     * @param[in]    alarm_time Pointer to alarm time to be set
00139     * @param[in]    period Alarm periodicity, one of ALARM_PERIOD_*
00140     *
00141     * @return       MAX3133X_NO_ERR on success, error code on failure
00142     */
00143     int set_alarm(alarm_no_t alarm_no, const struct tm *alarm_time, alarm_period_t period);
00144 
00145     /**
00146     * @brief        Get alarm data & time
00147     *
00148     * @param[in]    alarm_no Alarm number, ALARM1 or ALARM2
00149     * @param[out]   alarm_time Pointer to alarm time to be filled in
00150     * @param[out]   period Pointer to the period of alarm, one of ALARM_PERIOD_*
00151     * @param[out]   is_enabled Pointer to the state of alarm
00152     *
00153     * @return       MAX3133X_NO_ERR on success, error code on failure
00154     */
00155     int get_alarm(alarm_no_t alarm_no, struct tm *alarm_time, alarm_period_t *period, bool *is_enabled);
00156 
00157     /**
00158      * @brief       Gets Status Register Value
00159      *
00160      * @param[in]   status_reg
00161      *
00162      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00163      */
00164     int get_status_reg(max3133x_status_reg_t * status_reg);
00165 
00166     /**
00167      * @brief       Gets Interrupt Enable Register Value
00168      *
00169      * @param[in]   int_en_reg
00170      *
00171      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00172      */
00173     int get_interrupt_reg(max3133x_int_en_reg_t * int_en_reg);
00174 
00175     /**
00176     * @brief        Selection of interrupt ids
00177     */
00178     typedef enum {
00179         INTR_ID_A1IE,       /**< Alarm1 interrupt flag */
00180         INTR_ID_A2IE,       /**< Alarm2 interrupt flag */
00181         INTR_ID_TIE,        /**< Timer interrupt flag */
00182         INTR_ID_DIE,        /**< Digital (DIN) interrupt flag */
00183         INTR_ID_VBATLOWIE,  /**< VBAT Low Interrupt enable */
00184         INTR_ID_PFAILE      /**< Power fail Interrupt flag */
00185     }intr_id_t;
00186 
00187     /*Interrupt Enable Register Masks*/
00188     #define A1IE        0b00000001  /*Alarm1 interrupt mask*/
00189     #define A2IE        0b00000010  /*Alarm2 interrupt mask*/
00190     #define TIE         0b00000100  /*Timer interrupt mask*/
00191     #define DIE         0b00001000  /*Digital (DIN) interrupt mask*/
00192     #define VBATLOWIE   0b00010000  /*VBAT Low Interrupt mask*/
00193     #define PFAILE      0b00100000  /*Power fail Interrupt mask*/
00194     #define DOSF        0b01000000  /*Disable oscillator flag*/
00195     #define INT_ALL     0b00111111  /*All Interrupts*/
00196     #define NUM_OF_INTR_ID  6       /*Number of Interrupt IDs*/
00197 
00198     /**
00199      * @brief       Enables Interrupts
00200      *
00201      * @param[in]   mask
00202      *
00203      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00204      */
00205     int interrupt_enable(uint8_t mask);
00206 
00207     /**
00208      * @brief       Disables Interrupts
00209      *
00210      * @param[in]   mask
00211      *
00212      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00213      */
00214     int interrupt_disable(uint8_t mask);
00215 
00216     /**
00217     * @brief        Put device into reset state
00218     *
00219     * @return       MAX3133X_NO_ERR on success, error code on failure
00220     */
00221     int sw_reset_assert();
00222 
00223     /**
00224     * @brief        Release device from state state
00225     *
00226     * @return       MAX3133X_NO_ERR on success, error code on failure
00227     */
00228     int sw_reset_release();
00229 
00230     /**
00231      * @brief       Resets the digital block and the I2C programmable registers except for RAM registers and RTC_reset.
00232      *
00233      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00234      */
00235     int sw_reset();
00236 
00237     /**
00238      * @brief Data retention mode enable/disable Configuration
00239      *
00240      * @details
00241      *  - Register      : RTC_CONFIG1
00242      *  - Bit Fields    : [2]
00243      *  - Default       : 0x0
00244      *  - Description   : Data retention mode enable/disable.
00245      */
00246     typedef enum {
00247         NORMAL_OP_MODE,
00248         DATA_RETENTION_MODE
00249     }data_ret_t;
00250 
00251     /**
00252      * @brief I2C timeout enable Configuration
00253      *
00254      * @details
00255      *  - Register      : RTC_CONFIG1
00256      *  - Bit Fields    : [1]
00257      *  - Default       : 0x1
00258      *  - Description   : I2C timeout enable
00259      */
00260     typedef enum {
00261         DISABLE_I2C_TIMEOUT,
00262         ENABLE_I2C_TIMEOUT
00263     }i2c_timeout_t;
00264 
00265     /**
00266      * @brief Active-high enable for the crystal oscillator Configuration
00267      *
00268      * @details
00269      *  - Register      : RTC_CONFIG1
00270      *  - Bit Fields    : [0]
00271      *  - Default       : 0x1
00272      *  - Description   : Active-high enable for the crystal oscillator
00273      */
00274     typedef enum {
00275         DISABLE_OSCILLATOR,
00276         ENABLE_OSCILLATOR
00277     }en_osc_t;
00278 
00279     /**
00280      * @brief Digital (DIN) pin Sleep Entry Enable Configuration
00281      *
00282      * @details
00283      *  - Register      : RTC_CONFIG2
00284      *  - Bit Fields    : [4]
00285      *  - Default       : 0x0
00286      *  - Description   : Digital (DIN) pin Sleep Entry Enable
00287      */
00288     typedef enum {
00289         DIN_SLEEP_ENTRY_DISABLE,
00290         DIN_SLEEP_ENTRY_ENABLE
00291     }dse_t;
00292 
00293     /**
00294      * @brief Digital (DIN) pin Debounce Enable Configuration
00295      *
00296      * @details
00297      *  - Register      : RTC_CONFIG2
00298      *  - Bit Fields    : [3]
00299      *  - Default       : 0x0
00300      *  - Description   : Digital (DIN) pin Debounce Enable
00301      */
00302     typedef enum {
00303         DIN_DEBOUNCE_DISABLE,
00304         DIN_DEBOUNCE_ENABLE
00305     }ddb_t;
00306 
00307     /**
00308      * @brief CLKOUT enable Configuration
00309      *
00310      * @details
00311      *  - Register      : RTC_CONFIG2
00312      *  - Bit Fields    : [2]
00313      *  - Default       : 0x0
00314      *  - Description   : CLKOUT enable
00315      */
00316     typedef enum {
00317         INTERRUPT,
00318         CLOCK_OUTPUT
00319     }enclko_t;
00320 
00321     /**
00322      * @brief Register Configuration
00323      *
00324      * @details
00325      *  - Register      : RTC_CONFIG1
00326      *  - Bit Fields    : [5:4]
00327      *  - Default       : 0x0
00328      *  - Description   : Alarm1 Auto Clear
00329      */
00330     typedef enum {
00331         BY_READING,     /**< 0x0: Alarm1 flag and interrupt can only be cleared by reading Status register via I2C */
00332         AFTER_10MS,     /**< 0x1: Alarm1 flag and interrupt are cleared ~10ms after assertion */
00333         AFTER_500MS,    /**< 0x2: Alarm1 flag and interrupt are cleared ~500ms after assertion */
00334         AFTER_5s        /**< 0x3: Alarm1 flag and interrupt are cleared ~5s after assertion. This option should not be used when Alarm1 is set to OncePerSec. */
00335     }a1ac_t;
00336 
00337     /**
00338      * @brief       Sets Alarm1 Auto Clear Mode
00339      *
00340      * @param[in]   a1ac A1AC bits.
00341      *
00342      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00343      */
00344     int set_alarm1_auto_clear(a1ac_t a1ac);
00345 
00346     /**
00347      * @brief Digital (DIN) interrupt polarity configuration
00348      *
00349      * @details
00350      *  - Register      : RTC_CONFIG1
00351      *  - Bit Fields    : [3]
00352      *  - Default       : 0x0
00353      *  - Description   : Digital (DIN) interrupt polarity
00354      */
00355     typedef enum {
00356         FALLING_EDGE,   /**< 0x0: Interrupt triggers on falling edge of DIN input. */
00357         RISING_EDGE     /**< 0x1: Interrupt triggers on rising edge of DIN input. */
00358     }dip_t;
00359 
00360     /**
00361      * @brief       Digital (DIN) interrupt polarity
00362      *
00363      * @param[in]   dip
00364      *
00365      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00366      */
00367     int set_din_polarity(dip_t dip);
00368 
00369     /**
00370     * @brief    Put device into data retention mode
00371     *
00372     * @return   MAX3133X_NO_ERR on success, error code on failure
00373     */
00374     int data_retention_mode_enter();
00375 
00376     /**
00377     * @brief    Remove device from data retention mode
00378     *
00379     * @return   MAX3133X_NO_ERR on success, error code on failure
00380     */
00381     int data_retention_mode_exit();
00382 
00383     /**
00384     * @brief    Enable I2C timeout
00385     *
00386     * @return   MAX3133X_NO_ERR on success, error code on failure
00387     */
00388     int i2c_timeout_enable();
00389 
00390     /**
00391     * @brief    Disable I2C timeout
00392     *
00393     * @return   MAX3133X_NO_ERR on success, error code on failure
00394     */
00395     int i2c_timeout_disable();
00396 
00397     /**
00398     * @brief    Enable the crystal oscillator.
00399     *
00400     * @return   MAX3133X_NO_ERR on success, error code on failure
00401     */
00402     int oscillator_enable();
00403 
00404     /**
00405     * @brief    Disable the crystal oscillator.
00406     *
00407     * @return   MAX3133X_NO_ERR on success, error code on failure
00408     */
00409     int oscillator_disable();
00410 
00411     /**
00412     * @brief    Enable the CLKOUT. Sets INTBb/CLKOUT pin as CLKO (clock output).
00413     *
00414     * @return   MAX3133X_NO_ERR on success, error code on failure
00415     */
00416     int clkout_enable();
00417 
00418     /**
00419     * @brief    Disable the CLKOUT. Sets INTBb/CLKOUT pin as INTBb (interrupt).
00420     *
00421     * @return   MAX3133X_NO_ERR on success, error code on failure
00422     */
00423     int clkout_disable();
00424 
00425     /**
00426      * @brief Set output clock frequency on INTBb/CLKOUT pin Configuration
00427      *
00428      * @details
00429      *  - Register      : RTC_CONFIG2
00430      *  - Bit Fields    : [1:0]
00431      *  - Default       : 0x3
00432      *  - Description   : Output clock frequency on INTBb/CLKOUT pin
00433      */
00434     typedef enum {
00435         CLKOUT_1HZ,
00436         CLKOUT_64HZ,
00437         CLKOUT_1024KHZ,
00438         CLKOUT_32KHZ_UNCOMP
00439     }clko_hz_t;
00440 
00441     /**
00442      * @brief       Set output clock frequency on INTBb/CLKOUT pin
00443      *
00444      * @param[in]   clko_hz
00445      *
00446      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00447      */
00448     int set_clko_freq(clko_hz_t    clko_hz);
00449 
00450     /**
00451      * @brief       Get output clock frequency on INTBb/CLKOUT pin
00452      *
00453      * @param[out]  clko_hz
00454      *
00455      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00456      */
00457     int get_clko_freq(clko_hz_t    *clko_hz);
00458 
00459     /**
00460      * @brief   Enable the Timestamp Function
00461      *
00462      * @returns MAX3133X_NO_ERR on success, error code on failure.
00463      */
00464     int timestamp_function_enable();
00465 
00466     /**
00467      * @brief   Disable the Timestamp Function
00468      *
00469      * @returns MAX3133X_NO_ERR on success, error code on failure.
00470      */
00471     int timestamp_function_disable();
00472 
00473     /**
00474      * @brief   All Timestamp registers are reset to 0x00. If the Timestamp Function is Enabled, timestamp recording will start again.
00475      *
00476      * @returns MAX3133X_NO_ERR on success, error code on failure.
00477      */
00478     int timestamp_registers_reset();
00479 
00480     /**
00481     * @brief    Enable Timestamp Overwrite mode
00482     *
00483     * @details  More than 4 timestamps are recorded by overwriting oldest timestamp. Latest timestamp is always stored in the TS0 bank; earliest timestamp will be stored in the TS3 bank.
00484     *
00485     * @return   MAX3133X_NO_ERR on success, error code on failure
00486     */
00487     int timestamp_overwrite_enable();
00488 
00489     /**
00490     * @brief    Disable Timestamp Overwrite mode
00491     *
00492     * @details  Timestamps are recorded (TS0 -> .. -> TS3). Latest timestamp is always stored in the TS0 bank. Further TS trigger events do not record timestamps.
00493     *
00494     * @return   MAX3133X_NO_ERR on success, error code on failure
00495     */
00496     int timestamp_overwrite_disable();
00497 
00498     /*Timestamp Config Register Masks*/
00499     #define TSVLOW       0b00100000  /*Record Timestamp on VBATLOW detection */
00500     #define TSPWM        0b00010000  /*Record Timestamp on power supply switch (VCC <-> VBAT)*/
00501     #define TSDIN        0b00001000  /*Record Timestamp on DIN transition. Polarity controlled by DIP bitfield in RTC_Config1 register.*/
00502 
00503     /**
00504      * @brief       Enable Timestamp Records
00505      *
00506      * @param[in]   record_enable_mask one or more of TS*
00507      *
00508      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00509      */
00510     int timestamp_record_enable(uint8_t record_enable_mask);
00511 
00512     /**
00513      * @brief       Disable Timestamp Records
00514      *
00515      * @param[in]   record_disable_mask one or more of TS*
00516      *
00517      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00518      */
00519     int timestamp_record_disable(uint8_t record_disable_mask);
00520 
00521     /**
00522      * @brief Timer frequency selection Configuration
00523      *
00524      * @details
00525      *  - Register      : TIMER_CONFIG
00526      *  - Bit Fields    : [1:0]
00527      *  - Default       : 0x0
00528      *  - Description   : Timer frequency selection
00529      */
00530     typedef enum {
00531         TIMER_FREQ_1024HZ,  /**< 1024Hz */
00532         TIMER_FREQ_256HZ,   /**< 256Hz */
00533         TIMER_FREQ_64HZ,    /**< 64Hz */
00534         TIMER_FREQ_16HZ,    /**< 16Hz */
00535     }timer_freq_t;
00536 
00537     /**
00538     * @brief    Enable timer
00539     *
00540     * @return   MAX3133X_NO_ERR on success, error code on failure
00541     */
00542     int timer_start();
00543 
00544     /**
00545     * @brief    Pause timer, timer value is preserved
00546     *
00547     * @return   MAX3133X_NO_ERR on success, error code on failure
00548     */
00549     int timer_pause();
00550 
00551     /**
00552     * @brief    Start timer from the paused value
00553     *
00554     * @return   MAX3133X_NO_ERR on success, error code on failure
00555     */
00556     int timer_continue();
00557 
00558     /**
00559     * @brief    Disable timer
00560     *
00561     * @return   MAX3133X_NO_ERR on success, error code on failure
00562     */
00563     int timer_stop();
00564 
00565     /**
00566     * @brief    Turn-on the Battery Voltage Detector Function
00567     *
00568     * @return   MAX3133X_NO_ERR on success, error code on failure
00569     */
00570     int battery_voltage_detector_enable();
00571 
00572     /**
00573     * @brief    Turn-off the Battery Voltage Detector Function
00574     *
00575     * @return   MAX3133X_NO_ERR on success, error code on failure
00576     */
00577     int battery_voltage_detector_disable();
00578 
00579     /**
00580     * @brief    Supply voltage select.
00581     */
00582     typedef enum {
00583         POW_MGMT_SUPPLY_SEL_AUTO,   /**< Circuit decides whether to use VCC or VBACKUP */
00584         POW_MGMT_SUPPLY_SEL_VCC,    /**< Use VCC as supply */
00585         POW_MGMT_SUPPLY_SEL_VBAT,   /**< Use VBAT as supply */
00586     }power_mgmt_supply_t;
00587 
00588     /**
00589     * @brief        Select device power source
00590     *
00591     * @param[in]    supply Supply selection, one of POW_MGMT_SUPPLY_SEL_*
00592     *
00593     * @return       MAX3133X_NO_ERR on success, error code on failure
00594     */
00595     int supply_select(power_mgmt_supply_t supply);
00596 
00597     /**
00598     * @brief    Selection of charging path's resistor value
00599     */
00600     typedef enum {
00601         TRICKLE_CHARGER_3K,     /**< 3000 Ohm */
00602         TRICKLE_CHARGER_3K_2,   /**< 3000 Ohm */
00603         TRICKLE_CHARGER_6K,     /**< 6000 Ohm */
00604         TRICKLE_CHARGER_11K,    /**< 11000 Ohm */
00605     }trickle_charger_ohm_t;
00606 
00607     /**
00608     * @brief        Configure trickle charger charging path, also enable it
00609     *
00610     * @param[in]    res Value of resistor
00611     * @param[in]    diode Enable diode
00612     *
00613     * @return       MAX3133X_NO_ERR on success, error code on failure
00614     */
00615     int trickle_charger_enable(trickle_charger_ohm_t res, bool diode);
00616 
00617     /**
00618     * @brief        Disable Trickle Charger
00619     *
00620     * @return       MAX3133X_NO_ERR on success, error code on failure
00621     */
00622     int trickle_charger_disable();
00623 
00624     /**
00625     * @brief    Selection of Timestamp
00626     */
00627     typedef enum {
00628         TS0,        /**< Timestamp 0 */
00629         TS1,        /**< Timestamp 1 */
00630         TS2,        /**< Timestamp 2 */
00631         TS3,        /**< Timestamp 3 */
00632         NUM_OF_TS   /**< Number of Timestamps */
00633     }ts_num_t;
00634 
00635     /**
00636     * @brief    Timestamp Triggers
00637     */
00638     typedef enum {
00639         NOT_TRIGGERED,      /**< Not Triggered */
00640         DINF,               /**< triggered by DIN transition */
00641         VCCF,               /**< triggered by VBAT -> VCC switch */
00642         VBATF,              /**< triggered by VCC -> VBAT switch */
00643         VLOWF,              /**< triggered by VLOW detection */
00644         NUM_OF_TRIG         /**< Number of Triggers */
00645     }ts_trigger_t;
00646 
00647     typedef struct {
00648         ts_num_t     ts_num;
00649         ts_trigger_t ts_trigger;
00650         uint16_t     sub_sec;
00651         struct tm    ctime;
00652     }timestamp_t;
00653 
00654     /**
00655     * @brief        Read Timestamp info.
00656     *
00657     * @param[in]    ts_num Timestamp number.
00658     * @param[out]   timestamp Time info.
00659     *
00660     * @returns      MAX3133X_NO_ERR on success, error code on failure.
00661     */
00662     int get_timestamp(int ts_num, timestamp_t *timestamp);
00663 
00664     /**
00665     * @brief        correct the clock accuracy on your board. refer the datasheet for additional informations
00666     *
00667     * @param[in]    meas Timestamp number.
00668     *
00669     * @returns      MAX3133X_NO_ERR on success, error code on failure.
00670     */
00671     int offset_configuration(int meas);
00672 
00673     /**
00674      * @brief       Allow the OSF to indicate the oscillator status.
00675      *
00676      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00677      */
00678     int oscillator_flag_enable();
00679 
00680     /**
00681      * @brief       Disable the oscillator flag, irrespective of the oscillator status
00682      *
00683      * @returns     MAX3133X_NO_ERR on success, error code on failure.
00684      */
00685     int oscillator_flag_disable();
00686 
00687     /**
00688     * @brief        Function pointer type to interrupt handler function
00689     */
00690     typedef void (*interrupt_handler_function)(void *);
00691 
00692     /**
00693     * @brief        Set interrupt handler for a specific interrupt id
00694     *
00695     * @param[in]    id Interrupt id, one of INTR_ID_*
00696     * @param[in]    func Interrupt handler function
00697     * @param[in]    cb Interrupt handler data
00698     */
00699     void set_intr_handler(intr_id_t id, interrupt_handler_function func, void *cb);
00700 
00701 protected:
00702 
00703     typedef struct {
00704         uint8_t     status_reg_addr;
00705         uint8_t     int_en_reg_addr;
00706         uint8_t     rtc_reset_reg_addr;
00707         uint8_t     rtc_config1_reg_addr;
00708         uint8_t     rtc_config2_reg_addr;
00709         uint8_t     timestamp_config_reg_addr;
00710         uint8_t     timer_config_reg_addr;
00711         uint8_t     sleep_config_reg_addr;
00712         uint8_t     seconds_1_128_reg_addr;
00713         uint8_t     seconds_reg_addr;
00714         uint8_t     minutes_reg_addr;
00715         uint8_t     hours_reg_addr;
00716         uint8_t     day_reg_addr;
00717         uint8_t     date_reg_addr;
00718         uint8_t     month_reg_addr;
00719         uint8_t     year_reg_addr;
00720         uint8_t     alm1_sec_reg_addr;
00721         uint8_t     alm1_min_reg_addr;
00722         uint8_t     alm1_hrs_reg_addr;
00723         uint8_t     alm1_day_date_reg_addr;
00724         uint8_t     alm1_mon_reg_addr;
00725         uint8_t     alm1_year_reg_addr;
00726         uint8_t     alm2_min_reg_addr;
00727         uint8_t     alm2_hrs_reg_addr;
00728         uint8_t     alm2_day_date_reg_addr;
00729         uint8_t     timer_count_reg_addr;
00730         uint8_t     timer_count2_reg_addr;
00731         uint8_t     timer_count1_reg_addr;
00732         uint8_t     timer_init_reg_addr;
00733         uint8_t     timer_init2_reg_addr;
00734         uint8_t     timer_init1_reg_addr;
00735         uint8_t     pwr_mgmt_reg_addr;
00736         uint8_t     trickle_reg_addr;
00737         uint8_t     offset_high_reg_addr;
00738         uint8_t     offset_low_reg_addr;
00739         uint8_t     ts0_sec_1_128_reg_addr;
00740         uint8_t     ts0_sec_reg_addr;
00741         uint8_t     ts0_min_reg_addr;
00742         uint8_t     ts0_hour_reg_addr;
00743         uint8_t     ts0_date_reg_addr;
00744         uint8_t     ts0_month_reg_addr;
00745         uint8_t     ts0_year_reg_addr;
00746         uint8_t     ts0_flags_reg_addr;
00747         uint8_t     ts1_sec_1_128_reg_addr;
00748         uint8_t     ts1_sec_reg_addr;
00749         uint8_t     ts1_min_reg_addr;
00750         uint8_t     ts1_hour_reg_addr;
00751         uint8_t     ts1_date_reg_addr;
00752         uint8_t     ts1_month_reg_addr;
00753         uint8_t     ts1_year_reg_addr;
00754         uint8_t     ts1_flags_reg_addr;
00755         uint8_t     ts2_sec_1_128_reg_addr;
00756         uint8_t     ts2_sec_reg_addr;
00757         uint8_t     ts2_min_reg_addr;
00758         uint8_t     ts2_hour_reg_addr;
00759         uint8_t     ts2_date_reg_addr;
00760         uint8_t     ts2_month_reg_addr;
00761         uint8_t     ts2_year_reg_addr;
00762         uint8_t     ts2_flags_reg_addr;
00763         uint8_t     ts3_sec_1_128_reg_addr;
00764         uint8_t     ts3_sec_reg_addr;
00765         uint8_t     ts3_min_reg_addr;
00766         uint8_t     ts3_hour_reg_addr;
00767         uint8_t     ts3_date_reg_addr;
00768         uint8_t     ts3_month_reg_addr;
00769         uint8_t     ts3_year_reg_addr;
00770         uint8_t     ts3_flags_reg_addr;
00771     }reg_addr_t;
00772 
00773     /* Constructors */
00774     MAX3133X(const reg_addr_t *reg_addr, I2C *i2c, PinName inta_pin = NC, PinName intb_pin = NC);
00775 
00776 private:
00777     /* PRIVATE TYPE DECLARATIONS */
00778 
00779     /* PRIVATE VARIABLE DECLARATIONS */
00780     I2C *i2c_handler;
00781     InterruptIn *inta_pin;
00782     InterruptIn *intb_pin;
00783 
00784     /* PRIVATE CONSTANT VARIABLE DECLARATIONS */
00785     const reg_addr_t *reg_addr;
00786 
00787     /* PRIVATE FUNCTION DECLARATIONS */
00788     void rtc_regs_to_time(struct tm *time, const max3133x_rtc_time_regs_t *regs, uint16_t *sub_sec);
00789 
00790     int time_to_rtc_regs(max3133x_rtc_time_regs_t *regs, const struct tm *time, hour_format_t format);
00791 
00792     void timestamp_regs_to_time(timestamp_t *timestamp, const max3133x_ts_regs_t *timestamp_reg);
00793 
00794     int time_to_alarm_regs(max3133x_alarm_regs_t &regs, const struct tm *alarm_time, hour_format_t format);
00795 
00796     void alarm_regs_to_time(alarm_no_t alarm_no, struct tm *alarm_time, const max3133x_alarm_regs_t *regs, hour_format_t format);
00797 
00798     int set_alarm_period(alarm_no_t alarm_no, max3133x_alarm_regs_t &regs, alarm_period_t period);
00799 
00800     int set_alarm_regs(alarm_no_t alarm_no, const max3133x_alarm_regs_t *regs);
00801 
00802     uint8_t to_24hr(uint8_t hr, uint8_t pm);
00803 
00804     void to_12hr(uint8_t hr, uint8_t *hr_12, uint8_t *pm);
00805 
00806     int get_rtc_time_format(hour_format_t *format);
00807 
00808     int data_retention_mode_config(bool enable);
00809 
00810     int battery_voltage_detector_config(bool enable);
00811 
00812     int clkout_config(bool enable);
00813 
00814     int i2c_timeout_config(bool enable);
00815 
00816     int oscillator_config(bool enable);
00817 
00818     int timestamp_overwrite_config(bool enable);
00819 
00820     int oscillator_flag_config(bool enable);
00821 
00822     /**
00823     * @brief    Interrupt handler function
00824     */
00825     void interrupt_handler();
00826 
00827     /**
00828     * @brief    Post interrupt jobs after interrupt is detected.
00829     */
00830     void post_interrupt_work();
00831 
00832     Thread *post_intr_work_thread;
00833 
00834     struct handler {
00835         void (*func)(void *);
00836         void *cb;
00837     };
00838 
00839     handler interrupt_handler_list[NUM_OF_INTR_ID];
00840 };
00841 
00842 /** MAX31334 Device Class
00843 *
00844 * Hold configurations for the MAX31334
00845 */
00846 class MAX31334 : public MAX3133X
00847 {
00848 private:
00849     static const reg_addr_t reg_addr;
00850 
00851     int din_sleep_entry_config(bool enable);
00852 
00853     int din_pin_debounce_config(bool enable);
00854 
00855 public:
00856     typedef struct {
00857         a1ac_t          a1ac;       /*RTC_CONFIG1 - Alarm1 Auto Clear */
00858         dip_t           dip;        /*RTC_CONFIG1 - Digital (DIN) interrupt polarity */
00859         data_ret_t      data_ret;   /*RTC_CONFIG1 - Data retention mode enable/disable. */
00860         i2c_timeout_t   i2c_timeout;/*RTC_CONFIG1 - I2C timeout enable */
00861         en_osc_t        en_osc;     /*RTC_CONFIG1 - Active-high enable for the crystal oscillator */
00862         dse_t           dse;        /*RTC_CONFIG2 - Digital (DIN) pin Sleep Entry Enable */
00863         ddb_t           ddb;        /*RTC_CONFIG2 - Digital (DIN) pin Debounce Enable */
00864         enclko_t        enclko;     /*RTC_CONFIG2 - CLKOUT enable */
00865         clko_hz_t       clko_hz;    /*RTC_CONFIG2 - Set output clock frequency on INTBb/CLKOUT pin */
00866     }rtc_config_t;
00867 
00868     /**
00869     * @brief        Configure the device
00870     *
00871     * @param[in]    max31334_config Device configuration
00872     *
00873     * @return       MAX3133X_NO_ERR on success, error code on failure
00874     *
00875     * @note         RTC_CONFIG1 and RTC_CONFIG2 registers are set.
00876     */
00877     int rtc_config(rtc_config_t *max31334_config);
00878 
00879     /**
00880     * @brief        Get device configuration
00881     *
00882     * @param[out]   max31334_config Device configuration
00883     *
00884     * @return       MAX3133X_NO_ERR on success, error code on failure
00885     *
00886     * @note         RTC_CONFIG1 and RTC_CONFIG2 register values are read.
00887     */
00888     int get_rtc_config(rtc_config_t *max31334_config);
00889 
00890     /**
00891     * @brief        Initialize timer
00892     *
00893     * @param[in]    init_val Timer initial value
00894     * @param[in]    repeat Timer repeat mode enable/disable
00895     * @param[in]    freq Timer frequency, one of TIMER_FREQ_*
00896     *
00897     * @return       MAX3133X_NO_ERR on success, error code on failure
00898     */
00899     int timer_init(uint16_t init_val, bool repeat, timer_freq_t freq);
00900 
00901     /**
00902     * @brief    Read timer value
00903     *
00904     * @return   timer value on success, error code on failure
00905     */
00906     int timer_get();
00907 
00908     /**
00909     * @brief    Get Sleep State
00910     *
00911     * @return   Sleep State. 0: SLST=0 indicates the PSW SM is not in Sleep state,
00912     *                        1: SLST=1 indicates the PSW SM is in Sleep state.
00913     *                 negative: on failure
00914     */
00915     int get_sleep_state();
00916 
00917     /**
00918     * @brief    Enable the Digital (DIN) pin Sleep Entry
00919     *
00920     * @details  DIN pin can be used to enter sleep state.
00921     *
00922     * @return   MAX3133X_NO_ERR on success, error code on failure
00923     */
00924     int din_sleep_entry_enable();
00925 
00926     /**
00927     * @brief    Disable the Digital (DIN) pin Sleep Entry
00928     *
00929     * @details  DIN pin cannot be used to enter sleep state (Sleep state entry is only possible by writing SLP=1 over I2C).
00930     *
00931     * @return   MAX3133X_NO_ERR on success, error code on failure
00932     */
00933     int din_sleep_entry_disable();
00934 
00935     /**
00936     * @brief    Enable the Digital (DIN) pin Debounce function
00937     *
00938     * @details  50ms debounce on DIN pin enabled.
00939     *
00940     * @return   MAX3133X_NO_ERR on success, error code on failure
00941     */
00942     int din_pin_debounce_enable();
00943 
00944     /**
00945     * @brief    Disable the Digital (DIN) pin Debounce function
00946     *
00947     * @details  No debounce on DIN pin.
00948     *
00949     * @return   MAX3133X_NO_ERR on success, error code on failure
00950     */
00951     int din_pin_debounce_disable();
00952 
00953     /**
00954     * @brief    Put PSW SM into Active state.
00955     *
00956     * @return   MAX3133X_NO_ERR on success, error code on failure
00957     */
00958     int sleep_enter();
00959 
00960     /**
00961     * @brief    Put PSW SM into Sleep state.
00962     *
00963     * @return   MAX3133X_NO_ERR on success, error code on failure
00964     */
00965     int sleep_exit();
00966 
00967     /**
00968      * @brief Register Configuration
00969      *
00970      * @details
00971      *  - Register      : SLEEP_CONFIG
00972      *  - Bit Fields    : [6:4]
00973      *  - Default       : 0x0
00974      *  - Description   : Wait State Timeout. This bitfield must be set before writing SLP=1 if a finite wait state duration is
00975      *                    desired before entering the sleep state.
00976      */
00977     typedef enum {
00978         WSTO_0MS,    /**< 0ms */
00979         WSTO_8MS,    /**< 8ms */
00980         WSTO_16MS,    /**< 16ms */
00981         WSTO_24MS,    /**< 24ms */
00982         WSTO_32MS,    /**< 32ms */
00983         WSTO_40MS,    /**< 40ms */
00984         WSTO_48MS,    /**< 48ms */
00985         WSTO_56MS    /**< 56ms */
00986     }wsto_t;
00987 
00988     /**
00989     * @brief       Set Wait State Timeout
00990     *
00991     * @param[in]   wsto Wait State Timeout
00992     *
00993     * @return      MAX3133X_NO_ERR on success, error code on failure
00994     */
00995     int set_wait_state_timeout(wsto_t wsto);
00996 
00997     /**
00998     * @brief        Get Wait State Timeout
00999     *
01000     * @param[out]   wsto Wait State Timeout
01001     *
01002     * @return       MAX3133X_NO_ERR on success, error code on failure
01003     */
01004     int get_wait_state_timeout(wsto_t* wsto);
01005 
01006     /*Sleep Config Register Masks*/
01007     #define A1WE      0b00000001  /*Alarm1 Wakeup Enable */
01008     #define A2WE      0b00000010  /*Alarm2 Wakeup Enable */
01009     #define TWE       0b00000100  /*Timer Wakeup Enable */
01010     #define DWE       0b00001000  /*DIN Wakeup Enable */
01011 
01012     /**
01013      * @brief       Enable Wakeup
01014      *
01015      * @param[in]   wakeup_enable_mask one or more of Sleep Config Register Masks
01016      *
01017      * @returns     MAX3133X_NO_ERR on success, error code on failure.
01018      */
01019     int wakeup_enable(uint8_t wakeup_enable_mask);
01020 
01021     /**
01022      * @brief       Disable Wakeup
01023      *
01024      * @param[in]   wakeup_disable_mask one or more of Sleep Config Register Masks
01025      *
01026      * @returns     MAX3133X_NO_ERR on success, error code on failure.
01027      */
01028     int wakeup_disable(uint8_t wakeup_disable_mask);
01029 
01030     MAX31334(I2C *i2c, PinName inta_pin = NC, PinName intb_pin = NC) : MAX3133X(&reg_addr, i2c, inta_pin, intb_pin) {}
01031 };
01032 
01033 /** MAX31331 Device Class
01034 *
01035 * Hold configurations for the MAX31331
01036 */
01037 class MAX31331 : public MAX3133X
01038 {
01039 private:
01040     static const reg_addr_t reg_addr;
01041 
01042 public:
01043     typedef struct {
01044         a1ac_t          a1ac;       /*RTC_CONFIG1 - Alarm1 Auto Clear */
01045         dip_t           dip;        /*RTC_CONFIG1 - Digital (DIN) interrupt polarity */
01046         data_ret_t      data_ret;   /*RTC_CONFIG1 - Data retention mode enable/disable. */
01047         i2c_timeout_t   i2c_timeout;/*RTC_CONFIG1 - I2C timeout enable */
01048         en_osc_t        en_osc;     /*RTC_CONFIG1 - Active-high enable for the crystal oscillator */
01049         enclko_t        enclko;     /*RTC_CONFIG2 - CLKOUT enable */
01050         clko_hz_t       clko_hz;    /*RTC_CONFIG2 - Set output clock frequency on INTBb/CLKOUT pin */
01051     }rtc_config_t;
01052 
01053     /**
01054     * @brief        Configure the device
01055     *
01056     * @param[in]    max31331_config Device configuration
01057     *
01058     * @return       MAX3133X_NO_ERR on success, error code on failure
01059     *
01060     * @note         RTC_CONFIG1 and RTC_CONFIG2 registers are set.
01061     */
01062     int rtc_config(rtc_config_t *max31331_config);
01063 
01064     /**
01065     * @brief        Get device configuration
01066     *
01067     * @param[out]   max31331_config Device configuration
01068     *
01069     * @return       MAX3133X_NO_ERR on success, error code on failure
01070     *
01071     * @note         RTC_CONFIG1 and RTC_CONFIG2 register values are read.
01072     */
01073     int get_rtc_config(rtc_config_t *max31331_config);
01074 
01075     /**
01076     * @brief        Initialize timer
01077     *
01078     * @param[in]    init_val Timer initial value
01079     * @param[in]    repeat Timer repeat mode enable/disable
01080     * @param[in]    freq Timer frequency, one of TIMER_FREQ_*
01081     *
01082     * @return       MAX3133X_NO_ERR on success, error code on failure
01083     */
01084     int timer_init(uint8_t  init_val, bool repeat, timer_freq_t freq);
01085 
01086     /**
01087     * @brief    Read timer value
01088     *
01089     * @return   timer value on success, error code on failure
01090     */
01091     int timer_get();
01092 
01093     MAX31331(I2C *i2c, PinName inta_pin = NC, PinName intb_pin = NC) : MAX3133X(&reg_addr, i2c, inta_pin, intb_pin) {}
01094 };
01095 
01096 #endif /* MAX3133X_HPP_ */